def get_mqtt_callbacks(self):
callbacks = []
template = {
'en': """
.. mqtt:function:: register/{device}/<UID>/{callback_name_under}\n\n{meta_table}\n
A callback can be registered for this event by publishing to the ``.../register/{device}/<UID>/{callback_name_under}[/<SUFFIX>]`` topic with the payload "true".
An added callback can be removed by publishing to the same topic with the payload "false".
To support multiple (de)registrations, e.g. for message filtering, an optional suffix can be used.
If the callback is triggered, a message with it's payload is published under the corresponding ``.../callback/{device}/<UID>/{callback_name_under}[/<SUFFIX>]`` topic for each registered suffix.
{desc}
""",
'de': """
.. mqtt:function:: register/{device}/<UID>/{callback_name_under}\n\n{meta_table}\n
Ein Callback für dieses Event kann durch Senden des Payloads "true" an das ``.../register/{device}/<UID>/{callback_name_under}[/<SUFFIX>]``-Topic hinzugefügt werden.
Ein hinzugefügtes Callback kann durch Senden des Payloads "false" an das selbe Topic wieder entfernt werden.
Um mehrere (De-)Registrierungen zu unterstützen, z.B. um Nachrichten filtern zu können, kann ein optionaler Suffix verwendet werden.
Wenn das Callback ausgelöst wird, wird dessen Payload für jeden Suffix auf dem entsprechenden ``.../callback/{device}/<UID>/{callback_name_under}[/<SUFFIX>]``-Topic veröffentlicht.
{desc}
"""
}
device = self.get_mqtt_device_name()
for packet in self.get_packets('callback'):
skip = -2 if packet.has_high_level() else 0
meta = common.format_simple_element_meta([('register', 'bool', 1, 'in')],
parameter_label_override={'en': 'Register Request', 'de': 'Registrierungsanfrage'})
meta += packet.get_formatted_element_meta(lambda element, cardinality=None: element.get_mqtt_type(for_doc=True, cardinality=cardinality),
lambda element, index=None: element.get_name(index=index).under,
callback_parameter_label_override={'en': 'Callback Response', 'de': 'Callback-Antwort'},
constants_hint_override={'en': ('See symbols', 'with symbols'), 'de': ('Siehe Symbole', 'mit Symbolen')},
no_out_value={'en': 'empty payload', 'de': 'keine Nutzdaten'},
explicit_string_cardinality=True,
explicit_variable_stream_cardinality=True,
explicit_fixed_stream_cardinality=True,
explicit_common_cardinality=True,
high_level=True)
meta_table = common.make_rst_meta_table(meta)
desc = packet.get_mqtt_formatted_doc()
callbacks.append(common.select_lang(template).format(device=device,
callback_name_under=packet.get_mqtt_name(skip=skip),
meta_table=meta_table,
desc=desc))
return ''.join(callbacks)
def get_mqtt_functions(self, type_):
functions = []
template = '.. mqtt:function:: request/{struct_name}/<UID>/{func_name}\n\n{meta_table}{desc}\n'
for packet in self.get_packets('function'):
if packet.get_doc_type() != type_ or packet.is_virtual():
continue
skip = -2 if packet.has_high_level() else 0
name = packet.get_mqtt_name(skip=skip)
meta = packet.get_formatted_element_meta(lambda element, cardinality=None: element.get_mqtt_type(for_doc=True, cardinality=cardinality),
lambda element, index=None: element.get_name(index=index).under,
parameter_label_override={'en': 'Request', 'de': 'Anfrage'},
return_label_override={'en': 'Response', 'de': 'Antwort'},
no_in_value={'en': 'empty payload', 'de': 'keine Nutzdaten'},
no_out_value={'en': 'no response', 'de': 'keine Antwort'},
constants_hint_override={'en': ('See symbols', 'with symbols'), 'de': ('Siehe Symbole', 'mit Symbolen')},
explicit_string_cardinality=True,
explicit_variable_stream_cardinality=True,
explicit_fixed_stream_cardinality=True,
explicit_common_cardinality=True,
high_level=True)
if packet.get_name().space == 'Get Identity':
meta += common.format_simple_element_meta([('_display_name', 'string', None, 'out')],
return_label_override={'en': 'Response', 'de': 'Antwort'})
meta_table = common.make_rst_meta_table(common.merge_meta_sections(meta))
desc = packet.get_mqtt_formatted_doc()
if packet.get_name().under == 'get_identity':
get_id_desc = {
'en': """If symbolic output is not disabled, the device identifier is mapped to the corresponding name in the format used in topics.
The display name contains the {}'s name in a human readable form.""",
'de': """Falls die symbolische Ausgabe nicht deaktiviert wurde, wird der Device Identifier auf den entsprechenden Namen im Format, welches die Topics verwenden, abgebildet.
Der Display Name enthält den Anzeigenamen des {}."""
}
desc += common.select_lang(get_id_desc).format(self.get_short_display_name())
functions.append(template.format(struct_name=self.get_mqtt_device_name(),
func_name=name,
meta_table=meta_table,
desc=desc))
return ''.join(functions)
def get_c_api(self):
create_str = {
'en':
"""
.. c:function:: void {0}_create({1} *{0}, const char *uid, IPConnection *ipcon)
{2}
Creates the device object ``{0}`` with the unique device ID ``uid`` and adds
it to the IPConnection ``ipcon``:
.. code-block:: c
{1} {0};
{0}_create(&{0}, "YOUR_DEVICE_UID", &ipcon);
This device object can be used after the IP connection has been connected.
""",
'de':
"""
.. c:function:: void {0}_create({1} *{0}, const char *uid, IPConnection *ipcon)
{2}
Erzeugt ein Geräteobjekt ``{0}`` mit der eindeutigen Geräte ID ``uid`` und
fügt es der IP Connection ``ipcon`` hinzu:
.. code-block:: c
{1} {0};
{0}_create(&{0}, "YOUR_DEVICE_UID", &ipcon);
Dieses Geräteobjekt kann benutzt werden, nachdem die IP Connection verbunden.
"""
}
destroy_str = {
'en':
"""
.. c:function:: void {0}_destroy({1} *{0})
{2}
Removes the device object ``{0}`` from its IPConnection and destroys it.
The device object cannot be used anymore afterwards.
""",
'de':
"""
.. c:function:: void {0}_destroy({1} *{0})
{2}
Entfernt das Geräteobjekt ``{0}`` von dessen IP Connection und zerstört es.
Das Geräteobjekt kann hiernach nicht mehr verwendet werden.
"""
}
register_str = {
'en':
"""
.. c:function:: void {1}_register_callback({2} *{1}, int16_t callback_id, void (*function)(void), void *user_data)
{3}
Registers the given ``function`` with the given ``callback_id``. The
``user_data`` will be passed as the last parameter to the ``function``.
The available callback IDs with corresponding function signatures are
listed :ref:`below <{0}_c_callbacks>`.
""",
'de':
"""
.. c:function:: void {1}_register_callback({2} *{1}, int16_t callback_id, void (*function)(void), void *user_data)
{3}
Registriert die ``function`` für die gegebene ``callback_id``. Die ``user_data``
werden der Funktion als letztes Parameter mit übergeben.
Die verfügbaren Callback IDs mit den zugehörigen Funktionssignaturen
sind :ref:`unten <{0}_c_callbacks>` zu finden.
"""
}
c_str = {
'en':
"""
.. _{0}_c_callbacks:
Callbacks
^^^^^^^^^
Callbacks can be registered to receive time critical or recurring data from the
device. The registration is done with the :c:func:`{1}_register_callback` function:
.. code-block:: c
void my_callback(int value, void *user_data) {{
printf("Value: %d\\n", value);
}}
{1}_register_callback(&{1},
{4} {2}_CALLBACK_EXAMPLE,
{4} (void (*)(void))my_callback,
{4} NULL);
The available constants with corresponding function signatures are described below.
.. note::
Using callbacks for recurring events is *always* preferred
compared to using getters. It will use less USB bandwidth and the latency
will be a lot better, since there is no round trip time.
{3}
""",
'de':
"""
.. _{0}_c_callbacks:
Callbacks
^^^^^^^^^
Callbacks können registriert werden um zeitkritische oder wiederkehrende Daten
vom Gerät zu erhalten. Die Registrierung kann mit der :c:func:`{1}_register_callback`
Funktion durchgeführt werden:
.. code-block:: c
void my_callback(int value, void *user_data) {{
printf("Value: %d\\n", value);
}}
{1}_register_callback(&{1},
{4} {2}_CALLBACK_EXAMPLE,
{4} (void (*)(void))my_callback,
{4} NULL);
Die verfügbaren Konstanten mit den zugehörigen Funktionssignaturen werden weiter
unten beschrieben.
.. note::
Callbacks für wiederkehrende Ereignisse zu verwenden ist
*immer* zu bevorzugen gegenüber der Verwendung von Abfragen.
Es wird weniger USB-Bandbreite benutzt und die Latenz ist
erheblich geringer, da es keine Paketumlaufzeit gibt.
{3}
"""
}
api = {
'en':
"""
.. _{0}_c_api:
API
---
Most functions of the C/C++ bindings return an error code (``e_code``).
Data returned from the device, when a getter is called,
is handled via output parameters. These parameters are labeled with the
``ret_`` prefix.
Possible error codes are:
* **E**\\ _OK = 0
* **E**\\ _TIMEOUT = -1
* **E**\\ _NO_STREAM_SOCKET = -2
* **E**\\ _HOSTNAME_INVALID = -3
* **E**\\ _NO_CONNECT = -4
* **E**\\ _NO_THREAD = -5
* **E**\\ _NOT_ADDED = -6 (unused since C/C++ bindings version 2.0.0)
* **E**\\ _ALREADY_CONNECTED = -7
* **E**\\ _NOT_CONNECTED = -8
* **E**\\ _INVALID_PARAMETER = -9
* **E**\\ _NOT_SUPPORTED = -10
* **E**\\ _UNKNOWN_ERROR_CODE = -11
* **E**\\ _STREAM_OUT_OF_SYNC = -12
* **E**\\ _INVALID_UID = -13
* **E**\\ _NON_ASCII_CHAR_IN_SECRET = -14
* **E**\\ _WRONG_DEVICE_TYPE = -15
* **E**\\ _DEVICE_REPLACED = -16
* **E**\\ _WRONG_RESPONSE_LENGTH = -17
as defined in :file:`ip_connection.h`.
All functions listed below are thread-safe.
{1}
{2}
""",
'de':
"""
.. _{0}_c_api:
API
---
Die meistens Funktionen der C/C++ Bindings geben einen Fehlercode (``e_code``)
zurück. Vom Gerät zurückgegebene Daten werden, wenn eine
Abfrage aufgerufen wurde, über Ausgabeparameter gehandhabt. Diese Parameter
sind mit dem ``ret_`` Präfix gekennzeichnet.
Mögliche Fehlercodes sind:
* **E**\\ _OK = 0
* **E**\\ _TIMEOUT = -1
* **E**\\ _NO_STREAM_SOCKET = -2
* **E**\\ _HOSTNAME_INVALID = -3
* **E**\\ _NO_CONNECT = -4
* **E**\\ _NO_THREAD = -5
* **E**\\ _NOT_ADDED = -6 (seit C/C++ Bindings Version 2.0.0 nicht mehr verwendet)
* **E**\\ _ALREADY_CONNECTED = -7
* **E**\\ _NOT_CONNECTED = -8
* **E**\\ _INVALID_PARAMETER = -9
* **E**\\ _NOT_SUPPORTED = -10
* **E**\\ _UNKNOWN_ERROR_CODE = -11
* **E**\\ _STREAM_OUT_OF_SYNC = -12
* **E**\\ _INVALID_UID = -13
* **E**\\ _NON_ASCII_CHAR_IN_SECRET = -14
* **E**\\ _WRONG_DEVICE_TYPE = -15
* **E**\\ _DEVICE_REPLACED = -16
* **E**\\ _WRONG_RESPONSE_LENGTH = -17
wie in :file:`ip_connection.h` definiert.
Alle folgend aufgelisteten Funktionen sind Thread-sicher.
{1}
{2}
"""
}
const_str = {
'en':
"""
.. _{0}_c_constants:
Constants
^^^^^^^^^
.. c:var:: {1}_DEVICE_IDENTIFIER
This constant is used to identify a {4}.
The :c:func:`{2}_get_identity` function and the :c:data:`IPCON_CALLBACK_ENUMERATE`
callback of the IP Connection have a ``device_identifier`` parameter to specify
the Brick's or Bricklet's type.
.. c:var:: {1}_DEVICE_DISPLAY_NAME
This constant represents the human readable name of a {4}.
""",
'de':
"""
.. _{0}_c_constants:
Konstanten
^^^^^^^^^^
.. c:var:: {1}_DEVICE_IDENTIFIER
Diese Konstante wird verwendet um {3} {4} zu identifizieren.
Die :c:func:`{2}_get_identity` Funktion und der :c:data:`IPCON_CALLBACK_ENUMERATE`
Callback der IP Connection haben ein ``device_identifier`` Parameter um den Typ
des Bricks oder Bricklets anzugeben.
.. c:var:: {1}_DEVICE_DISPLAY_NAME
Diese Konstante stellt den Anzeigenamen eines {4} dar.
"""
}
create_meta = common.format_simple_element_meta([
(self.get_name().under, self.get_name().camel + ' *', 1, 'in'),
('uid', 'const char *', 1, 'in'),
('ipcon', 'IPConnection *', 1, 'in')
])
create_meta_table = common.make_rst_meta_table(create_meta)
cre = common.select_lang(create_str).format(self.get_name().under,
self.get_name().camel,
create_meta_table)
destroy_meta = common.format_simple_element_meta([
(self.get_name().under, self.get_name().camel + ' *', 1, 'in')
])
destroy_meta_table = common.make_rst_meta_table(destroy_meta)
des = common.select_lang(destroy_str).format(self.get_name().under,
self.get_name().camel,
destroy_meta_table)
reg_meta = common.format_simple_element_meta([
(self.get_name().under, self.get_name().camel + ' *', 1, 'in'),
('callback_id', 'int16_t', 1, 'in'),
('function', 'void (*)(void)', 1, 'in'),
('user_data', 'void *', 1, 'in')
])
red_meta_table = common.make_rst_meta_table(reg_meta)
reg = common.select_lang(register_str).format(
self.get_doc_rst_ref_name(),
self.get_name().under,
self.get_name().camel, red_meta_table)
bf = self.get_c_functions('bf')
af = self.get_c_functions('af')
ccf = self.get_c_functions('ccf')
c = self.get_c_callbacks()
vf = self.get_c_functions('vf')
if_ = self.get_c_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format(cre + des, bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
api_str += common.select_lang(common.ccf_str).format(reg, ccf)
api_str += common.select_lang(c_str).format(
self.get_doc_rst_ref_name(),
self.get_name().under,
self.get_name().upper, c, ' ' * len(self.get_name().under))
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
article = 'ein'
if self.is_brick():
article = 'einen'
api_str += common.select_lang(const_str).format(
self.get_doc_rst_ref_name(),
self.get_name().upper,
self.get_name().under, article, self.get_long_display_name())
return common.select_lang(api).format(
self.get_doc_rst_ref_name(),
self.specialize_c_doc_function_links(
common.select_lang(self.get_doc())), api_str)
def get_java_api(self):
create_str = {
'en':
"""
.. java:function:: class {0}(String uid, IPConnection ipcon)
{2}
Creates an object with the unique device ID ``uid``:
.. code-block:: java
{0} {1} = new {0}("YOUR_DEVICE_UID", ipcon);
This object can then be used after the IP Connection is connected.
""",
'de':
"""
.. java:function:: class {0}(String uid, IPConnection ipcon)
{2}
Erzeugt ein Objekt mit der eindeutigen Geräte ID ``uid``:
.. code-block:: java
{0} {1} = new {0}("YOUR_DEVICE_UID", ipcon);
Dieses Objekt kann benutzt werden, nachdem die IP Connection verbunden ist.
"""
}
ccf_str = {
'en':
"""
Listener Configuration Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
{0}
""",
'de':
"""
Konfigurationsfunktionen für Listener
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
{0}
"""
}
c_str = {
'en':
"""
.. _{0}_java_callbacks:
Listeners
^^^^^^^^^
Listeners can be registered to receive
time critical or recurring data from the device. The registration is done
with ``add*Listener()`` functions of the device object.
The parameter is a listener class object, for example:
.. code-block:: java
device.addExampleListener(new {1}.ExampleListener() {{
public void property(int value) {{
System.out.println("Value: " + value);
}}
}});
The available listener classes with inherent methods to be overwritten
are described below. It is possible to add several listeners and
to remove them with the corresponding ``remove*Listener()`` function.
.. note::
Using listeners for recurring events is *always* preferred
compared to using getters. It will use less USB bandwidth and the latency
will be a lot better, since there is no round trip time.
{2}
""",
'de':
"""
.. _{0}_java_callbacks:
Listener
^^^^^^^^
Listener können registriert werden um zeitkritische
oder wiederkehrende Daten vom Gerät zu erhalten. Die Registrierung kann
mit ``add*Listener()`` Funktionen eines Geräteobjekts durchgeführt werden.
Der Parameter ist ein Listener Klassen Objekt, z.B.:
.. code-block:: java
device.addExampleListener(new {1}.ExampleListener() {{
public void property(int value) {{
System.out.println("Value: " + value);
}}
}});
Die verfügbaren Listener Klassen mit den Methoden welche überschrieben
werden können werden unterhalb beschrieben. Es ist möglich mehrere
Listener hinzuzufügen und auch mit einem korrespondierenden
``remove*Listener()`` wieder zu entfernen.
.. note::
Listener für wiederkehrende Ereignisse zu verwenden ist
*immer* zu bevorzugen gegenüber der Verwendung von Abfragen.
Es wird weniger USB-Bandbreite benutzt und die Latenz ist
erheblich geringer, da es keine Paketumlaufzeit gibt.
{2}
"""
}
api = {
'en':
"""
.. _{0}_java_api:
API
---
Generally, every method of the Java bindings that returns a value can
throw a ``TimeoutException``. This exception gets thrown if the
device did not respond. If a cable based connection is used, it is
unlikely that this exception gets thrown (assuming nobody unplugs the
device). However, if a wireless connection is used, timeouts will occur
if the distance to the device gets too big.
Beside the ``TimeoutException`` there is also a ``NotConnectedException`` that
is thrown if a method needs to communicate with the device while the
IP Connection is not connected.
Since Java does not support multiple return values and return by reference
is not possible for primitive types, we use small classes that
only consist of member variables. The member variables of the returned objects
are described in the corresponding method descriptions.
The package for all Brick/Bricklet bindings and the IP Connection is
``com.tinkerforge.*``
All methods listed below are thread-safe.
{1}
{2}
""",
'de':
"""
.. _{0}_java_api:
API
---
Prinzipiell kann jede Methode der Java Bindings eine ``TimeoutException``
werfen. Diese Exception wird
geworfen wenn das Gerät nicht antwortet. Wenn eine Kabelverbindung genutzt
wird, ist es unwahrscheinlich, dass die Exception geworfen wird (unter der
Annahme, dass das Gerät nicht abgesteckt wird). Bei einer drahtlosen Verbindung
können Zeitüberschreitungen auftreten, sobald die Entfernung zum Gerät zu
groß wird.
Neben der ``TimeoutException`` kann auch noch eine ``NotConnectedException``
geworfen werden, wenn versucht wird mit einem Brick oder Bricklet zu
kommunizieren, aber die IP Connection nicht verbunden ist.
Da Java nicht mehrere Rückgabewerte unterstützt und eine Referenzrückgabe
für elementare Type nicht möglich ist, werden kleine Klassen verwendet, die
nur aus Member-Variablen bestehen. Die Member-Variablen des zurückgegebenen
Objektes werden in der jeweiligen Methodenbeschreibung erläutert.
Das Package für alle Brick/Bricklet Bindings und die IP Connection ist
``com.tinkerforge.*``
Alle folgend aufgelisteten Methoden sind Thread-sicher.
{1}
{2}
"""
}
const_str = {
'en':
"""
.. _{0}_java_constants:
Constants
^^^^^^^^^
.. java:member:: int {1}::DEVICE_IDENTIFIER
This constant is used to identify a {3}.
The :java:func:`getIdentity() <{1}::getIdentity>` function and the
:java:func:`IPConnection.EnumerateListener <IPConnection::EnumerateListener>`
listener of the IP Connection have a ``deviceIdentifier`` parameter to specify
the Brick's or Bricklet's type.
.. java:member:: String {1}::DEVICE_DISPLAY_NAME
This constant represents the human readable name of a {3}.
""",
'de':
"""
.. _{0}_java_constants:
Konstanten
^^^^^^^^^^
.. java:member:: int {1}::DEVICE_IDENTIFIER
Diese Konstante wird verwendet um {2} {3} zu identifizieren.
Die :java:func:`getIdentity() <{1}::getIdentity>` Funktion und der
:java:func:`IPConnection.EnumerateListener <IPConnection::EnumerateListener>`
Listener der IP Connection haben ein ``deviceIdentifier`` Parameter um den Typ
des Bricks oder Bricklets anzugeben.
.. java:member:: String {1}::DEVICE_DISPLAY_NAME
Diese Konstante stellt den Anzeigenamen eines {3} dar.
"""
}
create_meta = common.format_simple_element_meta([
('uid', 'String', 1, 'in'), ('ipcon', 'IPConnection', 1, 'in'),
(self.get_name().headless, self.get_java_class_name(), 1, 'out')
])
create_meta_table = common.make_rst_meta_table(create_meta)
cre = common.select_lang(create_str).format(self.get_java_class_name(),
self.get_name().headless,
create_meta_table)
bf = self.get_java_functions('bf')
af = self.get_java_functions('af')
ccf = self.get_java_functions('ccf')
c = self.get_java_callbacks()
vf = self.get_java_functions('vf')
if_ = self.get_java_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format(cre, bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
if ccf:
api_str += common.select_lang(ccf_str).format(ccf)
api_str += common.select_lang(c_str).format(
self.get_doc_rst_ref_name(), self.get_java_class_name(), c)
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
article = 'ein'
if self.is_brick():
article = 'einen'
api_str += common.select_lang(const_str).format(
self.get_doc_rst_ref_name(), self.get_java_class_name(), article,
self.get_long_display_name())
return common.select_lang(api).format(
self.get_doc_rst_ref_name(),
self.specialize_java_doc_function_links(
common.select_lang(self.get_doc())), api_str)
def get_perl_api(self):
create_str = {
'en':
"""
.. perl:function:: {0}->new($uid, $ipcon)
{2}
Creates an object with the unique device ID ``$uid``:
.. code-block:: perl
${1} = {0}->new("YOUR_DEVICE_UID", $ipcon);
This object can then be used after the IP Connection is connected.
""",
'de':
"""
.. perl:function:: {0}->new($uid, $ipcon)
{2}
Erzeugt ein Objekt mit der eindeutigen Geräte ID ``$uid``:
.. code-block:: perl
${1} = {0}->new("YOUR_DEVICE_UID", $ipcon);
Dieses Objekt kann benutzt werden, nachdem die IP Connection verbunden ist.
"""
}
register_str = {
'en':
"""
.. perl:function:: {1}->register_callback($callback_id, $function)
{2}
Registers the given ``$function`` name with the given ``$callback_id``.
The available callback IDs with corresponding function signatures are listed
:ref:`below <{0}_perl_callbacks>`.
""",
'de':
"""
.. perl:function:: {1}->register_callback($callback_id, $function)
{2}
Registriert den ``$function`` Namen für die gegebene ``$callback_id``.
Die verfügbaren Callback IDs mit den zugehörigen Funktionssignaturen
sind :ref:`unten <{0}_perl_callbacks>` zu finden.
"""
}
c_str = {
'en':
"""
.. _{0}_perl_callbacks:
Callbacks
^^^^^^^^^
Callbacks can be registered to receive
time critical or recurring data from the device. The registration is done
with the :perl:func:`register_callback() <{1}->register_callback>` function of
the device object. The first parameter is the callback ID and the second
parameter the callback function name:
.. code-block:: perl
sub my_callback
{{
print "@_[0]";
}}
${2}->register_callback({1}->CALLBACK_EXAMPLE, 'my_callback')
The callback function will be called from an internal thread of the
IP Connection. In contrast to many other programming languages, variables are
not automatically shared between threads in Perl. If you want to share a global
variable between a callback function and the rest for your program it has to be
marked as ``:shared``. See the documentation of the `threads::shared
<https://perldoc.perl.org/threads/shared.html>`__ Perl module for more details.
The available constants with inherent number and type of parameters are
described below.
.. note::
Using callbacks for recurring events is *always* preferred
compared to using getters. It will use less USB bandwidth and the latency
will be a lot better, since there is no round trip time.
{3}
""",
'de':
"""
.. _{0}_perl_callbacks:
Callbacks
^^^^^^^^^
Callbacks können registriert werden um zeitkritische
oder wiederkehrende Daten vom Gerät zu erhalten. Die Registrierung kann
mit der Funktion :perl:func:`register_callback() <{1}->register_callback>` des
Geräte Objektes durchgeführt werden. Der erste Parameter ist die Callback ID
und der zweite Parameter ist der Name der Callback-Funktion:
.. code-block:: perl
sub my_callback
{{
print "@_[0]";
}}
${2}->register_callback({1}->CALLBACK_EXAMPLE, 'my_callback')
Die Callback Funktion wird dann von einem internen Thread der IP Connection
aufgerufen werden. Im Gegensatz zu vielen anderen Programmiersprachen werden
Variablen nicht automatisch zwischen Threads geteilt. Wenn eine Variable
gleichzeitig in einer Callback Funktion und dem Rest des Programms genutzt
werden soll, dann muss diese als ``:shared`` markiert werden. Siehe dazu auch
die Dokumentation des `threads::shared
<https://perldoc.perl.org/threads/shared.html>`__ Perl Moduls für weitere
Details.
Die verfügbaren IDs mit der dazugehörigen Parameteranzahl und -typen werden
weiter unten beschrieben.
.. note::
Callbacks für wiederkehrende Ereignisse zu verwenden ist
*immer* zu bevorzugen gegenüber der Verwendung von Abfragen.
Es wird weniger USB-Bandbreite benutzt und die Latenz ist
erheblich geringer, da es keine Paketumlaufzeit gibt.
{3}
"""
}
api = {
'en':
"""
.. _{0}_perl_api:
API
---
Generally, every subroutine of the Perl bindings can report an error as
``Tinkerforge::Error`` object via ``croak()``. The object has a
``get_code()`` and a ``get_message()`` subroutine. There are different
error code:
* Error->ALREADY_CONNECTED = 11
* Error->NOT_CONNECTED = 12
* Error->CONNECT_FAILED = 13
* Error->INVALID_FUNCTION_ID = 21
* Error->TIMEOUT = 31
* Error->INVALID_PARAMETER = 41
* Error->FUNCTION_NOT_SUPPORTED = 42
* Error->UNKNOWN_ERROR = 43
* Error->STREAM_OUT_OF_SYNC = 51
* Error->INVALID_UID = 61
* Error->NON_ASCII_CHAR_IN_SECRET = 71
* Error->WRONG_DEVICE_TYPE = 81
* Error->DEVICE_REPLACED = 82
* Error->WRONG_RESPONSE_LENGTH = 83
All functions listed below are thread-safe.
{1}
{2}
""",
'de':
"""
.. _{0}_perl_api:
API
---
Allgemein kann jede Subroutine der Perl Bindings Fehler als
``Tinkerforge::Error`` Objekt mittels ``croak()`` melden. Das Objekt hat eine
``get_code()`` und eine ``get_message()`` Subroutine. Es sind verschiedene
Fehlercodes definiert:
* Error->ALREADY_CONNECTED = 11
* Error->NOT_CONNECTED = 12
* Error->CONNECT_FAILED = 13
* Error->INVALID_FUNCTION_ID = 21
* Error->TIMEOUT = 31
* Error->INVALID_PARAMETER = 41
* Error->FUNCTION_NOT_SUPPORTED = 42
* Error->UNKNOWN_ERROR = 43
* Error->STREAM_OUT_OF_SYNC = 51
* Error->INVALID_UID = 61
* Error->NON_ASCII_CHAR_IN_SECRET = 71
* Error->WRONG_DEVICE_TYPE = 81
* Error->DEVICE_REPLACED = 82
* Error->WRONG_RESPONSE_LENGTH = 83
Alle folgend aufgelisteten Funktionen sind Thread-sicher.
{1}
{2}
"""
}
const_str = {
'en':
"""
.. _{0}_perl_constants:
Constants
^^^^^^^^^
.. perl:attribute:: {1}->DEVICE_IDENTIFIER
This constant is used to identify a {3}.
The :perl:func:`get_identity() <{1}->get_identity>` function and the
:perl:attr:`IPConnection->CALLBACK_ENUMERATE <IPConnection->CALLBACK_ENUMERATE>`
callback of the IP Connection have a ``device_identifier`` parameter to specify
the Brick's or Bricklet's type.
.. perl:attribute:: {1}->DEVICE_DISPLAY_NAME
This constant represents the human readable name of a {3}.
""",
'de':
"""
.. _{0}_perl_constants:
Konstanten
^^^^^^^^^^
.. perl:attribute:: {1}->DEVICE_IDENTIFIER
Diese Konstante wird verwendet um {2} {3} zu identifizieren.
Die :perl:func:`get_identity() <{1}->get_identity>` Funktion und der
:perl:attr:`IPConnection->CALLBACK_ENUMERATE <IPConnection->CALLBACK_ENUMERATE>`
Callback der IP Connection haben ein ``device_identifier`` Parameter um den Typ
des Bricks oder Bricklets anzugeben.
.. perl:attribute:: {1}->DEVICE_DISPLAY_NAME
Diese Konstante stellt den Anzeigenamen eines {3} dar.
"""
}
create_meta = common.format_simple_element_meta([
('$uid', 'string', 1, 'in'), ('$ipcon', 'IPConnection', 1, 'in'),
('$' + self.get_name().under, self.get_perl_class_name(), 1, 'out')
])
create_meta_table = common.make_rst_meta_table(create_meta)
cre = common.select_lang(create_str).format(self.get_perl_class_name(),
self.get_name().under,
create_meta_table)
reg_meta = common.format_simple_element_meta(
[('$callback_id', 'int', 1, 'in'),
('$function', 'string', 1, 'in')],
no_out_value={
'en': 'undef',
'de': 'undef'
})
reg_meta_table = common.make_rst_meta_table(reg_meta)
reg = common.select_lang(register_str).format(
self.get_doc_rst_ref_name(), self.get_perl_class_name(),
reg_meta_table)
bf = self.get_perl_functions('bf')
af = self.get_perl_functions('af')
ccf = self.get_perl_functions('ccf')
c = self.get_perl_callbacks()
vf = self.get_perl_functions('vf')
if_ = self.get_perl_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format(cre, bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
api_str += common.select_lang(common.ccf_str).format(reg, ccf)
api_str += common.select_lang(c_str).format(
self.get_doc_rst_ref_name(), self.get_perl_class_name(),
self.get_name().under, c)
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
article = 'ein'
if self.is_brick():
article = 'einen'
api_str += common.select_lang(const_str).format(
self.get_doc_rst_ref_name(), self.get_perl_class_name(), article,
self.get_long_display_name())
return common.select_lang(api).format(
self.get_doc_rst_ref_name(),
self.specialize_perl_doc_function_links(
common.select_lang(self.get_doc())), api_str)
def get_shell_api(self):
c_str = {
'en':
"""
.. _{0}_shell_callbacks:
Callbacks
^^^^^^^^^
Callbacks can be used to receive time critical or recurring data from the
device:
.. code-block:: bash
tinkerforge dispatch {1} <uid> example
The available callbacks are described below.
.. note::
Using callbacks for recurring events is *always* preferred
compared to using getters. It will use less USB bandwidth and the latency
will be a lot better, since there is no round trip time.
{2}
""",
'de':
"""
.. _{0}_shell_callbacks:
Callbacks
^^^^^^^^^
Callbacks können registriert werden um zeitkritische oder wiederkehrende Daten
vom Gerät zu erhalten:
.. code-block:: bash
tinkerforge dispatch {1} <uid> example
Die verfügbaren Callbacks werden weiter unten beschrieben.
.. note::
Callbacks für wiederkehrende Ereignisse zu verwenden ist
*immer* zu bevorzugen gegenüber der Verwendung von Abfragen.
Es wird weniger USB-Bandbreite benutzt und die Latenz ist
erheblich geringer, da es keine Paketumlaufzeit gibt.
{2}
"""
}
api = {
'en':
"""
.. _{0}_shell_api:
API
---
Possible exit codes for all ``tinkerforge`` commands are:
* 1: interrupted (ctrl+c)
* 2: syntax error
* 21: Python 2.5 or newer is required
* 22: Python ``argparse`` module is missing
* 23: socket error
* 24: other exception
* 25: invalid placeholder in format string
* 26: authentication error
* 201: timeout occurred
* 209: invalid argument value
* 210: function is not supported
* 211: unknown error
{1}
Command Structure
^^^^^^^^^^^^^^^^^
The common options of the ``call`` and ``dispatch`` commands are documented
:ref:`here <ip_connection_shell_api>`. The specific command structure is shown below.
.. sh:function:: X Stinkerforge Pcall N{3} A[<option>..] L<uid> L<function> L[<argument>..]
{5}
The ``call`` command is used to call a function of the {4}. It can take several
options:
* ``--help`` shows help for the specific ``call`` command and exits
* ``--list-functions`` shows a list of known functions of the {4} and exits
.. sh:callback:: X Stinkerforge Pdispatch N{3} A[<option>..] L<uid> L<callback>
{6}
The ``dispatch`` command is used to dispatch a callback of the {4}. It can
take several options:
* ``--help`` shows help for the specific ``dispatch`` command and exits
* ``--list-callbacks`` shows a list of known callbacks of the {4} and exits
.. sh:function:: X Stinkerforge Scall P{3} L<uid> N<function> A[<option>..] L[<argument>..]
{5}
The ``<function>`` to be called can take different options depending of its
kind. All functions can take the following options:
* ``--help`` shows help for the specific function and exits
Getter functions can take the following options:
* ``--execute <command>`` shell command line to execute for each incoming
response (see section about :ref:`output formatting <ip_connection_shell_output>`
for details)
Setter functions can take the following options:
* ``--expect-response`` requests response and waits for it
The ``--expect-response`` option for setter functions allows to detect
timeouts and other error conditions calls of setters as well. The device will
then send a response for this purpose. If this option is not given for a
setter function then no response is sent and errors are silently ignored,
because they cannot be detected.
.. sh:callback:: X Stinkerforge Sdispatch P{3} L<uid> N<callback> A[<option>..]
{6}
The ``<callback>`` to be dispatched can take several options:
* ``--help`` shows help for the specific callback and exits
* ``--execute <command>`` shell command line to execute for each incoming
response (see section about :ref:`output formatting <ip_connection_shell_output>`
for details)
{2}
""",
'de':
"""
.. _{0}_shell_api:
API
---
Mögliche Exit Codes für alle ``tinkerforge`` Befehle sind:
* 1: Unterbrochen (Ctrl+C)
* 2: Syntaxfehler
* 21: Python 2.5 oder neuer wird benötigt
* 22: Python ``argparse`` Modul fehlt
* 23: Socket-Fehler
* 24: Andere Exception
* 25: Ungültiger Platzhalter in Format-String
* 26: Authentifizierungsfehler
* 201: Timeout ist aufgetreten
* 209: Ungültiger Argumentwert
* 210: Funktion wird nicht unterstützt
* 211: Unbekannter Fehler
{1}
Befehlsstruktur
^^^^^^^^^^^^^^^
Allgemeine Optionen des ``call`` und des ``dispatch`` Befehls sind
:ref:`hier <ip_connection_shell_api>` zu finden. Im Folgenden wird die spezifische
Befehlsstruktur dargestellt.
.. sh:function:: X Stinkerforge Pcall N{3} A[<option>..] L<uid> L<function> L[<argument>..]
{5}
Der ``call`` Befehl wird verwendet um eine Funktion des {4} aufzurufen. Der
Befehl kennt mehrere Optionen:
* ``--help`` zeigt Hilfe für den spezifischen ``call`` Befehl an und endet dann
* ``--list-functions`` zeigt eine Liste der bekannten Funktionen des {4} an
und endet dann
.. sh:callback:: X Stinkerforge Pdispatch N{3} A[<option>..] L<uid> L<callback>
{6}
Der ``dispatch`` Befehl wird verwendet um eingehende Callbacks des {4}
abzufertigen. Der Befehl kennt mehrere Optionen:
* ``--help`` zeigt Hilfe für den spezifischen ``dispatch`` Befehl an und endet
dann
* ``--list-callbacks`` zeigt eine Liste der bekannten Callbacks des {4} an
und endet dann
.. sh:function:: X Stinkerforge Scall P{3} L<uid> N<function> A[<option>..] L[<argument>..]
{5}
Abhängig von der Art der aufzurufenden ``<function>`` kennt diese verschiedene
Optionen. Alle Funktionen kennen die folgenden Optionen:
* ``--help`` zeigt Hilfe für die spezifische ``<function>`` an und endet dann
Getter-Funktionen kennen zusätzlich die folgenden Optionen:
* ``--execute <command>`` Shell-Befehl der für jede eingehende Antwort
ausgeführt wird (siehe den Abschnitt über :ref:`Ausgabeformatierung
<ip_connection_shell_output>` für Details)
Setter-Funktionen kennen zusätzlich die folgenden Optionen:
* ``--expect-response`` fragt Antwort an und wartet auf diese
Mit der ``--expect-response`` Option für Setter-Funktionen können Timeouts und
andere Fehlerfälle auch für Aufrufe von Setter-Funktionen detektiert werden.
Das Gerät sendet dann eine Antwort extra für diesen Zweck. Wenn diese Option
für eine Setter-Funktion nicht angegeben ist, dann wird keine Antwort vom
Gerät gesendet und Fehler werden stillschweigend ignoriert, da sie nicht
detektiert werden können.
.. sh:callback:: X Stinkerforge Sdispatch P{3} L<uid> N<callback> A[<option>..]
{6}
Der abzufertigende ``<callback>`` kennt mehrere Optionen:
* ``--help`` zeigt Hilfe für den spezifische ``<callback>`` an und endet dann
* ``--execute <command>`` Shell-Befehlszeile der für jede eingehende Antwort
ausgeführt wird (siehe den Abschnitt über :ref:`Ausgabeformatierung
<ip_connection_shell_output>` für Details)
{2}
"""
}
bf = self.get_shell_functions('bf')
af = self.get_shell_functions('af')
ccf = self.get_shell_functions('ccf')
c = self.get_shell_callbacks()
vf = self.get_shell_functions('vf')
if_ = self.get_shell_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format('', bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
if ccf:
api_str += common.select_lang(common.ccf_str).format('', ccf)
api_str += common.select_lang(c_str).format(
self.get_doc_rst_ref_name(), self.get_shell_device_name(), c)
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
call_meta = common.format_simple_element_meta([
('<uid>', 'String', 1, 'in'), ('<function>', 'String', 1, 'in')
])
call_meta_table = common.make_rst_meta_table(call_meta)
dispatch_meta = common.format_simple_element_meta([
('<uid>', 'String', 1, 'in'), ('<callback>', 'String', 1, 'in')
])
dispatch_meta_table = common.make_rst_meta_table(dispatch_meta)
return common.select_lang(api).format(
self.get_doc_rst_ref_name(),
self.specialize_shell_doc_function_links(
common.select_lang(self.get_doc())), api_str,
self.get_shell_device_name(), self.get_long_display_name(),
call_meta_table, dispatch_meta_table)
def get_c_api(self):
create_str = {
'en':
"""
.. c:function:: int tf_{device_under}_create(TF_{device_camel} *{device_under}, const char *uid, TF_HalContext *hal)
{meta_table}
Creates the device object ``{device_under}`` with the unique device ID ``uid`` and adds
it to the HAL context ``hal``:
.. code-block:: c
TF_{device_camel} {device_under};
tf_{device_under}_create(&{device_under}, "YOUR_DEVICE_UID", &hal);
This device object can be used after the HAL has been initialized.
""",
'de':
"""
.. c:function:: int tf_{device_under}_create(TF_{device_camel} *{device_under}, const char *uid, TF_HalContext *hal)
{meta_table}
Erzeugt ein Geräteobjekt ``{device_under}`` mit der eindeutigen Geräte ID ``uid`` und
fügt es dem HAL-Context ``hal`` hinzu:
.. code-block:: c
TF_{device_camel} {device_under};
tf_{device_under}_create(&{device_under}, "YOUR_DEVICE_UID", &ipcon);
Dieses Geräteobjekt kann benutzt werden, nachdem der HAL initialisiert wurde.
"""
}
destroy_str = {
'en':
"""
.. c:function:: int tf_{device_under}_destroy(TF_{device_camel} *{device_under})
{meta_table}
Removes the device object ``{device_under}`` from its HAL context and destroys it.
The device object cannot be used anymore afterwards.
""",
'de':
"""
.. c:function:: int tf_{device_under}_destroy(TF_{device_camel} *{device_under})
{meta_table}
Entfernt das Geräteobjekt ``{device_under}`` von dessen HAL-Context und zerstört es.
Das Geräteobjekt kann hiernach nicht mehr verwendet werden.
"""
}
c_str = {
'en':
"""
.. _{device_doc_rst_ref}_uc_callbacks:
Callbacks
^^^^^^^^^
Callbacks can be registered to receive time critical or recurring data from the
device. The registration is done with the corresponding ``tf_{device_under}_register_*_callback`` function.
The ``user_data`` passed to the registration function as well as the device that triggered the callback are
passed to the registered callback handler.
Only one handler can be registered to a callback at the same time.
To deregister a callback, call the ``tf_{device_under}_register_*_callback`` function
with NULL as handler.
.. note::
Using callbacks for recurring events is preferred
compared to using getters. Polling for a callback requires
writing one byte only. See here :ref:`api_bindings_uc_performance`.
.. warning::
Calling bindings function from inside a callback handler is not allowed.
See here :ref:`api_bindings_uc_thread_safety`.
{callbacks}
""",
'de':
"""
.. _{device_doc_rst_ref}_uc_callbacks:
Callbacks
^^^^^^^^^
Callbacks können registriert werden um zeitkritische oder wiederkehrende Daten
vom Gerät zu erhalten. Die Registrierung kann mit der entsprechenden ``tf_{device_under}_register_*_callback``
Funktion durchgeführt werden. Die ``user_data``, sowie das Gerät, dass das Callback ausgelöst hat, werden
dem registrierten Callback-Handler übergeben.
Nur ein Handler kann gleichzeitig auf das selbe Callback registriert werden.
Um einen Handler zu deregistrieren, kann die ``tf_{device_under}_register_*_callback``-Funktion
mit ``NULL`` als Handler aufgerufen werden.
.. note::
Callbacks für wiederkehrende Ereignisse zu verwenden ist
gegenüber der Verwendung von Abfragen zu bevorzugen.
Es muss nur ein Byte abgefragt werden um zu prüfen ob ein Callback
vorliegt. Siehe hier :ref:`api_bindings_uc_performance`.
.. warning::
Aus Callback-Handlern heraus können keine Bindings-Funktionen verwendet werden.
Siehe hier :ref:`api_bindings_uc_callbacks`.
{callbacks}
"""
}
api = {
'en':
"""
.. _{device_doc_rst_ref}_uc_api:
API
---
Most functions of the C/C++ bindings for microcontrollers return an error code
(``e_code``).
Possible error codes are:
* TF\_\ **E**\\ _OK = 0
* TF\_\ **E**\\ _TIMEOUT = -1
* TF\_\ **E**\\ _INVALID_PARAMETER = -2
* TF\_\ **E**\\ _NOT_SUPPORTED = -3
* TF\_\ **E**\\ _UNKNOWN_ERROR_CODE = -4
* TF\_\ **E**\\ _STREAM_OUT_OF_SYNC = -5
* TF\_\ **E**\\ _INVALID_CHAR_IN_UID = -6
* TF\_\ **E**\\ _UID_TOO_LONG = -7
* TF\_\ **E**\\ _UID_OVERFLOW = -8
* TF\_\ **E**\\ _TOO_MANY_DEVICES = -9
* TF\_\ **E**\\ _DEVICE_NOT_FOUND = -10
* TF\_\ **E**\\ _WRONG_DEVICE_TYPE = -11
* TF\_\ **E**\\ _LOCKED = -12
* TF\_\ **E**\\ _PORT_NOT_FOUND = -13
(as defined in :file:`errors.h`) as well as the errors returned from
the hardware abstraction layer (HAL) that is used.
Use :cpp:func`tf_hal_strerror` (defined in the HAL's header file) to get
an error string for an error code.
Data returned from the device, when a getter is called,
is handled via output parameters. These parameters are labeled with the
``ret_`` prefix. The bindings will not write to an output parameter if NULL or nullptr
is passed. This can be used to ignore outputs that you are not interested in.
**None of the functions listed below are thread-safe.**
See the :ref:`API bindings description <api_bindings_uc>` for details.
{doc_str}
{api_str}
""",
'de':
"""
.. _{device_doc_rst_ref}_uc_api:
API
---
Die meistens Funktionen der C/C++ Bindings für Mikrocontroller geben einen
Fehlercode (``e_code``) zurück
Mögliche Fehlercodes sind:
* TF\_\ **E**\\ _OK = 0
* TF\_\ **E**\\ _TIMEOUT = -1
* TF\_\ **E**\\ _INVALID_PARAMETER = -2
* TF\_\ **E**\\ _NOT_SUPPORTED = -3
* TF\_\ **E**\\ _UNKNOWN_ERROR_CODE = -4
* TF\_\ **E**\\ _STREAM_OUT_OF_SYNC = -5
* TF\_\ **E**\\ _INVALID_CHAR_IN_UID = -6
* TF\_\ **E**\\ _UID_TOO_LONG = -7
* TF\_\ **E**\\ _UID_OVERFLOW = -8
* TF\_\ **E**\\ _TOO_MANY_DEVICES = -9
* TF\_\ **E**\\ _DEVICE_NOT_FOUND = -10
* TF\_\ **E**\\ _WRONG_DEVICE_TYPE = -11
* TF\_\ **E**\\ _CALLBACK_EXEC = -12
* TF\_\ **E**\\ _PORT_NOT_FOUND = -13
(wie in :file:`errors.h` definiert), sowie die Fehlercodes des verwendeten
Hardware-Abstraction-Layers (HALs). Mit ``tf_hal_strerror`` (im Header das HALs definiert)
kann ein Fehlerstring zu einem Fehlercode abgefragt werden.
Vom Gerät zurückgegebene Daten werden, wenn eine
Abfrage aufgerufen wurde, über Ausgabeparameter gehandhabt. Diese Parameter
sind mit dem ``ret_`` Präfix gekennzeichnet. Die Bindings schreiben einen
Ausgabeparameter nicht, wenn NULL bzw. nullptr übergeben wird. So können
uninteressante Ausgaben ignoriert werden.
**Keine der folgend aufgelisteten Funktionen ist Thread-sicher.**
Details finden sich in der :ref:`Beschreibung der API-Bindings <api_bindings_uc>`.
{doc_str}
{api_str}
"""
}
const_str = {
'en':
"""
.. _{device_doc_rst_ref}_uc_constants:
Constants
^^^^^^^^^
.. c:var:: TF_{device_upper}_DEVICE_IDENTIFIER
This constant is used to identify a {device_display}.
The functions :c:func:`tf_{device_under}_get_identity` and :c:func:`tf_hal_get_device_info`
have a ``device_identifier`` output parameter to specify
the Brick's or Bricklet's type.
.. c:var:: TF_{device_upper}_DEVICE_DISPLAY_NAME
This constant represents the human readable name of a {device_display}.
""",
'de':
"""
.. _{device_doc_rst_ref}_uc_constants:
Konstanten
^^^^^^^^^^
.. c:var:: TF_{device_upper}_DEVICE_IDENTIFIER
Diese Konstante wird verwendet um {article} {device_display} zu identifizieren.
Die Funktionen :c:func:`tf_{device_under}_get_identity` und :c:func:`tf_hal_get_device_info`
haben einen ``device_identifier`` Ausgabe-Parameter um den Typ
des Bricks oder Bricklets anzugeben.
.. c:var:: TF_{device_upper}_DEVICE_DISPLAY_NAME
Diese Konstante stellt den Anzeigenamen eines {device_display} dar.
"""
}
create_meta = common.format_simple_element_meta([
(format('{device_under}', self), format('TF_{device_camel} *',
self), 1, 'in'),
('uid', 'const char *', 1, 'in'),
('hal', 'TF_HalContext *', 1, 'in')
])
create_meta_table = common.make_rst_meta_table(create_meta)
cre = format(common.select_lang(create_str),
self,
meta_table=create_meta_table)
destroy_meta = common.format_simple_element_meta([
(format('{device_under}', self), format('TF_{device_camel} *',
self), 1, 'in')
])
destroy_meta_table = common.make_rst_meta_table(destroy_meta)
des = format(common.select_lang(destroy_str),
self,
meta_table=destroy_meta_table)
bf = self.get_c_functions('bf')
af = self.get_c_functions('af')
ccf = self.get_c_functions('ccf')
c = self.get_c_callbacks()
vf = self.get_c_functions('vf')
if_ = self.get_c_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format(cre + des, bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
api_str += common.select_lang(common.ccf_str).format('', ccf)
api_str += format(common.select_lang(c_str),
self,
device_doc_rst_ref=self.get_doc_rst_ref_name(),
callbacks=c,
padding=' ' * len(self.get_name().under))
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
article = 'ein'
if self.is_brick():
article = 'einen'
api_str += format(common.select_lang(const_str),
self,
device_doc_rst_ref=self.get_doc_rst_ref_name(),
article=article)
return format(common.select_lang(api),
self,
device_doc_rst_ref=self.get_doc_rst_ref_name(),
doc_str=self.specialize_c_doc_function_links(
common.select_lang(self.get_doc())),
api_str=api_str)
def get_rust_api(self):
create_str = {
'en':
"""
.. rust:function:: {device_camel}::new(uid: &str, ip_connection: &IpConnection) -> {device_camel}
{meta_table}
Creates a new ``{device_camel}`` object with the unique device ID ``uid`` and adds
it to the IPConnection ``ip_connection``:
.. code-block:: rust
let {device_under} = {device_camel}::new("YOUR_DEVICE_UID", &ip_connection);
This device object can be used after the IP connection has been connected.
""",
'de':
"""
.. rust:function:: {device_camel}::new(uid: &str, ip_connection: &IpConnection) -> {device_camel}
{meta_table}
Erzeugt ein neues ``{device_camel}``-Objekt mit der eindeutigen Geräte ID ``uid`` und
fügt es der IP-Connection ``ip_connection`` hinzu:
.. code-block:: rust
let {device_under} = {device_camel}::new("YOUR_DEVICE_UID", &ip_connection);
Dieses Geräteobjekt kann benutzt werden, nachdem die IP-Connection verbunden.
"""
}
c_str = {
'en':
"""
.. _{0}_rust_callbacks:
Callbacks
^^^^^^^^^
Callbacks can be registered to receive
time critical or recurring data from the device. The registration is done
with the corresponding `get_*_callback_receiver` function, which returns a receiver
for callback events.
.. note::
Using callbacks for recurring events is *always* preferred
compared to using getters. It will use less USB bandwidth and the latency
will be a lot better, since there is no round trip time.
{3}
""",
'de':
"""
.. _{0}_rust_callbacks:
Callbacks
^^^^^^^^^
Callbacks können registriert werden um zeitkritische
oder wiederkehrende Daten vom Gerät zu erhalten. Die Registrierung kann
mit der entsprechenden `get_*_callback_receiver`-Function durchgeführt werden,
welche einen Receiver für Callback-Events zurück gibt.
.. note::
Callbacks für wiederkehrende Ereignisse zu verwenden ist
*immer* zu bevorzugen gegenüber der Verwendung von Abfragen.
Es wird weniger USB-Bandbreite benutzt und die Latenz ist
erheblich geringer, da es keine Paketumlaufzeit gibt.
{3}
"""
}
api = {
'en':
"""
.. _{0}_rust_api:
API
---
To allow non-blocking usage, nearly every function of the Rust bindings returns
a wrapper around a mpsc::Receiver. To block until the function has finished and
get your result, call one of the receiver's recv variants. Those return either
the result sent by the device, or any error occurred.
Functions returning a result directly will block until the device has finished
processing the request.
All functions listed below are thread-safe, those which return a receiver are lock-free.
{1}
{2}
""",
'de':
"""
.. _{0}_rust_api:
API
---
Um eine nicht-blockierende Verwendung zu erlauben, gibt fast jede Funktion der Rust-Bindings
einen Wrapper um einen mpsc::Receiver zurück. Um das Ergebnis eines Funktionsaufrufs zu erhalten
und zu blockieren, bis das Gerät die Anfrage verarbeitet hat, können die recv-Varianten des
Receivers verwendet werden. Diese geben entweder das vom Gerät gesendete Ergebnis, oder einen
aufgetretenen Fehler zurück.
Funktionen die direkt ein Result zurückgeben, blockieren bis das Gerät die Anfrage verarbeitet hat.
Alle folgend aufgelisteten Funktionen sind Thread-sicher, diese, die einen Receiver zurückgeben, sind
Lock-frei.
{1}
{2}
"""
}
const_str = {
'en':
"""
.. _{device_name_ref}_rust_constants:
Constants
^^^^^^^^^
.. rust:constant:: {device_name_camel}::DEVICE_IDENTIFIER: u16
This constant is used to identify a {device_name_display}.
The :rust:func:`{device_name_camel}::get_identity()` function and the :rust:func:`IpConnection::get_enumerate_callback_receiver()`
callback of the IP Connection have a ``device_identifier`` parameter to specify
the Brick's or Bricklet's type.
.. rust:constant:: {device_name_camel}::DEVICE_DISPLAY_NAME: &str
This constant represents the human readable name of a {device_name_display}.
""",
'de':
"""
.. _{device_name_ref}_rust_constants:
Konstanten
^^^^^^^^^^
.. rust:constant:: {device_name_camel}::DEVICE_IDENTIFIER: u16
Diese Konstante wird verwendet um {article} {device_name_display} zu identifizieren.
Die :rust:func:`{device_name_camel}::get_identity()` Funktion und der :rust:func:`IpConnection::get_enumerate_callback_receiver()`
Callback der IP Connection haben ein ``device_identifier`` Parameter um den Typ
des Bricks oder Bricklets anzugeben.
.. rust:constant:: {device_name_camel}::DEVICE_DISPLAY_NAME: &str
Diese Konstante stellt den Anzeigenamen eines {device_name_display} dar.
"""
}
create_meta = common.format_simple_element_meta([
('uid', '&str', 1, 'in'),
('ip_connection', '&IPConnection', 1, 'in'),
(self.get_name().under, self.get_rust_name(), 1, 'out')
])
create_meta_table = common.make_rst_meta_table(create_meta)
cre = common.select_lang(create_str).format(
device_camel=self.get_rust_name(),
device_under=self.get_name().under,
meta_table=create_meta_table)
bf = self.get_rust_functions('bf')
af = self.get_rust_functions('af')
ccf = self.get_rust_functions('ccf')
c = self.get_rust_callbacks()
vf = self.get_rust_functions('vf')
if_ = self.get_rust_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format(cre, bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
if ccf:
api_str += common.select_lang(common.ccf_str).format("", ccf)
api_str += common.select_lang(c_str).format(
self.get_doc_rst_ref_name(),
self.get_name().under,
self.get_name().upper, c)
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
article = 'ein'
if self.is_brick():
article = 'einen'
api_str += common.select_lang(const_str).format(
device_name_ref=self.get_doc_rst_ref_name(),
device_name_camel=self.get_rust_name(),
article=article,
device_name_display=self.get_long_display_name())
return common.select_lang(api).format(
self.get_doc_rst_ref_name(),
self.specialize_rust_doc_function_links(
common.select_lang(self.get_doc())), api_str)
def get_delphi_api(self):
create_str = {
'en':
"""
.. delphi:function:: constructor {0}.Create(const uid: string; ipcon: TIPConnection)
{2}
Creates an object with the unique device ID ``uid``:
.. code-block:: delphi
{1} := {0}.Create('YOUR_DEVICE_UID', ipcon);
This object can then be used after the IP Connection is connected.
""",
'de':
"""
.. delphi:function:: constructor {0}.Create(const uid: string; ipcon: TIPConnection)
{2}
Erzeugt ein Objekt mit der eindeutigen Geräte ID ``uid``:
.. code-block:: delphi
{1} := {0}.Create('YOUR_DEVICE_UID', ipcon);
Dieses Objekt kann benutzt werden, nachdem die IP Connection verbunden ist.
"""
}
c_str = {
'en':
"""
.. _{0}_delphi_callbacks:
Callbacks
^^^^^^^^^
Callbacks can be registered to receive time critical or recurring data from
the device. The registration is done by assigning a procedure to an callback
property of the device object:
.. code-block:: delphi
procedure TExample.MyCallback(sender: {1}; const value: longint);
begin
WriteLn(Format('Value: %d', [value]));
end;
{2}.OnExample := {{$ifdef FPC}}@{{$endif}}example.MyCallback;
The available callback properties and their parameter types are described below.
.. note::
Using callbacks for recurring events is *always* preferred
compared to using getters. It will use less USB bandwidth and the latency
will be a lot better, since there is no round trip time.
{3}
""",
'de':
"""
.. _{0}_delphi_callbacks:
Callbacks
^^^^^^^^^
Callbacks können registriert werden um zeitkritische oder
wiederkehrende Daten vom Gerät zu erhalten. Die Registrierung erfolgt indem
eine Prozedur einem Callback Property des Geräte Objektes zugewiesen wird:
.. code-block:: delphi
procedure TExample.MyCallback(sender: {1}; const value: longint);
begin
WriteLn(Format('Value: %d', [value]));
end;
{2}.OnExample := {{$ifdef FPC}}@{{$endif}}example.MyCallback;
Die verfügbaren Callback Properties und ihre Parametertypen werden weiter
unten beschrieben.
.. note::
Callbacks für wiederkehrende Ereignisse zu verwenden ist
*immer* zu bevorzugen gegenüber der Verwendung von Abfragen.
Es wird weniger USB-Bandbreite benutzt und die Latenz ist
erheblich geringer, da es keine Paketumlaufzeit gibt.
{3}
"""
}
api = {
'en':
"""
.. _{0}_delphi_api:
API
---
Since Delphi does not support multiple return values directly, we use the
``out`` keyword to return multiple values from a function.
All functions and procedures listed below are thread-safe.
{1}
{2}
""",
'de':
"""
.. _{0}_delphi_api:
API
---
Da Delphi nicht mehrere Rückgabewerte direkt unterstützt, wird das ``out``
Schlüsselwort genutzt um mehrere Werte von einer Funktion zurückzugeben.
Alle folgend aufgelisteten Funktionen und Prozeduren sind Thread-sicher.
{1}
{2}
"""
}
const_str = {
'en':
"""
.. _{0}_delphi_constants:
Constants
^^^^^^^^^
.. delphi:function:: const {1}_{2}_DEVICE_IDENTIFIER
This constant is used to identify a {4}.
The :delphi:func:`GetIdentity <{5}.GetIdentity>` function and the
:delphi:func:`TIPConnection.OnEnumerate <TIPConnection.OnEnumerate>`
callback of the IP Connection have a ``deviceIdentifier`` parameter to specify
the Brick's or Bricklet's type.
.. delphi:function:: const {1}_{2}_DEVICE_DISPLAY_NAME
This constant represents the human readable name of a {4}.
""",
'de':
"""
.. _{0}_delphi_constants:
Konstanten
^^^^^^^^^^
.. delphi:function:: const {1}_{2}_DEVICE_IDENTIFIER
Diese Konstante wird verwendet um {3} {4} zu identifizieren.
Die :delphi:func:`GetIdentity <{5}.GetIdentity>` Funktion und der
:delphi:func:`TIPConnection.OnEnumerate <TIPConnection.OnEnumerate>`
Callback der IP Connection haben ein ``deviceIdentifier`` Parameter um den Typ
des Bricks oder Bricklets anzugeben.
.. delphi:function:: const {1}_{2}_DEVICE_DISPLAY_NAME
Diese Konstante stellt den Anzeigenamen eines {4} dar.
"""
}
create_meta = common.format_simple_element_meta([
('uid', 'string', 1, 'in'), ('ipcon', 'TIPConnection', 1, 'in'),
(self.get_name().headless, self.get_delphi_class_name(), 1, 'out')
])
create_meta_table = common.make_rst_meta_table(create_meta)
cre = common.select_lang(create_str).format(
self.get_delphi_class_name(),
self.get_name().headless, create_meta_table)
bf = self.get_delphi_functions('bf')
af = self.get_delphi_functions('af')
ccf = self.get_delphi_functions('ccf')
c = self.get_delphi_callbacks()
vf = self.get_delphi_functions('vf')
if_ = self.get_delphi_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format(cre, bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
if ccf:
api_str += common.select_lang(common.ccf_str).format('', ccf)
api_str += common.select_lang(c_str).format(
self.get_doc_rst_ref_name(), self.get_delphi_class_name(),
self.get_name().headless, c)
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
article = 'ein'
if self.is_brick():
article = 'einen'
api_str += common.select_lang(const_str).format(
self.get_doc_rst_ref_name(),
self.get_category().upper,
self.get_name().upper, article, self.get_long_display_name(),
self.get_delphi_class_name())
return common.select_lang(api).format(
self.get_doc_rst_ref_name(),
self.specialize_delphi_doc_function_links(
common.select_lang(self.get_doc())), api_str)
def get_labview_api(self):
create_str = {
'en':
"""
.. labview:function:: {0}(uid, ipcon) -> {1}
{2}
Creates an object with the unique device ID ``uid``.
This object can then be used after the IP Connection is connected.
""",
'de':
"""
.. labview:function:: {0}(uid, ipcon) -> {1}
{2}
Erzeugt ein Objekt mit der eindeutigen Geräte ID ``uid``.
Dieses Objekt kann benutzt werden, nachdem die IP Connection verbunden ist.
"""
}
c_str = {
'en':
"""
.. _{0}_labview_callbacks:
Callbacks
^^^^^^^^^
Callbacks can be registered to receive time critical or recurring data from
the device. The registration is done by assigning a function to a callback
property of the device object. The available callback property and their type
of parameters are described below.
.. note::
Using callbacks for recurring events is *always* preferred
compared to using getters. It will use less USB bandwidth and the latency
will be a lot better, since there is no round trip time.
{1}
""",
'de':
"""
.. _{0}_labview_callbacks:
Callbacks
^^^^^^^^^
Callbacks können registriert werden um zeitkritische oder
wiederkehrende Daten vom Gerät zu erhalten. Die Registrierung erfolgt indem
eine Funktion einem Callback Property des Geräte Objektes zugewiesen wird.
Die verfügbaren Callback Properties und ihre Parametertypen werden weiter
unten beschrieben.
.. note::
Callbacks für wiederkehrende Ereignisse zu verwenden ist
*immer* zu bevorzugen gegenüber der Verwendung von Abfragen.
Es wird weniger USB-Bandbreite benutzt und die Latenz ist
erheblich geringer, da es keine Paketumlaufzeit gibt.
{1}
"""
}
api = {
'en':
"""
.. _{0}_labview_api:
API
---
Generally, every function of the LabVIEW bindings that outputs a value can
report a ``Tinkerforge.TimeoutException``. This error gets reported if the
device did not respond. If a cable based connection is used, it is
unlikely that this exception gets thrown (assuming nobody plugs the
device out). However, if a wireless connection is used, timeouts will occur
if the distance to the device gets too big.
The namespace for all Brick/Bricklet bindings and the IPConnection is
``Tinkerforge.*``.
{1}
{2}
""",
'de':
"""
.. _{0}_labview_api:
API
---
Prinzipiell kann jede Funktion der LabVIEW Bindings, welche einen Wert ausgibt
eine ``Tinkerforge.TimeoutException`` melden. Dieser Fehler wird
gemeldet wenn das Gerät nicht antwortet. Wenn eine Kabelverbindung genutzt
wird, ist es unwahrscheinlich, dass die Exception geworfen wird (unter der
Annahme, dass das Gerät nicht abgesteckt wird). Bei einer drahtlosen Verbindung
können Zeitüberschreitungen auftreten, sobald die Entfernung zum Gerät zu
groß wird.
Der Namensraum für alle Brick/Bricklet Bindings und die IPConnection ist
``Tinkerforge.*``.
{1}
{2}
"""
}
const_str = {
'en':
"""
.. _{0}_labview_constants:
Constants
^^^^^^^^^
.. labview:symbol:: {1}.DEVICE_IDENTIFIER
This constant is used to identify a {3}.
The :labview:func:`GetIdentity() <{1}.GetIdentity>` function and the
:labview:func:`IPConnection.EnumerateCallback <IPConnection.EnumerateCallback>`
callback of the IP Connection have a ``deviceIdentifier`` parameter to specify
the Brick's or Bricklet's type.
.. labview:symbol:: {1}.DEVICE_DISPLAY_NAME
This constant represents the human readable name of a {3}.
""",
'de':
"""
.. _{0}_labview_constants:
Konstanten
^^^^^^^^^^
.. labview:symbol:: {1}.DEVICE_IDENTIFIER
Diese Konstante wird verwendet um {2} {3} zu identifizieren.
Die :labview:func:`GetIdentity() <{1}.GetIdentity>` Funktion und der
:labview:func:`IPConnection.EnumerateCallback <IPConnection.EnumerateCallback>`
Callback der IP Connection haben ein ``deviceIdentifier`` Parameter um den Typ
des Bricks oder Bricklets anzugeben.
.. labview:symbol:: {1}.DEVICE_DISPLAY_NAME
Diese Konstante stellt den Anzeigenamen eines {3} dar.
"""
}
create_meta = common.format_simple_element_meta(
[('uid', 'String', 1, 'in'),
('ipcon', '.NET Refnum (IPConnection)', 1, 'in'),
(self.get_name().headless, '.NET Refnum ({0})'.format(
self.get_labview_class_name()), 1, 'out')],
parameter_label_override={
'en': 'Input',
'de': 'Eingabe'
},
return_label_override={
'en': 'Output',
'de': 'Ausgabe'
})
create_meta_table = common.make_rst_meta_table(create_meta)
cre = common.select_lang(create_str).format(
self.get_labview_class_name(),
self.get_name().headless, create_meta_table)
bf = self.get_labview_functions('bf')
af = self.get_labview_functions('af')
ccf = self.get_labview_functions('ccf')
c = self.get_labview_callbacks()
vf = self.get_labview_functions('vf')
if_ = self.get_labview_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format(cre, bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
if ccf:
api_str += common.select_lang(common.ccf_str).format('', ccf)
api_str += common.select_lang(c_str).format(
self.get_doc_rst_ref_name(), c)
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
article = 'ein'
if self.is_brick():
article = 'einen'
api_str += common.select_lang(const_str).format(
self.get_doc_rst_ref_name(), self.get_labview_class_name(),
article, self.get_long_display_name())
return common.select_lang(api).format(
self.get_doc_rst_ref_name(),
self.specialize_labview_doc_function_links(
common.select_lang(self.get_doc())), api_str)
def get_matlab_api(self):
create_str = {
'en':
"""
.. matlab:function:: class {0}(String uid, IPConnection ipcon)
{2}
Creates an object with the unique device ID ``uid``.
In MATLAB:
.. code-block:: matlab
import com.tinkerforge.{0};
{1} = {0}('YOUR_DEVICE_UID', ipcon);
In Octave:
.. code-block:: octave_fixed
{1} = java_new("com.tinkerforge.{0}", "YOUR_DEVICE_UID", ipcon);
This object can then be used after the IP Connection is connected.
""",
'de':
"""
.. matlab:function:: class {0}(String uid, IPConnection ipcon)
{2}
Erzeugt ein Objekt mit der eindeutigen Geräte ID ``uid``.
In MATLAB:
.. code-block:: matlab
import com.tinkerforge.{0};
{1} = {0}("YOUR_DEVICE_UID", ipcon);
In Octave:
.. code-block:: octave_fixed
{1} = java_new("com.tinkerforge.{0}", "YOUR_DEVICE_UID", ipcon);
Dieses Objekt kann benutzt werden, nachdem die IP Connection verbunden ist.
"""
}
ccf_str = {
'en':
"""
Callback Configuration Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
{0}
""",
'de':
"""
Konfigurationsfunktionen für Callbacks
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
{0}
"""
}
c_str = {
'en':
"""
.. _{0}_matlab_callbacks:
Callbacks
^^^^^^^^^
Callbacks can be registered to receive time critical or recurring data from
the device. The registration is done with "set" function of MATLAB. The
parameters consist of the IP Connection object, the callback name and the
callback function. For example, it looks like this in MATLAB:
.. code-block:: matlab
function my_callback(e)
fprintf('Parameter: %s\\n', e.param);
end
set(device, 'ExampleCallback', @(h, e) my_callback(e));
Due to a difference in the Octave Java support the "set" function cannot be
used in Octave. The registration is done with "add*Callback" functions of the
device object. It looks like this in Octave:
.. code-block:: octave_fixed
function my_callback(e)
fprintf("Parameter: %s\\n", e.param);
end
device.addExampleCallback(@my_callback);
It is possible to add several callbacks and to remove them with the
corresponding "remove*Callback" function.
The parameters of the callback are passed to the callback function as fields of
the structure ``e``, which is derived from the ``java.util.EventObject`` class.
The available callback names with corresponding structure fields are described
below.
.. note::
Using callbacks for recurring events is *always* preferred
compared to using getters. It will use less USB bandwidth and the latency
will be a lot better, since there is no round trip time.
{1}
""",
'de':
"""
.. _{0}_matlab_callbacks:
Callbacks
^^^^^^^^^
Callbacks können registriert werden um zeitkritische oder wiederkehrende
Daten vom Gerät zu erhalten. Die Registrierung wird mit MATLABs "set"
Funktion durchgeführt. Die Parameter sind ein Gerätobjekt, der Callback-Name
und die Callback-Funktion. Hier ein Beispiel in MATLAB:
.. code-block:: matlab
function my_callback(e)
fprintf('Parameter: %s\\n', e.param);
end
set(device, 'ExampleCallback', @(h, e) my_callback(e));
Die Octave Java Unterstützung unterscheidet sich hier von MATLAB, die "set"
Funktion kann hier nicht verwendet werden. Die Registrierung wird in Octave
mit "add*Callback" Funktionen des Gerätobjekts durchgeführt. Hier ein Beispiel
in Octave:
.. code-block:: octave_fixed
function my_callback(e)
fprintf("Parameter: %s\\n", e.param);
end
device.addExampleCallback(@my_callback);
Es ist möglich mehrere Callback-Funktion hinzuzufügen und auch mit einem
korrespondierenden "remove*Callback" wieder zu entfernen.
Die Parameter des Callbacks werden der Callback-Funktion als Felder der
Struktur ``e`` übergeben. Diese ist von der ``java.util.EventObject`` Klasse
abgeleitete. Die verfügbaren Callback-Namen mit den entsprechenden
Strukturfeldern werden unterhalb beschrieben.
.. note::
Callbacks für wiederkehrende Ereignisse zu verwenden ist
*immer* zu bevorzugen gegenüber der Verwendung von Abfragen.
Es wird weniger USB-Bandbreite benutzt und die Latenz ist
erheblich geringer, da es keine Paketumlaufzeit gibt.
{1}
"""
}
api = {
'en':
"""
.. _{0}_matlab_api:
API
---
Generally, every method of the MATLAB bindings that returns a value can
throw a ``TimeoutException``. This exception gets thrown if the
device did not respond. If a cable based connection is used, it is
unlikely that this exception gets thrown (assuming nobody unplugs the
device). However, if a wireless connection is used, timeouts will occur
if the distance to the device gets too big.
Beside the ``TimeoutException`` there is also a ``NotConnectedException`` that
is thrown if a method needs to communicate with the device while the
IP Connection is not connected.
Since the MATLAB bindings are based on Java and Java does not support multiple
return values and return by reference is not possible for primitive types, we
use small classes that only consist of member variables. The member variables
of the returned objects are described in the corresponding method descriptions.
The package for all Brick/Bricklet bindings and the IP Connection is
``com.tinkerforge.*``
All methods listed below are thread-safe.
{1}
{2}
""",
'de':
"""
.. _{0}_matlab_api:
API
---
Prinzipiell kann jede Methode der MATLAB Bindings eine ``TimeoutException``
werfen. Diese Exception wird
geworfen wenn das Gerät nicht antwortet. Wenn eine Kabelverbindung genutzt
wird, ist es unwahrscheinlich, dass die Exception geworfen wird (unter der
Annahme, dass das Gerät nicht abgesteckt wird). Bei einer drahtlosen Verbindung
können Zeitüberschreitungen auftreten, sobald die Entfernung zum Gerät zu
groß wird.
Neben der ``TimeoutException`` kann auch noch eine ``NotConnectedException``
geworfen werden, wenn versucht wird mit einem Brick oder Bricklet zu
kommunizieren, aber die IP Connection nicht verbunden ist.
Da die MATLAB Bindings auf Java basieren und Java nicht mehrere Rückgabewerte
unterstützt und eine Referenzrückgabe für elementare Type nicht möglich ist,
werden kleine Klassen verwendet, die nur aus Member-Variablen bestehen. Die
Member-Variablen des zurückgegebenen Objektes werden in der jeweiligen
Methodenbeschreibung erläutert.
Das Package für alle Brick/Bricklet Bindings und die IP Connection ist
``com.tinkerforge.*``
Alle folgend aufgelisteten Methoden sind Thread-sicher.
{1}
{2}
"""
}
const_str = {
'en':
"""
.. _{0}_matlab_constants:
Constants
^^^^^^^^^
.. matlab:member:: int {1}::DEVICE_IDENTIFIER
This constant is used to identify a {3}.
The :matlab:func:`getIdentity() <{1}::getIdentity>` function and the
:matlab:member:`IPConnection.EnumerateCallback <IPConnection::EnumerateCallback>`
callback of the IP Connection have a ``deviceIdentifier`` parameter to specify
the Brick's or Bricklet's type.
.. matlab:member:: String {1}::DEVICE_DISPLAY_NAME
This constant represents the human readable name of a {3}.
""",
'de':
"""
.. _{0}_matlab_constants:
Konstanten
^^^^^^^^^^
.. matlab:member:: int {1}::DEVICE_IDENTIFIER
Diese Konstante wird verwendet um {2} {3} zu identifizieren.
Die :matlab:func:`getIdentity() <{1}::getIdentity>` Funktion und der
:matlab:member:`IPConnection.EnumerateCallback <IPConnection::EnumerateCallback>`
Callback der IP Connection haben ein ``deviceIdentifier`` Parameter um den Typ
des Bricks oder Bricklets anzugeben.
.. matlab:member:: String {1}::DEVICE_DISPLAY_NAME
Diese Konstante stellt den Anzeigenamen eines {3} dar.
"""
}
create_meta = common.format_simple_element_meta([
('uid', 'String', 1, 'in'), ('ipcon', 'IPConnection', 1, 'in'),
(self.get_name().headless, self.get_matlab_class_name(), 1, 'out')
])
create_meta_table = common.make_rst_meta_table(
create_meta, index_format_func=lambda index: str(index + 1))
cre = common.select_lang(create_str).format(
self.get_matlab_class_name(),
self.get_name().headless, create_meta_table)
bf = self.get_matlab_functions('bf')
af = self.get_matlab_functions('af')
ccf = self.get_matlab_functions('ccf')
c = self.get_matlab_callbacks()
vf = self.get_matlab_functions('vf')
if_ = self.get_matlab_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format(cre, bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
if ccf:
api_str += common.select_lang(ccf_str).format(ccf)
api_str += common.select_lang(c_str).format(
self.get_doc_rst_ref_name(), c)
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
article = 'ein'
if self.is_brick():
article = 'einen'
api_str += common.select_lang(const_str).format(
self.get_doc_rst_ref_name(), self.get_matlab_class_name(), article,
self.get_long_display_name())
return common.select_lang(api).format(
self.get_doc_rst_ref_name(),
self.specialize_matlab_doc_function_links(
common.select_lang(self.get_doc())), api_str)
def get_csharp_api(self):
create_str = {
'en': """
.. csharp:function:: class {0}(string uid, IPConnection ipcon)
{2}
Creates an object with the unique device ID ``uid``:
.. code-block:: csharp
{0} {1} = new {0}("YOUR_DEVICE_UID", ipcon);
This object can then be used after the IP Connection is connected.
""",
'de': """
.. csharp:function:: class {0}(string uid, IPConnection ipcon)
{2}
Erzeugt ein Objekt mit der eindeutigen Geräte ID ``uid``:
.. code-block:: csharp
{0} {1} = new {0}("YOUR_DEVICE_UID", ipcon);
Dieses Objekt kann benutzt werden, nachdem die IP Connection verbunden ist.
"""
}
c_str = {
'en': """
.. _{0}_csharp_callbacks:
Callbacks
^^^^^^^^^
Callbacks can be registered to receive time critical or recurring data from
the device. The registration is done by appending your callback handler to
the corresponding event:
.. code-block:: csharp
void MyCallback({1} sender, int value)
{{
System.Console.WriteLine("Value: " + value);
}}
{2}.ExampleCallback += MyCallback;
The available events are described below.
.. note::
Using callbacks for recurring events is *always* preferred
compared to using getters. It will use less USB bandwidth and the latency
will be a lot better, since there is no round trip time.
{3}
""",
'de': """
.. _{0}_csharp_callbacks:
Callbacks
^^^^^^^^^
Callbacks können registriert werden um zeitkritische oder wiederkehrende Daten
vom Gerät zu erhalten. Die Registrierung geschieht durch Anhängen des Callback
Handlers an den passenden Event:
.. code-block:: csharp
void MyCallback({1} sender, int value)
{{
System.Console.WriteLine("Value: " + value);
}}
{2}.ExampleCallback += MyCallback;
Die verfügbaren Events werden weiter unten beschrieben.
.. note::
Callbacks für wiederkehrende Ereignisse zu verwenden ist
*immer* zu bevorzugen gegenüber der Verwendung von Abfragen.
Es wird weniger USB-Bandbreite benutzt und die Latenz ist
erheblich geringer, da es keine Paketumlaufzeit gibt.
{3}
"""
}
api = {
'en': """
.. _{0}_csharp_api:
API
---
Generally, every method of the C# bindings that returns a value can
throw a ``Tinkerforge.TimeoutException``. This exception gets thrown if the
device did not respond. If a cable based connection is used, it is
unlikely that this exception gets thrown (assuming nobody plugs the
device out). However, if a wireless connection is used, timeouts will occur
if the distance to the device gets too big.
Since C# does not support multiple return values directly, we use the ``out``
keyword to return multiple values from a method.
The namespace for all Brick/Bricklet bindings and the IPConnection is
``Tinkerforge.*``.
All methods listed below are thread-safe.
{1}
{2}
""",
'de': """
.. _{0}_csharp_api:
API
---
Prinzipiell kann jede Funktion der C# Bindings, welche einen Wert zurück gibt
eine ``Tinkerforge.TimeoutException`` werfen. Diese Exception wird
geworfen wenn das Gerät nicht antwortet. Wenn eine Kabelverbindung genutzt
wird, ist es unwahrscheinlich, dass die Exception geworfen wird (unter der
Annahme, dass das Gerät nicht abgesteckt wird). Bei einer drahtlosen Verbindung
können Zeitüberschreitungen auftreten, sobald die Entfernung zum Gerät zu
groß wird.
Da C# nicht mehrere Rückgabewerte direkt unterstützt, wird das ``out`` Schlüsselwort
genutzt, um mehrere Werte aus einer Funktion zurückzugeben.
Der Namensraum für alle Brick/Bricklet Bindings und die IPConnection ist
``Tinkerforge.*``.
Alle folgend aufgelisteten Methoden sind Thread-sicher.
{1}
{2}
"""
}
const_str = {
'en': """
.. _{0}_csharp_constants:
Constants
^^^^^^^^^
.. csharp:member:: int {1}::DEVICE_IDENTIFIER
This constant is used to identify a {3}.
The :csharp:func:`GetIdentity() <{1}::GetIdentity>` function and the
:csharp:func:`IPConnection.EnumerateCallback <IPConnection::EnumerateCallback>`
callback of the IP Connection have a ``deviceIdentifier`` parameter to specify
the Brick's or Bricklet's type.
.. csharp:member:: string {1}::DEVICE_DISPLAY_NAME
This constant represents the human readable name of a {3}.
""",
'de': """
.. _{0}_csharp_constants:
Konstanten
^^^^^^^^^^
.. csharp:member:: int {1}::DEVICE_IDENTIFIER
Diese Konstante wird verwendet um {2} {3} zu identifizieren.
Die :csharp:func:`GetIdentity() <{1}::GetIdentity>` Funktion und der
:csharp:func:`IPConnection.EnumerateCallback <IPConnection::EnumerateCallback>`
Callback der IP Connection haben ein ``deviceIdentifier`` Parameter um den Typ
des Bricks oder Bricklets anzugeben.
.. csharp:member:: string {1}::DEVICE_DISPLAY_NAME
Diese Konstante stellt den Anzeigenamen eines {3} dar.
"""
}
create_meta = common.format_simple_element_meta([('uid', 'string', 1, 'in'),
('ipcon', 'IPConnection', 1, 'in'),
(self.get_name().headless, self.get_csharp_class_name(), 1, 'out')])
create_meta_table = common.make_rst_meta_table(create_meta)
cre = common.select_lang(create_str).format(self.get_csharp_class_name(),
self.get_name().headless,
create_meta_table)
bf = self.get_csharp_functions('bf')
af = self.get_csharp_functions('af')
ccf = self.get_csharp_functions('ccf')
c = self.get_csharp_callbacks()
vf = self.get_csharp_functions('vf')
if_ = self.get_csharp_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format(cre, bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
if ccf:
api_str += common.select_lang(common.ccf_str).format('', ccf)
api_str += common.select_lang(c_str).format(self.get_doc_rst_ref_name(),
self.get_csharp_class_name(),
self.get_name().headless,
c)
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
article = 'ein'
if self.is_brick():
article = 'einen'
api_str += common.select_lang(const_str).format(self.get_doc_rst_ref_name(),
self.get_csharp_class_name(),
article,
self.get_long_display_name())
return common.select_lang(api).format(self.get_doc_rst_ref_name(),
self.specialize_csharp_doc_function_links(common.select_lang(self.get_doc())),
api_str)
def get_javascript_api(self):
create_str = {
'en': """
.. javascript:function:: new {0}(uid, ipcon)
{2}
Creates an object with the unique device ID ``uid``:
.. code-block:: javascript
var {1} = new {0}("YOUR_DEVICE_UID", ipcon);
This object can then be used after the IP Connection is connected.
""",
'de': """
.. javascript:function:: new {0}(uid, ipcon)
{2}
Erzeugt ein Objekt mit der eindeutigen Geräte ID ``uid``:
.. code-block:: javascript
var {1} = new {0}("YOUR_DEVICE_UID", ipcon)
Dieses Objekt kann benutzt werden, nachdem die IP Connection verbunden ist.
"""
}
register_str = {
'en': """
.. javascript:function:: {1}.on(callback_id, function[, errorCallback])
{2}
Registers the given ``function`` with the given ``callback_id``.
The available callback IDs with corresponding function signatures are
listed :ref:`below <{0}_javascript_callbacks>`.
""",
'de': """
.. javascript:function:: {1}.on(callback_id, function[, errorCallback])
{2}
Registriert die ``function`` für die gegebene ``callback_id``.
Die verfügbaren Callback IDs mit den zugehörigen Funktionssignaturen
sind :ref:`unten <{0}_javascript_callbacks>` zu finden.
"""
}
c_str = {
'en': """
.. _{0}_javascript_callbacks:
Callbacks
^^^^^^^^^
Callbacks can be registered to receive
time critical or recurring data from the device. The registration is done
with the :javascript:func:`on() <{1}.on>` function of
the device object. The first parameter is the callback ID and the second
parameter the callback function:
.. code-block:: javascript
{2}.on({1}.CALLBACK_EXAMPLE,
function (param) {{
console.log(param);
}}
);
The available constants with inherent number and type of parameters are
described below.
.. note::
Using callbacks for recurring events is *always* preferred
compared to using getters. It will use less USB bandwidth and the latency
will be a lot better, since there is no round trip time.
{3}
""",
'de': """
.. _{0}_javascript_callbacks:
Callbacks
^^^^^^^^^
Callbacks können registriert werden um zeitkritische
oder wiederkehrende Daten vom Gerät zu erhalten. Die Registrierung kann
mit der Funktion :javascript:func:`on() <{1}.on>` des
Geräte Objektes durchgeführt werden. Der erste Parameter ist die Callback ID
und der zweite Parameter die Callback-Funktion:
.. code-block:: javascript
{2}.on({1}.CALLBACK_EXAMPLE,
function (param) {{
console.log(param);
}}
);
Die verfügbaren IDs mit der dazugehörigen Parameteranzahl und -typen werden
weiter unten beschrieben.
.. note::
Callbacks für wiederkehrende Ereignisse zu verwenden ist
*immer* zu bevorzugen gegenüber der Verwendung von Abfragen.
Es wird weniger USB-Bandbreite benutzt und die Latenz ist
erheblich geringer, da es keine Paketumlaufzeit gibt.
{3}
"""
}
api = {
'en': """
.. _{0}_javascript_api:
API
---
Generally, every function of the JavaScript bindings can take two optional
parameters, ``returnCallback`` and ``errorCallback``. These are two user
defined callback functions. The ``returnCallback`` function is called with the
results as arguments, if the function returns its results asynchronously. The
``errorCallback`` is called with an error code in case of an error. The error
code can be one of the following values:
* IPConnection.\\ **ERROR**\\ _ALREADY_CONNECTED = 11
* IPConnection.\\ **ERROR**\\ _NOT_CONNECTED = 12
* IPConnection.\\ **ERROR**\\ _CONNECT_FAILED = 13
* IPConnection.\\ **ERROR**\\ _INVALID_FUNCTION_ID = 21
* IPConnection.\\ **ERROR**\\ _TIMEOUT = 31
* IPConnection.\\ **ERROR**\\ _INVALID_PARAMETER = 41
* IPConnection.\\ **ERROR**\\ _FUNCTION_NOT_SUPPORTED = 42
* IPConnection.\\ **ERROR**\\ _UNKNOWN_ERROR = 43
* IPConnection.\\ **ERROR**\\ _STREAM_OUT_OF_SYNC = 51
* IPConnection.\\ **ERROR**\\ _NON_ASCII_CHAR_IN_SECRET = 71
* IPConnection.\\ **ERROR**\\ _WRONG_DEVICE_TYPE = 81
* IPConnection.\\ **ERROR**\\ _DEVICE_REPLACED = 82
* IPConnection.\\ **ERROR**\\ _WRONG_RESPONSE_LENGTH = 83
* IPConnection.\\ **ERROR**\\ _INT64_NOT_SUPPORTED = 91
The namespace for the JavaScript bindings is ``Tinkerforge.*``.
{1}
{2}
""",
'de': """
.. _{0}_javascript_api:
API
---
Allgemein kann jede Funktion der JavaScript Bindings zwei optionale Parameter
haben, ``returnCallback`` und ``errorCallback``. Dies sind benutzerdefinierte
Callback-Funktionen. Die ``returnCallback``-Funktion wird mit dem Ergebnissen
der Funktion als Argumente aufgerufen, falls die Funktion ihre
Ergebnisse asynchron zurückgibt. Die ``errorCallback``-Funktion wird im
Fehlerfall mit einem Fehlercode aufgerufen. Der Fehlercode kann einer der
folgenden Werte sein:
* IPConnection.\\ **ERROR**\\ _ALREADY_CONNECTED = 11
* IPConnection.\\ **ERROR**\\ _NOT_CONNECTED = 12
* IPConnection.\\ **ERROR**\\ _CONNECT_FAILED = 13
* IPConnection.\\ **ERROR**\\ _INVALID_FUNCTION_ID = 21
* IPConnection.\\ **ERROR**\\ _TIMEOUT = 31
* IPConnection.\\ **ERROR**\\ _INVALID_PARAMETER = 41
* IPConnection.\\ **ERROR**\\ _FUNCTION_NOT_SUPPORTED = 42
* IPConnection.\\ **ERROR**\\ _UNKNOWN_ERROR = 43
* IPConnection.\\ **ERROR**\\ _STREAM_OUT_OF_SYNC = 51
* IPConnection.\\ **ERROR**\\ _NON_ASCII_CHAR_IN_SECRET = 71
* IPConnection.\\ **ERROR**\\ _WRONG_DEVICE_TYPE = 81
* IPConnection.\\ **ERROR**\\ _DEVICE_REPLACED = 82
* IPConnection.\\ **ERROR**\\ _WRONG_RESPONSE_LENGTH = 83
* IPConnection.\\ **ERROR**\\ _INT64_NOT_SUPPORTED = 91
Der Namespace der JavaScript Bindings ist ``Tinkerforge.*``.
{1}
{2}
"""
}
const_str = {
'en': """
.. _{0}_javascript_constants:
Constants
^^^^^^^^^
.. javascript:attribute:: {1}.DEVICE_IDENTIFIER
This constant is used to identify a {3}.
The :javascript:func:`getIdentity() <{1}.getIdentity>` function and the
:javascript:attr:`IPConnection.CALLBACK_ENUMERATE <IPConnection.CALLBACK_ENUMERATE>`
callback of the IP Connection have a ``device_identifier`` parameter to specify
the Brick's or Bricklet's type.
.. javascript:attribute:: {1}.DEVICE_DISPLAY_NAME
This constant represents the human readable name of a {3}.
""",
'de': """
.. _{0}_javascript_constants:
Konstanten
^^^^^^^^^^
.. javascript:attribute:: {1}.DEVICE_IDENTIFIER
Diese Konstante wird verwendet um {2} {3} zu identifizieren.
Die :javascript:func:`getIdentity() <{1}.getIdentity>` Funktion und der
:javascript:attr:`IPConnection.CALLBACK_ENUMERATE <IPConnection.CALLBACK_ENUMERATE>`
Callback der IP Connection haben ein ``device_identifier`` Parameter um den Typ
des Bricks oder Bricklets anzugeben.
.. javascript:attribute:: {1}.DEVICE_DISPLAY_NAME
Diese Konstante stellt den Anzeigenamen eines {3} dar.
"""
}
create_meta = common.format_simple_element_meta([('uid', 'string', 1, 'in'),
('ipcon', 'IPConnection', 1, 'in'),
(self.get_name().headless, self.get_javascript_class_name(), 1, 'out')])
create_meta_table = common.make_rst_meta_table(create_meta)
cre = common.select_lang(create_str).format(self.get_javascript_class_name(),
self.get_name().headless,
create_meta_table)
reg_meta = common.format_simple_element_meta([('callback_id', 'int', 1, 'in'),
('function', 'function', 1, 'in')],
no_out_value={'en': 'undefined', 'de': 'undefined'})
reg_meta_table = common.make_rst_meta_table(reg_meta)
reg = common.select_lang(register_str).format(self.get_doc_rst_ref_name(),
self.get_javascript_class_name(),
reg_meta_table)
bf = self.get_javascript_functions('bf')
af = self.get_javascript_functions('af')
ccf = self.get_javascript_functions('ccf')
c = self.get_javascript_callbacks()
vf = self.get_javascript_functions('vf')
if_ = self.get_javascript_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format(cre, bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
api_str += common.select_lang(common.ccf_str).format(reg, ccf)
api_str += common.select_lang(c_str).format(self.get_doc_rst_ref_name(),
self.get_javascript_class_name(),
self.get_name().headless,
c)
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
article = 'ein'
if self.is_brick():
article = 'einen'
api_str += common.select_lang(const_str).format(self.get_doc_rst_ref_name(),
self.get_javascript_class_name(),
article,
self.get_long_display_name())
return common.select_lang(api).format(self.get_doc_rst_ref_name(),
self.specialize_javascript_doc_function_links(common.select_lang(self.get_doc())),
api_str)
def get_ruby_api(self):
create_str = {
'en':
"""
.. rb:function:: {0}::new(uid, ipcon) -> {1}
{2}
Creates an object with the unique device ID ``uid``:
.. code-block:: ruby
{1} = {0}.new 'YOUR_DEVICE_UID', ipcon
This object can then be used after the IP Connection is connected.
""",
'de':
"""
.. rb:function:: {0}::new(uid, ipcon) -> {1}
{2}
Erzeugt ein Objekt mit der eindeutigen Geräte ID ``uid``:
.. code-block:: ruby
{1} = {0}.new 'YOUR_DEVICE_UID', ipcon
Dieses Objekt kann benutzt werden, nachdem die IP Connection verbunden ist.
"""
}
register_str = {
'en':
"""
.. rb:function:: {1}#register_callback(callback_id) {{ |param [, ...]| block }} -> nil
{2}
Registers the given ``block`` with the given ``callback_id``.
The available callback IDs with corresponding function signatures are listed
:ref:`below <{0}_ruby_callbacks>`.
""",
'de':
"""
.. rb:function:: {1}#register_callback(callback_id) {{ |param [, ...]| block }} -> nil
{2}
Registriert den ``block`` für die gegebene ``callback_id``.
Die verfügbaren Callback IDs mit den zugehörigen Funktionssignaturen sind
:ref:`unten <{0}_ruby_callbacks>` zu finden.
"""
}
c_str = {
'en':
"""
.. _{0}_ruby_callbacks:
Callbacks
^^^^^^^^^
Callbacks can be registered to receive time critical or recurring data from
the device. The registration is done with the
:rb:func:`#register_callback <{1}#register_callback>` function of
the device object. The first parameter is the callback ID and the second
parameter is a block:
.. code-block:: ruby
{2}.register_callback {1}::CALLBACK_EXAMPLE, do |param|
puts "#{{param}}"
end
The available constants with inherent number and type of parameters are
described below.
.. note::
Using callbacks for recurring events is *always* preferred
compared to using getters. It will use less USB bandwidth and the latency
will be a lot better, since there is no round trip time.
{3}
""",
'de':
"""
.. _{0}_ruby_callbacks:
Callbacks
^^^^^^^^^
Callbacks können registriert werden um zeitkritische
oder wiederkehrende Daten vom Gerät zu erhalten. Die Registrierung kann
mit der Funktion :rb:func:`#register_callback <{1}#register_callback>` des
Geräte Objektes durchgeführt werden. Der erste Parameter ist der Callback ID
und der zweite Parameter der Block:
.. code-block:: ruby
{2}.register_callback {1}::CALLBACK_EXAMPLE, do |param|
puts "#{{param}}"
end
Die verfügbaren IDs mit der dazugehörigen Parameteranzahl und -typen werden
weiter unten beschrieben.
.. note::
Callbacks für wiederkehrende Ereignisse zu verwenden ist
*immer* zu bevorzugen gegenüber der Verwendung von Abfragen.
Es wird weniger USB-Bandbreite benutzt und die Latenz ist
erheblich geringer, da es keine Paketumlaufzeit gibt.
{3}
"""
}
api = {
'en':
"""
.. _{0}_ruby_api:
API
---
All functions listed below are thread-safe.
{1}
{2}
""",
'de':
"""
.. _{0}_ruby_api:
API
---
Alle folgend aufgelisteten Funktionen sind Thread-sicher.
{1}
{2}
"""
}
const_str = {
'en':
"""
.. _{0}_ruby_constants:
Constants
^^^^^^^^^
.. rb:attribute:: {1}::DEVICE_IDENTIFIER
This constant is used to identify a {3}.
The :rb:func:`#get_identity() <{1}#get_identity>` function and the
:rb:attr:`IPConnection::CALLBACK_ENUMERATE <IPConnection::CALLBACK_ENUMERATE>`
callback of the IP Connection have a ``device_identifier`` parameter to specify
the Brick's or Bricklet's type.
.. rb:attribute:: {1}::DEVICE_DISPLAY_NAME
This constant represents the human readable name of a {3}.
""",
'de':
"""
.. _{0}_ruby_constants:
Konstanten
^^^^^^^^^^
.. rb:attribute:: {1}::DEVICE_IDENTIFIER
Diese Konstante wird verwendet um {2} {3} zu identifizieren.
Die :rb:func:`#get_identity() <{1}#get_identity>` Funktion und der
:rb:attr:`IPConnection::CALLBACK_ENUMERATE <IPConnection::CALLBACK_ENUMERATE>`
Callback der IP Connection haben ein ``device_identifier`` Parameter um den Typ
des Bricks oder Bricklets anzugeben.
.. rb:attribute:: {1}::DEVICE_DISPLAY_NAME
Diese Konstante stellt den Anzeigenamen eines {3} dar.
"""
}
create_meta = common.format_simple_element_meta([
('uid', 'str', 1, 'in'), ('ipcon', 'IPConnection', 1, 'in'),
(self.get_name().under, self.get_ruby_class_name(), 1, 'out')
])
create_meta_table = common.make_rst_meta_table(create_meta)
cre = common.select_lang(create_str).format(self.get_ruby_class_name(),
self.get_name().under,
create_meta_table)
reg_meta = common.format_simple_element_meta([('callback_id', 'int', 1,
'in')])
reg_meta_table = common.make_rst_meta_table(reg_meta)
reg = common.select_lang(register_str).format(
self.get_doc_rst_ref_name(), self.get_ruby_class_name(),
reg_meta_table)
bf = self.get_ruby_functions('bf')
af = self.get_ruby_functions('af')
ccf = self.get_ruby_functions('ccf')
c = self.get_ruby_callbacks()
vf = self.get_ruby_functions('vf')
if_ = self.get_ruby_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format(cre, bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
api_str += common.select_lang(common.ccf_str).format(reg, ccf)
api_str += common.select_lang(c_str).format(
self.get_doc_rst_ref_name(), self.get_ruby_class_name(),
self.get_name().under, c)
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
article = 'ein'
if self.is_brick():
article = 'einen'
api_str += common.select_lang(const_str).format(
self.get_doc_rst_ref_name(), self.get_ruby_class_name(), article,
self.get_long_display_name())
return common.select_lang(api).format(
self.get_doc_rst_ref_name(),
self.specialize_ruby_doc_function_links(
common.select_lang(self.get_doc())), api_str)
def get_mathematica_api(self):
create_str = {
'en':
"""
.. mathematica:function:: {0}[uid, ipcon] -> {1}
{2}
Creates an object with the unique device ID ``uid``:
.. code-block:: mathematica
{1}=NETNew["Tinkerforge.{0}","YOUR_DEVICE_UID",ipcon]
This object can then be used after the IP Connection is connected.
The .NET runtime has built-in garbage collection that frees objects that are
no longer in use by a program. But because Mathematica can not automatically
tell when a Mathematica "program" doesn't use a .NET object anymore, this has
to be done by the program. For this the `ReleaseNETObject[]
<https://reference.wolfram.com/language/NETLink/ref/ReleaseNETObject.html>`__
function is used in the examples.
For further information about object management in .NET/Link see the
corresponding Mathematica `.NET/Link documentation
<https://reference.wolfram.com/language/NETLink/tutorial/CallingNETFromTheWolframLanguage.html#14400>`__.
""",
'de':
"""
.. mathematica:function:: {0}[uid, ipcon] -> {1}
{2}
Erzeugt ein Objekt mit der eindeutigen Geräte ID ``uid``:
.. code-block:: mathematica
{1}=NETNew["Tinkerforge.{0}","YOUR_DEVICE_UID",ipcon]
Dieses Objekt kann benutzt werden, nachdem die IP Connection verbunden ist.
Die .NET Runtime hat eingebauten Garbage Collection welche Objekte wieder
freigibt, wenn sie vom Programm nicht mehr verwendet werden. Da Mathematica
aber selbst nicht automatisch feststellen kann, wann ein Mathematica "Programm"
ein .NET Objekt nicht mehr verwendet, muss sich das Programm selbst darum
kümmern. Für diesen Zweck wird die `ReleaseNETObject[]
<https://reference.wolfram.com/language/NETLink/ref/ReleaseNETObject.html>`__
Funktion in den Beispielen verwendet.
Weitere Informationen über Objekt-Verwaltung mittels .NET/Link sind in der
entsprechende Mathematica `.NET/Link Dokumentation
<https://reference.wolfram.com/language/NETLink/tutorial/CallingNETFromTheWolframLanguage.html#14400>`__
zu finden.
"""
}
c_str = {
'en':
"""
.. _{0}_mathematica_callbacks:
Callbacks
^^^^^^^^^
Callbacks can be registered to receive time critical or recurring data from
the device. The registration is done by assigning a function to a callback
property of the device object:
.. code-block:: mathematica
MyCallback[sender_,value_]:=Print["Value: "<>ToString[value]]
AddEventHandler[{1}@ExampleCallback,MyCallback]
For further information about event handling using .NET/Link see the
corresponding Mathematica `.NET/Link documentation
<https://reference.wolfram.com/language/NETLink/tutorial/CallingNETFromTheWolframLanguage.html#17034>`__.
The available callback property and their type of parameters are described below.
.. note::
Using callbacks for recurring events is *always* preferred
compared to using getters. It will use less USB bandwidth and the latency
will be a lot better, since there is no round trip time.
{2}
""",
'de':
"""
.. _{0}_mathematica_callbacks:
Callbacks
^^^^^^^^^
Callbacks können registriert werden um zeitkritische oder
wiederkehrende Daten vom Gerät zu erhalten. Die Registrierung erfolgt indem
eine Funktion einem Callback Property des Geräte Objektes zugewiesen wird:
.. code-block:: mathematica
MyCallback[sender_,value_]:=Print["Value: "<>ToString[value]]
AddEventHandler[{1}@ExampleCallback,MyCallback]
Weitere Informationen über Event-Behandlung mittels .NET/Link sind in der
entsprechende Mathematica `.NET/Link Dokumentation
<https://reference.wolfram.com/language/NETLink/tutorial/CallingNETFromTheWolframLanguage.html#17034>`__
zu finden.
Die verfügbaren Callback Properties und ihre Parametertypen werden weiter
unten beschrieben.
.. note::
Callbacks für wiederkehrende Ereignisse zu verwenden ist
*immer* zu bevorzugen gegenüber der Verwendung von Abfragen.
Es wird weniger USB-Bandbreite benutzt und die Latenz ist
erheblich geringer, da es keine Paketumlaufzeit gibt.
{2}
"""
}
api = {
'en':
"""
.. _{0}_mathematica_api:
API
---
Generally, every function of the Mathematica bindings that returns a value can
throw a ``Tinkerforge.TimeoutException``. This exception gets thrown if the
device did not respond. If a cable based connection is used, it is
unlikely that this exception gets thrown (assuming nobody plugs the
device out). However, if a wireless connection is used, timeouts will occur
if the distance to the device gets too big.
Since .NET/Link does not support multiple return values directly, we use the
``out`` keyword to return multiple values from a function. For further
information about the ``out`` keyword in .NET/Link see the corresponding
Mathematica `.NET/Link documentation
<https://reference.wolfram.com/language/NETLink/tutorial/CallingNETFromTheWolframLanguage.html#15993>`__.
The namespace for all Brick/Bricklet bindings and the IPConnection is
``Tinkerforge.*``.
{1}
{2}
""",
'de':
"""
.. _{0}_mathematica_api:
API
---
Prinzipiell kann jede Funktion der Mathematica Bindings, welche einen Wert zurück gibt
eine ``Tinkerforge.TimeoutException`` werfen. Diese Exception wird
geworfen wenn das Gerät nicht antwortet. Wenn eine Kabelverbindung genutzt
wird, ist es unwahrscheinlich, dass die Exception geworfen wird (unter der
Annahme, dass das Gerät nicht abgesteckt wird). Bei einer drahtlosen Verbindung
können Zeitüberschreitungen auftreten, sobald die Entfernung zum Gerät zu
groß wird.
Da .NET/Link nicht mehrere Rückgabewerte direkt unterstützt, wird das ``out``
Schlüsselwort genutzt, um mehrere Werte aus einer Funktion zurückzugeben.
Weitere Informationen über das ``out`` Schlüsselwort in .NET/Link sind in der
entsprechende Mathematica `.NET/Link Dokumentation
<https://reference.wolfram.com/language/NETLink/tutorial/CallingNETFromTheWolframLanguage.html#15993>`__
zu finden.
Der Namensraum für alle Brick/Bricklet Bindings und die IPConnection ist
``Tinkerforge.*``.
{1}
{2}
"""
}
const_str = {
'en':
"""
.. _{0}_mathematica_constants:
Constants
^^^^^^^^^
.. mathematica:symbol:: {1}`DEVICEUIDENTIFIER
This constant is used to identify a {3}.
The :mathematica:func:`GetIdentity[] <{1}@GetIdentity>` function and the
:mathematica:func:`IPConnection@EnumerateCallback <IPConnection@EnumerateCallback>`
callback of the IP Connection have a ``deviceIdentifier`` parameter to specify
the Brick's or Bricklet's type.
.. mathematica:symbol:: {1}`DEVICEDISPLAYNAME
This constant represents the human readable name of a {3}.
""",
'de':
"""
.. _{0}_mathematica_constants:
Konstanten
^^^^^^^^^^
.. mathematica:symbol:: {1}`DEVICEUIDENTIFIER
Diese Konstante wird verwendet um {2} {3} zu identifizieren.
Die :mathematica:func:`GetIdentity[] <{1}@GetIdentity>` Funktion und der
:mathematica:func:`IPConnection@EnumerateCallback <IPConnection@EnumerateCallback>`
Callback der IP Connection haben ein ``deviceIdentifier`` Parameter um den Typ
des Bricks oder Bricklets anzugeben.
.. mathematica:symbol:: {1}`DEVICEDISPLAYNAME
Diese Konstante stellt den Anzeigenamen eines {3} dar.
"""
}
create_meta = common.format_simple_element_meta([
('uid', 'String', 1, 'in'),
('ipcon', 'NETObject[IPConnection]', 1, 'in'),
(self.get_name().headless,
'NETObject[{0}]'.format(self.get_mathematica_class_name()), 1,
'out')
])
create_meta_table = common.make_rst_meta_table(
create_meta, index_format_func=lambda index: str(index + 1))
cre = common.select_lang(create_str).format(
self.get_mathematica_class_name(),
self.get_name().headless, create_meta_table)
bf = self.get_mathematica_functions('bf')
af = self.get_mathematica_functions('af')
ccf = self.get_mathematica_functions('ccf')
c = self.get_mathematica_callbacks()
vf = self.get_mathematica_functions('vf')
if_ = self.get_mathematica_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format(cre, bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
if ccf:
api_str += common.select_lang(common.ccf_str).format('', ccf)
api_str += common.select_lang(c_str).format(
self.get_doc_rst_ref_name(),
self.get_name().headless, c)
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
article = 'ein'
if self.is_brick():
article = 'einen'
api_str += common.select_lang(const_str).format(
self.get_doc_rst_ref_name(), self.get_mathematica_class_name(),
article, self.get_long_display_name())
return common.select_lang(api).format(
self.get_doc_rst_ref_name(),
self.specialize_mathematica_doc_function_links(
common.select_lang(self.get_doc())), api_str)
def get_php_api(self):
create_str = {
'en':
"""
.. php:function:: class {0}(string $uid, IPConnection $ipcon)
{2}
Creates an object with the unique device ID ``$uid``:
.. code-block:: php
<?php ${1} = new {0}('YOUR_DEVICE_UID', $ipcon); ?>
This object can then be used after the IP Connection is connected.
""",
'de':
"""
.. php:function:: class {0}(string $uid, IPConnection $ipcon)
{2}
Erzeugt ein Objekt mit der eindeutigen Geräte ID ``$uid``:
.. code-block:: php
<?php ${1} = new {0}('YOUR_DEVICE_UID', $ipcon); ?>
Dieses Objekt kann benutzt werden, nachdem die IP Connection verbunden ist.
"""
}
register_str = {
'en':
"""
.. php:function:: void {1}::registerCallback(int $callback_id, callable $callback, mixed $user_data = NULL)
{2}
Registers the given ``$function`` with the given ``$callback_id``. The optional
``$user_data`` will be passed as the last parameter to the function.
The available callback IDs with corresponding function signatures are listed
:ref:`below <{0}_php_callbacks>`.
""",
'de':
"""
.. php:function:: void {1}::registerCallback(int $callback_id, callable $callback, mixed $user_data = NULL)
{2}
Registriert die ``$function`` für die gegebene ``$callback_id``. Die optionalen
``$user_data`` werden der Funktion als letztes Parameter mit übergeben.
Die verfügbaren Callback IDs mit den zugehörigen Funktionssignaturen sind
:ref:`unten <{0}_php_callbacks>` zu finden.
"""
}
c_str = {
'en':
"""
.. _{0}_php_callbacks:
Callbacks
^^^^^^^^^
Callbacks can be registered to receive
time critical or recurring data from the device. The registration is done
with the :php:func:`registerCallback() <{1}::registerCallback>` function of
the device object. The first parameter is the callback ID and the second
parameter the callback function:
.. code-block:: php
<?php
function myCallback($param)
{{
echo $param . "\\n";
}}
${2}->registerCallback({1}::CALLBACK_EXAMPLE, 'myCallback');
?>
The available constants with corresponding function signatures are
described below.
.. note::
Using callbacks for recurring events is *always* preferred
compared to using getters. It will use less USB bandwidth and the latency
will be a lot better, since there is no round trip time.
{3}
""",
'de':
"""
.. _{0}_php_callbacks:
Callbacks
^^^^^^^^^
Callbacks können registriert werden um zeitkritische
oder wiederkehrende Daten vom Gerät zu erhalten. Die Registrierung kann
mit der Funktion :php:func:`registerCallback() <{1}::registerCallback>` des
Geräte Objektes durchgeführt werden. Der erste Parameter ist der Callback ID
und der zweite die Callback-Funktion:
.. code-block:: php
<?php
function myCallback($param)
{{
echo $param . "\\n";
}}
${2}->registerCallback({1}::CALLBACK_EXAMPLE, 'myCallback');
?>
Die verfügbaren IDs mit den dazugehörigen Funktionssignaturen werden
weiter unten beschrieben.
.. note::
Callbacks für wiederkehrende Ereignisse zu verwenden ist
*immer* zu bevorzugen gegenüber der Verwendung von Abfragen.
Es wird weniger USB-Bandbreite benutzt und die Latenz ist
erheblich geringer, da es keine Paketumlaufzeit gibt.
{3}
"""
}
api = {
'en':
"""
.. _{0}_php_api:
API
---
Functions that return multiple values return them in an associative array.
{1}
{2}
""",
'de':
"""
.. _{0}_php_api:
API
---
Funktion die mehrere Werte zurückgeben geben diese in einem assoziativen Array
zurück.
{1}
{2}
"""
}
const_str = {
'en':
"""
.. _{0}_php_constants:
Constants
^^^^^^^^^
.. php:member:: int {1}::DEVICE_IDENTIFIER
This constant is used to identify a {3}.
The :php:func:`getIdentity() <{1}::getIdentity>` function and the
:php:member:`IPConnection::CALLBACK_ENUMERATE <IPConnection::CALLBACK_ENUMERATE>`
callback of the IP Connection have a ``deviceIdentifier`` parameter to specify
the Brick's or Bricklet's type.
.. php:member:: string {1}::DEVICE_DISPLAY_NAME
This constant represents the human readable name of a {3}.
""",
'de':
"""
.. _{0}_php_constants:
Konstanten
^^^^^^^^^^
.. php:member:: int {1}::DEVICE_IDENTIFIER
Diese Konstante wird verwendet um {2} {3} zu identifizieren.
Die :php:func:`getIdentity() <{1}::getIdentity>` Funktion und der
:php:func:`IPConnection::CALLBACK_ENUMERATE <IPConnection::CALLBACK_ENUMERATE>`
Callback der IP Connection haben ein ``deviceIdentifier`` Parameter um den Typ
des Bricks oder Bricklets anzugeben.
.. php:member:: string {1}::DEVICE_DISPLAY_NAME
Diese Konstante stellt den Anzeigenamen eines {3} dar.
"""
}
create_meta = common.format_simple_element_meta([
('$uid', 'string', 1, 'in'), ('$ipcon', 'IPConnection', 1, 'in'),
('$' + self.get_name().under, self.get_php_class_name(), 1, 'out')
])
create_meta_table = common.make_rst_meta_table(create_meta)
cre = common.select_lang(create_str).format(self.get_php_class_name(),
self.get_name().under,
create_meta_table)
reg_meta = common.format_simple_element_meta([
('$callback_id', 'int', 1, 'in'), ('$callback', 'callable', 1,
'in'),
('$user_data', 'mixed', 1, 'in')
])
red_meta_table = common.make_rst_meta_table(reg_meta)
reg = common.select_lang(register_str).format(
self.get_doc_rst_ref_name(), self.get_php_class_name(),
red_meta_table)
bf = self.get_php_functions('bf')
af = self.get_php_functions('af')
ccf = self.get_php_functions('ccf')
c = self.get_php_callbacks()
vf = self.get_php_functions('vf')
if_ = self.get_php_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format(cre, bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
api_str += common.select_lang(common.ccf_str).format(reg, ccf)
api_str += common.select_lang(c_str).format(
self.get_doc_rst_ref_name(), self.get_php_class_name(),
self.get_name().under, c)
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
article = 'ein'
if self.is_brick():
article = 'einen'
api_str += common.select_lang(const_str).format(
self.get_doc_rst_ref_name(), self.get_php_class_name(), article,
self.get_long_display_name())
return common.select_lang(api).format(
self.get_doc_rst_ref_name(),
self.specialize_php_doc_function_links(
common.select_lang(self.get_doc())), api_str)
def get_go_api(self):
create_str = {
'en':
"""
.. go:function:: func {device_name_under}.New{device_name_camel}(uid string, ipcon *IPConnection) (device {device_name_camel}, err error)
{meta}
Creates a new ``{device_name_camel}`` object with the unique device ID ``uid`` and adds
it to the IPConnection ``ipcon``:
.. code-block:: go
device, err := {device_name_under}.New("YOUR_DEVICE_UID", &ipcon)
This device object can be used after the IPConnection has been connected.
""",
'de':
"""
.. go:function:: func {device_name_under}.New{device_name_camel}(uid string, ipcon *IPConnection) (device {device_name_camel}, err error)
{meta}
Erzeugt ein neues ``{device_name_camel}``-Objekt mit der eindeutigen Geräte ID ``uid`` und
fügt es der IPConnection ``ipcon`` hinzu:
.. code-block:: go
device, err := {device_name_under}.New("YOUR_DEVICE_UID", &ipcon)
Dieses Geräteobjekt kann benutzt werden, nachdem die IPConnection verbunden.
"""
}
c_str = {
'en':
"""
.. _{0}_go_callbacks:
Callbacks
^^^^^^^^^
Callbacks can be registered to receive
time critical or recurring data from the device. The registration is done
with the corresponding ``Register*Callback`` function, which returns a unique callback ID.
This ID can be used to deregister the callback later with the corresponding ``Deregister*Callback``
function.
.. note::
Using callbacks for recurring events is *always* preferred
compared to using getters. It will use less USB bandwidth and the latency
will be a lot better, since there is no round trip time.
{3}
""",
'de':
"""
.. _{0}_go_callbacks:
Callbacks
^^^^^^^^^
Callbacks können registriert werden um zeitkritische
oder wiederkehrende Daten vom Gerät zu erhalten. Die Registrierung kann
mit der entsprechenden ``Register*Callback``-Function durchgeführt werden,
welche eine eindeutige Callback-ID zurück gibt. Mit dieser ID kann das Callback
später deregistriert werden.
.. note::
Callbacks für wiederkehrende Ereignisse zu verwenden ist
*immer* zu bevorzugen gegenüber der Verwendung von Abfragen.
Es wird weniger USB-Bandbreite benutzt und die Latenz ist
erheblich geringer, da es keine Paketumlaufzeit gibt.
{3}
"""
}
api = {
'en':
"""
.. _{0}_go_api:
API
---
The {device_name_display} API is defined in the package ``github.com/Tinkerforge/go-api-bindings/{device_name_under}``
Nearly every function of the Go bindings can return an
``ipconnection.DeviceError``, implementing the error interface. The error can have one of the following values:
* ipconnection.\\ **DeviceError**\\ Success = 0
* ipconnection.\\ **DeviceError**\\ InvalidParameter = 1
* ipconnection.\\ **DeviceError**\\ FunctionNotSupported = 2
* ipconnection.\\ **DeviceError**\\ UnknownError = 3
which correspond to the values returned from Bricks and Bricklets.
All functions listed below are thread-safe.
{1}
{2}
""",
'de':
"""
.. _{0}_go_api:
API
---
Die API des {device_name_display} ist im Package ``github.com/Tinkerforge/go-api-bindings/{device_name_under}`` definiert.
Fast alle Funktionen der Go Bindings können einen ``ipconnection.DeviceError``, der das error-Interface implementiert,
zurückgeben. Dieser kann folgende Werte annehmen:
* ipconnection.\\ **DeviceError**\\ Success = 0
* ipconnection.\\ **DeviceError**\\ InvalidParameter = 1
* ipconnection.\\ **DeviceError**\\ FunctionNotSupported = 2
* ipconnection.\\ **DeviceError**\\ UnknownError = 3
welche den Werten entsprechen, die der Brick oder das Bricklet zurückgeben.
Alle folgend aufgelisteten Funktionen sind Thread-sicher.
{1}
{2}
"""
}
const_str = {
'en':
"""
.. _{device_name_ref}_go_constants:
Constants
^^^^^^^^^
.. go:constant:: {device_name_under}.DeviceIdentifier
This constant is used to identify a {device_name_display}.
The :go:func:`GetIdentity() <(*{device_name_camel}) GetIdentity>` function and
the :go:func:`(*IPConnection) RegisterEnumerateCallback`
callback of the IPConnection have a ``deviceIdentifier`` parameter to specify
the Brick's or Bricklet's type.
.. go:constant:: {device_name_under}.DeviceDisplayName
This constant represents the human readable name of a {device_name_display}.
""",
'de':
"""
.. _{device_name_ref}_go_constants:
Konstanten
^^^^^^^^^^
.. go:constant:: {device_name_under}.DeviceIdentifier
Diese Konstante wird verwendet um {article} {device_name_display} zu identifizieren.
Die :go:func:`GetIdentity() <(*{device_name_camel}) GetIdentity>` Funktion und
der :go:func:`(*IPConnection) RegisterEnumerateCallback`
Callback der IPConnection haben ein ``deviceIdentifier`` Parameter um den Typ
des Bricks oder Bricklets anzugeben.
.. go:constant:: {device_name_under}.DeviceDisplayName
Diese Konstante stellt den Anzeigenamen eines {device_name_display} dar.
"""
}
create_meta = common.format_simple_element_meta([
('uid', 'string', 1, 'in'), ('ipcon', '*IPConnection', 1, 'in'),
('device', self.get_go_name(), 1, 'out'),
('err', 'error', 1, 'out')
])
create_meta_table = common.make_rst_meta_table(create_meta)
cre = common.select_lang(create_str).format(
device_name_under=self.get_go_package(),
device_name_camel=self.get_go_name(),
meta=create_meta_table)
bf = self.get_go_functions('bf')
af = self.get_go_functions('af')
ccf = self.get_go_functions('ccf')
c = self.get_go_callbacks()
vf = self.get_go_functions('vf')
if_ = self.get_go_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format(cre, bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
if ccf:
api_str += common.select_lang(common.ccf_str).format('', ccf)
api_str += common.select_lang(c_str).format(
self.get_doc_rst_ref_name(),
self.get_name().under,
self.get_name().upper, c)
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
article = 'ein'
if self.is_brick():
article = 'einen'
api_str += common.select_lang(const_str).format(
device_name_ref=self.get_doc_rst_ref_name(),
device_name_camel=self.get_go_name(),
device_name_under=self.get_go_package(),
article=article,
device_name_display=self.get_long_display_name())
return common.select_lang(api).format(
self.get_doc_rst_ref_name(),
self.specialize_go_doc_function_links(
common.select_lang(self.get_doc())),
api_str,
device_name_display=self.get_long_display_name(),
device_name_under=self.get_go_package())
def get_python_api(self):
create_str = {
'en':
"""
.. py:function:: {0}(uid, ipcon)
{2}
Creates an object with the unique device ID ``uid``:
.. code-block:: python
{1} = {0}("YOUR_DEVICE_UID", ipcon)
This object can then be used after the IP Connection is connected.
""",
'de':
"""
.. py:function:: {0}(uid, ipcon)
{2}
Erzeugt ein Objekt mit der eindeutigen Geräte ID ``uid``:
.. code-block:: python
{1} = {0}("YOUR_DEVICE_UID", ipcon)
Dieses Objekt kann benutzt werden, nachdem die IP Connection verbunden ist.
"""
}
register_str = {
'en':
"""
.. py:function:: {2}{1}.register_callback(callback_id, function)
{3}
Registers the given ``function`` with the given ``callback_id``.
The available callback IDs with corresponding function signatures are listed
:ref:`below <{0}_python_callbacks>`.
""",
'de':
"""
.. py:function:: {2}{1}.register_callback(callback_id, function)
{3}
Registriert die ``function`` für die gegebene ``callback_id``.
Die verfügbaren Callback IDs mit den zugehörigen Funktionssignaturen sind
:ref:`unten <{0}_python_callbacks>` zu finden.
"""
}
c_str = {
'en':
"""
.. _{0}_python_callbacks:
Callbacks
^^^^^^^^^
Callbacks can be registered to receive
time critical or recurring data from the device. The registration is done
with the :py:func:`register_callback() <{1}.register_callback>` function of
the device object. The first parameter is the callback ID and the second
parameter the callback function:
.. code-block:: python
def my_callback(param):
print(param)
{2}.register_callback({1}.CALLBACK_EXAMPLE, my_callback)
The available constants with inherent number and type of parameters are
described below.
.. note::
Using callbacks for recurring events is *always* preferred
compared to using getters. It will use less USB bandwidth and the latency
will be a lot better, since there is no round trip time.
{3}
""",
'de':
"""
.. _{0}_python_callbacks:
Callbacks
^^^^^^^^^
Callbacks können registriert werden um zeitkritische
oder wiederkehrende Daten vom Gerät zu erhalten. Die Registrierung kann
mit der Funktion :py:func:`register_callback() <{1}.register_callback>` des
Geräte Objektes durchgeführt werden. Der erste Parameter ist die Callback ID
und der zweite Parameter die Callback-Funktion:
.. code-block:: python
def my_callback(param):
print(param)
{2}.register_callback({1}.CALLBACK_EXAMPLE, my_callback)
Die verfügbaren IDs mit der dazugehörigen Parameteranzahl und -typen werden
weiter unten beschrieben.
.. note::
Callbacks für wiederkehrende Ereignisse zu verwenden ist
*immer* zu bevorzugen gegenüber der Verwendung von Abfragen.
Es wird weniger USB-Bandbreite benutzt und die Latenz ist
erheblich geringer, da es keine Paketumlaufzeit gibt.
{3}
"""
}
api = {
'en':
"""
.. _{0}_python_api:
API
---
Generally, every function of the Python bindings can throw an
``tinkerforge.ip_connection.Error`` exception that has a ``value`` and a
``description`` property. ``value`` can have different values:
* Error.TIMEOUT = -1
* Error.NOT_ADDED = -6 (unused since Python bindings version 2.0.0)
* Error.ALREADY_CONNECTED = -7
* Error.NOT_CONNECTED = -8
* Error.INVALID_PARAMETER = -9
* Error.NOT_SUPPORTED = -10
* Error.UNKNOWN_ERROR_CODE = -11
* Error.STREAM_OUT_OF_SYNC = -12
* Error.INVALID_UID = -13
* Error.NON_ASCII_CHAR_IN_SECRET = -14
* Error.WRONG_DEVICE_TYPE = -15
* Error.DEVICE_REPLACED = -16
* Error.WRONG_RESPONSE_LENGTH = -17
All functions listed below are thread-safe.
{1}
{2}
""",
'de':
"""
.. _{0}_python_api:
API
---
Prinzipiell kann jede Funktion der Python Bindings
``tinkerforge.ip_connection.Error`` Exception werfen, welche ein ``value`` und
eine ``description`` Property hat. ``value`` kann verschiende Werte haben:
* Error.TIMEOUT = -1
* Error.NOT_ADDED = -6 (seit Python Bindings Version 2.0.0 nicht mehr verwendet)
* Error.ALREADY_CONNECTED = -7
* Error.NOT_CONNECTED = -8
* Error.INVALID_PARAMETER = -9
* Error.NOT_SUPPORTED = -10
* Error.UNKNOWN_ERROR_CODE = -11
* Error.STREAM_OUT_OF_SYNC = -12
* Error.INVALID_UID = -13
* Error.NON_ASCII_CHAR_IN_SECRET = -14
* Error.WRONG_DEVICE_TYPE = -15
* Error.DEVICE_REPLACED = -16
* Error.WRONG_RESPONSE_LENGTH = -17
Alle folgend aufgelisteten Funktionen sind Thread-sicher.
{1}
{2}
"""
}
const_str = {
'en':
"""
.. _{0}_python_constants:
Constants
^^^^^^^^^
.. py:attribute:: {1}.DEVICE_IDENTIFIER
This constant is used to identify a {3}.
The :py:func:`get_identity() <{1}.get_identity>` function and the
:py:attr:`IPConnection.CALLBACK_ENUMERATE <IPConnection.CALLBACK_ENUMERATE>`
callback of the IP Connection have a ``device_identifier`` parameter to specify
the Brick's or Bricklet's type.
.. py:attribute:: {1}.DEVICE_DISPLAY_NAME
This constant represents the human readable name of a {3}.
""",
'de':
"""
.. _{0}_python_constants:
Konstanten
^^^^^^^^^^
.. py:attribute:: {1}.DEVICE_IDENTIFIER
Diese Konstante wird verwendet um {2} {3} zu identifizieren.
Die :py:func:`get_identity() <{1}.get_identity>` Funktion und der
:py:attr:`IPConnection.CALLBACK_ENUMERATE <IPConnection.CALLBACK_ENUMERATE>`
Callback der IP Connection haben ein ``device_identifier`` Parameter um den Typ
des Bricks oder Bricklets anzugeben.
.. py:attribute:: {1}.DEVICE_DISPLAY_NAME
Diese Konstante stellt den Anzeigenamen eines {3} dar.
"""
}
create_meta = common.format_simple_element_meta([
('uid', 'str', 1, 'in'), ('ipcon', 'IPConnection', 1, 'in'),
(self.get_name().under, self.get_python_class_name(), 1, 'out')
])
create_meta_table = common.make_rst_meta_table(create_meta)
cre = common.select_lang(create_str).format(
self.get_python_class_name(),
self.get_name().under, create_meta_table)
reg_meta = common.format_simple_element_meta(
[('callback_id', 'int', 1, 'in'),
('function', 'callable', 1, 'in')],
no_out_value={
'en': 'None',
'de': 'None'
})
reg_meta_table = common.make_rst_meta_table(reg_meta)
reg = common.select_lang(register_str).format(
self.get_doc_rst_ref_name(),
self.get_name().camel,
self.get_category().camel, reg_meta_table)
bf = self.get_python_functions('bf')
af = self.get_python_functions('af')
ccf = self.get_python_functions('ccf')
c = self.get_python_callbacks()
vf = self.get_python_functions('vf')
if_ = self.get_python_functions('if')
api_str = ''
if bf:
api_str += common.select_lang(common.bf_str).format(cre, bf)
if af:
api_str += common.select_lang(common.af_str).format(af)
if c:
api_str += common.select_lang(common.ccf_str).format(reg, ccf)
api_str += common.select_lang(c_str).format(
self.get_doc_rst_ref_name(), self.get_python_class_name(),
self.get_name().under, c)
if vf:
api_str += common.select_lang(common.vf_str).format(vf)
if if_:
api_str += common.select_lang(common.if_str).format(if_)
article = 'ein'
if self.is_brick():
article = 'einen'
api_str += common.select_lang(const_str).format(
self.get_doc_rst_ref_name(), self.get_python_class_name(), article,
self.get_long_display_name())
return common.select_lang(api).format(
self.get_doc_rst_ref_name(),
self.specialize_python_doc_function_links(
common.select_lang(self.get_doc())), api_str)
