Wakaama LwM2M

Component Type: Protocol

Status: In Progress

Overview

CProtoWakaama is an LwM2M client protocol object based on Eclipse Wakaama. It exposes descriptor-bound Dawn IO objects as LwM2M resources over UDP/CoAP.

Implementation

  • CProtoWakaama owns the Wakaama client context, UDP socket, registration objects, and worker thread.

  • Built-in Security, Server, and Device objects are created by the protocol instance. Descriptor bindings are created as internal Wakaama object bindings objects.

  • The built-in Device object (3) is firmware-owned, but selected resources may be fed from descriptor IOs through the config.device block (the same pattern as nimble’s built-in services): battery_voltage, battery_level and battery_status bind IOs to resources 7 (Power Source Voltage), 9 (Battery Level) and 20 (Battery Status), which the Device object then serves through the generic IO read path, converting to the LwM2M units/enum.

  • LwM2M server configuration is descriptor-owned. Kconfig values only provide defaults for descriptors that do not list config.servers.

  • UDP no-security, UDP multi-server registration, bootstrap provisioning, and DTLS PSK transport are implemented. DTLS requires TinyDTLS and CONFIG_DAWN_PROTO_WAKAAMA_DTLS_PSK.

  • Upstream Wakaama allocates during normal runtime request handling. Dawn keeps that rule violation contained by routing Wakaama allocation hooks through a protocol-owned static memory pool instead of the system heap.

  • Standard object/resource names are firmware-owned. Descriptor tooling resolves names from CProtoWakaama::WAKAAMA_OBJECT_* and CProtoWakaama::WAKAAMA_RESOURCE_* definitions.

  • DTYPE_BLOCK resources are encoded as LwM2M opaque values. When the server requests text format, Wakaama returns opaque payloads as base64 text.

Observe/Notify

Observe is handled through Wakaama. When Dawn notify support is enabled, writes to bound IO resources queue resource-change notifications and the Wakaama thread publishes them with lwm2m_resource_value_changed.

Limitations

  • Wakaama is an exception to the Dawn rule that dynamic allocation is allowed only during initialization. The upstream core calls its allocation hook from read, discover, write, observe, registration, and bootstrap processing. The allocation is still runtime allocation, but it is bounded by CONFIG_DAWN_PROTO_WAKAAMA_MEMORY_POOL_SIZE and isolated from the system heap.

  • DTLS support is PSK-only.

  • Bootstrap coverage currently provisions no-security UDP client registration.

  • Bootstrap-created coaps:// final servers must be preconfigured in YAML so their DTLS buffers and credentials exist before runtime.

Configuration

Kconfig

  • CONFIG_DAWN_PROTO_WAKAAMA: enables Wakaama protocol support.

  • CONFIG_DAWN_PROTO_WAKAAMA_ENDPOINT: default endpoint name.

  • CONFIG_DAWN_PROTO_WAKAAMA_SERVER_HOST: default LwM2M server host.

  • CONFIG_DAWN_PROTO_WAKAAMA_SERVER_PORT: default server UDP port.

  • CONFIG_DAWN_PROTO_WAKAAMA_LOCAL_PORT: default local UDP port.

  • CONFIG_DAWN_PROTO_WAKAAMA_LIFETIME: default registration lifetime.

  • CONFIG_DAWN_PROTO_WAKAAMA_SHORT_SERVER_ID: default short server ID.

  • CONFIG_DAWN_PROTO_WAKAAMA_DTLS_PSK: enables coaps:// connections with TinyDTLS PSK credentials supplied by YAML.

  • CONFIG_DAWN_PROTO_WAKAAMA_MEMORY_POOL_SIZE: static arena size used by the Wakaama allocation hooks for runtime request processing.

  • CONFIG_DAWN_PROTO_WAKAAMA_DEVICE_MANUFACTURER: Device object manufacturer string used when YAML does not override it.

  • CONFIG_DAWN_PROTO_WAKAAMA_DEVICE_MODEL_NUMBER: Device object model number string used when YAML does not override it.

  • CONFIG_DAWN_PROTO_WAKAAMA_DEVICE_SERIAL_NUMBER: Device object serial number string used when YAML does not override it.

  • CONFIG_DAWN_PROTO_WAKAAMA_DEVICE_FIRMWARE_VERSION: Device object firmware version string used when YAML does not override it.

YAML

protocols:
  - id: wakaama_main
    type: wakaama
    config:
      endpoint: ntfc-wakaama
      local_port: 56830
      servers:
        - host: 127.0.0.1
          port: 5683
          lifetime: 60
          short_server_id: 123
        - host: 127.0.0.1
          port: 5684
          lifetime: 60
          short_server_id: 124
          security_instance: 1
          server_instance: 1
      device:
        manufacturer: Dawn
        model_number: simulator
        serial_number: dawn-wakaama
        firmware_version: '0.1'
      objects:
        - object: temperature
          instance: 0
          resources:
            - resource: sensor_value
              io: temperature
              access: read
        - object: digital_output
          instance: 0
          resources:
            - resource: digital_output_state
              io: led
              access: rw
        - object_id: 33000
          instance: 0
          resources:
            - resource_id: 1
              io: counter
              access: rw
        - object: binary_app_data_container
          instance: 0
          resources:
            - resource: binary_app_data
              io: blob
              access: rw

Supported fields:

  • config.endpoint: LwM2M endpoint name. If omitted, the Kconfig default is used.

  • config.server_host: LwM2M server IPv4 address or host name. If omitted, the Kconfig default is used.

  • config.server_port: LwM2M server UDP port. If omitted, the Kconfig default is used.

  • config.local_port: local UDP port used by the client. If omitted, the Kconfig default is used.

  • config.lifetime: registration lifetime in seconds. If omitted, the Kconfig default is used.

  • config.short_server_id: short server ID used by the default server when config.servers is omitted.

  • config.servers: explicit Security/Server Object instances. When present, this list replaces the Kconfig server defaults.

  • config.device: Device object strings. Each field is optional and falls back to its Kconfig default when omitted.

  • config.objects: object/resource bindings. Use object and resource for firmware-defined names, or object_id and resource_id for numeric IDs.

Supported server fields:

  • host: server IPv4 address or host name. Defaults to config.server_host or the Kconfig default.

  • port: server UDP port.

  • scheme: coap or coaps. coaps requires CONFIG_DAWN_PROTO_WAKAAMA_DTLS_PSK.

  • security_mode: none or psk.

  • psk_identity: PSK identity string for security_mode: psk.

  • psk_key: PSK key as a hexadecimal string.

  • lifetime: registration lifetime for this server.

  • short_server_id: LwM2M short server ID.

  • security_instance: Security Object instance ID.

  • server_instance: Server Object instance ID.

  • bootstrap: marks the server as a bootstrap server. Requires CONFIG_WAKAAMA_BOOTSTRAP.

  • holdoff: Security Object bootstrap holdoff.

  • bootstrap_timeout: Security Object bootstrap timeout.

Supported resource fields:

  • io: Dawn IO object bound to the resource.

  • access: read, write, or rw.

  • resource: standard resource name.

  • resource_id: numeric custom resource ID.

Supported Objects

The generic Wakaama object binding supports one or more instances per LwM2M object. Each configured resource maps to one Dawn IO.

Standard objects currently used by the qemu NTFC target:

Name

ID

digital_input

3200

digital_output

3201

analog_input

3202

analog_output

3203

generic_sensor

3300

temperature

3303

humidity

3304

actuation

3306

light_control

3311

binary_app_data_container

19

Additional standard object names are defined for later bindings: illuminance, pressure, barometer, voltage, current, accelerometer, magnetometer, gyrometer, connectivity_monitoring, and cellular_connectivity.

Supported Resources

Common scalar resources:

  • digital_input_state (5500)

  • digital_output_state (5550)

  • analog_input_current_value (5600)

  • analog_output_current_value (5650)

  • sensor_value (5700)

  • sensor_units / units (5701)

  • min_measured_value (5601)

  • max_measured_value (5602)

  • min_range_value (5603)

  • max_range_value (5604)

  • application_type (5750)

  • on_off (5850)

  • dimmer (5851)

  • colour / color (5706)

Block resources:

  • binary_app_data (/19/x/0): opaque data backed by seekable DTYPE_BLOCK IO.

External Control

ControlIO: supported.

CProtoWakaama supports runtime start/stop control through CIOControl. When stopped, the Wakaama worker thread and UDP client processing are inactive. When started again, the client resumes registration and resource processing.

TriggerIO: not supported.

Doxygen