Adding a New Sensor

Adding a New Sensor

Most UART sensors can be added with a JSON file only — no code changes.

1. Collect protocol details from the datasheet

• Serial settings: baud rate, data bits, stop bits, parity
• Does it stream automatically, or must you send a command?
• Frame layout: header byte(s), total length, terminator, byte-stuffing
• Checksum algorithm and where it sits in the frame
• Position, byte order and scaling of each value

2. Check whether a similar sensor exists

If your sensor uses the same protocol as a supported one (common for sensor families and clones), use Inheritance and override only what differs.

3. Write a minimal config

Start with a single signal and a checksum that always passes, so you can see raw frames:

{
  "sensors": [
    {
      "name": "My Sensor (test)",
      "command": "none",
      "port": { "baudRate": 9600, "dataBits": 8, "stopBits": 1, "parity": "none" },
      "frame": { "startByte": [66, 77], "endByte": "none", "length": 32 },
      "checksum": { "eval": "1", "compare": "1" },
      "data": {
        "Raw word 1": { "value": "(data[4] << 8) + data[5]", "unit": "raw" }
      }
    }
  ]
}

4. Load and test it

1. In the app, use Custom JSON Sensor Configuration to upload your file. Your sensor appears with 🆕.
2. Connect and watch the Log. Check that frames start where you expect and have the right length.
3. Replace the dummy checksum with the real one and confirm packets show ✅.
4. Add the real signals with correct scaling and units, then compare the readings with a reference or the datasheet.

5. Contribute it

Contributions of new sensor configurations are welcome:

1. Make sure the configuration has been tested with the real sensor via custom JSON upload.
2. Fork the repository and add your sensor object to sensors.json.
3. Open a pull request. Mention the sensor model, how you connected it (adapter, wiring) and what you verified.

See also: Sensor Configuration Reference · Multi-Command Sensors · CONTRIBUTING.md