Introduction
Relevant source files
The following files were used as context for generating this wiki page:
LuCI Mobile is an open-source Flutter client designed for managing OpenWrt routers. The application interfaces with the LuCI RPC (Remote Procedure Call) system to facilitate administrative tasks, monitor network health, and configure router hardware directly from a mobile device. It supports multiple router profiles, enabling users to switch between different network environments seamlessly.
The project prioritizes security and privacy by storing all credentials locally on the device and communicating directly with the router without intermediate servers. It provides a modern interface using Material Design 3 and implements safety mechanisms like the apply-with-rollback protocol to prevent permanent loss of connectivity during configuration changes.
Sources: README.md:19-22, PRIVACY_POLICY.md:12-23, fastlane/metadata/android/en-US/full_description.txt:37-43
Core System Architecture
LuCI Mobile functions as a bridge between the user and the OpenWrt router's internal ubus system via the LuCI RPC interface. The app requires specific modules on the router to retrieve network and wireless data.
Communication Flow
The application initiates requests to the router using either HTTP or HTTPS. It specifically targets the luci-rpc object to execute commands and retrieve system information.
The diagram shows the communication path from the mobile application to the router's internal bus via RPC modules.
Sources: README.md:83-93, fastlane/metadata/android/en-US/full_description.txt:45-47
Technical Stack
The application is built using the Flutter framework and utilizes several key libraries for state management, networking, and security.
| Component | Technology | Purpose |
|---|---|---|
| Framework | Flutter (SDK ^3.8.1) | Cross-platform UI development |
| State Management | flutter_riverpod | Reactive application state handling |
| Networking | dio | Handling HTTP/RPC requests |
| Secure Storage | flutter_secure_storage | Encrypting router credentials locally |
| Charts | fl_chart | Visualizing throughput and CPU metrics |
| Notifications | flutter_local_notifications | Background activity alerts (Android) |
Sources: pubspec.yaml:27-50, CONTRIBUTING.md:21-25
Key Features and Functionalities
LuCI Mobile provides a comprehensive suite of tools for router administration. The system categorizes these into monitoring, configuration, and diagnostics.
Dashboard and Monitoring
The dashboard aggregates real-time metrics including CPU load, memory usage, uptime, and wireless signal strength. It tracks active clients and allows searching by hostname, IP, or MAC address.
Network and Wireless Configuration
Users can modify wireless parameters such as SSID, security protocols, channels, and radio widths. The app also manages advanced network features:
- Firewall: Port forwarding, traffic rules, and zone management.
- DHCP: Static address reservations and client blocking.
- Services: Control for SQM, adblock, UPnP, and DDNS.
Safety Protocol: Apply-with-Rollback
For configuration changes, the app utilizes the router's native protocol. If the application cannot confirm the success of a change within a specific timeframe, the router automatically restores the previous configuration to prevent lockout.
Sources: README.md:24-48, fastlane/metadata/android/en-US/full_description.txt:39-41
Development and Contribution Workflow
The project follows standard Flutter development practices and uses automated scripts for release management.
Development Standards
Contributors must adhere to the Dart Style Guide and pass static analysis checks. The analysis_options.yaml file enforces specific lint rules, including mandatory closing of sinks and subscription cancellation to prevent memory leaks.
The diagram illustrates the mandatory steps for contributing code to the repository.
Sources: CONTRIBUTING.md:47-60, analysis_options.yaml:41-45
Release Process
A CI-driven release script (scripts/release.sh) manages versioning. It automates the following:
- Increments version numbers (major, minor, or patch) in
pubspec.yaml. - Bumps the build number.
- Creates a Git tag.
- Pushes changes to trigger CI builds.
Sources: scripts/release.sh:45-98
Security and Privacy Model
LuCI Mobile implements a zero-knowledge privacy model. No usage data, analytics, or credentials are sent to external servers.
- Credential Encryption: Uses
flutter_secure_storagefor industry-standard encryption on the device. - Direct Connection: All traffic remains within the user's network or VPN.
- Certificate Handling: The app explicitly asks for user permission before trusting self-signed HTTPS certificates commonly found on home routers.
Sources: PRIVACY_POLICY.md:12-32, README.md:50-53
LuCI Mobile provides a secure, modern interface for OpenWrt management, focusing on technical transparency and robust network control through the LuCI RPC framework.