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 eth 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 Shell

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

Modbus

Blinky Modbus RTU 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

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, 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. 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/can_blinky_cli.py

descriptors/examples/blinky_nimble_demo.yaml

Blinky NimBLE Demo

Sequencer-driven LED output with BLE control via NimBLE. Start/stop, full state table, and individual dwell times are exposed over a custom BLE service.

Required resources: /dev/gpio4, ble

Host helper: tools/examples/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. The shell exposes start/stop control and runtime configuration via ConfigIO objects (start index and state table).

Required resources: /dev/leds0

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. 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/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 and PWM 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

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. Host-side writes are handled by tools/examples/nimble_sensor_producer_cli.py.

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: eth

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: eth, /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, 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/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: eth, /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_nimble_all.yaml

NTFC NimBLE All-Services Target

Descriptor used by ntfc/tests/nimble_ntfc. It advertises as ntfc-nimbl 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