Diagnostic Tools & Logs
Relevant source files
The following files were used as context for generating this wiki page:
Diagnostic Tools & Logs in LuCI Mobile allow you to monitor, troubleshoot, and analyze the state of an OpenWrt router directly from a mobile device. The system provides interfaces for executing standard network utilities and retrieving low-level system events generated by the router's kernel and operating system.
These tools interact with the router via the LuCI RPC protocol, enabling remote execution of commands such as ping and traceroute while displaying real-time output within the application. This ensures that administrators can diagnose connectivity issues or system instabilities without requiring a full desktop environment or SSH access.
Sources: README.md:27-27, fastlane/metadata/android/en-US/full_description.txt:20-20
Network Utilities
LuCI Mobile implements a suite of standard network diagnostic tools that execute on the router itself. This provides a "router-side" view of network connectivity, which is essential for determining if issues exist within the local network or at the WAN gateway.
Available Diagnostic Commands
| Tool | Function | Application Usage |
|---|---|---|
| Ping | Tests reachability of a host and measures round-trip time. | Verifies basic end-to-end connectivity. |
| Traceroute | Displays the path and measuring transit delays of packets across a network. | Identifies where packets are being dropped or delayed in the routing path. |
| nslookup | Queries Domain Name System (DNS) to obtain domain name or IP address mapping. | Diagnoses DNS resolution issues on the router. |
Sources: README.md:27-27, fastlane/metadata/android/en-US/full_description.txt:20-20
Diagnostic Execution Flow
The following diagram illustrates how the mobile client requests a diagnostic operation from the OpenWrt router:
The application uses the dio package for handling these HTTP-based RPC requests and flutter_riverpod for state management during the execution of long-running diagnostic commands.
Sources: pubspec.yaml:45-48, README.md:14-14
System & Kernel Logs
LuCI Mobile provides read access to the router's internal logging systems. These logs are critical for identifying hardware failures, driver issues, or service crashes.
Log Types
- System Logs: Capture events from the OpenWrt system services, initialization scripts, and user-space applications.
- Kernel Logs: Capture low-level messages from the Linux kernel, including hardware detection, firewall (Netfilter) events, and driver notifications.
Sources: README.md:27-27, fastlane/metadata/android/en-US/full_description.txt:20-20
Configuration Parameters
System log behavior is governed by the system configuration section within the UCI (Unified Configuration Interface).
{
"cfg01e48a": {
".type": "system",
"hostname": "LuCIMobile",
"log_size": "64"
}
}
- log_size: Defines the size of the local log buffer on the router (e.g., "64" KB).
Sources: assets/mock/uci_system.json:3-15
Activity Feed & Notifications
The application maintains an activity feed that tracks changes and events occurring on the managed router. On Android devices, this is supplemented by background notifications to alert users of significant status changes.
Implementation Details
The diagnostic and monitoring background tasks are managed via platform-specific and cross-platform Flutter plugins:
- workmanager: Handles the scheduling of background tasks for polling router status.
- flutter_local_notifications: Manages the delivery of alerts to the user's device when diagnostic thresholds or activity events are triggered.
Sources: pubspec.yaml:53-54, README.md:28-28, android/app/src/main/AndroidManifest.xml:4-5
Development and Troubleshooting Tools
For developers contributing to LuCI Mobile, the project includes configuration for static analysis and debugging tools to ensure the reliability of diagnostic features.
Analyzer Configuration
The analysis_options.yaml file enforces rules that prevent common diagnostic errors, such as unhandled asynchronous calls which could lead to "zombie" RPC requests.
unawaited_futures: true: Ensures that diagnostic commands are properly awaited.avoid_print: true: Prevents sensitive log data from being leaked to the standard console in production.
Sources: analysis_options.yaml:48-49, analysis_options.yaml:44-44
Reporting Issues
When reporting bugs related to diagnostic tools, the project requires specific environment details to assist in debugging:
- Flutter version (
flutter --version). - Router configuration details and LuCI RPC availability.
- Steps to reproduce the failure.
- Error messages or stack traces captured during the diagnostic attempt.
Sources: CONTRIBUTING.md:144-150
Summary
Diagnostic Tools & Logs in LuCI Mobile provide a comprehensive interface for router maintenance. By integrating standard network utilities (Ping, Traceroute, nslookup) with direct access to System and Kernel logs, the application enables effective troubleshooting of OpenWrt environments. The system relies on the rpcd-mod-luci module on the router to bridge mobile requests with the underlying Linux operating system.
Sources: README.md:65-70, fastlane/metadata/android/en-US/full_description.txt:20-20