Descriptor Examples

This page lists YAML descriptors available in the repository.

These descriptors are example and reference configurations. They show how to define IO, programs, and protocols for Dawn devices, but they do not all have the same maturity level or resource requirements.

`os_required` metadata

The metadata.os_required field is informational metadata. Dawn does not use it at build time or runtime; it tells users which OS-visible resources a descriptor expects to exist.

Use the following naming rule when filling the field:

use the concrete device-node path for OS-exposed instances (for example /dev/can0, /dev/adc0, /dev/pwm0, /dev/gpio0, /dev/leds0, /dev/buttons0, /dev/urandom)
use the explicit configured path when the descriptor hardcodes a transport endpoint (for example /dev/ttyS0, /tmp/ttySIM0)
use the concrete sensor device path for sensor-backed IO (for example /dev/uorb/sensor_accel0, /dev/uorb/sensor_humi0)
use named subsystem resources for protocol prerequisites without a concrete device path in the descriptor (for example udp, tcp, or ble)

This keeps os_required aligned with the actual OS-visible paths used by Dawn on NuttX.

Feature index

Feature	Descriptors
Blinky	Blinky Buttons, Blinky CAN, Blinky NimBLE, Blinky Modbus RTU, Blinky Modbus TCP, Blinky Serial, Blinky Shell, Blinky UDP, Blinky Wakaama
CAN	Blinky CAN, CAN Button/LED, CAN Sensor Producer, CAN Dummy IO, Programs Over CAN, Serial to CAN Gateway
Dynamic descriptors	Dynamic Descriptor Slot0, Dynamic Descriptor Slot1
Gateway	Serial to CAN Gateway
IPC	Local IPC
LwM2M	NTFC Wakaama LwM2M, Wakaama Leshan Demo, nRF9160-DK Wakaama over LTE, Thingy:91 Wakaama over LTE, Blinky Wakaama
Modbus	Blinky Modbus RTU Demo, Blinky Modbus TCP Demo, Feature Modbus Slot0, Feature Modbus Slot1, NTFC Modbus RTU Dummy Map, Modbus TCP Dummy Map
NimBLE / BLE	Blinky NimBLE, NimBLE AIOS, NimBLE Environmental Sensor, NimBLE GPIO and Analog, NimBLE OTS, NimBLE Sensor Producer, NTFC NimBLE All-Services, NTFC NimBLE Buffer, NTFC NimBLE Custom Service, Shell and NimBLE Environmental
NXScope	NXScope Serial, NXScope UDP
Serial	Blinky Serial, Dynamic Descriptor Slot0, Dynamic Descriptor Slot1, Serial Core, Serial LEDs and Buttons, Serial to CAN Gateway
Shell	Blinky Shell, Shell Core, Shell GPIO and Config, Shell and NimBLE Environmental
Tests	Empty Placeholder
UDP	Basic UDP, Blinky UDP NXScope UDP

Catalog

Examples

descriptors/examples/blinky_buttons_demo.yaml

Blinky Buttons Demo (Extended)

Extended 4-mode, 4-button runtime-control example. No protocols are used; all logic is managed by interconnected programs (BitSplit, Toggle, Counter, Switch, Expression, Redirect, Selector, Sequencer). Button 1 toggles run/stop. Button 2 cycles the four modes: all LEDs blink, LEDs chase one-by-one, selected LED blinks, and selected LED constant-on. Button 3 selects the active LED for the two selected-LED modes; those modes keep independent selections. Button 4 adjusts the dwell time for blinking modes in visible steps.

Data flow:

buttons0 -> bitsplit -> button state IOs
  Button 1 -> toggle_run -> selector_leds run gate
  Button 2 -> counter_mode -> selector_modes
  Button 3 -> gated counters -> selected LED for modes 2 and 3
  Button 4 -> counter_p2 -> dwell ConfigIO for modes 0, 1, and 2

Required resources: /dev/buttons0, /dev/leds0

descriptors/examples/blinky_can_demo.yaml

Blinky CAN Demo

Sequencer-driven LED output with CAN control. This descriptor includes the shared blinky core block and defines only the CAN-specific mapping locally. Start/stop, reset, start-index configuration, individual dwell values, current LED state, and segmented access to the full sequencer state table are exposed through CAN frames.

The simple write mappings use standard CAN IDs 0x150 through 0x154. The host helper updates the blink period by writing cfg_dwell_off on 0x153 and cfg_dwell_on on 0x154.

Required resources: /dev/can0, /dev/leds0

Host helper: tools/examples/blinky/can_blinky_cli.py

descriptors/examples/blinky_nimble_demo.yaml

Blinky NimBLE Demo

Sequencer-driven LED output with BLE control via NimBLE. This descriptor includes the shared blinky core block and keeps only the NimBLE service layout local. Start/stop, reset, full state table, and individual dwell times are exposed over a custom BLE service.

Required resources: /dev/gpio4, ble

Host helper: tools/examples/blinky/nimble_blinky_cli.py

descriptors/examples/blinky_shell_demo.yaml

Blinky Shell Demo

Provides a shell-controlled runtime example where a sequencer drives an LED output. This descriptor includes the shared blinky core block; the shell section stays local and exposes start/stop control plus runtime configuration via ConfigIO objects (start index and state table).

Required resources: /dev/leds0

descriptors/examples/blinky_serial_demo.yaml

Blinky Serial Demo

Provides a serial-controlled runtime example where a sequencer drives the board LED lower-half. This descriptor includes the shared blinky core block; the serial section keeps only protocol-specific transport settings and bindings. Start/stop and runtime dwell parameters are exposed over the Dawn serial protocol together with readback of the sequencer start index and current output state.

Required resources: /dev/leds0, /dev/ttyS0

Host helper: tools/examples/blinky/serial_blinky_cli.py

descriptors/examples/blinky_udp_demo.yaml

Blinky UDP Demo

Provides a UDP-controlled runtime example where a sequencer drives the board LED lower-half. This descriptor includes the shared blinky core block; the UDP section keeps only transport-specific settings and bindings. Start/stop and runtime dwell parameters are exposed over the Dawn UDP protocol together with readback of the sequencer start index and current output state.

Required resources: /dev/leds0, udp

Host helper: tools/examples/blinky/udp_blinky_cli.py

descriptors/examples/blinky_wakaama_demo.yaml

Blinky Wakaama Demo (nrf9160-dk over LTE)

LED blinky controlled over LwM2M (Wakaama). A sequencer drives the board LED lower-half through the shared blinky core block. A custom LwM2M object (id 33000) exposes the LED state plus start/stop, blink-phase reset, and the on/off dwell times. An LTE system object brings up connectivity before registration. Built by the boards/arm/nrf91/nrf9160-dk/configs/blinky_wakaama config.

Required resources: /dev/leds0, udp, /tmp

descriptors/examples/blinky_modbus_tcp_demo.yaml

Blinky Modbus TCP Demo

Provides a Modbus-TCP controlled blinky demo where a sequencer drives an LED output through the shared blinky core block. Start/stop and runtime parameters are exposed as Modbus coil and holding registers, including writable dwell values and start-index control.

Required resources: /dev/leds0, tcp

Host helper: tools/examples/blinky/modbus_tcp_blinky_cli.py

descriptors/examples/blinky_modbus_rtu_demo.yaml

Blinky Modbus RTU Demo

Provides a Modbus-RTU controlled blinky demo where a sequencer drives an LED output through the shared blinky core block. Start/stop and runtime parameters are exposed as Modbus registers, including writable dwell values and start-index control.

Required resources: /dev/leds0, /dev/ttyS1

Host helper: tools/examples/blinky/modbus_blinky_cli.py

descriptors/examples/can_button_led.yaml

Minimal CAN Buttons and LEDs Demo

Provides a minimal CAN mapping with one writable LED output and one pushed button-state input.

Required resources: /dev/can0, /dev/leds0, /dev/buttons0

descriptors/examples/can_sensor_producer.yaml

CAN Sensor Producer Demo

Receives environmental values over CAN and republishes them as NuttX user sensor topics. The descriptor creates temperature, humidity, barometer, and light topics using sensor_producer IOs. Another NuttX application can read those topics through /dev/uorb while Dawn only provides the CAN write path.

CAN write mappings start at 0x150: can_temp_sensor_pub is one float, can_humi_sensor_pub is one float, can_baro_sensor_pub is two floats (pressure, temperature), and can_light_sensor_pub is two floats (light, infrared).

Required resources: /dev/can0, /dev/usensor, /dev/uorb/sensor_temp10, /dev/uorb/sensor_humi11, /dev/uorb/sensor_baro12, /dev/uorb/sensor_light13

descriptors/examples/dynamic_desc_slot0.yaml

Dynamic Descriptor Slot0 Bootstrap

Bootstrap descriptor exposing descriptor slots and selector over serial for runtime descriptor upload and switching.

Required resources: /dev/ttyS1

descriptors/examples/dynamic_desc_slot1.yaml

Dynamic Descriptor Slot1 Runtime

Runtime descriptor for switch verification. Uses a different dummy initial value than slot0 to prove descriptor activation.

Required resources: /dev/ttyS1

descriptors/examples/feature_modbus_slot0.yaml

Feature Demo - Modbus RTU Bootstrap (slot 0)

Board-agnostic Modbus RTU bootstrap descriptor. Exposes ADC, PWM, and pulsecount plus the descriptor slots and selector so a host can upload and activate the full feature descriptor at runtime.

Required resources: /dev/ttyS1, /dev/adc0, /dev/pwm0, /dev/pulsecount0

descriptors/examples/feature_modbus_slot1.yaml

Feature Demo - Modbus RTU Full Map (slot 1)

Feature demo over Modbus RTU. Exercises ADC, PWM, one LED, one button, a sequencer-driven blinky program, runtime config, control and trigger bridges, descriptor swap, capabilities, and uname/sysinfo introspection.

Required resources: /dev/ttyS1, /dev/userleds, /dev/buttons0

descriptors/examples/gateway_serial_can.yaml

Serial to CAN Gateway Demo

Provides a gateway that forwards virtual IO traffic between serial and CAN, including both scalar and segmented 64-bit data paths.

Required resources: /dev/ttyS1, /dev/can0

descriptors/examples/ipc_demo.yaml

Local IPC Demo

Exposes two dummy IO values through the local FIFO-based IPC transport for same-device control and monitoring.

Required resources: /tmp

descriptors/examples/nimble_aios_demo.yaml

NimBLE Automation IO Service (AIOS) Demo

Focused AIOS demo. Exposes four GPIO-backed Digital Inputs, four GPIO-backed Digital Outputs, one dummy Analog Input, and five Analog Outputs backed by a four-channel /dev/pwm0 driver. Four AIOS Analog Outputs write scalar virtual IOs; vecpack combines those values into one four-element PWM duty vector. The fifth Analog Output writes a config IO bound to the PWM frequency. PWM is exposed as Analog Output because duty cycle and frequency are numeric values rather than boolean Digital states.

Required resources: /dev/gpio0, /dev/gpio1, /dev/gpio2, /dev/gpio3, /dev/gpio4, /dev/gpio5, /dev/gpio6, /dev/gpio7, /dev/pwm0, ble

descriptors/examples/nimble_env_sensor_demo.yaml

NimBLE Environmental Sensor Demo

Exposes environmental sensor values and one ADC input over NimBLE standard services, with dummy values used for additional demo data.

Required resources: /dev/adc0, /dev/uorb/sensor_humi0, /dev/uorb/sensor_temp0, /dev/uorb/sensor_baro0, /dev/uorb/sensor_gas0, ble

descriptors/examples/nimble_gpio_analog_demo.yaml

NimBLE GPIO and Analog Demo

Exposes digital inputs, digital outputs, and simple analog values over NimBLE services using a mixed GPIO and dummy IO layout.

Required resources: /dev/gpio0, /dev/gpio1, /dev/gpio2, /dev/gpio3, /dev/gpio4, /dev/gpio5, /dev/gpio6, /dev/gpio7, ble

descriptors/examples/nimble_ots_demo.yaml

NimBLE Object Transfer Service Demo

Exposes two pre-populated tmpfs files over BLE using the standard Bluetooth SIG Object Transfer Service. Bulk data is carried over an L2CAP CoC channel; metadata and OACP/OLCP control points are over GATT.

Required resources: ble, /tmp

descriptors/examples/nimble_sensor_producer.yaml

NimBLE Sensor Producer Demo

Receives environmental values over a descriptor-defined NimBLE custom service and republishes them as NuttX user sensor topics. It uses the same topic layout as can_sensor_producer.yaml: temperature on instance 10, humidity on instance 11, barometer on instance 12, and light on instance 13.

The device advertises as dawn-sensor-prod. The descriptor exposes four write-only custom BLE characteristics for those sensor values. Host-side writes are handled by tools/examples/nimble_sensor_producer_cli.py.

The NTFC hardware suites use this descriptor together with the examples/apps/usensor_reader helper so a parallel NuttX app can confirm that BLE writes were republished into the expected /dev/uorb/sensor_* topics.

Required resources: ble, /dev/usensor, /dev/uorb/sensor_temp10, /dev/uorb/sensor_humi11, /dev/uorb/sensor_baro12, /dev/uorb/sensor_light13

descriptors/examples/nxscope_serial.yaml

NXScope Serial Demo

Streams accelerometer, magnetometer, gyroscope, and a writable dummy-notify signal over an NXScope serial endpoint.

Required resources: /dev/ttyS1, /dev/uorb/sensor_accel0, /dev/uorb/sensor_mag0, /dev/uorb/sensor_gyro0

descriptors/examples/qemu_modbus_tcp_dummy_map.yaml

Modbus TCP Dummy Map

Provides a Modbus TCP register map backed by a large dummy IO set covering coil, packed coil, holding, and input register access.

Required resources: tcp

descriptors/examples/qemu_nxscope_udp.yaml

NXScope UDP Demo

Streams a dummy-notify signal over NXScope UDP and exposes writable channels for NXScope user extension set requests.

Required resources: udp, /tmp

descriptors/examples/serial_core_demo.yaml

Serial Core Demo

Provides the core demo IO set over both shell and serial protocols, including sensors, ADC, DAC, GPIO, PWM, config objects, and descriptor inspection.

Required resources: /dev/ttyS1, /dev/uorb/sensor_accel0, /dev/uorb/sensor_mag0, /dev/uorb/sensor_gyro0, /dev/gpio0, /dev/gpio1, /dev/gpio2, /dev/gpio3, /dev/gpio8, /dev/gpio9, /dev/gpio10, /dev/gpio4, /dev/gpio5, /dev/gpio6, /dev/gpio7, /dev/adc0, /dev/adc1, /dev/adc2, /dev/dac0, /dev/dac1, /dev/dac2, /dev/pwm0, /dev/pwm1, /dev/pwm2, /dev/qe0, /dev/qe1, /dev/urandom

descriptors/examples/serial_leds_buttons_demo.yaml

Serial LEDs and Buttons Demo

Provides serial access to demo data together with one LED output and one button input.

Required resources: /dev/ttyS0, /dev/leds0, /dev/buttons0

descriptors/examples/shell_core_demo.yaml

Shell Core Demo

Provides a broad shell-accessible demo of mixed Dawn IO, including sensors, ADC, DAC, GPIO, PWM, pulsecount, config objects, descriptor inspection, and processing outputs.

Required resources: /dev/uorb/sensor_accel0, /dev/uorb/sensor_mag0, /dev/uorb/sensor_gyro0, /dev/gpio0, /dev/gpio1, /dev/gpio2, /dev/gpio3, /dev/gpio8, /dev/gpio9, /dev/gpio10, /dev/gpio4, /dev/gpio5, /dev/gpio6, /dev/gpio7, /dev/adc0, /dev/adc1, /dev/adc2, /dev/dac0, /dev/dac1, /dev/dac2, /dev/pwm0, /dev/pwm1, /dev/pwm2, /dev/pulsecount0, /dev/qe0, /dev/qe1, /dev/urandom

descriptors/examples/shell_gpio_config_demo.yaml

Shell GPIO and Config Demo

Provides shell access to demo IO, GPIO inputs and outputs, ADC, PWM, config-backed values, system information, and reset control.

Required resources: /dev/adc0, /dev/pwm0, /dev/gpio0, /dev/gpio1, /dev/gpio2, /dev/gpio3, /dev/gpio4, /dev/gpio5, /dev/gpio6, /dev/gpio7

descriptors/examples/shell_nimble_env_demo.yaml

Shell and NimBLE Environmental Demo

Provides shell access and NimBLE exposure for an environmental sensor oriented demo with reset and power control objects.

Required resources: /dev/uorb/sensor_humi0, /dev/uorb/sensor_baro0, ble

descriptors/examples/udp_basic.yaml

Basic UDP Demo

Provides basic UDP access to two dummy IO values plus one notify-capable IO for simple network protocol demonstrations.

Required resources: udp, /tmp

NTFC

descriptors/ntfc/ntfc_can_dummy.yaml

CAN Dummy IO Demo

Provides CAN read, write, indexed, and segmented access to demo IO objects, with shell inspection available on the same device.

Required resources: /dev/can0, /dev/urandom

descriptors/ntfc/ntfc_modbus_rtu_dummy_map.yaml

NTFC Modbus RTU Dummy Map

Provides an NTFC Modbus RTU register map backed by a large dummy IO set covering coil, packed coil, holding, input register, seekable, and file access.

Required resources: /dev/ttyS1, /tmp

descriptors/ntfc/ntfc_wakaama.yaml

NTFC Wakaama LwM2M Demo

Descriptor used by ntfc/tests/wakaama. It registers as ntfc-wakaama and exposes standard digital, analog, sensor, actuation, binary app data, and firmware package resources plus one custom object backed by dummy/file IO values.

Required resources: udp, /tmp

descriptors/examples/wakaama_leshan.yaml

Wakaama LwM2M Leshan Demo

Descriptor used by boards/sim/sim/sim/configs/nsh_wakaama_leshan. It registers as dawn-wakaama-leshan against the public Eclipse Leshan sandbox and exposes the same mixed sensor, actuation, binary-data, and firmware-update object set as the NTFC Wakaama demo. It carries no LTE: the simulator already has host networking.

The descriptor intentionally leaves the Device model number to the board config so simulator and real-board targets can report different model names without forking the object map.

Required resources: udp, /tmp

descriptors/examples/nrf9160dk_wakaama_lte.yaml

nRF9160-DK Wakaama over LTE

Real-board variant of the Wakaama Leshan demo used by boards/arm/nrf91/nrf9160-dk/configs/wakaama. Same Wakaama object set as wakaama_leshan.yaml, plus an LTE system object (system: section) that brings up the data connection before registration. Kept separate from the simulator descriptor because LTE is hardware-only.

Required resources: udp, /tmp

descriptors/examples/thingy91_wakaama_lte.yaml

Thingy:91 Wakaama over LTE

Used by boards/arm/nrf91/thingy91/configs/wakaama. An LTE system object (system: section) brings up the data connection, then the device registers with the public Eclipse Leshan sandbox over Wakaama LwM2M.

Four sensor IOs (temperature, humidity, pressure, gas) feed a latest program that caches each newest sample into a virt IO; LwM2M binds the virts to Temperature (3303), Humidity (3304), Barometer (3315), and Generic Sensor (3300). One sensor IO produces a 3-element RGB vector that a vecsplit program splits into red/green/blue virts, mapped to a custom colour object (id 33001) on resources 0/1/2.

Required resources: udp, /tmp, /dev/uorb/sensor_ambient_temp0, /dev/uorb/sensor_humi0, /dev/uorb/sensor_baro0, /dev/uorb/sensor_gas0, /dev/uorb/sensor_rgb0

descriptors/ntfc/ntfc_nimble_all.yaml

NTFC NimBLE All-Services Target

Descriptor used by ntfc/tests/nimble_ntfc and the nimble_ntfc board configs for nRF52840-DK and nRF5340-DK. It advertises as ntfc-nimble and enables the supported NimBLE service set used by the NTFC BLE suite: DIS, BAS, TPS, AIOS, ESS, IMDS, and OTS.

Most measurement values are backed by dummy_notify IOs with short update intervals so the host can test reads and notifications without requiring real sensors. GPIO inputs and outputs are mapped through GPIO devices. Configuration characteristics use config IO objects that point back to source IO configuration fields, so writes through GATT update the descriptor-backed runtime settings. The OTS section exposes object-transfer state for the BLE object transfer tests.

Required resources: /dev/gpio0, /dev/gpio1, /dev/gpio2, /dev/gpio3, /dev/gpio4, /dev/gpio5, /dev/gpio6, /dev/gpio7, ble

descriptors/ntfc/ntfc_nimble_custom.yaml

NTFC NimBLE Custom Service Target

Minimal descriptor used by ntfc/tests/nimble_ntfc_custom to validate descriptor-declared custom GATT services. It advertises as ntfc-nimx and creates one vendor service 12345678-1234-5678-1234-56789abcdef0 with one read/write characteristic bound to a uint32 dummy IO initialized to 1234.

The test reads the characteristic, writes a new value through BLE, then reads it back. This verifies that the descriptor custom-service schema, NimBLE service registration, GATT read callback, and GATT write callback all use the same bound IO object.

Required resources: ble

descriptors/ntfc/ntfc_nimble_buffer.yaml

NTFC NimBLE Buffer Target

Descriptor used by ntfc/tests/nimble_ntfc_buffer to exercise bulk buffer reads over a descriptor-defined NimBLE custom service. It advertises as ntfc-nimb and exposes one vendor service 12345678-1234-5678-1234-56789abcdf00 with four characteristics:

...df01 reads buf_out_u32, the selected output window.
...df02 reads and writes buf_sel_u32, the history selector offset.
...df03 reads buf_stat_u32, the buffer status words.
...df04 writes buf_trigger, the start/stop capture trigger.

Data flow:

buf_src_ts_u32 -> buf_buffer1 -> buf_out_u32
                      |              ^
                      |              |
                      +-> buf_stat_u32
                      |
                      +<- buf_sel_u32
                      +<- buf_trigger

buf_src_ts_u32 is a periodic timestamp IO. buf_buffer1 is a CProgBuffer with depth 1024 and one-shot capture enabled. The buffer stores incoming timestamp samples in RAM. buf_sel_u32 selects the history offset where 0 means newest sample; writes to the selector update the output window. buf_stat_u32 reports count, depth, head, overflow, snapshot sequence, runtime flags, selected offset, and a reserved word. buf_trigger maps BLE writes to buffer trigger commands: trigger1 restarts capture and trigger2 stops capture.

buf_buffer1 is configured with chunk_size: 32. Because the source timestamp is one uint32 value, the buffer initializes buf_out_u32 as a 32-element virtual output and each GATT read returns 32 samples, or 128 bytes. The test waits until the 1024-sample buffer is full, stops capture to freeze capture, walks selector offsets 0, 32, 64, ..., and reads all pages through the custom characteristic.

Required resources: ble

descriptors/ntfc/ntfc_programs_can.yaml

Programs Over CAN Demo

Provides CAN access to edge-processing programs, including sampled data, control endpoints, push notifications, and segmented transfers.

Required resources: /dev/can0, /dev/urandom

Tests

descriptors/tests/empty_placeholder.yaml

Empty Placeholder Descriptor

Provides an empty descriptor used as a placeholder for builds that do not require any configured IO, programs, or protocols.

Required resources: none

Descriptor Examples

os_required metadata

Feature index

Catalog

Examples

NTFC

Tests

`os_required` metadata