How rdkcentral/networkmanager works
This repository implements a Thunder plugin that unifies network and WiFi management behind one API surface. The architectural center is a Thunder-hosted, out-of-process service that exposes both COMRPC and JSONRPC, then forwards those requests to one of two backend ecosystems selected at build time:
• GNOME NetworkManager
• RDK Network Service Manager
The plugin replaces the older separate Network and WiFiManager Thunder plugins that used IARM.
Main architectural layers
1. Public API and contract layer
• definition/NetworkManager.json is the Thunder JSON-RPC API definition.
• interface/INetworkManager.h is the C++ interface boundary used inside the plugin.
• docs/NetworkManagerPlugin.md documents the supported behavior.
• The legacy/ folder contains the older Network and WiFiManager API surfaces kept for compatibility and regression coverage.
2. Thunder plugin host layer
• plugin/Module.cpp and plugin/NetworkManager.cpp are the Thunder plugin entry points.
• plugin/NetworkManager.config and plugin/NetworkManager.conf.in define plugin packaging and runtime registration.
• This layer is responsible for service lifecycle, registration with Thunder, and routing external method calls into the implementation.
3. Core orchestration layer
• plugin/NetworkManagerImplementation.cpp/.h contains the main business logic.
• plugin/NetworkManagerJsonRpc.cpp maps JSON-RPC requests into internal operations.
• plugin/NetworkManagerConnectivity.cpp/.h, plugin/NetworkManagerStunClient.cpp/.h, and plugin/NetworkManagerTimer.h handle connectivity state, reachability checks, STUN-based network discovery, and time-based retries/refreshes.
• plugin/NetworkManagerSecretAgent.cpp/.h handles credential/secret exchange with the backend network manager when WiFi authentication requires it.
• plugin/NetworkManagerLogger.cpp/.h centralizes logging.
4. Backend adapter layer
This is where the repo’s major architectural boundary lives: the same Thunder-facing API is adapted to different networking stacks.
GNOME path:
• plugin/gnome/NetworkManagerGnome* files implement GNOME-specific adapters, utilities, event handling, WiFi handling, and proxy logic.
• plugin/gnome/gdbus/* is the D-Bus/GDBus client and proxy layer used to communicate with GNOME NetworkManager.
• This path depends on GLib/libnm-style integration and GDBus-style IPC.
RDK path:
• plugin/rdk/NetworkManagerRDKProxy.cpp/.h is the adapter for RDK’s network service manager.
The compile-time selection is important: the plugin is designed so the Thunder API remains stable while the backend implementation changes underneath.
5. Legacy compatibility layer
• legacy/LegacyNetworkAPIs.* and legacy/LegacyWiFiManagerAPIs.* implement the older Thunder plugin behavior that interacted over IARM.
• These files represent the previous subsystem boundary and are kept to support existing consumers and test coverage during migration.
Core data flow
The main runtime flow is:
Thunder client
→ Thunder plugin entry point
→ JSONRPC/COMRPC handling
→ NetworkManagerImplementation
→ backend proxy/adaptor
→ D-Bus or backend-specific IPC
→ GNOME NetworkManager or RDK Network Service Manager
→ state/event callbacks back through the proxy
→ Thunder events/return values to the client
Connectivity-related behavior is a second flow:
• The plugin queries backend network state.
• It may use STUN and route/connectivity checks to determine external reachability, not just link status.
• Event handling propagates changes from the backend up to Thunder clients.
Secrets/WiFi authentication follow another flow:
• A backend request for credentials is handled by the secret-agent component.
• Credentials are fed back to the backend through the adapter layer.
Important boundaries
• Thunder boundary: everything external to the plugin enters through Thunder’s COMRPC/JSONRPC interfaces.
• IPC boundary: the plugin does not directly own the OS networking stack; it talks to an external service over D-Bus/GDBus or backend proxy interfaces.
• Backend abstraction boundary: GNOME and RDK implementations are separated so the same front-end API can work across platforms.
• Legacy boundary: the old IARM-based plugins are isolated from the new unified plugin, but their APIs and tests remain in-tree.
Supporting tools and services
• tools/plugincli/ contains small CLI/test utilities for exercising the plugin interfaces.
• tools/upnp/ contains router-discovery helpers and systemd units/scripts for UPnP-based discovery workflows.
• conf/99-default-link-local suggests default network configuration behavior used in packaging or deployment.
• plugin/gnome/systemd/* and plugin/gnome/scripts/* support operational setup and migration.
Testing architecture
The test layout reflects the architecture:
• tests/l1Test/ covers lower-level components such as connectivity, route discovery, and STUN behavior.
• tests/l2Test/ covers backend-specific and legacy-facing integration behavior:
- legacy/
- libnm/
- rdk/
• tests/mocks/ provides wrappers and mocks for external dependencies:
- GLib
- libnm
- curl
- IARM
- Thunder framework types
- legacy bus interfaces
That mock layer is important because it mirrors the repo’s real boundaries: the code is designed to isolate the plugin core from system libraries and IPC dependencies.
Build and integration model
• The project uses CMake throughout.
• cmake/Find*.cmake files indicate optional external dependencies such as IARM bus, T2, and rdklogger.
• The repo is built and validated via GitHub Actions workflows in .github/workflows/, including backend-specific tests and PR validation.
In diagram form, the most important thing to show is that this is not a simple monolith: it is a Thunder-facing orchestration layer sitting between a stable network-management API and two alternative backend IPC stacks, with additional subcomponents for connectivity assessment, secret handling, and legacy compatibility.
Main entry points: NetworkManagerImplementation.cpp Manager impl · NetworkManagerGnomeProxy.cpp GNOME proxy · NetworkManagerConnectivity.cpp Connectivity · l2Test L2 tests
Components 24
API & contract
Public surface, interface boundary, and documentation.
- Network API · Thunder JSON-RPC definition for the unified network manager.
definition/NetworkManager.json - INetworkManager · Internal C++ interface boundary used by the plugin.
interface/INetworkManager.h - Plugin docs · Behavioral documentation for the unified plugin.
docs/NetworkManagerPlugin.md
Thunder host
Plugin entry points, registration, and lifecycle.
- Module · Thunder plugin module entry and registration glue.
plugin/Module.cpp - Plugin host · Thunder-facing plugin bootstrap and lifecycle implementation.
plugin/NetworkManager.cpp
Core orchestration
Shared runtime logic for connectivity, STUN, secrets, and logging.
- Manager impl · Main business logic coordinating requests and backend selection.
plugin/NetworkManagerImplementation.cpp - JSON-RPC map · Maps Thunder JSON-RPC calls into internal operations.
plugin/NetworkManagerJsonRpc.cpp - Connectivity · Connectivity state, route checks, and reachability assessment.
plugin/NetworkManagerConnectivity.cpp - STUN client · STUN-based discovery and external reachability checks.
plugin/NetworkManagerStunClient.cpp - Secret agent · Handles WiFi credential and secret exchange with the backend.
plugin/NetworkManagerSecretAgent.cpp - Logger · Centralized logging for the plugin runtime.
plugin/NetworkManagerLogger.cpp
GNOME backend
GNOME NetworkManager adapter and GDBus integration.
- GNOME proxy · GNOME-specific adapter layer for the unified API.
plugin/gnome/NetworkManagerGnomeProxy.cpp - GNOME WiFi · GNOME backend WiFi management logic.
plugin/gnome/NetworkManagerGnomeWIFI.cpp - GNOME events · Event translation and propagation from GNOME backend.
plugin/gnome/NetworkManagerGnomeEvents.cpp - GDBus client · GDBus client used to talk to GNOME NetworkManager.
plugin/gnome/gdbus/NetworkManagerGdbusClient.cpp - GDBus proxy · Proxy layer for GNOME D-Bus communication.
plugin/gnome/gdbus/NetworkManagerGdbusProxy.cpp
RDK backend
RDK Network Service Manager adapter.
- RDK proxy · RDK Network Service Manager adapter.
plugin/rdk/NetworkManagerRDKProxy.cpp
Legacy compatibility
Older Network and WiFiManager surfaces kept for compatibility.
- Legacy network · Older Network plugin surface retained for compatibility.
legacy/LegacyNetworkAPIs.cpp - Legacy WiFi · Older WiFiManager plugin surface retained for compatibility.
legacy/LegacyWiFiManagerAPIs.cpp
Support & tests
Tools, test layers, and mock boundaries.
- L1 tests · Low-level tests for connectivity, routes, and STUN.
tests/l1Test - L2 tests · Backend-specific and legacy-facing integration coverage.
tests/l2Test - Mocks · Wrappers and mocks for Thunder, GLib, libnm, curl, and IARM.
tests/mocks - Plugin CLI · Small CLI utilities for exercising backend interfaces.
tools/plugincli - UPnP tools · Router discovery helpers and supporting scripts.
tools/upnp
Connections 30
- Network API → INetworkManager: defines · The public RPC contract maps to the internal interface boundary.
- Plugin docs → Network API: documents · Docs describe the published JSON-RPC surface.
- Module → Plugin host: boots · Module entry loads and registers the plugin implementation.
- Plugin host → Manager impl: creates · The host layer instantiates the core implementation.
- Manager impl → JSON-RPC map: handles · Implementation delegates request decoding to the JSON-RPC mapper.
- JSON-RPC map → INetworkManager: targets · Mapped operations are expressed through the internal interface.
- Manager impl → Connectivity: uses · Core orchestration consults connectivity state.
- Connectivity → STUN client: probes · Connectivity assessment may trigger STUN-based reachability checks.
- Manager impl → Secret agent: delegates · WiFi credential exchanges are handled by the secret agent.
- Manager impl → Logger: logs · Runtime activity is centralized through the logging layer.
- Manager impl → GNOME proxy: selects · One backend path is the GNOME adapter stack.
- Manager impl → RDK proxy: selects · The alternative backend path is the RDK proxy.
- GNOME proxy → GDBus proxy: bridges · GNOME adapter uses the GDBus proxy layer.
- GDBus proxy → GDBus client: calls · The proxy communicates through the GDBus client.
- GDBus client → GNOME events: receives · Backend state changes are converted into event notifications.
- GNOME proxy → GNOME WiFi: implements · GNOME path includes WiFi-specific behavior.
- GNOME proxy → Secret agent: requests secrets · Secret handling feeds backend authentication flows.
- RDK proxy → Connectivity: reports state · RDK backend participates in connectivity updates.
- Legacy network → Plugin host: compat with · Legacy Network API is retained alongside the new plugin.
- Legacy WiFi → Plugin host: compat with · Legacy WiFiManager API is retained alongside the new plugin.
- L1 tests → Connectivity: covers · L1 tests focus on low-level connectivity behavior.
- L1 tests → STUN client: covers · L1 tests cover STUN and discovery behavior.
- L2 tests → GNOME proxy: covers · Integration tests exercise the GNOME/libnm-style backend path.
- L2 tests → RDK proxy: covers · Integration tests exercise the RDK backend path.
- L2 tests → Legacy network: covers · Legacy tests validate the older Network API surface.
- L2 tests → Legacy WiFi: covers · Legacy tests validate the older WiFiManager API surface.
- Mocks → GDBus client: stubs · Mocks isolate the GDBus and system-library boundaries.
- Mocks → RDK proxy: stubs · Mocks isolate the RDK adapter boundary.
- Plugin CLI → GNOME proxy: exercises · CLI utilities drive backend interface checks.
- UPnP tools → Connectivity: supports · UPnP discovery assists connectivity and router discovery workflows.