Oasis Device Configuration Schema

This document defines the YAML schema for declarative device definitions. The oasis-build tool parses these files to generate Rust firmware for both MCU (ESP32, Arduino) and RPi platforms.

Schema Overview

device.yaml
├── device           # Device identity and board config
├── connectivity     # Network/serial communication
├── auth             # Cloud authentication
├── sensors[]        # Sensor definitions
├── actuators[]      # Actuator definitions
├── control_loops[]  # On-device control logic
├── data_publishing  # MQTT/HTTPS output config
└── system           # Logging, watchdog, power, OTA

Device Section

Field	Type	Required	Description
`device.id`	string	✓	Unique device identifier (e.g., `greenhouse-node-01`)
`device.name`	string	✓	Human-readable name
`device.board.platform`	enum	✓	`rpi` or `mcu`
`device.board.model`	string	✓	Board model (see supported boards below)

Supported Boards

MCU Platform:

esp32_devkit, esp32_c3, esp32_s3
arduino_uno, arduino_mega, arduino_nano
teensy_40, teensy_41
stm32f103, stm32f411

RPi Platform:

rpi_zero_w, rpi_zero_2w
rpi_3b, rpi_4b, rpi_5

Connectivity Section

Field	Type	Required	Description
`connectivity.mode`	enum	✓	`direct_mqtt`, `direct_https`, `serial_gateway`, `hybrid`
`connectivity.wifi.ssid`	string	*	WiFi SSID (supports `${ENV_VAR}` syntax)
`connectivity.wifi.password`	string	*	WiFi password (supports `${ENV_VAR}` syntax)
`connectivity.mqtt.broker`	string	*	MQTT broker hostname
`connectivity.mqtt.port`	integer		Default: `8883`
`connectivity.mqtt.use_tls`	boolean		Default: `true`
`connectivity.https.endpoint`	string	*	HTTPS endpoint URL
`connectivity.serial.baud_rate`	integer		Default: `115200`
`connectivity.serial.protocol`	enum		`cobs_msgpack`, `cobs_json`, `raw_json`

*Required depending on connectivity mode

Auth Section

Field	Type	Required	Description
`auth.api_key`	string	✓	Device API key (supports `${ENV_VAR}` syntax)
`auth.source_id`	integer		Pre-registered source ID in oasis-data
`auth.admin_id`	string		Tenant admin ID for multi-tenant deployments

Sensors Section

Each sensor in the sensors[] array:

Field	Type	Required	Description
`name`	string	✓	Unique sensor name within device
`type`	enum	✓	Sensor type (see supported sensors)
`pins`	object	✓	Pin configuration (varies by sensor)
`i2c_address`	integer		I2C address (hex, e.g., `0x76`)
`sampling.interval_ms`	integer	✓	Sampling interval in milliseconds
`sampling.averaging`	integer		Number of samples to average
`output.measurements[]`	array	✓	List of measurement outputs
`calibration.offset`	float		Calibration offset
`calibration.scale`	float		Calibration scale factor
`thresholds[]`	array		Alert thresholds

Supported Sensor Types

Category	Types
Temperature/Humidity	`dht11`, `dht22`, `bme280`, `bme680`, `sht31`, `ds18b20`
Light	`bh1750`, `tsl2561`, `veml7700`, `photoresistor`
Moisture	`capacitive_moisture`, `resistive_moisture`
Distance	`hcsr04`, `vl53l0x`, `vl53l1x`
Motion	`mpu6050`, `mpu9250`, `bno055`, `pir`
Gas/Air	`mq2`, `mq135`, `ccs811`, `sgp30`
Current/Voltage	`ina219`, `acs712`, `voltage_divider`
Weight	`hx711`
Camera	`esp_cam`, `rpi_camera`
Generic	`adc_raw`, `i2c_custom`

Pin Configuration

Sensor Type	Required Pins
DHT11/22, DS18B20	`data`
I2C sensors	`sda`, `scl` (or use board defaults)
HC-SR04	`trigger`, `echo`
ADC sensors	`adc` (channel number)

Actuators Section

Each actuator in the actuators[] array:

Field	Type	Required	Description
`name`	string	✓	Unique actuator name
`type`	enum	✓	Actuator type (see supported types)
`pins`	object	✓	Pin configuration
`default.state`	enum		`on` or `off`
`default.value`	integer		PWM value (0-255 or 0-100%)
`constraints.min_value`	integer		Minimum output value
`constraints.max_value`	integer		Maximum output value
`constraints.ramp_rate`	integer		Max change per second
`safety.watchdog_timeout_ms`	integer		Auto-off if no heartbeat
`safety.max_on_duration_ms`	integer		Max continuous on time

Supported Actuator Types

Category	Types
Digital	`relay`, `relay_nc`, `led`, `buzzer`
PWM	`pwm`, `servo`, `dc_motor`
Stepper	`stepper_a4988`, `stepper_drv8825`, `stepper_tmc2209`
I2C	`pca9685`, `mcp23017`
Communication	`rs485`, `modbus`

Control Loops Section

On-device control loops for low-latency automation:

Field	Type	Required	Description
`name`	string	✓	Control loop name
`type`	enum	✓	`threshold`, `pid`, `schedule`, `state_machine`
`input.sensor`	string	✓	Input sensor name
`input.measurement`	string	✓	Which measurement to use
`output.actuator`	string	✓	Output actuator name

Threshold Control

threshold:
  setpoint: 25.0
  hysteresis: 2.0
  direction: cool  # 'heat' or 'cool'

PID Control

pid:
  kp: 1.0
  ki: 0.1
  kd: 0.05
  setpoint: 25.0
  output_min: 0
  output_max: 255
  sample_time_ms: 1000

Schedule Control

schedule:
  - start_time: "06:00"
    end_time: "18:00"
    value: true
    days: [mon, tue, wed, thu, fri]

Data Publishing Section

Field	Type	Description
`mqtt.enabled`	boolean	Enable MQTT publishing
`mqtt.telemetry_topic`	string	Topic for sensor data
`mqtt.state_topic`	string	Topic for state changes
`mqtt.cmd_topic`	string	Topic for commands
`mqtt.publish_interval_ms`	integer	Aggregation interval
`mqtt.qos`	integer	MQTT QoS (0, 1, or 2)
`https.enabled`	boolean	Enable HTTPS batching
`https.batch_interval_s`	integer	Batch POST interval
`https.max_batch_size`	integer	Max measurements per batch
`https.retry_count`	integer	Retries on failure
`local_storage.enabled`	boolean	Enable offline caching
`local_storage.max_records`	integer	Ring buffer size
`local_storage.persist_on_reboot`	boolean	Persist to flash

System Section

Field	Type	Description
`system.log_level`	enum	`error`, `warn`, `info`, `debug`, `trace`
`system.watchdog.enabled`	boolean	Enable hardware watchdog
`system.watchdog.timeout_ms`	integer	Watchdog timeout
`system.power.sleep_mode`	enum	`none`, `light`, `deep`
`system.power.wake_interval_ms`	integer	Wake interval for deep sleep
`system.power.wake_on_interrupt`	array	GPIO pins that wake device
`system.ota.enabled`	boolean	Enable OTA updates
`system.ota.check_interval_s`	integer	Update check interval
`system.ota.update_topic`	string	MQTT topic for updates

Hardware/PCB Section (KiCAD Integration)

Link device configuration to physical PCB design:

Field	Type	Description
`hardware.kicad_project`	string	Path to `.kicad_pro` file
`hardware.symbols[]`	array	Map components to schematic symbols
`hardware.connectors[]`	array	Connector definitions
`hardware.housing`	object	Enclosure configuration
`hardware.bom_overrides[]`	array	BOM part number overrides

Symbol Mapping

hardware:
  kicad_project: "./pcb/greenhouse-monitor.kicad_pro"
  symbols:
    - component: air_temp_humidity
      symbol_ref: "U1"
      footprint: "Package_SO:SOIC-8_3.9x4.9mm_P1.27mm"
    - component: grow_light
      symbol_ref: "K1"

Connectors

  connectors:
    - name: "J1"
      connector_type: "screw_terminal_4p"
      signals: [VCC, GND, SOIL_ADC, NC]
      symbol_ref: "J1"
    - name: "J2"
      connector_type: "jst_xh_4"
      signals: [VCC, GND, SDA, SCL]

Housing

  housing:
    model: "ip65_abs_100x68x50"
    cad_file: "./enclosure/greenhouse-monitor.FCStd"
    ip_rating: "IP65"
    dimensions_mm: [100, 68, 50]

Deployment Section

Configure flashing and deployment methods:

Field	Type	Description
`deployment.flash_method`	enum	`usb_serial`, `debug_probe`, `ota_mqtt`, `ota_https`, `ssh_rsync`, `docker`
`deployment.target_address`	string	Device address (serial port or IP)
`deployment.ssh`	object	SSH config for RPi deployment
`deployment.ota`	object	OTA update configuration

USB Serial (ESP32)

deployment:
  flash_method: usb_serial
  target_address: "/dev/ttyUSB0"

SSH Deployment (RPi)

deployment:
  flash_method: ssh_rsync
  ssh:
    host: "greenhouse-rpi.local"
    port: 22
    user: "oasis"
    key_path: "~/.ssh/oasis_deploy"
    install_dir: "/opt/oasis/greenhouse-node-01"

OTA Updates

deployment:
  flash_method: ota_mqtt
  ota:
    endpoint: "oasis/devices/${device.id}/ota"
    signing_key: "./keys/firmware_signing.pem"
    require_signature: true

Environment Variable Substitution

Use ${ENV_VAR} syntax for secrets:

connectivity:
  wifi:
    ssid: "${WIFI_SSID}"
    password: "${WIFI_PASSWORD}"
auth:
  api_key: "${OASIS_API_KEY}"

The build tool will:

Substitute from environment at build time for MCU (compiled in)
Read from .env file at runtime for RPi

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Oasis Device Configuration Schema

Schema Overview

Device Section

Supported Boards

Connectivity Section

Auth Section

Sensors Section

Supported Sensor Types

Pin Configuration

Actuators Section

Supported Actuator Types

Control Loops Section

Threshold Control

PID Control

Schedule Control

Data Publishing Section

System Section

Hardware/PCB Section (KiCAD Integration)

Symbol Mapping

Connectors

Housing

Deployment Section

USB Serial (ESP32)

SSH Deployment (RPi)

OTA Updates

Environment Variable Substitution

FilesExpand file tree

DEVICE_SCHEMA.md

Latest commit

History

DEVICE_SCHEMA.md

File metadata and controls

Oasis Device Configuration Schema

Schema Overview

Device Section

Supported Boards

Connectivity Section

Auth Section

Sensors Section

Supported Sensor Types

Pin Configuration

Actuators Section

Supported Actuator Types

Control Loops Section

Threshold Control

PID Control

Schedule Control

Data Publishing Section

System Section

Hardware/PCB Section (KiCAD Integration)

Symbol Mapping

Connectors

Housing

Deployment Section

USB Serial (ESP32)

SSH Deployment (RPi)

OTA Updates

Environment Variable Substitution