Wireless AP Controller System
A centralized cloud-to-edge management platform for wireless access points running custom OpenWrt firmware — built on an architecture that applies equally to any fleet of connected edge devices.
Overview
The platform was originally built to manage a fleet of wireless access points running custom OpenWrt firmware. The core architecture, however, is not tied to any specific device type. The same control plane can onboard and manage any embedded device that runs a lightweight management agent — IoT sensors, industrial edge nodes, smart controllers, or networked appliances.
When a device powers on, its agent connects outbound to the cloud over MQTT, identifies itself, and requests provisioning. The controller validates the device, assigns the correct profile and configuration, and adds it to the managed fleet. From that point on, all configuration updates, health monitoring, firmware upgrades, and maintenance operations are executed centrally — without requiring physical access or per-device manual setup.
The Core Architectural Idea
Any Device
Any embedded device that can run the agent and reach the internet becomes a managed edge node — APs, sensors, PLCs, smart devices.
Outbound-Only MQTT
Devices initiate all connections outbound. No inbound ports needed on remote sites. Works across NAT, cellular, and constrained networks.
Desired-State Model
The controller stores what the device should look like. A reconnecting device is automatically reconciled back to its desired state.
Top-Level Architecture
Admin Console
Vue.js — fleet management UI
Cloud Controller
Laravel Control Plane
MQTT Broker
Real-time messaging backbone
Device Agent
Device Agent
Device Agent
Device Agent
Architecture Components
Device Agent / Bootstrap Service
Embedded control-plane client on every edge device
- —Establishes secure MQTT session on device startup
- —Publishes device identity, model, firmware version, and MAC address
- —Receives provisioning instructions and desired configuration from cloud
- —Applies config locally and acknowledges result back to controller
- —Sends periodic heartbeats and reports health state
MQTT Broker
Real-time device-to-cloud messaging backbone
- —Terminates persistent MQTT sessions from thousands of edge devices
- —Routes bootstrap, heartbeat, telemetry, and command messages
- —Decouples always-on device connectivity from controller business logic
- —Supports topic-based separation of tenants, sites, or device groups
- —Enables outbound-only device connections — no inbound firewall exposure
Provisioning Service
Device onboarding and first-contact handler
- —Validates device identity on first contact
- —Determines whether device is new, known, or blocked
- —Creates or updates the device inventory record
- —Assigns default site, group, or device profile
- —Generates initial desired configuration and pushes it via MQTT
Device Registry & Inventory
Canonical source of truth for all managed devices
- —Maintains a record for every device known to the platform
- —Tracks online/offline status and last-seen timestamp
- —Stores firmware version, site assignment, and profile mapping
- —Records lifecycle state: new, provisioned, managed, updating, unhealthy
- —Supports fleet search, filtering, and targeting from the admin console
Profile & Configuration Service
Fleet-scale configuration modeling and push
- —Defines reusable device profiles mapped to multiple devices
- —Supports per-device overrides on top of profile defaults
- —Renders final desired configuration from profile plus overrides
- —Detects configuration drift between desired and reported state
- —Publishes updated desired state to affected devices via MQTT
Maintenance & Firmware Service
Operational job orchestration and upgrade management
- —Orchestrates firmware upgrades with staged rollout support
- —Dispatches reboot, restart, and remote diagnostics commands
- —Manages firmware artifact repository with version and model metadata
- —Tracks every maintenance job: queued, running, succeeded, failed
- —Maintains full audit trail of maintenance history per device
Telemetry, Health & Logs Service
Fleet observability and incident response
- —Tracks device heartbeat and connection state in real time
- —Records provisioning events and command execution results
- —Collects device-reported logs and diagnostic outputs
- —Surfaces alerts for offline devices, failed config apply, or failed upgrades
- —Stores historical activity for troubleshooting and reporting
Web Admin Console
Operator-facing management interface
- —Lists, searches, and filters the managed device fleet
- —Reviews onboarding status, health, and firmware versions
- —Creates and edits device profiles and configuration overrides
- —Triggers maintenance actions and monitors job progress
- —Displays logs, upgrade history, and device metadata
Device Lifecycle
- 1
Boot & Connect
The device boots its firmware and the management agent starts automatically. The agent establishes a secure outbound MQTT session to the cloud broker.
- 2
Bootstrap & Identify
The agent publishes its identity payload — serial number, hardware model, firmware version, MAC address, and any pre-assigned site or tenant hint.
- 3
Provisioning
The controller validates the device, checks whether it is known or new, assigns a profile, renders the desired configuration, and delivers it back through MQTT.
- 4
Managed Operation
The device applies its configuration locally, enters steady-state operation, and begins sending periodic heartbeats. The controller marks it as managed in the inventory.
- 5
Configuration Updates
When an operator changes a profile or overrides device settings, the controller recalculates desired state and pushes a config update command via MQTT. The device applies and acknowledges.
- 6
Maintenance & Firmware Upgrade
Operators schedule firmware upgrades, reboots, log collection, or diagnostics from the admin console. The controller dispatches the job through MQTT and tracks status through completion.
- 7
Reconnect & Reconcile
After a reboot or upgrade, the agent reconnects and the controller automatically reconciles actual device state against the latest desired state — no manual re-provisioning required.
Key Design Patterns
Desired-State Management
The controller is the authoritative source of desired device state. Devices report actual state. The gap between desired and actual triggers automatic provisioning, config push, or maintenance actions — making the system idempotent and self-healing.
Outbound-Only Device Connectivity
Devices initiate all connections to the cloud. No inbound ports are required at remote sites. This works naturally across NAT, cellular links, and constrained networks — and significantly reduces the attack surface at distributed locations.
Profile-Based Fleet Configuration
Configuration is defined once in a reusable profile and applied to many devices. Per-device overrides are supported where needed. One profile change can update thousands of devices without touching them individually.
Staged Firmware Rollout
Firmware upgrades are orchestrated as jobs with staged rollout support by device group or site. Each device downloads, validates, installs, reboots, and reports outcome. The controller tracks every stage and can halt a rollout on failure.
Per-Device Identity & Security
Each device connects with its own identity — certificates, keys, or signed bootstrap credentials. The controller maintains an allowlist and validates every device before provisioning. MQTT connections are TLS-protected. Firmware artifacts are signed and approved before distribution.
Health Monitoring & Alerting
Devices send heartbeats on a recurring interval. If heartbeat stops, the controller raises an alert. Operators can remotely collect logs, re-push configuration, or schedule a maintenance job — all without physical access to the device.
Beyond Wireless APs
The platform was built for wireless access points, but the architecture is intentionally generic. The edge agent pattern works for any device that can:
The same controller infrastructure — provisioning, profile management, firmware orchestration, telemetry, and admin console — can be reused for IoT sensor networks, industrial edge gateways, smart building controllers, networked appliances, or any fleet of remotely managed embedded devices.
- Run an embedded Linux or RTOS environment
- Establish an outbound TCP connection to the internet or a private cloud
- Communicate over MQTT
- Apply a rendered configuration file or command
- Report its own state and health