Deutsch
English
Menu
Software / API Bindings / openHAB / API Reference and Examples / Bricklets (Discontinued) / LED Strip Bricklet

openHAB - LED Strip Bricklet

Warning

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

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

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

Thing

UID:
  • tinkerforge:brickletledstrip:[UID]
Required firmware version:
  • 2.0.6
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.

  • Enable Frame Started Channel – Type: boolean, Default: false
  • Enables the frame started channel. This will result in a lot of spam in the openhab Log!

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:brickletledstrip:[UID]:BrickletLEDStripFrameStarted
Read only:
  • No
Predicate:
  • This channel will only be available if Enable Frame Started Channel is enabled.
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 (not the first value!) to set, additional integers are the values to set. 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 960 values (320 RGB or 240 RGBW LEDs).

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:brickletledstrip:[UID]:BrickletLEDStripLEDValues
Read only:
  • No
All LEDs

This channel allows you to set a configurable amount of LEDs (up to 240 RGBW LEDs or 320 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:brickletledstrip:[UID]:BrickletLEDStripAllLEDs
Read only:
  • No
Parameters:
  • LEDs – Type: integer, Default: 0, Min: 0, Max: 320
  • 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:brickletledstrip:[UID]")
val hwVersion = actions.brickletLEDStripGetIdentity().get("hardwareVersion") as short[]
logInfo("Example", "Hardware version: " + hwVersion.get(0) + "." + hwVersion.get(1) + "." + hwVersion.get(2))

Basic Actions

brickletLEDStripSetRGBValues(int index, short length, short[] r, short[] g, short[] b)
Parameters:
  • index – Type: int, Range: [0 to 319]
  • length – Type: short, Range: [0 to 16]
  • r – Type: short[], Length: 16, Range: [0 to 255]
  • g – Type: short[], Length: 16, Range: [0 to 255]
  • b – Type: short[], Length: 16, Range: [0 to 255]

Sets length RGB values for the LEDs starting from index.

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

Example: If you set

  • index to 5,
  • length to 3,
  • r to [255, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  • g to [0, 255, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0] and
  • b to [0, 0, 255, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]

the LED with index 5 will be red, 6 will be green and 7 will be blue.

Note

Depending on the LED circuitry colors can be permuted.

The colors will be transfered to actual 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.

The actual number of controllable LEDs depends on the number of free Bricklet ports. See here for more information. A call of LED Values with index + length above the bounds is ignored completely.

brickletLEDStripGetRGBValues(int index, short length)
Parameters:
  • index – Type: int, Range: [0 to 319]
  • length – Type: short, Range: [0 to 16]
Return Map:
  • r – Type: short[], Length: 16, Range: [0 to 255]
  • g – Type: short[], Length: 16, Range: [0 to 255]
  • b – Type: short[], Length: 16, Range: [0 to 255]

Returns length R, G and B values starting from the given LED index.

The values are the last values that were set by LED Values.

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

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

Returns the current supply voltage of the LEDs.

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

New in version 2.0.1 (Plugin).

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

New in version 2.0.2 (Plugin).

brickletLEDStripSetRGBWValues(int index, short length, short[] r, short[] g, short[] b, short[] w)
Parameters:
  • index – Type: int, Range: [0 to 239]
  • length – Type: short, Range: [0 to 12]
  • r – Type: short[], Length: 12, Range: [0 to 255]
  • g – Type: short[], Length: 12, Range: [0 to 255]
  • b – Type: short[], Length: 12, Range: [0 to 255]
  • w – Type: short[], Length: 12, Range: [0 to 255]

Sets length RGBW values for the LEDs starting from index.

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

The maximum length is 12, the index goes from 0 to 239 and the rgbw values have 8 bits each.

Example: If you set

  • index to 5,
  • length to 4,
  • r to [255, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  • g to [0, 255, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  • b to [0, 0, 255, 0, 0, 0, 0, 0, 0, 0, 0, 0] and
  • w to [0, 0, 255, 0, 0, 0, 0, 0, 0, 0, 0, 0]

the LED with index 5 will be red, 6 will be green, 7 will be blue and 8 will be white.

Note

Depending on the LED circuitry colors can be permuted.

The colors will be transfered to actual 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.

The actual number of controllable LEDs depends on the number of free Bricklet ports. See here for more information. A call of LED Values with index + length above the bounds is ignored completely.

The LPD8806 LED driver chips have 7-bit channels for RGB. Internally the LED Strip Bricklets divides the 8-bit values set using this function by 2 to make them 7-bit. Therefore, you can just use the normal value range (0-255) for LPD8806 LEDs.

The brightness channel of the APA102 LED driver chips has 5-bit. Internally the LED Strip Bricklets divides the 8-bit values set using this function by 8 to make them 5-bit. Therefore, you can just use the normal value range (0-255) for the brightness channel of APA102 LEDs.

New in version 2.0.6 (Plugin).

brickletLEDStripGetRGBWValues(int index, short length)
Parameters:
  • index – Type: int, Range: [0 to 239]
  • length – Type: short, Range: [0 to 12]
Return Map:
  • r – Type: short[], Length: 12, Range: [0 to 255]
  • g – Type: short[], Length: 12, Range: [0 to 255]
  • b – Type: short[], Length: 12, Range: [0 to 255]
  • w – Type: short[], Length: 12, Range: [0 to 255]

Returns length RGBW values starting from the given index.

The values are the last values that were set by LED Values.

New in version 2.0.6 (Plugin).

brickletLEDStripGetChannelMapping()
Return Map:
  • mapping – Type: short, 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

New in version 2.0.6 (Plugin).

Advanced Actions

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