openHAB - Industrial Quad Relay Bricklet

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

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

Thing

UID:
  • tinkerforge:brickletindustrialquadrelay:[UID]
Required firmware version:
  • 2.0.0
Firmware update supported:
  • yes
Channels:
Actions:

Channels

Relay 0

Switches Relay 0. A running monoflop timer for this relay will be aborted if the relay is toggled by this channel.

Type:
  • Switch
UID:
  • tinkerforge:brickletindustrialquadrelay:[UID]:BrickletIndustrialQuadRelayRelay0
Read only:
  • No
Relay 1

Switches Relay 1. A running monoflop timer for this relay will be aborted if the relay is toggled by this channel.

Type:
  • Switch
UID:
  • tinkerforge:brickletindustrialquadrelay:[UID]:BrickletIndustrialQuadRelayRelay1
Read only:
  • No
Relay 2

Switches Relay 2. A running monoflop timer for this relay will be aborted if the relay is toggled by this channel.

Type:
  • Switch
UID:
  • tinkerforge:brickletindustrialquadrelay:[UID]:BrickletIndustrialQuadRelayRelay2
Read only:
  • No
Relay 3

Switches Relay 3. A running monoflop timer for this relay will be aborted if the relay is toggled by this channel.

Type:
  • Switch
UID:
  • tinkerforge:brickletindustrialquadrelay:[UID]:BrickletIndustrialQuadRelayRelay3
Read only:
  • No
Monoflop Relay 0

Triggers a monoflop as configured

Type:
  • Commands (String)
UID:
  • tinkerforge:brickletindustrialquadrelay:[UID]:BrickletIndustrialQuadRelayMonoflopRelay0
Read only:
  • No
Commands:
  • Accepts any string
Parameters:
  • Monoflop Duration – Type: integer, Default: 1000, Unit: ms, Min: 0, Max: 4294967295
  • The time (in ms) that the relay should hold the configured value.

  • Monoflop Value – Type: boolean, Default: true
  • The desired value of the specified channel. Activated means relay closed and Deactivated means relay open.
Monoflop Relay 1

Triggers a monoflop as configured

Type:
  • Commands (String)
UID:
  • tinkerforge:brickletindustrialquadrelay:[UID]:BrickletIndustrialQuadRelayMonoflopRelay1
Read only:
  • No
Commands:
  • Accepts any string
Parameters:
  • Monoflop Duration – Type: integer, Default: 1000, Unit: ms, Min: 0, Max: 4294967295
  • The time (in ms) that the relay should hold the configured value.

  • Monoflop Value – Type: boolean, Default: true
  • The desired value of the specified channel. Activated means relay closed and Deactivated means relay open.
Monoflop Relay 2

Triggers a monoflop as configured

Type:
  • Commands (String)
UID:
  • tinkerforge:brickletindustrialquadrelay:[UID]:BrickletIndustrialQuadRelayMonoflopRelay2
Read only:
  • No
Commands:
  • Accepts any string
Parameters:
  • Monoflop Duration – Type: integer, Default: 1000, Unit: ms, Min: 0, Max: 4294967295
  • The time (in ms) that the relay should hold the configured value.

  • Monoflop Value – Type: boolean, Default: true
  • The desired value of the specified channel. Activated means relay closed and Deactivated means relay open.
Monoflop Relay 3

Triggers a monoflop as configured

Type:
  • Commands (String)
UID:
  • tinkerforge:brickletindustrialquadrelay:[UID]:BrickletIndustrialQuadRelayMonoflopRelay3
Read only:
  • No
Commands:
  • Accepts any string
Parameters:
  • Monoflop Duration – Type: integer, Default: 1000, Unit: ms, Min: 0, Max: 4294967295
  • The time (in ms) that the relay should hold the configured value.

  • Monoflop Value – Type: boolean, Default: true
  • The desired value of the specified channel. Activated means relay closed and Deactivated means relay open.

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

Basic Actions

brickletIndustrialQuadRelaySetValue(int valueMask)
Parameters:
  • valueMask – Type: int, Range: [0 to 216 - 1]

Sets the output value with a bitmask (16bit). A 1 in the bitmask means relay closed and a 0 means relay open.

For example: The value 3 or 0b0011 will close the relay of pins 0-1 and open the other pins.

All running monoflop timers will be aborted if this function is called.

brickletIndustrialQuadRelayGetValue()
Return Map:
  • valueMask – Type: int, Range: [0 to 216 - 1]

Returns the bitmask as set by Relay 0.

Advanced Actions

brickletIndustrialQuadRelaySetMonoflop(int selectionMask, int valueMask, long time)
Parameters:
  • selectionMask – Type: int, Range: [0 to 216 - 1]
  • valueMask – Type: int, Range: [0 to 216 - 1]
  • time – Type: long, Unit: 1 ms, Range: [0 to 232 - 1]

Configures a monoflop of the pins specified by the first parameter bitmask.

The second parameter is a bitmask with the desired value of the specified pins. A 1 in the bitmask means relay closed and a 0 means relay open.

The third parameter indicates the time that the pins should hold the value.

If this function is called with the parameters (9, 1, 1500) or (0b1001, 0b0001, 1500): Pin 0 will close and pin 3 will open. In 1.5s pin 0 will open and pin 3 will close again.

A monoflop can be used as a fail-safe mechanism. For example: Lets assume you have a RS485 bus and a Quad Relay Bricklet connected to one of the slave stacks. You can now call this function every second, with a time parameter of two seconds and pin 0 closed. Pin 0 will be closed all the time. If now the RS485 connection is lost, then pin 0 will be opened in at most two seconds.

brickletIndustrialQuadRelaySetSelectedValues(int selectionMask, int valueMask)
Parameters:
  • selectionMask – Type: int, Range: [0 to 216 - 1]
  • valueMask – Type: int, Range: [0 to 216 - 1]

Sets the output value with a bitmask, according to the selection mask. The bitmask is 16 bit long, true refers to a closed relay and false refers to an open relay.

For example: The values (3, 1) or (0b0011, 0b0001) will close the relay of pin 0, open the relay of pin 1 and leave the others untouched.

Running monoflop timers for the selected relays will be aborted if this function is called.

brickletIndustrialQuadRelayGetMonoflop(short pin)
Parameters:
  • pin – Type: short, Range: [0 to 15]
Return Map:
  • value – Type: int, Range: [0 to 1]
  • time – Type: long, Unit: 1 ms, Range: [0 to 232 - 1]
  • timeRemaining – Type: long, Unit: 1 ms, Range: [0 to 232 - 1]

Returns (for the given pin) the current value and the time as set by Monoflop Relay 0 as well as the remaining time until the value flips.

If the timer is not running currently, the remaining time will be returned as 0.

brickletIndustrialQuadRelayGetIdentity()
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