How ryunosuke0115/ot-br-posix works
1. Overall role
OpenThread Border Router (OTBR) is a POSIX-based border-router stack that bridges a Thread network to an infrastructure IP network such as Wi‑Fi or Ethernet. The architecture splits cleanly into a Thread-side control/data plane, an infrastructure-side networking plane, and several management/service planes.
2. Primary runtime: otbr-agent
The central daemon is in src/agent. It is the main process that wires together the Thread stack, routing services, discovery services, and platform/network abstractions. Most deployment targets ultimately start this agent, either directly or through service wrappers, init scripts, or Docker/OpenWrt packaging.
3. Thread stack integration and device modes
The src/host layer manages the OpenThread device connection in different modes: NCP and RCP. Files like ncp_host, rcp_host, ncp_spinel, and thread_host show that OTBR can talk to a separate Thread radio coprocessor over Spinel, while thread_helper and async_task provide the supporting execution model.
4. Control-plane boundary: DBus
src/dbus exposes OTBR functionality over DBus, with separate server and client implementations. The server side models Thread objects differently for NCP and RCP (dbus_thread_object_ncp, dbus_thread_object_rcp), while the client side (thread_api_dbus) is used by higher-level components that need to manage or query the Thread stack remotely.
5. Infrastructure networking and packet handling
The POSIX networking layer in src/host/posix handles the interface to the external LAN/WAN side. This includes infrastructure interface control (infra_if), network interface management (netif), UDP proxying, multicast routing, and DNS-SD integration. These pieces are what connect Thread traffic and service discovery to the host OS networking stack.
6. Border routing and backbone behavior
src/backbone_router contains the logic for Thread backbone routing, including DUA routing and neighbor discovery proxying. This is one of the key data-path subsystems: it makes Thread nodes reachable from the infrastructure network and helps maintain IPv6 reachability semantics across the border.
7. Service discovery and commissioning
OTBR supports bidirectional service discovery and commissioning through several focused subsystems: src/mdns, src/trel_dnssd, src/border_agent, and src/sdp_proxy. mdns has multiple backends (avahi, mdnssd, openthread), showing that the design abstracts over different host DNS-SD providers. border_agent is the commissioning-facing boundary for external Thread commissioners.
8. Higher-level APIs: REST and web UI
src/rest provides a REST service with OpenAPI documentation, using JSON serialization helpers and embedded web server support. src/web/web-service adds a web-facing service and static frontend assets for browser-based management. These are management surfaces rather than core routing components, and they sit above the agent/host subsystems.
9. OpenWrt-specific integration
The src/openwrt tree provides platform integration for OpenWrt, including UBus bindings, controller logic, UI views, and init/config templates. This is a separate management/deployment boundary for routers running OpenWrt, not a core protocol implementation.
10. Deployment and packaging
The repository includes multiple packaging targets under etc/, including Docker images, OpenWrt packaging, Yocto recipes, and example platform configs for Raspberry Pi, Debian, Ubuntu, Fedora, and NXP Linux. Service templates and init scripts in src/agent and src/web indicate the same core binaries are adapted into different system managers and container layouts.
11. Shared libraries and protocol assets
Common infrastructure lives in src/common and src/utils for logging, event loops, task runners, byte/string utilities, DNS helpers, PSKc/steering data, and socket/system helpers. src/proto defines protobufs for capabilities and telemetry, which support cross-component reporting but are not the main control path.
12. Testing and validation boundaries
The test structure mirrors the architecture: gtests for core utilities and host/network logic, DBus integration tests, mDNS tests, REST tests, and script-based end-to-end scenarios under tests/scripts. tools/reference_device and tests/mdns indicate the repo also validates against external device behavior, not just unit-level contracts.
13. Key architectural flow to diagram
A useful diagram should show: OpenThread radio/NCP/RCP ↔ host/posix and dbus layers ↔ otbr-agent ↔ infrastructure interface. From that central path, branch out to routing/backbone services, service discovery/commissioning services, and management surfaces such as DBus, REST, web UI, and OpenWrt integration.
Main entry points: agent otbr-agent · posix Infra network · host Host stack · mdns mDNS
Components 19
Runtime
Core daemon, host stack integration, and platform boundary
- otbr-agent · Main border-router process that wires together host, routing, and service subsystems
src/agent - Host stack · OpenThread device integration layer for NCP/RCP and async execution
src/host - NCP host · Controls a separate radio coprocessor in NCP mode
src/host/ncp_host.cpp - RCP host · Coordinates the host side of an RCP-based Thread setup
src/host/rcp_host.cpp - Thread host · Top-level host abstraction shared by the device-mode implementations
src/host/thread_host.cpp
Control Plane
DBus and agent-facing management interfaces
- DBus server · Exports OTBR state and actions over DBus
src/dbus/server - DBus client · Client-side DBus access used by higher-level components
src/dbus/client
Networking
Infrastructure-side networking, routing, and discovery
- Infra network · POSIX infrastructure-side interface, netif, multicast, and UDP proxying
src/host/posix - Backbone router · Thread backbone routing, DUA routing, and ND proxy behavior
src/backbone_router - mDNS · Abstraction over host DNS-SD backends for service discovery
src/mdns
Services
Commissioning, telemetry, REST, web, and OpenWrt surfaces
- Border agent · Commissioning-facing boundary for external Thread commissioners
src/border_agent - SDP proxy · Advertising and discovery proxying between Thread and infrastructure networks
src/sdp_proxy - TREL DNSSD · Bridges TREL traffic with DNS-SD service discovery
src/trel_dnssd - REST API · REST management service with JSON and OpenAPI support
src/rest - Web service · Browser-facing management service and static frontend assets
src/web/web-service - OpenWrt · OpenWrt-specific UBus, controller, init, and UI integration
src/openwrt
Shared
Common helpers, protocol definitions, and utilities
Connections 29
- otbr-agent → Host stack: uses · The daemon drives Thread device integration through the host layer
- otbr-agent → DBus server: serves · Exposes agent functionality over DBus
- otbr-agent → Infra network: binds · Connects Thread traffic to the infrastructure interface
- otbr-agent → Backbone router: routes · Installs backbone routing and ND proxy behavior
- otbr-agent → mDNS: publishes · Coordinates service discovery publishing and subscription
- otbr-agent → Border agent: commissioning · Provides the commissioning boundary for external controllers
- otbr-agent → SDP proxy: proxies · Handles service discovery proxying across the border
- otbr-agent → TREL DNSSD: bridges · Connects TREL with DNS-SD discovery
- otbr-agent → REST API: manages · Offers HTTP management services
- otbr-agent → Web service: hosts · Serves browser-based management UI
- otbr-agent → Common: shares · Uses core runtime utilities and main loop primitives
- otbr-agent → Utilities: shares · Uses common helper libraries
- Host stack → Thread host: abstracts · Provides the common Thread device abstraction
- Thread host → NCP host: mode · Implements NCP device mode
- Thread host → RCP host: mode · Implements RCP device mode
- Host stack → DBus client: queries · Can consume DBus-managed Thread state remotely
- DBus server → Host stack: controls · DBus server mediates host and Thread stack operations
- Infra network → Common: uses · Relies on shared main-loop and task infrastructure
- Backbone router → Infra network: depends · Uses infrastructure-side networking to forward reachability
- mDNS → Infra network: announces · Uses host networking for service discovery traffic
- REST API → Common: uses · Builds on shared runtime support
- Web service → Common: uses · Builds on shared runtime support
- OpenWrt → otbr-agent: wraps · Integrates deployment and UI around the core agent
- OpenWrt → Infra network: configures · Configures platform networking and firewall behavior
- Border agent → DBus server: exposes · Sits on the management/control boundary
- SDP proxy → mDNS: leverages · Uses DNS-SD backends for proxying discovery
- TREL DNSSD → mDNS: integrates · Connects TREL advertisement with mDNS/DNS-SD
- REST API → Protobufs: serializes · Uses shared schemas for capability and telemetry data
- otbr-agent → Protobufs: reports · Can emit capabilities and telemetry through shared schemas