Grillo Device Provisioner

Factory tool for provisioning Grillo sensors. Flashes firmware, reads device MAC addresses, registers devices in cloud inventory, and prints identification labels.

🚀 Quick Start

Windows (recommended): Download the latest Grillo Device Provisioner.exe and run it — no installation required.

Linux:

# Install dependencies
pip install -r requirements.txt

# Grant serial port access (log out and back in after)
sudo usermod -a -G dialout $USER

# Launch GUI
python esp32_device_reader_gui.py

# Or use CLI mode
python esp32_device_reader.py

On Linux, you may also need to install python3-tk for GUI support: sudo apt install python3-tk (Debian/Ubuntu) or sudo dnf install python3-tkinter (Fedora)

From source (other platforms):

pip install -r requirements.txt
python esp32_device_reader_gui.py    # Launch GUI
python esp32_device_reader.py        # CLI mode

If your PC doesn't recognize the ESP32, install the USB driver: CP210x or CH340

🏗️ Provisioning Flow

Firmware CDN ─→ Download firmware ─→ Flash ESP32 via USB ─→ Read MAC address
(S3+CloudFront)                                                    │
                                                                   ▼
                                              Print DYMO label ←─ Register device
                                              (ID, type, QR)      (cloud-backend API)

1. Select device type (Pulse or One) and firmware version
2. Download firmware from firmware.cloud.grillo.io
3. Flash firmware via esptool over USB serial
4. Read MAC address from flashed device (becomes device ID)
5. Register device via cloud-backend inventory API
6. Print label with device ID, type, firmware version, QR code

🖥️ GUI

Features:

• Device type selection and firmware version picker
• One-click flash, register, and label print
• Serial monitor with simplified device status view
• Status badges: Active, Connection, TimeSync, ADXL, ADS, Messaging, Data
• Hardware reset button (DTR/RTS)
• Auto-detects new devices on port refresh

📶 Reset NVS (clear APN / WiFi)

The Clear NVS button erases the device's nvs partition (0x9000, size 0x6000), where the firmware stores the cellular APN (cellular_creds/apn) and WiFi credentials. After clearing, the device re-opens its WiFi setup portal (GrilloPulse-XXXX → http://192.168.4.1) on the next boot, so a technician can pick the APN / WiFi from a phone — no scripts needed.

⚠️ This wipes the entire NVS partition, including station metadata. That's fine — the server re-pushes station metadata on the next check-in.

⌨️ CLI Usage

python esp32_device_reader.py [OPTIONS] [port]

Flag	Description
-p	Print label (requires labelle + DYMO printer)
-r	Register with cloud-backend API
-c [FILE]	Save to CSV (default: devices.csv)
-f [DIR]	Flash firmware from directory (default: firmware/)
-d TYPE	Device type: pulse or one (default: pulse)

⚡ Firmware Flashing

Device	Chip	Flash Size	Firmware File
Pulse	ESP32-S3	16MB	grillo-pulse-firmware.bin
One	ESP32	8MB	grillo-one-firmware.bin

python esp32_device_reader.py -f                    # Flash Pulse (default)
python esp32_device_reader.py -f -d one             # Flash One

Supports both merged binaries (recommended) and individual partition files. See --help for details.

🛠️ Development

pip install -r requirements.txt
python esp32_device_reader_gui.py    # Run from source

Build the Windows executable: run build_exe.bat on a Windows machine — it produces dist\Grillo Device Provisioner.exe.

Releasing: pushing a v* tag triggers the Build Windows EXE GitHub Action, which builds the exe on a Windows runner and attaches it to a GitHub Release. This is what the Windows download link above points at, so technicians always get the current build.

Platform Notes

Platform	Serial Access	Label Printing
Windows	Install CP210x/CH340 driver	DYMO + Zadig (WinUSB)
Linux	sudo usermod -a -G dialout $USER	pip install labelle
macOS	Built-in drivers	pip install labelle

🔗 Related Repos

Repo	Relationship
grillo-firmware-pulse	Firmware binary flashed onto Pulse devices
grillo-firmware-one	Firmware binary flashed onto One devices
grillo-cloud-backend	Inventory API for device registration