openHAB - LED Strip Bricklet 2.0

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

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

Examples

The example code below is Public Domain (CC0 1.0).

Simple

Download (ExampleSimple.rules)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
import java.util.Collections

val NUM_LEDS = 200
var counter = 0

rule "example"
when
    // System started has to be used as additional trigger to draw the first frame, the channel will only
    // trigger once the first frame has been sent.
    // Change XYZ to the UID of your LED Strip Bricklet 2.0
    System started or Channel "tinkerforge:brickletledstripv2:XYZ:BrickletLEDStripV2FrameStarted" triggered
then
    // Change XYZ to the UID of your LED Strip Bricklet 2.0
    val ledActions = getActions("tinkerforge", "tinkerforge:brickletledstripv2:XYZ")

    counter = counter + 1

    //Clear all LEDs when at the end of the strip.
    if (counter >= NUM_LEDS) {
         ledActions.brickletLEDStripV2SetLEDValues(0, Collections.nCopies(600, 0))
         counter = 0
    }

    // Draw pattern: black, red, green, blue, black
    // If the colors are exchanged, the channel mapping is misconfigured
    ledActions.brickletLEDStripV2SetLEDValues(counter * 3, newArrayList(0, 0, 0,
                                                                        255, 0, 0,
                                                                        0, 255, 0,
                                                                        0, 0, 255,
                                                                        0, 0, 0))
end

Thing

UID:
  • tinkerforge:brickletledstripv2:[UID]
Required firmware version:
  • 2.0.0
Firmware update supported:
  • yes
Channels:
Actions:
Parameters:
  • LED Driver Chip Type – Type: Choice, Default: WS2801
  • The type of the LED driver chip. We currently support the chips
    • WS2801
    • WS2811
    • WS2812 / SK6812 / NeoPixel RGB
    • SK6812RGBW / NeoPixel RGBW (Chip Type = WS2812)
    • LPD8806
    • APA102 / DotStar
  • Options: WS2801, WS2811, WS2812, LPD8806, APA102

  • LED Channel Mapping – Type: Choice, Default: BGR
  • The channel mapping for the connected LEDs. If the mapping has 4 colors, the LED Values channel expects 4 values per pixel and if the mapping has 3 colors it expects 3 values per pixel. The LED Values channel always expects the order RGB(W). The connected LED driver chips might have their 3 or 4 channels in a different order. For example, the WS2801 chips typically use BGR order, then WS2812 chips typically use GRB order and the APA102 chips typically use WBGR order. The APA102 chips are special. They have three 8-bit channels for RGB and an additional 5-bit channel for the overall brightness of the RGB LED making them 4-channel chips. Internally the brightness channel is the first channel, therefore one of the Wxyz channel mappings should be used. Then the W channel controls the brightness.
  • Options: RGB, RBG, BRG, BGR, GRB, GBR, RGBW, RGWB, RBGW, RBWG, RWGB, RWBG, GRWB, GRBW, GBWR, GBRW, GWBR, GWRB, BRGW, BRWG, BGRW, BGWR, BWRG, BWGR, WRBG, WRGB, WGBR, WGRB, WBGR, WBRG

  • Frame Duration – Type: integer, Default: 1000, Min: 0, Max: 65535
  • The frame duration in milliseconds. This configures how fast the Frame Started Channel will trigger.

  • Clock Frequency – Type: integer, Default: 1666666, Min: 10000, Max: 2000000
  • The frequency of the clock in Hz. The Bricklet will choose the nearest achievable frequency, which may be off by a few Hz. If you have problems with flickering LEDs, they may be bits flipping. You can fix this by either making the connection between the LEDs and the Bricklet shorter or by reducing the frequency. With a decreasing frequency your maximum frames per second will decrease too. The default value is 1.66MHz (1660000Hz).

  • 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

Frame Started

This channel is triggered directly after a new frame render is started. You should send the data for the next frame directly after this listener was triggered.

Type:
  • Trigger (system.trigger)
UID:
  • tinkerforge:brickletledstripv2:[UID]:BrickletLEDStripV2FrameStarted
Read only:
  • No
LED Values

The RGB(W) values for the LEDs. Changes will be applied the next time the Frame Started Channel triggers.

Command format is a ','-separated list of integers. The first integer is the index of the first LED to set, additional integers are the values to set. Values are between 0 (off) and 255 (on). If the channel mapping has 3 colors, you need to give the data in the sequence R,G,B,R,G,B,R,G,B,... if the channel mapping has 4 colors you need to give data in the sequence R,G,B,W,R,G,B,W,R,G,B,W...

The data is double buffered and the colors will be transfered to the LEDs when the next frame duration ends. You can set at most 2048 RGB values or 1536 RGBW values.

For example sending 2,255,0,0,0,255,0,0,0,255 will set the LED 2 to red, LED 3 to green and LED 4 to blue.

Type:
  • String
UID:
  • tinkerforge:brickletledstripv2:[UID]:BrickletLEDStripV2LEDValues
Read only:
  • No
All LEDs

This channel allows you to set a configurable amount of LEDs (up to 1536 RGBW LEDs or 2048 RGB LEDs) to the same color. If you want more fine-grained control over the LEDs, use the LED Values channel or the actions.

Type:
  • Color - Only HSBType commands are accepted. Updating the brightness without changing the hue (e.g. by sending a PercentType) may fail.
UID:
  • tinkerforge:brickletledstripv2:[UID]:BrickletLEDStripV2AllLEDs
Read only:
  • No
Parameters:
  • LED Count – Type: integer, Default: 0, Min: 0, Max: 2048
  • The number of LEDs to control.

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

Basic Actions

brickletLEDStripV2SetLEDValues(int index, int[] value)
Parameters:
  • index – Type: int, Range: [0 to 6144]
  • value – Type: int[], Length: variable, Range: [0 to 255]

Sets the RGB(W) values for the LEDs starting from index. You can set at most 2048 RGB values or 1536 RGBW values (6144 byte each).

To make the colors show correctly you need to configure the chip type (see the thing configuration) and a channel mapping (see the thing configuration) according to the connected LEDs.

If the channel mapping has 3 colors, you need to give the data in the sequence RGBRGBRGB... if the channel mapping has 4 colors you need to give data in the sequence RGBWRGBWRGBW...

The data is double buffered and the colors will be transfered to the LEDs when the next frame duration ends (see the thing configuration).

Generic approach:

  • Set the frame duration to a value that represents the number of frames per second you want to achieve.
  • Set all of the LED colors for one frame.
  • Wait for the Frame Started channel.
  • Set all of the LED colors for next frame.
  • Wait for the Frame Started channel.
  • And so on.

This approach ensures that you can change the LED colors with a fixed frame rate.

brickletLEDStripV2GetLEDValues(int index, int length)
Parameters:
  • index – Type: int, Range: [0 to 6144]
  • length – Type: int, Range: [0 to 6144]
Return Map:
  • value – Type: int[], Length: variable, Range: [0 to 255]

Returns length RGB(W) values starting from the given index.

If the channel mapping has 3 colors, you will get the data in the sequence RGBRGBRGB... if the channel mapping has 4 colors you will get the data in the sequence RGBWRGBWRGBW... (assuming you start at an index divisible by 3 (RGB) or 4 (RGBW)).

brickletLEDStripV2GetFrameDuration()
Return Map:
  • duration – Type: int, Unit: 1 ms, Range: [0 to 216 - 1], Default: 100

Returns the frame duration as set by the thing configuration.

brickletLEDStripV2GetSupplyVoltage()
Return Map:
  • voltage – Type: int, Unit: 1 mV, Range: [0 to 216 - 1]

Returns the current supply voltage of the LEDs.

brickletLEDStripV2GetClockFrequency()
Return Map:
  • frequency – Type: long, Unit: 1 Hz, Range: [10000 to 2000000], Default: 1666666

Returns the currently used clock frequency as set by the thing configuration.

brickletLEDStripV2GetChipType()
Return Map:
  • chip – Type: int, Range: See constants, Default: 2801

Returns the currently used chip type as set by the thing configuration.

The following constants are available for this function:

For chip:

  • val CHIP_TYPE_WS2801 = 2801
  • val CHIP_TYPE_WS2811 = 2811
  • val CHIP_TYPE_WS2812 = 2812
  • val CHIP_TYPE_LPD8806 = 8806
  • val CHIP_TYPE_APA102 = 102
brickletLEDStripV2GetChannelMapping()
Return Map:
  • mapping – Type: int, Range: See constants, Default: 36

Returns the currently used channel mapping as set by the thing configuration.

The following constants are available for this function:

For mapping:

  • val CHANNEL_MAPPING_RGB = 6
  • val CHANNEL_MAPPING_RBG = 9
  • val CHANNEL_MAPPING_BRG = 33
  • val CHANNEL_MAPPING_BGR = 36
  • val CHANNEL_MAPPING_GRB = 18
  • val CHANNEL_MAPPING_GBR = 24
  • val CHANNEL_MAPPING_RGBW = 27
  • val CHANNEL_MAPPING_RGWB = 30
  • val CHANNEL_MAPPING_RBGW = 39
  • val CHANNEL_MAPPING_RBWG = 45
  • val CHANNEL_MAPPING_RWGB = 54
  • val CHANNEL_MAPPING_RWBG = 57
  • val CHANNEL_MAPPING_GRWB = 78
  • val CHANNEL_MAPPING_GRBW = 75
  • val CHANNEL_MAPPING_GBWR = 108
  • val CHANNEL_MAPPING_GBRW = 99
  • val CHANNEL_MAPPING_GWBR = 120
  • val CHANNEL_MAPPING_GWRB = 114
  • val CHANNEL_MAPPING_BRGW = 135
  • val CHANNEL_MAPPING_BRWG = 141
  • val CHANNEL_MAPPING_BGRW = 147
  • val CHANNEL_MAPPING_BGWR = 156
  • val CHANNEL_MAPPING_BWRG = 177
  • val CHANNEL_MAPPING_BWGR = 180
  • val CHANNEL_MAPPING_WRBG = 201
  • val CHANNEL_MAPPING_WRGB = 198
  • val CHANNEL_MAPPING_WGBR = 216
  • val CHANNEL_MAPPING_WGRB = 210
  • val CHANNEL_MAPPING_WBGR = 228
  • val CHANNEL_MAPPING_WBRG = 225

Advanced Actions

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

brickletLEDStripV2GetStatusLEDConfig()
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
brickletLEDStripV2GetSPITFPErrorCount()
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.

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

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