Deutsch
English
Menu
Software / API Bindings / openHAB / API Reference and Examples / Bricklets / Ambient Light Bricklet 3.0

openHAB - Ambient Light Bricklet 3.0

Bemerkung

Die openHAB-Dokumentation ist nur auf Englisch verfügbar.

Warnung

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

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

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

Thing

UID:
  • tinkerforge:brickletambientlightv3:[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: 150ms
  • 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

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

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

Basic Actions

brickletAmbientLightV3GetIlluminance()
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. The illuminance is given in lux/100, i.e. a value of 450000 means that an illuminance of 4500lux is measured.

An illuminance of 0lux indicates an error condition where the sensor cannot perform a reasonable measurement. This can happen with very dim or very bright light conditions. In bright light conditions this might indicate that the sensor is saturated and the configuration should be modified (the thing configuration) to better match the conditions.

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

brickletAmbientLightV3GetConfiguration()
Return Map:
  • illuminanceRange – Type: int, Range: See constants, Default: 3
  • integrationTime – Type: int, Range: See constants, Default: 2

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

Advanced Actions

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

brickletAmbientLightV3GetStatusLEDConfig()
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
brickletAmbientLightV3GetSPITFPErrorCount()
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.

brickletAmbientLightV3Reset()

Calling this function will reset the Bricklet. All configurations will be lost.

After a reset you have to create new device objects, calling functions on the existing ones will result in undefined behavior!

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

Internal Actions

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