openHAB - Ambient Light Bricklet 2.0

This is the description of the openHAB API bindings for the Ambient Light Bricklet 2.0. General information and technical specifications for the Ambient Light 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:brickletambientlightv2:[UID]
Required firmware version:
  • 2.0.0
Firmware update supported:
  • yes
Channels:
Actions:
Parameters:
  • Illuminance Range – Type: Choice, Default: 8000Lux
  • The unlimited illuminance range allows to measure up to about 100000lux, but above 64000lux the precision starts to drop. A smaller illuminance range increases the resolution of the data. If the actual measure illuminance is out-of-range then the current illuminance range maximum +0.01lux is reported. For example, 8000.01 for the 0-8000lux range. If the measurement is out-of-range or the sensor is saturated then you should configure the next higher illuminance range. If the highest range is already in use, then start to reduce the integration time.
  • Options: Unlimited, 64000Lux, 32000Lux, 16000Lux, 8000Lux, 1300Lux, 600Lux

  • Integration Time – Type: Choice, Default: 200ms
  • A longer integration time will result in less noise on the data. With a long integration time the sensor might be saturated before the measured value reaches the maximum of the selected illuminance range. In this case 0lux is reported. If the measurement is out-of-range or the sensor is saturated then you should configure the next higher illuminance range. If the highest range is already in use, then start to reduce the integration time.
  • Options: 50ms, 100ms, 150ms, 200ms, 250ms, 300ms, 350ms, 400ms

Channels

Illuminance

The illuminance of the ambient light sensor. The measurement range goes up to about 100000lux, but above 64000lux the precision starts to drop. An illuminance of 0lux indicates that the sensor is saturated and the configuration should be modified.

Type:
  • Number:Illuminance
UID:
  • tinkerforge:brickletambientlightv2:[UID]:BrickletAmbientLightV2Illuminance
Read only:
  • Yes
Unit:
  • Lux
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.

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

Basic Actions

brickletAmbientLightV2GetIlluminance()
Return Map:
  • illuminance – Type: long, Unit: 1/100 lx, Range: [0 to 232 - 1]

Returns the illuminance of the ambient light sensor. The measurement range goes up to about 100000lux, but above 64000lux the precision starts to drop.

Changed in version 2.0.2 (Plugin): An illuminance of 0lux indicates that the sensor is saturated and the configuration should be modified, see the thing configuration.

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

Advanced Actions

brickletAmbientLightV2GetConfiguration()
Return Map:
  • illuminanceRange – Type: short, Range: See constants, Default: 3
  • integrationTime – Type: short, Range: See constants, Default: 3

Returns the configuration as set by the thing configuration.

The following constants are available for this function:

For illuminanceRange:

  • val ILLUMINANCE_RANGE_UNLIMITED = 6
  • val ILLUMINANCE_RANGE_64000LUX = 0
  • val ILLUMINANCE_RANGE_32000LUX = 1
  • val ILLUMINANCE_RANGE_16000LUX = 2
  • val ILLUMINANCE_RANGE_8000LUX = 3
  • val ILLUMINANCE_RANGE_1300LUX = 4
  • val ILLUMINANCE_RANGE_600LUX = 5

For integrationTime:

  • val INTEGRATION_TIME_50MS = 0
  • val INTEGRATION_TIME_100MS = 1
  • val INTEGRATION_TIME_150MS = 2
  • val INTEGRATION_TIME_200MS = 3
  • val INTEGRATION_TIME_250MS = 4
  • val INTEGRATION_TIME_300MS = 5
  • val INTEGRATION_TIME_350MS = 6
  • val INTEGRATION_TIME_400MS = 7
brickletAmbientLightV2GetIdentity()
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 as position 'z'.

The device identifier numbers can be found here