ESS - Environmental Sensing

Component Type: NimBLE GATT Service

Status: Implemented

Overview

CProtoNimblePrphEss - Bluetooth SIG Environmental Sensing Service (UUID 0x181A).

Units conversion: see Units conversion.

Configuration

Kconfig

  • CONFIG_DAWN_PROTO_NIMBLE_ESS: enables the Environmental Sensing Service.

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

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

  • CONFIG_DAWN_PROTO_NIMBLE_ESS_DESC_VALID_RANGE: enables Valid Range descriptors (0x2906).

  • CONFIG_DAWN_PROTO_NIMBLE_ESS_DESC_MEASUREMENT: enables ES Measurement descriptors (0x290C).

  • CONFIG_DAWN_PROTO_NIMBLE_ESS_DESC_CONFIGURATION: enables ES Configuration descriptors (0x290B).

  • CONFIG_DAWN_PROTO_NIMBLE_ESS_DESC_TRIGGER_SETTING: enables ES Trigger Setting descriptors (0x290D).

YAML

services:
  ess:
    characteristics:
      - type: temperature
        data: temp1
        metadata:
          user_description: "Ambient temperature"
          valid_range:
            min: 4294963296  # raw sint16 -4000, 0.01 C
            max: 8500        # raw sint16 8500, 0.01 C
          measurement:
            measurement_period: temp_measurement_period_cfg
            update_interval: temp_update_interval_cfg
          configuration: temp_es_configuration_cfg
          trigger_setting: temp_es_trigger_setting_cfg
      - type: humidity
        data: hum1

Supported characteristic type values:

  • temperature

  • humidity

  • pressure

  • uv_index

  • wind_speed

  • wind_direction

  • gas_resistance (uses non-standard 0x272A UUID; see Units conversion)

  • light

Supported metadata fields:

  • user_description: UTF-8 text for the Characteristic User Description descriptor (0x2901), truncated to 16 bytes by the current generator.

  • valid_range: raw BLE-format min/max values for the Valid Range descriptor (0x2906). Values are encoded little-endian using the measurement characteristic width.

  • measurement: fields for the ES Measurement descriptor (0x290C). Supported keys are flags, sampling_function, measurement_period, update_interval, application, and uncertainty. Each configured field is an IO reference, normally a config IO bound to the sensor IO configuration that owns that setting. Missing fields are encoded as zero. The descriptor value uses the Bluetooth ESS layout: flags as uint16, sampling function as uint8, measurement period and update interval as uint24 seconds, application as uint8, and uncertainty as uint8 in 0.5 percent units.

  • configuration: IO reference for the ES Configuration descriptor (0x290B). The referenced IO returns the Bluetooth-format descriptor bytes, typically through a config IO bound to the sensor setting.

  • trigger_setting: IO reference for the ES Trigger Setting descriptor (0x290D). The referenced IO returns the Bluetooth-format descriptor bytes, typically through a config IO bound to the sensor setting.

Optional Characteristics

Supported optional descriptors:

  • Characteristic User Description descriptor (UUID 0x2901) through metadata.user_description.

  • Valid Range descriptor (UUID 0x2906) through metadata.valid_range.

  • ES Measurement descriptor (UUID 0x290C) through metadata.measurement.

  • ES Configuration descriptor (UUID 0x290B) through metadata.configuration.

  • ES Trigger Setting descriptor (UUID 0x290D) through metadata.trigger_setting.

Limitations

The ESS Descriptor Value Changed characteristic is not implemented. Dynamic changes to descriptor metadata are not announced through ESS service-level metadata characteristics.

Doxygen