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)