# ieee1905d

## Introduction

This package implements IEEE 1905.1-2013 standard and parts of 1905.1a-2014.

It provides the following software components:

- `libieee1905.so` — shared library for IEEE 1905 TLV and CMDU generation functions
- `libmidgen.so` — shared library for generating message IDs for 1905 CMDUs
- `ieee1905d` — user-space daemon implementing the 1905 stack with CLI for status and management

Additionally, the package provides the following 1905 extension plugins:

- `map.so` — Multi-AP EasyMesh extension
- `snoop.so` — dumps all received 1905 CMDUs over UBUS (primarily for debugging)
- `topology.so` — builds and exposes the full network topology


## ieee1905d Command-Line Options

```
Usage: ieee1905d [options]

Options:
   -h                          print usage
   -v                          print version
   -s <socket path>            UBUS socket path (default: NULL)
   -D                          run as a daemon (default: false)
   -R                          run in 1905 Registrar mode
   -c <conf-file>              specify configuration file (default: /etc/config/ieee1905)
   -O <objname>                override the default UBUS object name
   -d                          debug level; more 'd's mean more verbose (default: LOG_INFO)
   -p <pidfile>                pid file path (default: /var/run/ieee1905.pid)
   -l                          log to syslog
   -o <file>                   log to file
   -f                          treat above file as a FIFO for rolling logs
   --version                   print version
   --alid <macaddress>         specify the AL MAC address for this instance
   --config <conf-file>        same as -c
   --no-lo                     exclude the 'lo' interface from the 1905 AL
   --help                      print usage
```


## UCI Configuration

### `ieee1905` Section

The main configuration section configures the 1905 stack, including extensions, AL identity, and device attributes.

Example configuration with the Multi-AP EasyMesh plugin (`map`) and Full-Topology plugin (`topology`) enabled. The `al-iface` section specifies that interfaces `br-lan` and any interface matching the patterns `/wl.*` and `/wds.*` are part of the 1905 AL. If `br-lan` is a bridge, all its enslaved interfaces are automatically included. The `ap` sections define AP credentials for WSC Registrar auto-configuration in the 2.4 GHz and 5 GHz bands:

```
config ieee1905 'ieee1905'
        option enabled '1'
        option extension '1'
        list extmodule 'map'
        list extmodule 'topology'
        option macaddress 'aa:aa:aa:10:20:30'
        option registrar '2 5'

config ap
        option band '2'
        option ssid 'TestSSID.2'
        option encryption 'psk2'
        option key '1234567890'

config ap
        option band '5'
        option ssid 'TestSSID.5'
        option encryption 'psk2'
        option key '1234567890'

config al-iface
        option ifname 'br-lan'
        option ifname '/wl.*'
        option ifname '/wds.*'
```

#### `ieee1905` Section Options

Section | Option | Type | Required | Default | Description
--------|--------|------|----------|---------|-------------
ieee1905 | enabled | boolean | no | 1 | Set to 0 to disable the 1905 stack.
 " | macaddress | MAC address | no | auto | The 1905 AL MAC address. Set to a valid locally administered MAC address, or `auto` to generate one randomly at startup.
 " | registrar | string | no | (none) | Space-separated list of frequency bands for which this device acts as a WSC Registrar. Valid values: `2` (2.4 GHz), `5` (5 GHz), `60` (60 GHz). When built with 6 GHz support: `6` (6 GHz). Use `*` to enable all bands.
 " | extension | boolean | no | 0 | Set to 1 to enable loading of extension plugins.
 " | extmodule | list | no | (none) | Names of extension plugins to load and start. Examples: `map`, `topology`, `snoop`.
 " | manufacturer | string | no | "IOPSYS" | Manufacturer name reported in WSC messages (max 64 characters).
 " | model_name | string | no | "1905-SampleDev" | Model name reported in WSC messages (max 32 characters).
 " | device_name | string | no | "1905Device" | Friendly device name reported in WSC messages (max 32 characters).
 " | model_number | string | no | (none) | Model number reported in WSC messages (max 32 characters).
 " | serial_number | string | no | (none) | Serial number reported in WSC messages (max 32 characters).
 " | device_type | string | no | (none) | WSC device type in the format `CC-OOOOOOOOO-SC` (category, OUI, sub-category).
 " | os_version | string | no | (none) | OS version reported in WSC messages (hex or decimal integer).
 " | uuid | string | no | (none) | Device UUID in standard hyphenated format (e.g. `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`).
 " | control_url | string | no | (none) | Control/management URL for this device.
 " | primary_vid | integer | no | 0 | Primary VLAN ID used for sending and receiving 802.1Q-tagged CMDUs. Valid range: 1–4094.
 " | exclude_tagging | list | no | (none) | Interface names that should not have CMDUs tagged. Supports regex names prefixed with `:` or `/`. Example: `/eth.*`
 " | frag_scheme | integer | no | (none) | CMDU fragmentation scheme. `1` = fragment at TLV boundary, `2` = fragment at octet boundary.

#### `al-iface` Section Options

Section | Option | Type | Required | Default | Description
--------|--------|------|----------|---------|-------------
al-iface | enabled | boolean | no | 1 | Set to 0 to disable this `al-iface` section entirely.
 " | ifname | list | no | (none) | Interface names to include in the 1905 AL. If an interface is a bridge, all its enslaved interfaces are automatically included. Supports regex names prefixed with `:` or `/`. Example: `/wlan.*`
 " | exclude_ifname | list | no | (none) | Interface names to exclude from the 1905 AL. Supports regex names prefixed with `:` or `/`.

#### `ap` Section Options

Section | Option | Type | Required | Default | Description
--------|--------|------|----------|---------|-------------
ap | band | integer | yes | (none) | Frequency band for this AP configuration. Must match one of the values in the `registrar` list. Valid values: `2`, `5`, `6`, `60`.
 " | ssid | string | yes | (none) | SSID for AP auto-configuration in this band.
 " | encryption | string | yes | psk2 | Encryption type. Valid values: `none`, `psk`, `psk2`, `psk-mixed`, `sae`, `sae-mixed`.
 " | key | string | yes | (none) | Pre-shared key (passphrase) when encryption is `psk`, `psk2`, `psk-mixed`, `sae`, or `sae-mixed`.
 " | uuid | string | no | (default UUID) | AP-specific UUID in standard hyphenated format.
 " | manufacturer | string | no | "IOPSYS" | AP manufacturer name (max 64 characters).
 " | model_name | string | no | "Multi-AP-device" | AP model name (max 32 characters).
 " | device_name | string | no | "Multi-AP-device" | AP device name (max 32 characters).
 " | model_number | string | no | (none) | AP model number (max 32 characters).
 " | serial_number | string | no | (none) | AP serial number (max 32 characters).
 " | device_type | string | no | (default type) | AP device type in WSC format `CC-OOOOOOOOO-SC`.
 " | os_version | string | no | (none) | AP OS version (hex or decimal integer).

---

Example configuration for ieee1905d in Registrar mode on 2.4 GHz and 5 GHz with VLAN tagging and full device identity:

```
config ieee1905 'ieee1905'
        option enabled '1'
        option registrar '2 5'
        option primary_vid '101'
        option manufacturer 'ABC Inc.'
        option model_name 'SmartDevice'
        option device_name 'SD123'
        option model_number '123.456.001'
        option serial_number '1234567890.001'
        option os_version '230005'

config ap
        option band '2'
        option ssid 'TestSSID.2'
        option encryption 'psk2'
        option key '1234567890'

config ap
        option band '5'
        option ssid 'TestSSID.5'
        option encryption 'psk2'
        option key '1234567890'

config al-iface
        option enabled 1
```

After ieee1905d starts with the above configuration, interfaces can be added to or removed from the 1905 AL at runtime using the `add_interface` and `del_interface` UBUS methods on the `ieee1905` object.


## UBUS Objects and APIs

### `ieee1905`

The main `ieee1905` UBUS object is always published by the daemon.

```
root@iopsys:~# ubus -v list ieee1905
'ieee1905' @1d99fac8
        "id":{}
        "log":{"feature":"String","level":"Integer"}
        "start":{}
        "stop":{}
        "status":{}
        "info":{}
        "neighbors":{}
        "links":{}
        "others":{}
        "arptable":{}
        "apconfig":{"ifname":"String","band":"Integer","action":"String"}
        "refresh":{}
        "cmdu":{"dst":"String","src":"String","type":"Integer","mid":"Integer","vid":"Integer","data":"String","ifname":"String"}
        "buildcmdu":{"type":"Integer","ifname":"String","args":"Array"}
        "rxcmdu":{"src":"String","ifname":"String","type":"String","mid":"Integer","data":"String"}
        "add_interface":{"ifname":"String"}
        "del_interface":{"ifname":"String"}
        "vlan":{"vid":"Integer"}
        "frag_scheme":{"dst":"String","mode":"Integer"}
```

Method | Parameters | Description
-------|-----------|------------
`id` | — | Returns the AL MAC address of this 1905 device.
`log` | `feature` (String, optional), `level` (Integer, optional) | Gets or sets the logging configuration.
`start` | — | Starts the 1905 stack.
`stop` | — | Stops the 1905 stack.
`status` | — | Returns the current service status.
`info` | — | Returns detailed information about this 1905 device.
`neighbors` | — | Lists all directly reachable 1905 neighbor devices.
`links` | — | Lists all known 1905 links.
`others` | — | Lists non-1905 neighbors.
`arptable` | — | Displays the internal ARP/neighbor table.
`apconfig` | `ifname` (String), `band` (Integer), `action` (String) | Triggers AP auto-configuration on the specified interface and band.
`refresh` | — | Requests a topology refresh.
`cmdu` | `dst` (String), `src` (String, optional), `type` (Integer), `mid` (Integer, optional), `vid` (Integer, optional), `data` (String), `ifname` (String, optional) | Sends a raw CMDU. `data` is a hex string of TLV bytes.
`buildcmdu` | `type` (Integer), `ifname` (String, optional), `args` (Array) | Builds a CMDU of the given type with the given arguments.
`rxcmdu` | `src` (String), `ifname` (String), `type` (String), `mid` (Integer, optional), `data` (String) | Injects a CMDU as if received from the network (for testing).
`add_interface` | `ifname` (String) | Adds an interface to the 1905 AL at runtime.
`del_interface` | `ifname` (String) | Removes an interface from the 1905 AL at runtime.
`vlan` | `vid` (Integer, optional) | Gets (if no argument) or sets the primary VLAN ID. Valid range: 0–4094.
`frag_scheme` | `dst` (String), `mode` (Integer) | Sets the CMDU fragmentation scheme for a specific peer. `mode`: `1` = TLV boundary, `2` = octet boundary.

### `ieee1905.al.*`

Per-interface UBUS objects are created for each active 1905 AL interface. The object name follows the pattern `ieee1905.al.<ifname>`.

```
root@iopsys:~# ubus -v list 'ieee1905.al.*'
'ieee1905.al.eth0' @eb801e37
        "status":{}
        "neighbors":{}
        "cmdu":{"dst":"String","src":"String","type":"Integer","mid":"Integer","vid":"Integer","data":"String","ifname":"String"}
```

Method | Parameters | Description
-------|-----------|------------
`status` | — | Returns status information for this interface.
`neighbors` | — | Lists 1905 neighbors reachable via this interface.
`cmdu` | `dst` (String), `src` (String, optional), `type` (Integer), `mid` (Integer, optional), `vid` (Integer, optional), `data` (String), `ifname` (String, optional) | Sends a CMDU on this specific interface.

### `ieee1905.extension`

When the package is built with extension support enabled, the `ieee1905.extension` object is published. It provides methods for dynamically loading, unloading, starting, and stopping extension plugins.

```
root@iopsys:~# ubus -v list ieee1905.extension
'ieee1905.extension' @d3d28211
        "load":{"name":"String"}
        "unload":{"name":"String"}
        "start":{"name":"String"}
        "stop":{"name":"String"}
        "list":{}
```

Method | Parameters | Description
-------|-----------|------------
`load` | `name` (String) | Loads and registers an extension plugin by name.
`unload` | `name` (String) | Unloads and deregisters an extension plugin by name.
`start` | `name` (String) | Starts (unpauses) a loaded extension plugin.
`stop` | `name` (String) | Stops (pauses) a loaded extension plugin.
`list` | — | Lists all loaded extension plugins with their name, status, and CMDU type range.

### `ieee1905.map` — Multi-AP Plugin

The Multi-AP plugin implements 1905 CMDUs and extensions required by the Wi-Fi Alliance Multi-AP EasyMesh specification.

After `map.so` is loaded via `ieee1905.extension` `load`, the `ieee1905.map` UBUS object is published.

```
root@iopsys:~# ubus -v list ieee1905.map
'ieee1905.map' @1cd3d8ae
        "register":{"module":"String","data":"String"}
        "status":{}
        "fuzz":{}
```

Method | Parameters | Description
-------|-----------|------------
`register` | `module` (String), `data` (String) | Registers a Multi-AP client application (e.g. mapagent, mapcontroller). `data` is a hex-encoded `map_module` structure describing the CMDU types the client handles.
`status` | — | Returns the list of registered Multi-AP client modules and whether CMDU fuzzing is enabled.
`fuzz` | — | Toggles CMDU fuzzing mode on or off (for testing purposes).

Through the `register` method, Multi-AP client applications can subscribe to receive, process, and transmit EasyMesh Multi-AP CMDUs.

### `ieee1905.topology` — Topology Plugin

The topology extension plugin builds the full topology of connected 1905 and non-1905 devices in the network.

```
root@iopsys:~# ubus -v list ieee1905.topology
'ieee1905.topology' @1cd3d8ae
        "dump":{}
        "show":{}
```

Method | Parameters | Description
-------|-----------|------------
`dump` | — | Returns detailed information about all discovered 1905 nodes, their interfaces, and connections.
`show` | — | Returns a concise view of the 1905 network nodes and their interconnections.

### `ieee1905.snoop` — Snoop Plugin

The snoop extension plugin intercepts all received 1905 CMDUs and emits them as UBUS events for debugging and analysis.

```
root@iopsys:~# ubus -v list ieee1905.snoop
'ieee1905.snoop' @2fa1c309
        "type":{"type":"Array"}
```

Method | Parameters | Description
-------|-----------|------------
`type` | `type` (Array of String) | Filters which CMDU types are snooped. Each element is a hex string (e.g. `"0x0001"`). Up to 16 types can be specified. If not set, all CMDU types are reported.

When a matching CMDU is received, the plugin emits a `ieee1905.cmdu` UBUS event with the following fields:

Field | Type | Description
------|------|------------
`type` | String | CMDU type in hex (e.g. `"0x0001"`)
`mid` | Integer | CMDU message ID
`ifname` | String | Receiving interface name
`source` | String | Physical source MAC address
`origin` | String | AL MAC address of the originating device
`cmdu` | String | Full raw CMDU as a hex string


## Code Structure

Source code is in the `src/` directory.

### Core Daemon

File | Description
-----|------------
`main.c` | Main entry point and command-line argument parsing.
`i1905.c,h` | Core daemon structures and functions.
`i1905_al.c` | IEEE-1905 Abstraction Layer (AL) functions.
`i1905_ubus.c` | UBUS object and method implementations.
`i1905_cmd.c` | Unix socket command server for the CLI.
`i1905_cmdresp.c` | CLI command response implementations.
`i1905_dm.c,h` | IEEE-1905 Data Model as per TR-181.
`i1905_extension.c,h` | Extension plugin registration and management interface.
`i1905_netlink.c` | rtnetlink event handling for interface state changes.
`i1905_wifi.c,h` | Wi-Fi HAL abstraction layer (wraps libwifi).
`i1905_wsc.c,h` | WSC M1 and M2 message generation and processing.
`config.c,h` | UCI configuration parsing and management.
`debug.c,h` | Logging and debug output functions.

### CMDU Processing

File | Description
-----|------------
`cmdu.c,h` | CMDU buffer manipulation, construction, and parsing.
`cmdu_input.c` | Processing of received CMDUs.
`cmdu_output.c` | Construction and transmission of CMDUs.
`cmdufrag.c,h` | CMDU fragmentation and defragmentation.
`cmdu_ackq.c,h` | Timer-queue for outgoing CMDUs awaiting a response or ACK.
`1905_tlvs.h` | IEEE-1905 CMDU type definitions and TLV data structures.
`i1905_tlvs.c` | TLV encoding and decoding.
`policy.c` | TLV policies and CMDU parsing rules.

### Libraries and Utilities

File | Description
-----|------------
`midgen.c` | CMDU message ID generator (`libmidgen.so`).
`neigh.c,h` | Directly connected network neighbor management.
`timer.c,h,timer_impl.h` | Timer utility functions.
`util.c,h` | General helper and utility functions.
`hlist.h` | Hash list data structure.
`cryptutil.c,h` | Cryptographic functions used by IEEE-1905 (AES, SHA etc.).
`bufutil.h` | Helpers for unaligned buffer read/write.

### Extension Plugins

**`extensions/map/`** — Multi-AP EasyMesh plugin (`map.so`)

File | Description
-----|------------
`easymesh.h` | Multi-AP EasyMesh TLV definitions and CMDU types.
`map.c` | Main plugin entry point implementing the 1905 extension interface.
`map_module.c` | West-side interface allowing Multi-AP client applications to register and exchange CMDUs.
`r1.c` | EasyMesh R1 TLV policies and parsing.
`r2.c` | EasyMesh R2 TLV policies and parsing.
`r3.c` | EasyMesh R3 TLV policies and parsing.
`r4.c` | EasyMesh R4 TLV policies and parsing.
`r6.c` | EasyMesh R6 TLV policies and parsing.
`policy.c` | Multi-AP TLV policy handling.
`maputil.c` | Shared utility functions (`libmaputil.so`).
`tlv_checker.c` | TLV structure validation.
`cmduchecker.c` | CMDU structure validation.
`aes-siv.c` | AES-SIV authenticated encryption (used for DPP/PMK).
`i1905_security.c` | IEEE-1905 security functions.
`i1905_eapol.c` | EAPOL frame handling for EasyMesh 1905 security support.
`cntlrsync.c` | Controller configuration synchronization support in dynamic controller mode.
`tests/mapclient.c`, `tests/mapclient1.c`, `tests/mapclient2.c` | Example Multi-AP applications demonstrating plugin use.

**`extensions/snoop/`** — CMDU snooping plugin (`snoop.so`)

File | Description
-----|------------
`snoop.c` | Intercepts all received CMDUs and emits them as `ieee1905.cmdu` UBUS events.

**`extensions/topology/`** — Network topology plugin (`topology.so`)

File | Description
-----|------------
`topology.c` | Builds and exposes the full 1905 network topology via the `ieee1905.topology` UBUS object.

### Tests

**`tests/fuzz/`** — Fuzzing test components for CMDU send and receive paths.


## Dependencies

| Dependency | Link | License |
|------------|------|---------|
| libeasy | https://dev.iopsys.eu/hal/libeasy.git | LGPL 2.1 |
| libwifi | https://dev.iopsys.eu/hal/libwifi.git | LGPL 2.1 |
| libuci | https://git.openwrt.org/project/uci.git | LGPL 2.1 |
| libubox | https://git.openwrt.org/project/libubox.git | ISC |
| libblobmsg_json | https://git.openwrt.org/project/libubox.git | ISC |
| libubus | https://git.openwrt.org/project/ubus.git | LGPL 2.1 |
| libjson-c | https://github.com/json-c/json-c | MIT |
| libnl-3 | https://github.com/thom311/libnl.git | LGPL 2.1 |
| libnl-genl-3 | https://github.com/thom311/libnl.git | LGPL 2.1 |
| libnl-route-3 | https://github.com/thom311/libnl.git | LGPL 2.1 |
| libssl / libcrypto | https://github.com/openssl/openssl | Apache 2.0 |
