MQTT - RS232 Bricklet¶

Loopback¶

Download (example-loopback.txt)

 1# For this example connect the RX1 and TX pin to receive the send message
 2
 3# Change XYZ to the UID of your RS232 Bricklet
 4
 5setup:
 6    # Handle incoming read callbacks
 7    subscribe to tinkerforge/callback/rs232_bricklet/XYZ/read # Received messages contain the message as string and it's length as int
 8    publish '{"register": true}' to tinkerforge/register/rs232_bricklet/XYZ/read # Register read callback
 9
10    # Enable read callback
11    publish '' to tinkerforge/request/rs232_bricklet/XYZ/enable_read_callback
12
13    # Write "test" string
14    publish '{"message": "test", "length": 4}' to tinkerforge/request/rs232_bricklet/XYZ/write

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 216 - 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.

Added in version 2.0.2$nbsp;(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.

Added in version 2.0.4$nbsp;(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 216 - 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.

Added in version 2.0.4$nbsp;(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().

Added in version 2.0.4$nbsp;(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.

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

Added in version 2.0.1$nbsp;(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.

Added in version 2.0.4$nbsp;(Plugin).