Explained¶

Understanding the JSON Response Structure¶

The REST API returns data in a structured JSON format. Understanding this structure is essential for working with device data effectively.

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": 121.55,
    "unit": "°C",
    "timestamp": "2025-12-12T01:48:28.714Z"
}

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": 121.55,
            "unit": "°C",
            "timestamp": "2025-12-12T01:48:28.714Z"
        }
    }
}

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., E22377).

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-RTD300-CAL")
• serial: Device serial number
• vendor: Manufacturer name
• model (string): Product model identifier linking to the products section

Example device entry:

{
    "E22377": {
        "channel_list": ["temperature"],
        "channels": {
            "temperature": {
                "period_ms": 100,
                "value": {
                    "magnitude": 121.55,
                    "unit": "°C",
                    "timestamp": "2025-12-12T01:48:28.714Z"
                }
            }
        },
        "info": {
            "firmware_version_major": 2,
            "firmware_version_minor": 4,
            "product": "VCP-RTD300-CAL",
            "serial": "E22377",
            "vendor": "Dracal technologies inc."
        },
        "model": "VCP-RTD300-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-RTD300-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
• info (object): Product information
• name: Product name
• vendor: Manufacturer
• sku: Stock keeping unit number
• interfaces: Supported communication protocols

Example product entry:

{
    "VCP-RTD300-CAL/v1": {
        "model": "VCP-RTD300-CAL/v1",
        "channels": {
            "temperature": {
                "label": "temperature",
                "description": "Temperature",
                "type": "Temperature",
                "unit": "°C",
                "details": {
                    "virtual": false
                }
            }
        },
        "info": {
            "name": "VCP-RTD300-CAL",
            "vendor": "Dracal technologies inc.",
            "sku": "605048",
            "interfaces": {
                "usb": "tenkiusb",
                "vcp": "tenkivcp"
            }
        }
    }
}

Putting It All Together¶

When working with the API response:

1. Start with devices to find connected devices by serial number
2. Check the model field to link to the product definition
3. Reference products for channel specifications and capabilities
4. Read channels for current sensor values with timestamps

This separation allows you to:

• Access real-time data from specific device instances
• Understand device capabilities from product specifications
• Build applications that adapt to different device models

Use the navigation menu on the left to explore the full documentation.