MQTT - RS232 Bricklet

This is the description of the MQTT API bindings for the RS232 Bricklet. General information and technical specifications for the RS232 Bricklet are summarized in its hardware description.

An installation guide for the MQTT API bindings is part of their general description.

Examples

The example code below is Public Domain (CC0 1.0).

Loopback

Download (example-loopback.txt)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# For this example connect the RX1 and TX pin to receive the send message

# Change XYZ to the UID of your RS232 Bricklet

setup:
    # Handle incoming read callbacks
    subscribe to tinkerforge/callback/rs232_bricklet/XYZ/read # Received messages contain the message as string and it's length as int
    publish '{"register": true}' to tinkerforge/register/rs232_bricklet/XYZ/read # Register read callback
    
    # Enable read callback
    publish '' to tinkerforge/request/rs232_bricklet/XYZ/enable_read_callback 
    
    # Write "test" string
    publish '{"message": "test", "length": 4}' to tinkerforge/request/rs232_bricklet/XYZ/write 

API

All published payload to an from the MQTT bindings is in the JSON format.

If an error occures, the bindings publish a JSON object containing the error message as attribute "_ERROR". It is published on the corresponding response topic: .../response/... for .../request/... and .../callback/... for .../register/....

Basic Functions

request/rs232_bricklet/<UID>/write
Request payload:
 
  • message -- string
  • length -- int
Response payload:
 
  • written -- int

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 request/rs232_bricklet/<UID>/set_configuration for configuration possibilities regarding baudrate, parity and so on.

request/rs232_bricklet/<UID>/read
Response payload:
 
  • message -- string
  • length -- int

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 request/rs232_bricklet/<UID>/enable_read_callback and register/rs232_bricklet/<UID>/read callback.

request/rs232_bricklet/<UID>/set_configuration
Request payload:
 
  • baudrate -- int (has symbols)
  • parity -- int (has symbols)
  • stopbits -- int (has symbols)
  • wordlength -- int (has symbols)
  • hardware_flowcontrol -- int (has symbols)
  • software_flowcontrol -- int (has symbols)

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 either be on or off but not both simultaneously on.

The default is: 115200 baud, parity none, 1 stop bit, word length 8, hard-/software flow control off.

The following symbols are available for this function:

for baudrate:

  • "300" = 0
  • "600" = 1
  • "1200" = 2
  • "2400" = 3
  • "4800" = 4
  • "9600" = 5
  • "14400" = 6
  • "19200" = 7
  • "28800" = 8
  • "38400" = 9
  • "57600" = 10
  • "115200" = 11
  • "230400" = 12

for parity:

  • "None" = 0
  • "Odd" = 1
  • "Even" = 2
  • "ForcedParity1" = 3
  • "ForcedParity0" = 4

for stopbits:

  • "1" = 1
  • "2" = 2

for wordlength:

  • "5" = 5
  • "6" = 6
  • "7" = 7
  • "8" = 8

for hardware_flowcontrol:

  • "Off" = 0
  • "On" = 1

for software_flowcontrol:

  • "Off" = 0
  • "On" = 1
request/rs232_bricklet/<UID>/get_configuration
Response payload:
 
  • baudrate -- int (has symbols)
  • parity -- int (has symbols)
  • stopbits -- int (has symbols)
  • wordlength -- int (has symbols)
  • hardware_flowcontrol -- int (has symbols)
  • software_flowcontrol -- int (has symbols)

Returns the configuration as set by request/rs232_bricklet/<UID>/set_configuration.

The following symbols are available for this function:

for baudrate:

  • "300" = 0
  • "600" = 1
  • "1200" = 2
  • "2400" = 3
  • "4800" = 4
  • "9600" = 5
  • "14400" = 6
  • "19200" = 7
  • "28800" = 8
  • "38400" = 9
  • "57600" = 10
  • "115200" = 11
  • "230400" = 12

for parity:

  • "None" = 0
  • "Odd" = 1
  • "Even" = 2
  • "ForcedParity1" = 3
  • "ForcedParity0" = 4

for stopbits:

  • "1" = 1
  • "2" = 2

for wordlength:

  • "5" = 5
  • "6" = 6
  • "7" = 7
  • "8" = 8

for hardware_flowcontrol:

  • "Off" = 0
  • "On" = 1

for software_flowcontrol:

  • "Off" = 0
  • "On" = 1
request/rs232_bricklet/<UID>/set_break_condition
Request payload:
 
  • break_time -- int

Sets a break condition (the TX output is forced to a logic 0 state). The parameter sets the hold-time of the break condition (in ms).

New in version 2.0.2 (Plugin).

Advanced Functions

request/rs232_bricklet/<UID>/get_identity
Response payload:
 
  • uid -- string
  • connected_uid -- string
  • position -- string
  • hardware_version -- [int,int,int]
  • firmware_version -- [int,int,int]
  • device_identifier -- int (has symbols)
  • _display_name -- string

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 here. 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 RS232's name in a human readable form.

Callback Configuration Functions

request/rs232_bricklet/<UID>/enable_read_callback

Enables the register/rs232_bricklet/<UID>/read callback.

By default the callback is disabled.

request/rs232_bricklet/<UID>/disable_read_callback

Disables the register/rs232_bricklet/<UID>/read callback.

By default the callback is disabled.

request/rs232_bricklet/<UID>/is_read_callback_enabled
Response payload:
 
  • enabled -- bool

Returns true if the register/rs232_bricklet/<UID>/read callback is enabled, false otherwise.

Callbacks

Callbacks can be registered to receive time critical or recurring data from the device. The registration is done with the corresponding .../register/... topic and an optional suffix. This suffix can be used to deregister the callback later.

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.

register/rs232_bricklet/<UID>/read
Request payload:
 
  • register -- bool
Response payload:
 
  • message -- string
  • length -- int

A callback can be registered for this event by publishing to the .../register/rs232_bricklet/<UID>/read[/<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/rs232_bricklet/<UID>/read[/<SUFFIX>] topic for each registered suffix.

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 request/rs232_bricklet/<UID>/enable_read_callback.

register/rs232_bricklet/<UID>/error
Request payload:
 
  • register -- bool
Response payload:
 
  • error -- int (has symbols)

A callback can be registered for this event by publishing to the .../register/rs232_bricklet/<UID>/error[/<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/rs232_bricklet/<UID>/error[/<SUFFIX>] topic for each registered suffix.

This callback is called if an error occurs. Possible errors are overrun, parity or framing error.

The following symbols are available for this function:

for error:

  • "Overrun" = 1
  • "Parity" = 2
  • "Framing" = 4

New in version 2.0.1 (Plugin).