Environmental Board User Manual

Table of contents


Rev. Number Author Checked Approved
Rev# 1.0: 2018-09-20 as    
Rev# 1.1: 2018-09-25 as ml
Rev# 1.2: 2019-05-23 kd  



  • Node - A wireless Vicotee sensor node.
  • End Point - Gateway/Server where sensor data is aggregated.
  • Driver - A specific set of instructions used to configure and read measurement data from sensor(s).
  • Driver Index - Memory location where driver is stored
  • Driver Type - A unique numerical value which identifies the driver
  • Sensor Type - same as Driver Type
  • Sequence - A set of instructions within a driver
  • Sequence Type - Numerical value which identifies return type of the measurement
  • Measurement Type - same as Sequence Type
  • Step - A single instruction within a sequence
  • IAQ - Indoor air quality index.
  • dBSPL - Acoustic Pressure referenced to 1 Pa
  • Lux - Illuminance unit, defines luminous flux per unit area.
  • VEB - Vicotee Environmental Board
  • vicpack - Python based parser class used to convert raw mesurements in to human-readable format.
  • viccmd - Python based class used to generate configuration commands destined for Vicotee nodes.


Device Description

Vicotee's Environmental Sensor Board is a complete solution for indoor environmental sensing covering HSE (Health and Safety Executive) needs in workspace environments. VEB consists of three individually controlled sensors which together provide a complete picture of : indoor air quality, temperature, humidity, pressure, ambient light intensity, and local acoustic pressure.

Air Quality Sensor

IAQ sensor is a single device which consists of four sub-sensors (gas resistance, temperature, humidity, pressure) which are capable of detecting a broad range of gases such as Volatile Organic Compounds from paints, lacquers, paint strippers, and glues. The presence of these harmful compounds are converted into an IAQ index which is a standardized way of expressing the overall pollution factor of the environment. IAQ index has a total range of 0 to 500 with the following sub-ranges:

IAQ Index Air Quality
0-50 Excellent
51-100 Good
101-150 Fair
151-200 Poor
201-300 Bad
301-500 Inadequate

The sensor will automatically calibrate itself based on its background history so that typically good air are represented by values of ~25 IAQ and typically bad air by values of ~250 IAQ. Values above or below these marks would be expected if the air quality observed by the sensor is significantly outside of sensor's current calibration bounds and while sensor is re-calibrating.

In addition to IAQ index VEB will also provide a parameter called iaq_state which defines current state of the Air Quality sensor, this parameter can be used to assess the reliability of the IAQ index currently being delivered.

IAQ State Description
0 Air Quality sensor needs to stabilize to its new environment.
1 Air Quality sensor's history is uncertain, new calibration is needed.
2 A new extremum in air quality has been detected, sensor is now being calibrated.
3 Calibration is done, sensor is running with optimal performance.

Initially, IAQ will remain fixed at 25 for at least 20 minutes, after which it will automatically switch to 1. A transition from 1 to 2 will require some time if the air quality is fairly constant. Once transition to 3 has occurred, you may notice the IAQ state may transition back to 2, this is normal and only means that a new extremum has been detected and the Air Quality sensor needs to adjust its parameters. Sensor to sensor deviation should not exceed +/- 15 %.

In addition to IAQ index and state, IAQ sensor will also sample and report temperature, humidity, and atmospheric pressure parameters. These parameters are sampled at exactly the same time as IAQ index and state and can not be disabled. It is, however, possible to modify the bundled driver and remove these parameters and thus reducing time-on-air while transmitting.


Ambient Light Sensor

Ambient light sensor has a high dynamic range, capable of measuring light intensity levels from 0.01 lux to 83000 lux with an effective range of 23 bits. Ambient light sensor is designed to match response of the Human Eye, rejecting over 99% of IR wavelengths.


Acoustic Pressure

==Is some text missing here?==


Operational Parameters

Driver Locations

The following table describes driver placement for the devices shipped with VEB:

Driver Index Driver Type Measurements
0 Reserved RF module n/a
1 Reserved RF module n/a
2 VEB, Air Quality IAQ, IAQ State, Temperature, Humidity, Pressure
3 VEB, Ambient Light Ambient Light
4 VEB, Acoustic Pressure Acoustic Pressure
5 n/a n/a
6 n/a n/a


Configuration Parameters

Each driver can be disabled and then later enabled if the user wishes to conserve battery and extend the lifetime of the sensor or if some of the reported parameters are unwanted. It can also be desirable to enable certain drivers only within certain time periods. This requires the backend to transmit commands to enable/disable certain drivers at predefined times, as the nodes only record time relative to their last reset.

Consider the following example:

import viccmd as vic

cmd = vic.viccmd ()
cmd.add ('set_drv 0 4')         # select Acoustic Pressure sensor driver
cmd.add ('ena_drv false')       # disable driver
cmd.add ('store_drv true')      # optional command which will permanently disable driver
array = cmd.get_int_array ()

The code snippet above will, when transmitted to the end device, disable driver at index 4 and, optionally, store the configuration to flash memory, thereby completely disabling the driver even after reboot. As mentioned in Driver Locations driver 4 corresponds to Acoustic Pressure sensor. The same logic applies to every other driver bundled with this board.

For modifying the sample rate of a given driver, consider the following example:

import viccmd as vic

cmd = viccmd ()
cmd.add ('set_drv 0 3')         # select Ambient Light sensor
cmd.add ('set_rate 300000')     # set sample rate to 5 minutes (300000 ms)
cmd.add ('store_drv true')      # optional command which will store sample rate
array = cmd.get_int_array ()

The code snippet above will change sample rate of the Ambient Light sensor to 5 minutes, optionally it is possible to store this new sample rate to flash memory as indicated in the snippet so that the sample rate will be retained even if the device is rebooted. When modifying sample rate, please consider the effect it will have on the radio network that the node is connected to. Some radio networks, such as LoRaWan, have certain air-time restrictions which must be observed.

Each sensor within the Environmental board can be individually controlled via its corresponding driver, hence each sensor can have an individual sample rate. The exception to the rule is the Air Quality Sensor, it has an internal update rate of 5 minutes, meaning that there is no reason to poll it more frequent than that. The Acoustic pressure sensor, on the other hand has an additional timer associated with it, which defines the sampling time, i.e. timespan, of a measurement. Default value is set to 10 seconds, meaning that at a given interval, defined by the driver, the Acoustic pressure sensor will sample its input for 10 seconds. In order to modify the sampling time, user can use the snippet below.

import viccmd as vic

time = 20                   # integration time (1 - 255) seconds

cmd = vic.viccmd ()
cmd.add ('set_drv 3 4')     # select Acoustic Pressure sensor driver
cmd.add ('mod_param 6 0x08 0x03 0x01 0x03 0x{:x}'.format(time))
cmd.add ('set_drv 3 4')
cmd.add ('exe_seq false')
array = cmd.get_int_array ()

The snippet above will modify the existing sampling time to a value given by time and will force the driver to re-initialize itself with new values. To retain newly applied values even after power-down or reboot event the following command must be sent.

import viccmd as vic

cmd = vic.viccmd ()
cmd.add ('set_drv 0 4')         # select Acoustic Pressure sensor driver
cmd.add ('store_drv true')      # store current driver to flash
array = cmd.get_int_array ()



Vicpack module available on GitHub can be used to parse an incoming bitstream into human-readable values as well as export measurement data into json format. The following assumptions are made:

  • Payload is supplied as string
  • Payload contains only valid hexadecimal values
  • Each byte must be represented by two characters.
  • Prepending identifiers such as 0x, 0h are not allowed
  • Spaces or tabs are not allowed

Consider example below

import vicpack as vic

pack = vic.vicpack ()
pack.add ("FA0117000501110002012B0000F4812C000000012D000078082E0000CA27CE53CD")
pack.detail = True
pack.prefix = False

print pack              # print out human-readable values
print pack.export ()    # print measurements as json string

Please note that when utilizing Vicotee Cloud as an end-point or as a forwarder, vicpack is not required due to automatic parsing and interpreting of results within Vicotee Cloud.



IAQ Sensor is stuck at state 1

This is typically caused by low air circulation within the sensing area. Based on history the IAQ sensor is unable to determine lower and upper range of expected values and hence, needs either more time or external excitation in order to enter calibrated state. A normal marker pen or any alcohol containing substance can be used as excitation source for testing purposes only. The excitation source must be placed near sensing area for 5 to 10 minutes.


IAQ Sensor reports same data when sample rate is around 5 minutes

This is intended mode of operation, to conserve battery the internal sample rate is fixed at 5 minutes, hence there is no reason to sample more frequently than 5 minutes.


Ambient Light / Acoustic pressure data is delayed by one sample

Due to deferred processing/acquisition model samples will be delayed by one sample. This is intended mode of operation and cannot be changed.