LuCI RPC Integration
Relevant source files
The following files were used as context for generating this wiki page:
LuCI Mobile communicates with OpenWrt routers using the LuCI RPC (Remote Procedure Call) system. This integration allows the mobile application to perform administrative tasks, monitor system health, and manage network configurations remotely. The app functions as a client that interacts with the rpcd daemon and its associated modules on the router to retrieve real-time data and commit configuration changes.
Sources: README.md:14-16, PRIVACY_POLICY.md:15-18
Architecture and Connectivity
The application establishes a direct link between the mobile device and the OpenWrt router. It supports both HTTP and HTTPS schemes, including the ability to handle self-signed certificates. Credentials, such as the router's IP address, username, and password, are stored locally on the device using encrypted storage to facilitate secure authentication with the LuCI RPC interface.
Sources: README.md:55-57, PRIVACY_POLICY.md:10-13
Communication Flow
The following diagram illustrates the interaction between the LuCI Mobile app and the router's internal services.
The app sends JSON-RPC requests to the router. The rpcd daemon processes these calls through specific modules like rpcd-mod-luci (for general system and UCI access) and rpcd-mod-iwinfo (for wireless-specific data).
Sources: README.md:14-16, README.md:73-75
Core RPC Components
The integration relies on specific OpenWrt packages to expose the necessary APIs. Without these modules, the application cannot populate its dashboard or manage network settings.
| Package | Purpose | ubus Object Example |
|---|---|---|
rpcd-mod-luci | Provides access to network devices, system status, and UCI management. | luci-rpc |
rpcd-mod-iwinfo | Provides detailed wireless interface and station information. | iwinfo |
Sources: README.md:73-77, README.md:83-85
Data Models and Payloads
The application consumes JSON responses from the router to represent network state. These payloads include details for interfaces, wireless radios, and DHCP leases.
Network Interface Dump
The app parses the output of getNetworkDevices (or similar interface dumps) to track the status of WAN, LAN, and Guest networks.
Sources: assets/mock/interface_dump.json, assets/mock/network_devices.json
Wireless Device Data
The RPC integration retrieves radio-level details, including frequency, transmission power, and hardware modes (e.g., 802.11ac).
Sources: assets/mock/wireless_devices.json
Configuration Management (UCI)
LuCI Mobile manages router settings by interacting with the Unified Configuration Interface (UCI) via RPC. It handles zones, forwarding rules, and DHCP reservations.
Apply-with-Rollback Protocol
For configuration changes, the application utilizes the router's native apply-with-rollback mechanism.
- The app sends a configuration change request.
- The router applies the change temporarily.
- The app must confirm the change within a specific timeframe.
- If the app fails to confirm (e.g., due to a lost connection), the router automatically reverts to the previous configuration.
Sources: README.md:49-53, fastlane/metadata/android/en-US/full_description.txt:27-28
Management Functions
- Firewall: Managing zones (e.g.,
lan,wan), port forwards, and traffic rules. Sources: assets/mock/uci_firewall.json - DHCP: Assigning static leases for specific MAC addresses. Sources: assets/mock/uci_dhcp.json
- System: Modifying hostname, timezone, and logging parameters. Sources: assets/mock/uci_system.json
The sequence shows the safe application of configuration changes where the "confirm" step prevents permanent lockouts.
Sources: README.md:49-53
Troubleshooting RPC Connections
Connection failures typically stem from missing modules or router-side resource constraints.
- Missing Modules: If the dashboard is empty, ensure
rpcd-mod-luciandrpcd-mod-iwinfoare installed and therpcdservice is restarted. - Parallel Request Stalls: Some routers stall when handling multiple parallel RPC requests. The recommended fix is limiting the
uhttpdserver to one request at a time. - Self-Signed Certificates: The app requires explicit user trust for self-signed certificates, which must be verified against the router's fingerprint.
Sources: README.md:92-106
Summary
LuCI RPC Integration enables LuCI Mobile to act as a comprehensive management interface for OpenWrt. By utilizing rpcd modules and the UCI system, the application provides real-time monitoring and safe configuration edits. The use of an apply-with-rollback protocol ensures that network changes do not result in permanent loss of access, while encrypted local storage maintains the security of administrative credentials.
Sources: README.md:14-18, README.md:49-53, PRIVACY_POLICY.md:10-13