AIOS - Automation IO

Component Type: NimBLE GATT Service

Status: Implemented

Overview

CProtoNimblePrphAios - Bluetooth SIG Automation IO Service (UUID 0x1815).

Each bound IO is exposed as one digital or analog characteristic. Seekable IOs are rejected at start time; use OTS for those.

Use Digital characteristics for boolean or bitfield-style inputs and outputs, such as GPIO. Use Analog characteristics for scalar numeric values, including DAC outputs and PWM duty-cycle controls. A PWM duty cycle is not a boolean Digital state, so expose PWM duty-cycle controls through analog_outputs.

For multichannel drivers, bind AIOS characteristics to scalar software IO surfaces and bridge them to the driver with a program. For example, expose one scalar virt Analog Output per PWM channel and use vecpack to write one multichannel vector to the physical PWM IO.

Runtime configuration surfaces can also be exposed as scalar Analog characteristics through config IO bindings. For example, a config IO bound to a PWM freq config item can provide runtime frequency control.

Configuration

Kconfig

  • CONFIG_DAWN_PROTO_NIMBLE_AIOS: enables the Automation IO Service.

  • CONFIG_DAWN_PROTO_NIMBLE_AIOS_AGGREGATE: enables the Aggregate characteristic (0x2A5A).

  • CONFIG_DAWN_PROTO_NIMBLE_EXTENDED_METADATA: enables optional metadata descriptor support for standard services.

  • CONFIG_DAWN_PROTO_NIMBLE_AIOS_DESC_USER_DESCRIPTION: enables Characteristic User Description descriptors (0x2901).

  • CONFIG_DAWN_PROTO_NIMBLE_AIOS_DESC_NUMBER_OF_DIGITALS: enables Number of Digitals descriptors (0x2909).

  • CONFIG_DAWN_PROTO_NIMBLE_AIOS_DESC_VALUE_TRIGGER_SETTING: enables Value Trigger Setting descriptors (0x290A).

  • CONFIG_DAWN_PROTO_NIMBLE_AIOS_DESC_TIME_TRIGGER_SETTING: enables Time Trigger Setting descriptors (0x290E).

  • CONFIG_DAWN_PROTO_NIMBLE_AIOS_DESC_PRESENTATION_FORMAT: enables Characteristic Presentation Format descriptors (0x2904).

  • CONFIG_DAWN_PROTO_NIMBLE_AIOS_DESC_EXTENDED_PROPERTIES: enables Characteristic Extended Properties descriptors (0x2900).

YAML

services:
   aios:
     aggregate: true
     groups:
      - digital_inputs:
          - data: din1
            metadata:
              user_description: "AIOS input 1"
              number_of_digitals: 1
              value_trigger_setting: din1_trigger_cfg
              time_trigger_setting: din1_time_trigger_cfg
              extended_properties: 0x0000
              presentation_format:
                format: 1
                exponent: 0
                unit: 0x2700
                namespace: 1
                description: 0
          - din2
        digital_outputs: [dout1, dout2]
        analog_outputs:  [aout1]
      - analog_inputs:   [ain1]

Supported fields:

  • groups: list of IO groups. Each group may contain digital_inputs, digital_outputs, analog_inputs, analog_outputs.

  • aggregate: optional boolean. When enabled, Dawn exposes one AIOS Aggregate characteristic (UUID 0x2A5A) that reads the current values of readable Digital characteristics followed by readable Analog characteristics.

  • group entries may be plain IO references or objects with data (or io) and optional metadata.

  • analog_outputs may bind writable scalar numeric outputs. For a multichannel PWM device, bind these to scalar virt IOs and use vecpack to update the physical PWM vector.

  • metadata.user_description: optional read-only Characteristic User Description descriptor (UUID 0x2901), encoded as UTF-8 and limited to 16 bytes in the descriptor configuration.

  • metadata.number_of_digitals: optional read-only Number of Digitals descriptor (UUID 0x2909), encoded as a single unsigned byte. This is intended for Digital characteristics.

  • metadata.value_trigger_setting: optional read-only Value Trigger Setting descriptor (UUID 0x290A). The value is read from the referenced IO object, whose bytes must already be encoded in the Bluetooth AIOS Value Trigger Setting descriptor format.

  • metadata.time_trigger_setting: optional read-only Time Trigger Setting descriptor (UUID 0x290E). The value is read from the referenced IO object, whose bytes must already be encoded in the Bluetooth AIOS Time Trigger Setting descriptor format. AIOS uses Time Trigger Setting together with Value Trigger Setting on the same characteristic.

  • metadata.presentation_format: optional read-only Characteristic Presentation Format descriptor (UUID 0x2904). Fields are encoded in the Bluetooth GATT Presentation Format layout: one-byte format, signed one-byte exponent, little-endian uint16 unit, one-byte namespace, and little-endian uint16 description.

  • metadata.extended_properties: optional read-only Characteristic Extended Properties descriptor (UUID 0x2900). The value is encoded as the standard little-endian uint16 bitfield. Set only bits that match the characteristic behavior exposed by the binding.

Optional Characteristics

Supported:

  • Aggregate characteristic (UUID 0x2A5A) through aggregate: true.

  • Characteristic User Description descriptor (UUID 0x2901) through metadata.user_description on each Digital or Analog binding.

  • Number of Digitals descriptor (UUID 0x2909) through metadata.number_of_digitals on Digital bindings.

  • Value Trigger Setting descriptor (UUID 0x290A) through metadata.value_trigger_setting on Digital or Analog bindings.

  • Time Trigger Setting descriptor (UUID 0x290E) through metadata.time_trigger_setting on Digital or Analog bindings.

  • Characteristic Presentation Format descriptor (UUID 0x2904) through metadata.presentation_format on Digital or Analog bindings.

  • Characteristic Extended Properties descriptor (UUID 0x2900) through metadata.extended_properties on Digital or Analog bindings.

Value Trigger Setting Format

The Value Trigger Setting descriptor uses the Bluetooth AIOS descriptor layout: one condition octet followed by a comparison value. The comparison value length and meaning depend on the condition:

  • no comparison bytes for conditions that use the None value format;

  • uint16 little-endian for an Analog comparison value;

  • a Digital bit mask with the same two-bit-field layout and size as the corresponding Digital characteristic;

  • two uint16 little-endian values for Analog boundary comparisons.

The Dawn descriptor does not reinterpret these bytes. The referenced IO must return exactly the bytes that should be exposed through descriptor 0x290A.

Time Trigger Setting Format

The Time Trigger Setting descriptor uses the Bluetooth AIOS descriptor layout: one condition octet followed by a comparison value. The comparison value length and meaning depend on the condition:

  • no comparison bytes for condition 0x00, no time-based triggering;

  • uint24 little-endian time interval in seconds for conditions 0x01 and 0x02;

  • uint16 little-endian count for condition 0x03.

The Dawn descriptor does not reinterpret these bytes. The referenced IO must return exactly the bytes that should be exposed through descriptor 0x290E.

Doxygen