Device configuration

About this section

This section corresponds to the firmware version 1.2.1 (released on 28.03.2020). If you have an older version of the device, please check the documentation for the v1.0. Please also note that it's relatively simple to update the firmware on your board, check here for detailed instructions.

Configuration commands

Interactive mode

For simplicity, in interactive mode all commands are 1 character long, (plus the Enter,line-feed, '\n', ASCII 0x0D). In case the command is sent through the CLI: $ printf 'C\n' > /dev/ttyACM0

JSON mode

The user should ensure that the string to send is a valid json object (programatically or you could use a linter, like https://jsonlint.com for instance).

The commands can also be combined in one JSON object. For example: {"led":true,"reportingPeriod":30,"format":"CSV"}

NOTE: For both modes. A status report is always returned after a command. This helps to ensure that the command was received properly.

Reporting format

Interactive

Command	Format
J	JSON
C	CSV
M	HUMAN

JSON

Command	Format
{"format":"json"}	JSON
{"format":"csv"}	CSV
{"format":"human"}	HUMAN

Reporting period

Interactive

Command	Reporting period
1	3 seconds (default)
2	10 seconds
3	30 seconds
4	1 minute
5	10 minutes
6	30 minutes
7	1 hour

JSON

Command	Reporting period
{"reportingPeriod":integer}	in seconds (min 1, max. 3600)

LEDs On/Off

Interactive

Command	State
E	Enabled
D	Disabled

JSON

Command	State
{"led":boolean}	true/false (Enabled/disabled)

Temperature calibration

Temperature calibration

The BSEC library accepts a temperature offset input to account for the system self-heating from other components in the PCB as the MCU, LDO, etc., as well as the heat conducted from the USB-hub or Host where the device is connected.

The uThing::VOC™ has been calibrated for ambient temperature while connected to a USB hub. If the dongle is plugged into a hotter system (PC, gateway, etc.) the output temperature is expected to be higher due to the heat transferred to the device. The temperature seen by the sensor could also change when you plug more devices to an USB hub.

In some setups, like the dongle connected to a RaspberryPi for instance, where the heat generated by the CPU highly depends on its load, a "perfect" calibration with ambient temperature may be even impossible due to this dynamic change.

If precise temperature values are important for your use case, the device can be connected through an USB extension instead, reducing the heat transfered from the host device. In addition, you can disable the LEDs. The power used by the Blue LED is not much (~10mW) but it's close enough to the sensor, so it may help to reduce the self-heating.

Since the value can have multiple characters (i.e. "-1.23"), this command is only available for the JSON mode:

Command	Detail
{"temperatureOffset": number}	Float number (±)

NOTE: The value can be also a negative number (if the reported temperature is lower than the ambient temperature for example).

Save configuration

This command is only available for the JSON mode, and it saves the configuration in permanent storage (it's mantained after reconnecting the device):

Command	Detail
{"saveConfig": true}	Store the configuration in Flash memory

Status

Interactive

Command	Detail
S	Retrieves the device, firmware, serial number, configuration and uptime (in ms)

Status response:

--------------------------------------------------------
***  Device: *"uThing::VOC rev.A"* -- Status:
 Reporing period: 3 sec, Format: JSON, Temp.Offset: 0.25 C, Uptime: 1546971 ms, Serial #: 27D521601B89CE9A, FW: v1.2.1
--------------------------------------------------------

JSON

Command	State
{"status":true}	Retrieves the configuration and uptime (in ms)

Status response:

{
    "status": {
        "reportingPeriod": 3,
        "format": "JSON",
        "temperatureOffset:": 0.2,
        "upTime": 1802065
    }
}

Info

This is available only in JSON since the same information is returned for the status command in interactive mode:

Command	State
{"info":true}	Retrieves the device information (HW, FW and Serial number)

Response:

{
    "info": {
        "device": "uThing::VOC rev.A",
        "serial": "27D521601B89CE9A",
        "firmware": "1.2.1"
    }
}

Commands summary

The table below summarizes the commands available in FW v1.2.1:

Command	Interactive	JSON	Description
Format	[J, C, M]	{"format":"string"}	Change reporting format (JSON, CSV, HUMAN)
Period	[1-7]	{"reportingPeriod":integer}	Change reporting period
LEDs	[E, D]	{"led":boolean}	Enable / Disable LEDs
Temp. Offset	not-available	{"temperatureOffset": number}	Temperature compensation, (±)
SaveConfig	not-available	{"saveConfig":true}	Save configuration parameters
Status	[S]	{"status":true}	Show actual configuration
DeviceInfo	[S]	{"info":true}	Show device info

The commands for the interactive mode will also be printed when an invalid character is sent (the letter 'h' for example):

-------------------------------------------------------
***  Invalid option.
 Use:              [m] Human readable, [j] JSON, [c] CSV, [s] Status, [e/d] enable/disable LED
 Reporting Period: [1] 3 sec, [2] 10 sec, [3] 30 sec, [4] 1 min, [5] 10 min, [6] 30 min, [7] 1 hour.
--------------------------------------------------------