Sensors

RIoT uses a pluggable driver framework to support a range of industrial sensor types. Each device declares its sensor configuration in config.json, and the platform handles data ingestion, storage, and health monitoring automatically. Sensor types are defined at the platform level and managed by super admins.

Supported Sensor Types

Type	Sensor	Interface	Measurements
`adxl345`	ADXL345	I2C	3-axis acceleration (x, y, z in g), tap detection, freefall detection
`sht21`	SHT21	I2C	Temperature (°C), Relative humidity (%)
`sht3x`	SHT3x	I2C	Temperature (°C), Relative humidity (%)
`sht4x`	SHT4x	I2C	Temperature (°C), Relative humidity (%)
`analog`	Any analog sensor	ADC (GPIO 32--39)	12-bit ADC value with configurable scale and offset
`digital_basic`	Binary state sensor	GPIO	Digital HIGH/LOW with debounce
`gps`	NEO-8M / A9G	UART	Latitude, longitude, altitude, speed, satellites

Sensor Configuration

Sensors are configured per-device in config.json. Each sensor entry specifies its type, sampling interval, and hardware parameters.

Sensor config fields:

Field	Type	Required	Description
`name`	string	Yes	A unique identifier for this sensor within the device.
`type`	string	Yes	Must match a registered sensor type (e.g., `sht21`, `adxl345`).
`enabled`	boolean	Yes	Whether the sensor is active. Disabled sensors are skipped during sampling.
`sample_interval_ms`	integer	Yes	Sampling interval in milliseconds. Determines how frequently the sensor is read.
`params`	object	Yes	Hardware-specific parameters. Contents vary by sensor type and interface.

Example -- SHT21 temperature and humidity sensor:

{
  "name": "temperature_humidity_sens",
  "type": "sht21",
  "enabled": true,
  "sample_interval_ms": 20000,
  "params": {
    "i2c_port": 0,
    "sda_pin": 39,
    "scl_pin": 40
  }
}

Interface Parameters

Parameters in the params object depend on the sensor interface.

I2C sensors (adxl345, sht21, sht3x, sht4x):

Parameter	Type	Description
`i2c_port`	integer	I2C bus number (typically `0`).
`sda_pin`	integer	GPIO pin for the I2C data line.
`scl_pin`	integer	GPIO pin for the I2C clock line.

Analog sensors (analog):

Parameter	Type	Description
`gpio_pin`	integer	ADC-capable GPIO pin (32--39 on ESP32).
`scale`	float	Multiplier applied to the raw ADC value.
`offset`	float	Offset added after scaling.

Digital sensors (digital_basic):

Parameter	Type	Description
`gpio_pin`	integer	GPIO pin to read.
`debounce_ms`	integer	Debounce interval in milliseconds.

GPS sensors (gps):

Parameter	Type	Description
`uart_port`	integer	UART bus number.
`tx_pin`	integer	GPIO pin for UART TX.
`rx_pin`	integer	GPIO pin for UART RX.
`baud_rate`	integer	UART baud rate (typically `9600`).

Sensor Readings

Sensor readings are persisted to PostgreSQL. Each reading is stored as a row in the sensor_readings table:

Column	Type	Description
`id`	integer	Auto-incrementing primary key.
`device_id`	string	The device that produced the reading.
`sensor_type`	string	Sensor type identifier (e.g., `sht21`).
`sensor_name`	string	The sensor's configured name.
`value`	JSONB	The measurement payload. Structure varies by sensor type.
`status`	string	Health status at the time of the reading.
`recorded_at`	timestamp	When the reading was taken on the device.

Value Field Structure

The value column is JSONB. Its structure depends on the sensor type.

Temperature and humidity (sht21, sht3x, sht4x):

{
  "temperature_c": 23.45,
  "humidity_pct": 61.2
}

Accelerometer (adxl345):

{
  "x_g": 0.012,
  "y_g": -0.004,
  "z_g": 1.003,
  "tap_detected": false,
  "freefall_detected": false
}

Analog (analog):

{
  "raw": 2048,
  "scaled": 1.65
}

Digital (digital_basic):

{
  "state": "HIGH"
}

GPS (gps):

{
  "latitude": 29.7604,
  "longitude": -95.3698,
  "altitude_m": 15.2,
  "speed_kmh": 0.0,
  "satellites": 9
}

Health Status

Every sensor reading includes a status field indicating the sensor's operational health at the time of measurement.

Status	Meaning
`HEALTHY`	The sensor is operating normally. Readings are within expected bounds and arriving on schedule.
`DEGRADED`	The sensor is responding but readings may be unreliable -- for example, intermittent communication errors, out-of-range values, or increased latency.
`OFFLINE`	The sensor has stopped responding. No readings are being produced. This typically indicates a wiring fault, driver failure, or hardware defect.

Health status is determined on the device and transmitted alongside each reading. The dashboard surfaces health indicators on the device detail page, allowing operators to identify failing sensors before data gaps appear.

Managing Sensor Types

Sensor types are a platform-level resource. Only users with the super_admin role can create, edit, or delete sensor types.

Navigate to Sensor Types (/sensor-types) to manage the registry. Each sensor type defines its identifier, display name, expected value schema, and default parameters. When a new sensor model is introduced to the fleet, register its type here before deploying device configurations that reference it.

Devices referencing an unregistered sensor type will log a configuration error and skip that sensor during initialization.