Explained¶

Values: The Building Blocks¶

Each sensor reading is represented as a value object containing three key components:

magnitude (number): The numerical measurement from the sensor
unit (string): The unit of measurement (e.g., "°C", "kPa", "mm")
timestamp (string): ISO 8601 timestamp in UTC indicating when the measurement was taken

Example value:

{
    "magnitude": 22.96,
    "unit": "°C",
    "timestamp": "2026-03-04T18:42:51.593Z"
}

Channels: Organizing Sensor Data¶

A channel represents a specific measurement type from a device (e.g., temperature, pressure, humidity). Each channel contains:

label (string): Unique identifier for the channel (e.g., "temperature")
period_ms (integer): Polling interval in milliseconds
value (object): The current sensor reading with magnitude, unit, and timestamp

Channels are organized under the channels object, with each channel identified by its label.

Example channel:

{
    "temperature": {
        "period_ms": 100,
        "value": {
            "magnitude": 22.96,
            "unit": "°C",
            "timestamp": "2026-03-04T18:42:51.593Z"
        }
    }
}

Channel List¶

The channel_list array enumerates every channel available on a device. It gives you a predictable, ordered list of channel names that act as keys into the channels object.

Example channel_list with corresponding channels subset:

{
    "channel_list": [
        "atmospheric_pressure",
        "temperature",
        "relative_humidity",
        "dew_point"
    ],
    "channels": {
        "atmospheric_pressure": {
            "period_ms": 100,
            "value": {
                "magnitude": 101.956,
                "unit": "kPa",
                "timestamp": "2026-03-04T18:42:51.593Z"
            }
        },
        "temperature": {
            "period_ms": 100,
            "value": {
                "magnitude": 22.96,
                "unit": "°C",
                "timestamp": "2026-03-04T18:42:51.593Z"
            }
        },
        "relative_humidity": {
            "period_ms": 100,
            "value": {
                "magnitude": 24.26,
                "unit": "%rh",
                "timestamp": "2026-03-04T18:42:51.593Z"
            }
        },
        "dew_point": {
            "period_ms": 100,
            "value": {
                "magnitude": 1.44,
                "unit": "°C",
                "timestamp": "2026-03-04T18:42:51.593Z"
            }
        }
    }
}

Every name in channel_list is guaranteed to have a matching entry in channels. Use channel_list to enumerate available channels rather than inspecting the channels object directly.

Devices: Instance-Specific Data¶

The devices section contains dynamic, real-time data for each connected device. Devices are keyed by their serial number (e.g., E22421).

Each device entry includes:

channel_list (array): List of available channel labels
channels (object): Current readings for each channel
config (object): Device configuration settings
connections (object): Current connection details (USB, VCP)
info (object): Device identification information
firmware_version_major and firmware_version_minor: Firmware version
product: Product name (e.g., "VCP-PTH450-CAL")
serial: Device serial number
vendor: Manufacturer name
model (string): Product model identifier linking to the products section

Example device entry:

{
    "E22421": {
        "channel_list": [
            "atmospheric_pressure",
            "temperature",
            "relative_humidity",
            "dew_point",
            "humidex",
            "heat_index",
            "altitude"
        ],
        "channels": {
            "atmospheric_pressure": {
                "period_ms": 100,
                "value": {
                    "magnitude": 101.956,
                    "unit": "kPa",
                    "timestamp": "2026-03-04T18:42:51.593Z"
                }
            },
            "temperature": {
                "period_ms": 100,
                "value": {
                    "magnitude": 22.96,
                    "unit": "°C",
                    "timestamp": "2026-03-04T18:42:51.593Z"
                }
            },
            "relative_humidity": {
                "period_ms": 100,
                "value": {
                    "magnitude": 24.26,
                    "unit": "%rh",
                    "timestamp": "2026-03-04T18:42:51.593Z"
                }
            },
            "dew_point": {
                "period_ms": 100,
                "value": {
                    "magnitude": 1.44,
                    "unit": "°C",
                    "timestamp": "2026-03-04T18:42:51.593Z"
                }
            },
            "humidex": {
                "period_ms": 100,
                "value": {
                    "magnitude": 21.17,
                    "unit": "°C",
                    "timestamp": "2026-03-04T18:42:51.593Z"
                }
            },
            "heat_index": {
                "period_ms": 100,
                "value": {
                    "magnitude": 22.96,
                    "unit": "°C",
                    "timestamp": "2026-03-04T18:42:51.593Z"
                }
            },
            "altitude": {
                "period_ms": 100,
                "value": {
                    "magnitude": -52393.89,
                    "unit": "mm",
                    "timestamp": "2026-03-04T18:42:51.593Z"
                }
            }
        },
        "config": {
            "protocol": {
                "usb": true,
                "vcp": true
            }
        },
        "connections": {
            "usb": {
                "address": 46,
                "bus": 2,
                "product_id": "0505",
                "vendor_id": "289B"
            },
            "vcp": null
        },
        "info": {
            "firmware_version_major": 2,
            "firmware_version_minor": 9,
            "product": "VCP-PTH450-CAL",
            "serial": "E22421",
            "vendor": "Dracal technologies inc."
        },
        "model": "VCP-PTH450-CAL/v1"
    }
}

Products: Model Definitions¶

The products section contains static specifications for each product model. This defines the capabilities and characteristics of device models, not individual device instances.

Products are keyed by their model identifier (e.g., VCP-PTH450-CAL/v1). The model field in each device entry links to its corresponding product definition.

Each product definition includes:

model (string): Unique model identifier
channels (object): Channel definitions for this product model
label: Channel identifier
description: Human-readable channel name
type: Data type (e.g., "Temperature", "Pressure")
unit: Unit of measurement
details: Additional channel properties (e.g., virtual: true for computed channels)
info (object): Product information
name: Product name
vendor: Manufacturer
sku: Stock keeping unit number
interfaces: Supported communication protocols

Example product entry:

{
    "VCP-PTH450-CAL/v1": {
        "model": "VCP-PTH450-CAL/v1",
        "channels": {
            "atmospheric_pressure": {
                "label": "atmospheric_pressure",
                "description": "Atmospheric pressure",
                "type": "Pressure",
                "unit": "Pa",
                "details": {
                    "virtual": false
                }
            },
            "temperature": {
                "label": "temperature",
                "description": "Temperature",
                "type": "Temperature",
                "unit": "°C",
                "details": {
                    "virtual": false
                }
            },
            "relative_humidity": {
                "label": "relative_humidity",
                "description": "Relative humidity",
                "type": "Humidity",
                "unit": "%rh",
                "details": {
                    "virtual": false
                }
            },
            "dew_point": {
                "label": "dew_point",
                "description": "Dew point",
                "type": "Temperature",
                "unit": "°C",
                "details": {
                    "virtual": true
                }
            },
            "humidex": {
                "label": "humidex",
                "description": "Humidex",
                "type": "Temperature",
                "unit": "°C",
                "details": {
                    "virtual": true
                }
            },
            "heat_index": {
                "label": "heat_index",
                "description": "Heat index",
                "type": "Temperature",
                "unit": "°C",
                "details": {
                    "virtual": true
                }
            },
            "altitude": {
                "label": "altitude",
                "description": "Altitude",
                "type": "Altitude",
                "unit": "m",
                "details": {
                    "virtual": true
                }
            }
        },
        "info": {
            "name": "VCP-PTH450-CAL",
            "vendor": "Dracal technologies inc.",
            "sku": "605081",
            "interfaces": {
                "usb": "tenkiusb",
                "vcp": "tenkivcp"
            }
        }
    }
}