Factory Device Provisioning Tool
Standalone Python GUI built for createq factory and lab operators to flash and provision ESP32-S3 devices at scale. Eliminates the #1 manufacturing failure mode — mismatched QR codes and wrong cloud credentials — by tying each physical device (MAC address) to a cloud-registered serial number, auth token, and MQTT password in one automated pipeline.
Project Overview
Before this tool existed, provisioning a createq device required manual steps across multiple systems — read MAC, register in dashboard, generate NVS, run esptool, print label, sync MQTT ACL. Errors at any step meant a device shipped with wrong credentials or a QR code that didn't match its serial. I built a single CustomTkinter GUI that automates the entire chain for non-technical operators.
The tool supports all four product types (ultrasonic, audio-aio, cove-aio, multicast), batch flashing with atomic serial pre-allocation, device replacement workflows, and standalone PyInstaller builds for Linux, macOS, and Windows.
End-to-End Provisioning Pipeline
- USB Auto-Detect — pyudev monitors USB ports; operator plugs in device
- MAC Read — esptool reads WiFi MAC from ESP32-S3
- Cloud Validate — REST API checks device status: NEW / EXISTS / REPLACED (blocks flash if mismatch)
- Serial Allocate — server assigns
CQ-XXXX-YYMM-NNNNN(prefix: US/AIO/COV/MC per product) - Credential Generate — auth token + MQTT password created server-side
- NVS Binary — ESP-IDF
nvs_partition_gen.pygenerates per-device NVS with credentials - Flash — esptool writes bootloader + partition table + OTA data + NVS + app firmware
- ACL Sync — Mosquitto MQTT ACL updated so device can connect immediately
- QR Label — Pillow generates MAC-tied QR code; PDF label sheet for physical device
My Key Contributions
Designed and built the complete detect → validate → allocate → generate → flash → sync workflow as a single operator action. Cloud validation runs before any flash occurs — if status is EXISTS or REPLACED, operator sees a clear warning. Outcome: zero mismatched credentials shipped to field since tool deployment.
Batch mode pre-allocates serial numbers atomically from the server (prevents race conditions when multiple stations flash simultaneously), then flashes devices in parallel with MAC verification after each write. Label mode wizard steps through physical labeling after batch completes. Outcome: factory can provision dozens of devices per hour across multiple workstations.
Product presets for ultrasonic (CWN), audio-aio, cove-aio, and multicast with correct firmware binary, NVS template, serial prefix, and fleet device-type validation against dashboard API. Outcome: one tool serves all product lines — operators select product type from dropdown.
When hardware fails in the field, operator plugs replacement board → tool detects REPLACED status → reassigns existing serial to new MAC → regenerates NVS → flashes → syncs ACL. Old MAC revoked. Outcome: field swap takes minutes, not a support ticket.
CustomTkinter dark/light themes, real-time console output, step-by-step status indicators, and PyInstaller standalone builds (no Python install required on factory PCs). Designed for non-technical operators — minimal training needed. Outcome: manufacturing team runs provisioning independently without engineering support.