Connect an I²C device
I²C sensors share two lines (SDA/SCL) on the gateway.
Protocol: i2c · Requires: a gateway
Connection fields:
| Field | Meaning |
|---|---|
sdaPin / sclPin |
I²C data and clock pins |
clockHz |
Bus clock (e.g. 100000, 400000) |
sampleIntervalMs |
Read interval (ms) |
Steps
- Wire SDA/SCL (with pull-ups) to the gateway pins.
- Add a device with protocol i2c, pick the gateway, and set the pins + clock.
- Add a tag per measurement the sensor exposes.
i2c/fault events usually mean a wrong address, missing pull-ups, or a clock too fast for the wiring.
Several sensors on one gateway
A gateway has one I²C bus, and every I²C device on it shares the same SDA/SCL pins. The sensors are told apart by address, so you can wire, say, a BH1750 (0x23) and a BME280 (0x76) to the same two pins and add them as two devices.
- Use the same pins for every I²C device. When you add a second device, the pins are pre-filled with the bus's pins. A different pair is refused with
I2C_BUS_MISMATCH, because the gateway can drive only one bus. - Give every sensor its own address. Two sensors at the same address on the bus answer each other's reads, so a clash is refused with
I2C_ADDRESS_IN_USE. Many chips have an ADDR pin that selects a second address (BH1750 0x23/0x5C, BME280 0x76/0x77, SHT31 0x44/0x45). - Use one bus clock. The bus runs at a single speed, so give every I²C device on a gateway the same
clockHz.
When a sensor stops answering
With gateway firmware 1.5.5 or later, a sensor that wasn't answering when the gateway started, or that drops off later (a loose wire, a power glitch), comes back on its own:
- After three polls in a row with no answer, the gateway starts that sensor again, and keeps trying on every poll until it answers. The gateway itself doesn't restart.
- After starting a sensor, the gateway waits for its first measurement before reading it, so the first value you see is a real reading rather than a 0.
Unplug the gateway's power before you rewire. Connecting a sensor's power to a running gateway can dip the supply enough to restart the gateway.
Sensors without a built-in driver (generic)
Built-in drivers: BME280, BMP280, SHT31, ADS1115 (I²C) and MAX31855, MAX6675 (SPI). For any other chip pick Sensor model: generic on the tag and describe the read from its datasheet:
| Field | Meaning | BH1750 light sensor (example) |
|---|---|---|
i2cAddress |
the chip's 7-bit address | 0x23 (35) with ADDR low · 0x5C (92) with ADDR high |
initByte |
one byte written when the gateway starts the sensor; 0 = none |
0x10 (16) — continuous high-resolution mode |
readBytes |
bytes read back on every poll (1–4) | 2 |
bigEndian |
most-significant byte first | yes |
| scale factor / offset | engineering = raw × factor + offset | ÷ 1.2 → lux |
The gateway writes the init byte when it starts the sensor (and again if it has to restart it), then reads readBytes bytes each poll and publishes the raw integer; the tag's scale factor and offset turn it into engineering units everywhere it is displayed or evaluated. Chips that need a register pointer written before each read are not covered by the generic model — use a built-in driver or a Modbus/UART bridge.
A connected AI assistant can set every one of these fields when it creates the device, so "a BH1750 at 0x23" in a sentence is enough for it to fill in the datasheet numbers.