Driver Configuration Reference

1. File structure

2. info

Device metadata shown in the Driver Library section.

3. connection

Defines transport settings. protocol and timeout apply to all transports. Serial fields are ignored for MODBUS_TCP; TCP fields are ignored for serial protocols. Topology entries can override any field — topology.json values take priority over driver defaults.

4. commands

Array of one or more measurement commands. Each command maps to a REST API endpoint /{device_id}/read/{parameter}.

 Multiple commands with the same write.cmd are batched — one serial request reads all their values simultaneously.

5. write

6. read

7. Protocol types

8. Parser types

9. Full example

STRING protocol — LT300 thermometer

// drivers/LT300.json
{
  "id":      "LT300",
  "enabled": true,
  "version": "1",
  "info": {
    "displayName":  "TermexLab LT300",
    "model":        "LT300",
    "manufacturer": "TermexLab",
    "type":         "thermometer"
  },
  "connection": {
    "protocol": "STRING",
    "baud":     4800,
    "parity":   0,
    "stopBit":  1,
    "timeout":  1000
  },
  "commands": [
    {
      "parameter": "TEMPERATURE",
      "unit":      "CELSIUS",
      "type":      "read",
      "write": { "cmd": "d\r" },   // send ASCII "d" + CR
      "read": {
        "parser": "[+-]?([0-9]*[.])?[0-9]+"  // extract last number
      }
    }
  ]
  }

BINARY (Modbus RTU) — IVA-6B2 thermohygrometer

// drivers/IVA6B2.json — two parameters, one request each
{
  "id": "IVA6B2", "enabled": true,
  "connection": { "protocol": "BINARY", "baud": 9600, "parity": 0, "stopBit": 1, "timeout": 1000 },
  "commands": [
    {
      "parameter": "TEMPERATURE", "unit": "CELSIUS", "type": "read",
      "write": { "cmd": "010300010001D5CA" },  // Read register 0x0001
      "read":  { "parser": "MODBUS_RTU", "bufsize": 7, "factor": 0.01 }
    },
    {
      "parameter": "RELATIVE_HUMIDITY", "unit": "%", "type": "read",
      "write": { "cmd": "010300000001840A" },  // Read register 0x0000
      "read":  { "parser": "MODBUS_RTU", "bufsize": 7, "factor": 0.01 }
    }
  ]
}

MODBUS_TCP — Generic Ethernet device

// drivers/GENERIC_MODBUS_TCP.json — Modbus TCP, single read-holding-register
{
  "id": "GENERIC_MODBUS_TCP", "enabled": true,
  "connection": {
    "protocol": "MODBUS_TCP",
    "host": "192.168.1.100",
    "tcp_port": 502,
    "unit_id": 1,
    "timeout": 1000
  },
  "commands": [
    {
      "parameter": "TEMPERATURE", "unit": "CELSIUS", "type": "read",
      "write": { "cmd": "0300010001" },  // PDU: func=03, addr=0x0001, count=1 (no MBAP here)
      "read":  { "parser": "MODBUS_TCP", "bufsize": 11, "factor": 0.1 }
    }
  ]
}

// config/topology.json — override host per instance
{
  "id": "temp-sensor-1",
  "driver_file": "GENERIC_MODBUS_TCP.json",
  "port": "TCP",
  "keep_alive": false,
  "enabled": true,
  "connection": { "host": "10.0.0.50", "unit_id": 3 }  // overrides driver defaults
}

Broadcast (no write.cmd) — IAKR thermohygrometer

// Device sends data automatically; no request needed.
// Two commands share the same response line: "T;025.50;F;060.00"
{
  "id": "IAKR", "enabled": true,
  "connection": { "protocol": "STRING", "baud": 9600, ... },
  "commands": [
    {
      "parameter": "TEMPERATURE", "unit": "CELSIUS", "type": "read",
      // no "write" field
      "read": { "parser": "T;[+-]?([0-9]{3}[.]){1}[0-9]{2}" }
    },
    {
      "parameter": "RELATIVE_HUMIDITY", "unit": "%", "type": "read",
      "read": { "parser": "F;[+-]?([0-9]{3}[.]){1}[0-9]{2}" }
    }
  ]
}

10. Complete field template

All fields with every possible value. Copy, remove what you don't need, fill in the rest.

// drivers/MY_DEVICE.json
{
  "id":      "MY_DEVICE",                 // required — unique, uppercase
  "enabled": true,                       // required — true | false
  "version": "1",                        // optional

  "info": {                               // optional block
    "displayName":  "Brand Model-X",
    "model":        "Model-X",
    "manufacturer": "Brand",
    "serie":        "X-Series",         // optional
    "type":         "thermometer"        // thermometer | scales | barometer |
                                           // thermphygrometer | multichannel thermometer |
                                           // thermohygrometer with barometer | comparator
  },

  "connection": {                         // required block. Topology can override any field.
    "protocol": "STRING",               // STRING | STRING_BINARY | BINARY | MODBUS_RTU | MODBUS_TCP
    "timeout":  1000,                    // ms — how long to wait for a response (all transports)

    // Serial fields — used by STRING / STRING_BINARY / BINARY / MODBUS_RTU
    "baud":     9600,                    // 1200 | 2400 | 4800 | 9600 | 19200 | 38400 | ...
    "parity":   0,                       // 0 = none | 1 = even
    "stopBit":  1,                       // 1 = 1 bit | 2 = 2 bits | 15 = 1.5 bits

    // TCP fields — used by MODBUS_TCP (serial fields are ignored)
    "host":     "192.168.1.100",         // IP address or hostname of the device/gateway
    "tcp_port": 502,                     // TCP port (default: 502)
    "unit_id":  1                         // Modbus unit ID in MBAP header (default: 1)
  },

  "commands": [
    {
      "parameter": "TEMPERATURE",         // required — TEMPERATURE | WEIGHT | PRESSURE |
                                           // RELATIVE_HUMIDITY | TEMPERATURE_1 | ...
      "unit":      "CELSIUS",             // required — CELSIUS | g | % | hPa | ...
      "type":      "read",                // required — read | command

      "write": {                          // optional — omit for broadcast devices
        "cmd": "d\r",                    // STRING: ASCII string  ("d\r", "SI\r\n")
                                           // BINARY: hex string    ("010300010001D5CA")
        "dtr": "SET_DTR",               // optional — SET_DTR | CLEAR_DTR
        "rts": "SET_RTS",               // optional — SET_RTS | CLEAR_RTS
        "brk": "IGNORE"                 // optional — IGNORE
      },

      "read": {                           // required block
        "parser":    "[+-]?\\d+\\.\\d+", // required — regex (STRING)
                                           //           "BE"          (binary, big-endian int)
                                           //           "BE_DECIMAL"  (binary, ASCII decimal)
                                           //           "MODBUS_RTU"  (Modbus RTU frame)
                                           //           "MODBUS_TCP"  (Modbus TCP — strips MBAP header)
        "validator": "S",               // optional — regex; no match → status UNSTABLE
        "offset":    6,                   // optional — byte offset (BE / BE_DECIMAL)
        "length":    2,                   // optional — byte count  (BE / BE_DECIMAL)
                                           //            2 → uint16 | 4 → uint32
        "head":      "1002",             // optional — expected hex header bytes
        "tail":      "1004",             // optional — expected hex footer bytes
        "bufsize":   64,                  // optional — bytes to read (default: 64)
        "factor":    0.01,                // optional — raw × factor = value (default: 1.0)
                                           //            raw 2500 × 0.01 = 25.00 °C
                                           //            ignored when expression is set
        "expression": "value * 1.8 + 32" // optional — arithmetic expression; takes precedence
                                           //            over factor. Variable: value (parsed raw)
                                           //            e.g. "value * 0.03527396" (g → oz)
      }
    }
  ]
}