..
 #############################################################
 # This file was automatically generated on 2015-05-11.      #
 #                                                           #
 # If you have a bugfix for this file and want to commit it, #
 # please fix the bug in the generator. You can find a link  #
 # to the generators git repository on tinkerforge.com       #
 #############################################################

:orphan:
:breadcrumbs: <a href="../../index.html">Home</a> / <a href="../../index.html#software-modbus">Software</a> / Modbus - RS232 Bricklet

.. |device_identifier_constant| unicode:: 0xA0
   :trim:

.. _rs232_bricklet_modbus:

Modbus - RS232 Bricklet
=======================

.. note::
 This Bricklet is currently in the prototype stage and the software/hardware
 as well as the documentation is in an incomplete state.


This is the description of the :ref:`Modbus protocol <llproto_modbus>` for the :ref:`RS232 Bricklet <rs232_bricklet>`. General information and technical
specifications for the RS232 Bricklet are summarized in its :ref:`hardware description
<rs232_bricklet_description>`.

.. _rs232_bricklet_modbus_api:

API
---

A general description of the Modbus protocol structure can be found
:ref:`here <llproto_modbus>`.




Basic Functions
^^^^^^^^^^^^^^^



.. modbus:function:: BrickletRS232.write

 :functionid: 1
 :request message: char[60]
 :request length: uint8

 :response written: uint8

 Writes a string of up to 60 characters to the RS232 interface. The string
 can be binary data, ASCII or similar is not necessary.
 
 The length of the string has to be given as an additional parameter.
 
 The return value is the number of bytes that could be written.
 
 See :func:`SetConfigurations` for configuration possibilities
 regarding baudrate, parity and so on.
 
.. modbus:function:: BrickletRS232.read

 :functionid: 2
 :emptyrequest: empty payload

 :response message: char[60]
 :response length: uint8

 Returns the currently buffered message. The maximum length
 of message is 60. If the length is given as 0, there was no
 new data available.
 
 Instead of polling with this function, you can also use
 callbacks. See :modbus:func:`enable_callback <BrickletRS232.enable_callback>` and :modbus:func:`CALLBACK_READ_CALLBACK <BrickletRS232.CALLBACK_READ_CALLBACK>`.
 
.. modbus:function:: BrickletRS232.set_configuration

 :functionid: 6
 :request baudrate: uint8
 :request parity: uint8
 :request stopbits: uint8
 :request wordlength: uint8
 :request hardware_flowcontrol: uint8
 :request software_flowcontrol: uint8

 :noresponse: no response

 Sets the configuration for the RS232 communication. Available options:
 
 * Baudrate between 300 and 230400 baud.
 * Parity of none, odd, even or forced parity.
 * Stopbits can be 1 or 2.
 * Word length of 5 to 8.
 * Hard-/Software flow control can each be on or off.
 
 The default is: 115200 baud, parity none, 1 stop bit, word length 8, hard-/software flow control off.
 
.. modbus:function:: BrickletRS232.get_configuration

 :functionid: 7
 :emptyrequest: empty payload

 :response baudrate: uint8
 :response parity: uint8
 :response stopbits: uint8
 :response wordlength: uint8
 :response hardware_flowcontrol: uint8
 :response software_flowcontrol: uint8

 Returns the configuration as set by :modbus:func:`set_configuration <BrickletRS232.set_configuration>`.
 


Advanced Functions
^^^^^^^^^^^^^^^^^^

.. modbus:function:: BrickletRS232.get_identity

 :functionid: 255
 :emptyrequest: empty payload

 :response uid: char[8]
 :response connected_uid: char[8]
 :response position: char
 :response hardware_version: uint8[3]
 :response firmware_version: uint8[3]
 :response device_identifier: uint16

 Returns the UID, the UID where the Bricklet is connected to, 
 the position, the hardware and firmware version as well as the
 device identifier.
 
 The position can be 'a', 'b', 'c' or 'd'.
 
 The device identifier numbers can be found :ref:`here <device_identifier>`.
 |device_identifier_constant|
 


Callback Configuration Functions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



.. modbus:function:: BrickletRS232.enable_callback

 :functionid: 3
 :emptyrequest: empty payload

 :noresponse: no response

 Enables the :modbus:func:`CALLBACK_READ_CALLBACK <BrickletRS232.CALLBACK_READ_CALLBACK>`.
 
 By default the callback is disabled.
 
.. modbus:function:: BrickletRS232.disable_callback

 :functionid: 4
 :emptyrequest: empty payload

 :noresponse: no response

 Disables the :modbus:func:`CALLBACK_READ_CALLBACK <BrickletRS232.CALLBACK_READ_CALLBACK>`.
 
 By default the callback is disabled.
 
.. modbus:function:: BrickletRS232.is_callback_enabled

 :functionid: 5
 :emptyrequest: empty payload

 :response enable: bool

 Returns *true* if the :modbus:func:`CALLBACK_READ_CALLBACK <BrickletRS232.CALLBACK_READ_CALLBACK>` is enabled,
 *false* otherwise.
 


.. _rs232_bricklet_modbus_callbacks:

Callbacks
^^^^^^^^^

.. modbus:function:: BrickletRS232.CALLBACK_READ_CALLBACK

 :functionid: 8

 :response message: char[60]
 :response length: uint8


 This callback is called if new data is available. The message has
 a maximum size of 60 characters. The actual length of the message
 is given in addition.
 
 To enable this callback, use :modbus:func:`enable_callback <BrickletRS232.enable_callback>`.
 


