Deutsch
English
Menu
Software / API Bindings / openHAB / API Reference and Examples / Bricklets / RS232 Bricklet 2.0

openHAB - RS232 Bricklet 2.0

Bemerkung

Die openHAB-Dokumentation ist nur auf Englisch verfügbar.

Warnung

The openHAB bindings are still in beta, but the development was stopped.

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

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

Thing

UID:
  • tinkerforge:brickletrs232v2:[UID]
Required firmware version:
  • 2.0.3
Firmware update supported:
  • yes
Channels:
Actions:
Parameters:
  • Baud Rate – Type: integer, Default: 115200, Min: 100, Max: 2000000
  • The baud rate to send/receive with.

  • Parity – Type: Choice, Default: None
  • The parity mode to use. See `here `__.
  • Options: None, Odd, Even

  • Stop Bits – Type: Choice, Default: 1
  • The number of stop bits to send/expect.
  • Options: 1, 2

  • Word Length – Type: Choice, Default: 8
  • The length of a serial word. Typically one byte.
  • Options: 5, 6, 7, 8

  • Flow Control – Type: Choice, Default: Off
  • The flow control mechanism to use. Software uses control characters in-band. Hardware uses the RTS and CTS lines.
  • Options: Off, Software, Hardware

  • Send Buffer Size – Type: integer, Default: 5120, Min: 1024, Max: 9216
  • The send buffer size in bytes. In total the send and receive buffers are 10240 byte (10 KiB) in size. The minimum buffer size is 1024 byte (1 KiB) each. The binding will configure the read buffer size accordingly. The send buffer holds data that is given by the user and can not be written to RS232 yet. The receive buffer holds data that is received through RS232 but could not yet be send to the user.

  • Frame Size – Type: integer, Default: 1, Min: 0, Max: 9216
  • The size of receivable data frames in bytes. Set this to something other than 1, if you want to receive data with a fix frame size. The frame readable channel will trigger every time a frame of this size is ready to be read, but will wait until this frame is read before triggering again. This means, you can use this channel as a trigger in a rule, that will read exactly one frame.

  • Status LED Configuration – Type: Choice, Default: Show Status
  • The status LED configuration. By default the LED shows communication traffic between Brick and Bricklet, it flickers once for every 10 received data packets. You can also turn the LED permanently on/off or show a heartbeat. If the Bricklet is in bootloader mode, the LED is will show heartbeat by default.
  • Options: Off, On, Show Heartbeat, Show Status

Channels

Frame Readable

This channel is triggered in when a new frame was received and can be read out. The channel will only trigger again if the frame was read.

Type:
  • Trigger (system.trigger)
UID:
  • tinkerforge:brickletrs232v2:[UID]:BrickletRS232V2FrameReadable
Read only:
  • No
Overrun Error Count

The current number of overrun errors

Type:
  • Number:Dimensionless
UID:
  • tinkerforge:brickletrs232v2:[UID]:BrickletRS232V2OverrunErrorCount
Read only:
  • Yes
Parity Error Count

The current number of parity errors

Type:
  • Number:Dimensionless
UID:
  • tinkerforge:brickletrs232v2:[UID]:BrickletRS232V2ParityErrorCount
Read only:
  • Yes
Send Buffer Used

The number of bytes currently in the send buffer

This channel will only update after the configured update interval, not on changed values.

Type:
  • Number:DataAmount
UID:
  • tinkerforge:brickletrs232v2:[UID]:BrickletRS232V2SendBufferUsed
Read only:
  • Yes
Unit:
  • Byte
Range:
  • 0 Byte to 9216 Byte (Step 1 Byte)
Parameters:
  • Update Interval – Type: integer, Default: 1000, Unit: ms
  • Specifies the update interval in milliseconds. A value of 0 disables automatic updates.
Receive Buffer Used

The number of bytes currently in the receive buffer

This channel will only update after the configured update interval, not on changed values.

Type:
  • Number:DataAmount
UID:
  • tinkerforge:brickletrs232v2:[UID]:BrickletRS232V2ReceiveBufferUsed
Read only:
  • Yes
Unit:
  • Byte
Range:
  • 0 Byte to 9216 Byte (Step 1 Byte)
Parameters:
  • Update Interval – Type: integer, Default: 1000, Unit: ms
  • Specifies the update interval in milliseconds. A value of 0 disables automatic updates.

Actions

Actions can be used in rules by creating an action object. All actions return a Map<String, Object>. Returned values can be accessed by name, sometimes the type deduction needs some hints, as shown below:

val actions = getActions("tinkerforge", "tinkerforge:brickletrs232v2:[UID]")
val hwVersion = actions.brickletRS232V2GetIdentity().get("hardwareVersion") as short[]
logInfo("Example", "Hardware version: " + hwVersion.get(0) + "." + hwVersion.get(1) + "." + hwVersion.get(2))

Basic Actions

brickletRS232V2Write(char[] message)
Parameters:
  • message – Type: char[], Length: variable
Return Map:
  • messageWritten – Type: int, Range: [0 to 216 - 1]

Writes characters to the RS232 interface. The characters can be binary data, ASCII or similar is not necessary.

The return value is the number of characters that were written.

See the thing configuration for configuration possibilities regarding baud rate, parity and so on.

brickletRS232V2Read(int length)
Parameters:
  • length – Type: int, Range: [0 to 216 - 1]
Return Map:
  • message – Type: char[], Length: variable

Returns up to length characters from receive buffer.

brickletRS232V2GetConfiguration()
Return Map:
  • baudrate – Type: long, Unit: 1 Bd, Range: [100 to 2000000], Default: 115200
  • parity – Type: int, Range: See constants, Default: 0
  • stopbits – Type: int, Range: See constants, Default: 1
  • wordlength – Type: int, Range: See constants, Default: 8
  • flowcontrol – Type: int, Range: See constants, Default: 0

Returns the configuration as set by the thing configuration.

The following constants are available for this function:

For parity:

  • val PARITY_NONE = 0
  • val PARITY_ODD = 1
  • val PARITY_EVEN = 2

For stopbits:

  • val STOPBITS_1 = 1
  • val STOPBITS_2 = 2

For wordlength:

  • val WORDLENGTH_5 = 5
  • val WORDLENGTH_6 = 6
  • val WORDLENGTH_7 = 7
  • val WORDLENGTH_8 = 8

For flowcontrol:

  • val FLOWCONTROL_OFF = 0
  • val FLOWCONTROL_SOFTWARE = 1
  • val FLOWCONTROL_HARDWARE = 2

Advanced Actions

brickletRS232V2GetBufferConfig()
Return Map:
  • sendBufferSize – Type: int, Unit: 1 B, Range: [210 to 9216], Default: 5120
  • receiveBufferSize – Type: int, Unit: 1 B, Range: [210 to 9216], Default: 5120

Returns the buffer configuration as set by the thing configuration.

brickletRS232V2GetBufferStatus()
Return Map:
  • sendBufferUsed – Type: int, Unit: 1 B, Range: [0 to 9216]
  • receiveBufferUsed – Type: int, Unit: 1 B, Range: [0 to 9216]

Returns the currently used bytes for the send and received buffer.

See the thing configuration for buffer size configuration.

brickletRS232V2GetErrorCount()
Return Map:
  • errorCountOverrun – Type: long, Range: [0 to 232 - 1]
  • errorCountParity – Type: long, Range: [0 to 232 - 1]

Returns the current number of overrun and parity errors.

brickletRS232V2GetChipTemperature()
Return Map:
  • temperature – Type: int, Unit: 1 °C, Range: [-215 to 215 - 1]

Returns the temperature as measured inside the microcontroller. The value returned is not the ambient temperature!

The temperature is only proportional to the real temperature and it has bad accuracy. Practically it is only useful as an indicator for temperature changes.

brickletRS232V2GetStatusLEDConfig()
Return Map:
  • config – Type: int, Range: See constants, Default: 3

Returns the configuration as set by the thing configuration

The following constants are available for this function:

For config:

  • val STATUS_LED_CONFIG_OFF = 0
  • val STATUS_LED_CONFIG_ON = 1
  • val STATUS_LED_CONFIG_SHOW_HEARTBEAT = 2
  • val STATUS_LED_CONFIG_SHOW_STATUS = 3
brickletRS232V2GetSPITFPErrorCount()
Return Map:
  • errorCountAckChecksum – Type: long, Range: [0 to 232 - 1]
  • errorCountMessageChecksum – Type: long, Range: [0 to 232 - 1]
  • errorCountFrame – Type: long, Range: [0 to 232 - 1]
  • errorCountOverflow – Type: long, Range: [0 to 232 - 1]

Returns the error count for the communication between Brick and Bricklet.

The errors are divided into

  • ACK checksum errors,
  • message checksum errors,
  • framing errors and
  • overflow errors.

The errors counts are for errors that occur on the Bricklet side. All Bricks have a similar function that returns the errors on the Brick side.

brickletRS232V2Reset()

Calling this function will reset the Bricklet. All configurations will be lost.

After a reset you have to create new device objects, calling functions on the existing ones will result in undefined behavior!

brickletRS232V2GetIdentity()
Return Map:
  • uid – Type: String, Length: up to 8
  • connectedUid – Type: String, Length: up to 8
  • position – Type: char, Range: ['a' to 'h', 'z']
  • hardwareVersion – Type: short[], Length: 3
    • 0: major – Type: short, Range: [0 to 255]
    • 1: minor – Type: short, Range: [0 to 255]
    • 2: revision – Type: short, Range: [0 to 255]
  • firmwareVersion – Type: short[], Length: 3
    • 0: major – Type: short, Range: [0 to 255]
    • 1: minor – Type: short, Range: [0 to 255]
    • 2: revision – Type: short, Range: [0 to 255]
  • deviceIdentifier – Type: int, Range: [0 to 216 - 1]

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. 

Internal Actions

brickletRS232V2ReadUID()
Return Map:
  • uid – Type: long, Range: [0 to 232 - 1]

Returns the current UID as an integer. Encode as Base58 to get the usual string version.