Software / API Bindings / MQTT / API Reference and Examples / Bricklets / RS232 Bricklet

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)

# 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 payloads to and from the MQTT bindings are in JSON format.

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

Basic Functions¶

request/rs232_bricklet/<UID>/write¶

Request:	message – Type: [char, ...], Length: 60 length – Type: int, Range: [0 to 60]
Response:	written – Type: int, Range: [0 to 60]

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¶

Request:	empty payload
Response:	message – Type: [char, ...], Length: 60 length – Type: int, Range: [0 to 60]

Returns the currently buffered message. The maximum length of message is 60. If the returned length is 0, no new data was 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:	baudrate – Type: int, Range: See symbols, Default: 11 parity – Type: int, Range: See symbols, Default: 0 stopbits – Type: int, Range: See symbols, Default: 1 wordlength – Type: int, Range: See symbols, Default: 8 hardware_flowcontrol – Type: int, Range: See symbols, Default: 0 software_flowcontrol – Type: int, Range: See symbols, Default: 0
Response:	no response

Sets the configuration for the RS232 communication.

Hard-/Software flow control can either be on or off but not both simultaneously on.

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
"forced_parity_1" = 3
"forced_parity_0" = 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¶

Request:	empty payload
Response:	baudrate – Type: int, Range: See symbols, Default: 11 parity – Type: int, Range: See symbols, Default: 0 stopbits – Type: int, Range: See symbols, Default: 1 wordlength – Type: int, Range: See symbols, Default: 8 hardware_flowcontrol – Type: int, Range: See symbols, Default: 0 software_flowcontrol – Type: int, Range: See symbols, Default: 0

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
"forced_parity_1" = 3
"forced_parity_0" = 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:	break_time – Type: int, Unit: 1 ms, Range: [0 to 2¹⁶ - 1]
Response:	no response

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

New in version 2.0.2 (Plugin).

request/rs232_bricklet/<UID>/read_frame¶

Request:	empty payload
Response:	message – Type: [char, ...], Length: 60 length – Type: int, Range: [0 to 60]

Returns up to one frame of bytes from the read buffer. The frame size is configured with request/rs232_bricklet/<UID>/set_frame_readable_callback_configuration. If the returned length is 0, no new data was available.

New in version 2.0.4 (Plugin).

Advanced Functions¶

request/rs232_bricklet/<UID>/get_identity¶

Request:

empty payload

Response:

uid – Type: string, Length: up to 8
connected_uid – Type: string, Length: up to 8
position – Type: char, Range: ["a" to "h", "z"]
hardware_version – Type: [int, ...], Length: 3

0: major – Type: int, Range: [0 to 255]
1: minor – Type: int, Range: [0 to 255]
2: revision – Type: int, Range: [0 to 255]

firmware_version – Type: [int, ...], Length: 3

0: major – Type: int, Range: [0 to 255]
1: minor – Type: int, Range: [0 to 255]
2: revision – Type: int, Range: [0 to 255]

device_identifier – Type: int, Range: [0 to 2¹⁶ - 1]
_display_name – Type: 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', 'd', 'e', 'f', 'g' or 'h' (Bricklet Port). A Bricklet connected to an Isolator Bricklet is always at position 'z'.

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¶

Request:	empty payload
Response:	no response

Enables the register/rs232_bricklet/<UID>/read callback. This will disable the register/rs232_bricklet/<UID>/frame_readable callback.

By default the callback is disabled.

request/rs232_bricklet/<UID>/disable_read_callback¶

Request:	empty payload
Response:	no response

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

By default the callback is disabled.

request/rs232_bricklet/<UID>/is_read_callback_enabled¶

Request:	empty payload
Response:	enabled – Type: bool, Default: false

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

request/rs232_bricklet/<UID>/set_frame_readable_callback_configuration¶

Request:	frame_size – Type: int, Unit: 1 B, Range: [0 to 100], Default: 0
Response:	no response

Configures the register/rs232_bricklet/<UID>/frame_readable callback. The frame size is the number of bytes, that have to be readable to trigger the callback. A frame size of 0 disables the callback. A frame size greater than 0 enables the callback and disables the register/rs232_bricklet/<UID>/read callback.

By default the callback is disabled.

New in version 2.0.4 (Plugin).

request/rs232_bricklet/<UID>/get_frame_readable_callback_configuration¶

Request:	empty payload
Response:	frame_size – Type: int, Unit: 1 B, Range: [0 to 100], Default: 0

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

New in version 2.0.4 (Plugin).

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¶

Register Request:	register – Type: bool
Callback Response:	message – Type: [char, ...], Length: 60 length – Type: int, Range: [1 to 60]

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¶

Register Request:	register – Type: bool
Callback Response:	error – Type: int, Range: See 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).

register/rs232_bricklet/<UID>/frame_readable¶

Register Request:	register – Type: bool
Callback Response:	frame_count – Type: int, Range: [0 to 255]

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

This callback is called if at least one frame of data is readable. The frame size is configured with request/rs232_bricklet/<UID>/set_frame_readable_callback_configuration. The frame count parameter is the number of frames that can be read. This callback is triggered only once until request/rs232_bricklet/<UID>/read or request/rs232_bricklet/<UID>/read_frame is called. This means, that if you have configured a frame size of X bytes, you can read exactly X bytes using the request/rs232_bricklet/<UID>/read_frame function, every time the callback triggers without checking the frame count callback payload.

New in version 2.0.4 (Plugin).