uThing::VOC Configuration¶

The uThing::VOC device can be configured through its serial interface using two distinct modes: Interactive and JSON.

Configuration Modes¶

Interactive Mode

The interactive mode is designed for simplicity and ease of use directly from a serial terminal. All commands are a single character followed by the Enter key.

For example, to send the C command via a Linux/macOS terminal, you would use:

$ printf 'C\n' > /dev/ttyACM0

JSON Mode

The JSON mode is intended for programmatic control. Commands are sent as a valid JSON object string. You can combine multiple commands into a single JSON object.

For example, to enable the LED, set the reporting period to 30 seconds, and change the format to CSV all at once, you would send:

{"led":true,"reportingPeriod":30,"format":"CSV"}

Note

For both modes, the device returns a status report after every command to confirm that it was received and processed correctly.

Commands¶

Below are the available commands to configure the uThing::VOC.

Reporting Format¶

This command changes the format of the periodic data output.

Interactive

Command	Format
`J`	JSON
`C`	CSV
`M`	Human-Readable

JSON

Command	Format
`{"format":"json"}`	JSON
`{"format":"csv"}`	CSV
`{"format":"human"}`	Human-Readable

Reporting Period¶

This command changes how often the device sends a data report.

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":<seconds>}`	An integer from 1 to 3600.

LEDs¶

This command enables or disables the onboard status LEDs.

Interactive

Command	State
`E`	Enabled
`D`	Disabled

JSON

Command	State
`{"led":true}`	Enabled
`{"led":false}`	Disabled

Temperature Calibration¶

This command applies a temperature offset to the sensor reading. Since the value can have multiple characters (e.g., -1.23), this command is only available in JSON mode.

Understanding Temperature Calibration

The BSEC library accepts a temperature offset to account for self-heating from components on the PCB (like the MCU and LDO) and heat conducted from the host device (PC, USB hub, etc.).

The uThing::VOC™ is calibrated for ambient temperature while connected to a standard USB hub. If you plug the dongle into a hotter system (like a laptop's exhaust-side port), the reported temperature will likely be higher due to heat transfer. The temperature can also fluctuate if other power-hungry devices are plugged into the same hub.

In setups where the host's heat output is dynamic (e.g., a Raspberry Pi under varying CPU load), achieving a perfect ambient temperature calibration can be challenging.

If precise temperature values are critical for your application, consider: 1. Connecting the device via a USB extension cable to reduce heat transfer from the host. 2. Disabling the LEDs. While the power usage is low (~10mW), the LED is close to the sensor and disabling it can help minimize self-heating.

JSON

Command	Detail
`{"temperatureOffset":<offset>}`	A positive or negative floating-point number.

Note

A negative offset can be used if the reported temperature is lower than the actual ambient temperature.

Save Configuration¶

This command saves the current settings to the device's permanent flash memory. The saved configuration will be retained after the device is unplugged and reconnected. This command is only available in JSON mode.

JSON

Command	Detail
`{"saveConfig":true}`	Stores the current configuration in Flash memory.

Status¶

This command retrieves the device's current configuration and status.

Interactive

Command	Detail
`S`	Retrieves device info, configuration, and uptime.

Example 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	Detail
`{"status":true}`	Retrieves the current configuration and uptime.

Example Response:

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

Device Info¶

This command retrieves static information about the device hardware, firmware, and serial number. This command is only available in JSON mode.

Interactive Mode

In Interactive mode, this information is already included in the Status command (S).

JSON

Command	Detail
`{"info":true}`	Retrieves device hardware, firmware, and serial number.

Example Response:

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

Help & Commands Summary¶

Invalid Command Response¶

In interactive mode, sending an invalid character (e.g., h) will print a help message summarizing the available commands.

-------------------------------------------------------
***  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.
--------------------------------------------------------

Commands Summary Table¶

The table below summarizes the commands available in firmware 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	n/a	`{"temperatureOffset":<number>}`	Set temperature compensation (±)
Save Config	n/a	`{"saveConfig":true}`	Save configuration parameters to flash
Status	`S`	`{"status":true}`	Show current configuration and uptime
Device Info	(`S`)	`{"info":true}`	Show device hardware, firmware, and serial