Deutsch
English
Menu
Software / API Bindings / openHAB / API Reference and Examples / Bricklets / Air Quality Bricklet

openHAB - Air Quality 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 Air Quality Bricklet. General information and technical specifications for the Air Quality Bricklet are summarized in its hardware description.

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

Thing

UID:
  • tinkerforge:brickletairquality:[UID]
Required firmware version:
  • 2.0.3
Firmware update supported:
  • yes
Channels:
Actions:
Parameters:
  • Temperature Offset – Type: decimal, Default: 0, Min: -21474836.48, Max: 21474836.47
  • If you install this Bricklet into an enclosure and you want to measure the ambient temperature, you may have to decrease the measured temperature by some value to compensate for the error because of the heating inside of the enclosure. We recommend that you leave the parts in the enclosure running for at least 24 hours such that a temperature equilibrium can be reached. After that you can measure the temperature directly outside of enclosure and set the difference as offset. This temperature offset is used to calculate the relative humidity and IAQ index measurements. In case the Bricklet is installed in an enclosure, we recommend to measure and set the temperature offset to imporve the accuracy of the measurements.

  • IAQ Index Update Interval – Type: integer, Default: 1000, Unit: ms, Min: 0, Max: 4294967295
  • Specifies the update interval for the IAQ index and accuracy in milliseconds. A value of 0 disables automatic updates.

  • 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

Humidity

The measured relative humidity

Type:
  • Number:Dimensionless
UID:
  • tinkerforge:brickletairquality:[UID]:BrickletAirQualityHumidity
Read only:
  • Yes
Unit:
  • Percent
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.
Temperature

The measured temperature

Type:
  • Number:Temperature
UID:
  • tinkerforge:brickletairquality:[UID]:BrickletAirQualityTemperature
Read only:
  • Yes
Unit:
  • Celsius
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.
Air Pressure

Messured air pressure

Type:
  • Number:Pressure
UID:
  • tinkerforge:brickletairquality:[UID]:BrickletAirQualityAirPressure
Read only:
  • Yes
Unit:
  • Bar
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.
IAQ Index

The IAQ index goes from 0 to 500. The higher the IAQ index, the greater the level of air pollution.

Type:
  • Number:Dimensionless
UID:
  • tinkerforge:brickletairquality:[UID]:BrickletAirQualityIAQIndex
Read only:
  • Yes
Range:
  • 0 to 500 (Step 1)
IAQ Index Accuracy

The Bricklet is building a database of measurements and uses this data to do an automatic background calibration and calculate an accurate IAQ index over time. It will take a few days until the IAQ index has a high reliability.

The IAQ accuracy is reflects the current state of the background calibration process.

Accuracy 0: The Bricklet was just started and the sensor is stabilizing. Accuracy 1: The background history is uncertain. This typically means the gas sensor data was too stable for the calibration algorithm to clearly define its references. Accuracy 2: The Bricklet found new calibration data and is currently calibrating. Accuracy 3: The Bricklets is calibrated successfully.

The effective duration of the calibration process depends on the stimuli observed by the sensor. An IAQ accuracy going back and fourth between 2 and 3 is expected, the Bricklet is recalibrating itself.

The Bricklet saves the current database of values and calculated coefficients every 12 hours in its internal flash memory. If the Bricklet loses power it will not take as long to receive reliable data again.

Starting with firmware version 2.0.3 the automatic background calibration considers 28 days of data. We recommend that you run the Bricklet for 28 full days before you consider the data as completely reliable. It is possible to reduce the calibration window to 4 days with the API.

Note

The currently released firmware (2.0.4) does not save the calibration every 12 hours. We had to disable this because of a bug in the proprietary load/save mechanism that we can't fix. We will release a new firmware that has this enabled again as soon as this bug is fixed.

Type:
  • Number:Dimensionless
UID:
  • tinkerforge:brickletairquality:[UID]:BrickletAirQualityIAQIndexAccuracy
Read only:
  • Yes

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

Basic Actions

brickletAirQualityGetAllValues()
Return Map:
  • iaqIndex – Type: int, Range: [0 to 500]
  • iaqIndexAccuracy – Type: int, Range: See constants
  • temperature – Type: int, Unit: 1/100 °C, Range: [-231 to 231 - 1]
  • humidity – Type: int, Unit: 1/100 %, Range: [-231 to 231 - 1]
  • airPressure – Type: int, Unit: 1/100 hPa, Range: [-231 to 231 - 1]

Returns all values measured by the Air Quality Bricklet. The values are IAQ (Indoor Air Quality) Index (higher value means greater level of air pollution), IAQ Index Accuracy, Temperature, Humidity and Air Pressure.

Air Quality Index description

The following constants are available for this function:

For iaqIndexAccuracy:

  • val ACCURACY_UNRELIABLE = 0
  • val ACCURACY_LOW = 1
  • val ACCURACY_MEDIUM = 2
  • val ACCURACY_HIGH = 3
brickletAirQualityGetTemperatureOffset()
Return Map:
  • offset – Type: int, Unit: 1/100 °C, Range: [-231 to 231 - 1]

Returns the temperature offset as set by the thing configuration.

brickletAirQualityGetIAQIndex()
Return Map:
  • iaqIndex – Type: int, Range: [0 to 500]
  • iaqIndexAccuracy – Type: int, Range: See constants

Returns the IAQ index and accuracy. The higher the IAQ index, the greater the level of air pollution.

IAQ index description

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

The following constants are available for this function:

For iaqIndexAccuracy:

  • val ACCURACY_UNRELIABLE = 0
  • val ACCURACY_LOW = 1
  • val ACCURACY_MEDIUM = 2
  • val ACCURACY_HIGH = 3
brickletAirQualityGetTemperature()
Return Map:
  • temperature – Type: int, Unit: 1/100 °C, Range: [-231 to 231 - 1]

Returns temperature.

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

brickletAirQualityGetHumidity()
Return Map:
  • humidity – Type: int, Unit: 1/100 %, Range: [-231 to 231 - 1]

Returns relative humidity.

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

brickletAirQualityGetAirPressure()
Return Map:
  • airPressure – Type: int, Unit: 1/100 hPa, Range: [-231 to 231 - 1]

Returns air pressure.

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

Advanced Actions

brickletAirQualityGetBackgroundCalibrationDuration()
Return Map:
  • duration – Type: int, Range: See constants, Default: 1

Returns the background calibration duration as set by This function is not available in openHAB. Please use Brick Viewer to change persistant device settings.

The following constants are available for this function:

For duration:

  • val DURATION_4_DAYS = 0
  • val DURATION_28_DAYS = 1

New in version 2.0.3 (Plugin).

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

brickletAirQualityGetStatusLEDConfig()
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
brickletAirQualityGetSPITFPErrorCount()
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.

brickletAirQualityReset()

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!

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

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