BOON PIN
Back to Projects

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.

MQTTOpenWrtLaravelVue.jsEdge ComputingIoTFirmware OTADesired-State Management

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

ProvisioningProfile & ConfigDevice RegistryJob OrchestratorTelemetry & LogsFirmware Repo

MQTT Broker

Real-time messaging backbone

outbound connect on boot

Device Agent

Device Agent

Device Agent

Device Agent

Cloud ControllerMQTT BrokerEdge Device (any type)

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. 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. 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. 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. 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. 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. 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. 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