Firmware

RIoT field devices run custom firmware on ESP32 hardware. Each device handles sensor data acquisition, local buffering, and secure upload to the RIoT cloud.

Device Configuration

Each device loads its configuration from a conf.cfg file on the SD card mounted at /sdcard. The file is JSON-formatted and validated at boot. If the configuration is missing or invalid, the device restarts.

Full Configuration Structure

{
  "device_uid": "home-madrid:test-logger-01",
  "connectivity": {
    "type": "wifi",
    "ssid": "YourSSID",
    "password": "YourWiFiPassword"
  },
  "ntp_server": "pool.ntp.org",
  "auth": {
    "api_key": "your-api-key",
    "api_secret": "your-api-secret"
  },
  "cloud": {
    "host": "api.example.com",
    "port": 8443,
    "endpoints": {
      "data_ingest": "/v1/data/ingest",
      "log_ingest": "/v1/device/logs",
      "status_update": "/v1/device/status",
      "config_poll": "/v1/device/config",
      "config_upload": "/v1/device/config/upload",
      "config_ack": "/v1/device/config/ack",
      "config_test_result": "/v1/device/config/test-result",
      "config_rollback": "/v1/device/config/rollback",
      "command_poll": "/v1/device/commands"
    }
  },
  "mtls": {
    "enabled": true,
    "client_cert_path": "/sdcard/certs/client.crt",
    "client_key_path": "/sdcard/certs/client.key",
    "ca_cert_path": "/sdcard/certs/ca.crt",
    "skip_cert_common_name_check": false
  },
  "upload_interval_ms": 100000,
  "upload": {
    "batch_size": 50,
    "max_retries": 3,
    "retry_initial_delay_ms": 1000,
    "retry_max_delay_ms": 30000,
    "retry_backoff_multiplier": 2.0
  },
  "polling_intervals_ms": {
    "config": 300000,
    "commands": 60000
  },
  "config_ota": {
    "rollback_threshold": 3,
    "confirm_threshold": 2
  },
  "sensors": [
    {
      "type": "sht4x",
      "name": "ambient_temp_rh",
      "enabled": true,
      "sample_frequency_ms": 5000,
      "params": {
        "i2c_port": 0,
        "i2c_address": 68,
        "precision": "high"
      }
    }
  ]
}

Field Reference

Field	Type	Description
`device_uid`	string	Unique device identifier. Max 64 characters.
`connectivity.type`	string	Connection type. Currently `"wifi"`.
`connectivity.ssid`	string	WiFi network name. Max 32 characters.
`connectivity.password`	string	WiFi password. 8-63 characters.
`ntp_server`	string	NTP server hostname for RTC synchronization.
`auth.api_key`	string	API key for backend authentication. Max 128 characters.
`auth.api_secret`	string	API secret for backend authentication. Max 128 characters.
`cloud.host`	string	Backend API hostname. Max 253 characters.
`cloud.port`	int	Backend API port.
`cloud.endpoints.*`	string	API endpoint paths. Max 512 characters each.
`mtls.enabled`	bool	Enable mutual TLS for device-to-cloud communication.
`mtls.client_cert_path`	string	Path to PEM client certificate on SD card.
`mtls.client_key_path`	string	Path to PEM client private key on SD card.
`mtls.ca_cert_path`	string	Path to PEM CA certificate for server validation.
`upload_interval_ms`	uint64	Interval between upload batches (1,000 - 86,400,000 ms).
`upload.batch_size`	uint32	Records per upload batch (1 - 500). Default: 50.
`upload.max_retries`	uint32	Maximum retry attempts per batch (0 - 10). Default: 3.
`upload.retry_backoff_multiplier`	float	Exponential backoff multiplier (1.0 - 5.0). Default: 2.0.
`polling_intervals_ms.config`	uint64	Config OTA poll interval (60,000 - 86,400,000 ms).
`polling_intervals_ms.commands`	uint64	Command poll interval (1,000 - 3,600,000 ms).
`config_ota.rollback_threshold`	uint8	Consecutive boot failures before config rollback. Default: 3.
`config_ota.confirm_threshold`	uint8	Successful boots to confirm config as known-good. Default: 2.
`sensors`	array	Sensor definitions. Max 40 sensors.

Sensor Configuration

Each entry in the sensors array defines a sensor driver instance:

Field	Type	Description
`type`	string	Sensor driver type. Must match a registered factory type.
`name`	string	Unique sensor name. Used in readings and SD storage.
`enabled`	bool	Whether the sensor is active. Disabled sensors are skipped.
`sample_frequency_ms`	uint64	Sampling interval in milliseconds.
`params`	object	Driver-specific parameters (I2C address, precision, pins, etc.).

mTLS Certificates

Place PEM-encoded certificates on the SD card:

/sdcard/
  certs/
    client.crt    # Device client certificate
    client.key    # Device private key
    ca.crt        # Platform CA certificate

Supported Sensors

Type	Description
`sht21`	Temperature and humidity
`sht3x`	Temperature and humidity
`sht4x`	Temperature and humidity (configurable precision and heater)
`scd40`	CO2, temperature, and humidity
`scd41`	CO2, temperature, and humidity (extended range)
`adxl345`	3-axis accelerometer
`veml7700`	Ambient light sensor
`analog`	Generic ADC input
`digital`	Generic digital GPIO input
`gps`	GPS receiver (NMEA)