openHAB - Thermocouple Bricklet 2.0

This is the description of the openHAB API bindings for the Thermocouple Bricklet 2.0. General information and technical specifications for the Thermocouple 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:brickletthermocouplev2:[UID]
Required firmware version:
  • 2.0.0
Firmware update supported:
  • yes
Channels:
Actions:
Parameters:
  • Average Length – Type: Choice, Default: 16
  • Available averaging sizes are 1, 2, 4, 8 and 16 samples. The conversion time depends on the averaging and filter configuration, it can be calculated as follows:
    • 60Hz: time = 82 + (samples - 1) * 16.67
    • 50Hz: time = 98 + (samples - 1) * 20
  • Options: 1, 2, 4, 8, 16

  • Thermocouple Type – Type: Choice, Default: K
  • As thermocouple type you can use B, E, J, K, N, R, S and T. If you have a different thermocouple or a custom thermocouple you can also use G8 and G32. With these types the returned value will not be in °C/100, it will be calculated by the following formulas:
    • G8: value = 8 * 1.6 * 2^17 * Vin
    • G32: value = 32 * 1.6 * 2^17 * Vin
    where Vin is the thermocouple input voltage.
  • Options: B, E, J, K, N, R, S, T, G8, G32

  • Frequency Filter – Type: Choice, Default: 50Hz
  • The frequency filter can be either configured to 50Hz or to 60Hz. You should configure it according to your utility frequency.
  • Options: 50Hz, 60Hz

  • Status LED Config – 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

Temperature

The temperature of the thermocouple.

Type:
  • Number:Temperature
UID:
  • tinkerforge:brickletthermocouplev2:[UID]:BrickletThermocoupleV2Temperature
Read only:
  • Yes
Unit:
  • Celsius
Range:
  • -210 Celsius to 1800 Celsius (Step 0.01 Celsius)
Parameters:
  • Update Interval – Type: integer, Default: 1000, Unit: ms, Min: 0, Max: 4294967295
  • Specifies the update interval in milliseconds. A value of 0 disables automatic updates.
Over/Under Voltage

Over/Under Voltage happens for voltages below 0V or above 3.3V. In this case it is very likely that your thermocouple is defective.

Type:
  • Switch
UID:
  • tinkerforge:brickletthermocouplev2:[UID]:BrickletThermocoupleV2OverUnderVoltage
Read only:
  • No
Open Circuit

An Open Circuit error indicates that there is no thermocouple connected.

Type:
  • Switch
UID:
  • tinkerforge:brickletthermocouplev2:[UID]:BrickletThermocoupleV2OpenCircuit
Read only:
  • No

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:brickletthermocouplev2:[UID]")
val hwVersion = actions.brickletThermocoupleV2GetIdentity().get("hardwareVersion") as short[]
logInfo("Example", "Hardware version: " + hwVersion.get(0) + "." + hwVersion.get(1) + "." + hwVersion.get(2))

Basic Actions

brickletThermocoupleV2GetTemperature()
Return Map:
  • temperature – Type: int, Unit: 1/100 °C, Range: [-21000 to 180000]

Returns the temperature of the thermocouple. The value is given in °C/100, e.g. a value of 4223 means that a temperature of 42.23 °C is measured.

If you want to get the temperature periodically, it is recommended to use the Temperature channel and set the period with the configuration of Temperature.

If you want to get the value periodically, it is recommended to use the Temperature channel. You can set the channel configuration with the configuration of Temperature.

Advanced Actions

brickletThermocoupleV2GetConfiguration()
Return Map:
  • averaging – Type: int, Range: See constants, Default: 16
  • thermocoupleType – Type: int, Range: See constants, Default: 3
  • filter – 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 averaging:

  • val AVERAGING_1 = 1
  • val AVERAGING_2 = 2
  • val AVERAGING_4 = 4
  • val AVERAGING_8 = 8
  • val AVERAGING_16 = 16

For thermocoupleType:

  • val TYPE_B = 0
  • val TYPE_E = 1
  • val TYPE_J = 2
  • val TYPE_K = 3
  • val TYPE_N = 4
  • val TYPE_R = 5
  • val TYPE_S = 6
  • val TYPE_T = 7
  • val TYPE_G8 = 8
  • val TYPE_G32 = 9

For filter:

  • val FILTER_OPTION_50HZ = 0
  • val FILTER_OPTION_60HZ = 1
brickletThermocoupleV2GetErrorState()
Return Map:
  • overUnder – Type: boolean
  • openCircuit – Type: boolean

Returns the current error state. There are two possible errors:

  • Over/Under Voltage and
  • Open Circuit.

Over/Under Voltage happens for voltages below 0V or above 3.3V. In this case it is very likely that your thermocouple is defective. An Open Circuit error indicates that there is no thermocouple connected.

You can use the Over/Under Voltage channel to automatically get triggered when the error state changes.

brickletThermocoupleV2GetChipTemperature()
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.

brickletThermocoupleV2GetStatusLEDConfig()
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
brickletThermocoupleV2GetSPITFPErrorCount()
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.

brickletThermocoupleV2GetIdentity()
Return Map:
  • uid – Type: String, Length: up to 8
  • connectedUid – Type: String, Length: up to 8
  • position – Type: char, Range: ['a' to 'h', 'i', '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). The Raspberry Pi HAT (Zero) Brick is always at position 'i' and the Bricklet connected to an Isolator Bricklet is always as position 'z'.

The device identifier numbers can be found here

Internal Actions

brickletThermocoupleV2ReadUID()
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.