Grok Gadgets ESP32 SDK
On this page
Build an ESP32 gadget for Grok with a reusable C++ library. M5Stack AtomS3 Lite C124 is the first USB example. Other boards need configuration and separate verification.
Documentation uses an ASD-STE100-inspired writing guide. Formal compliance is not claimed.
Experimental alpha. Software tests and ESP32-S3 compilation pass. Physical hardware, actual Grok invocation and mobile behavior remain unverified.
You can build and contribute without a board or Grok account. The example uses standalone Arduino firmware. It is not an ESPHome integration.
Firmware uses the SDK. A computer connects USB to the local gateway. The authenticated route from Grok remains pending.
Compilation checks the build. It does not prove physical LED, button or USB operation.
Start without hardware
Clone adidshaft/grok-gadgets-esp32-sdk and enter its root directory. A sibling repository is unnecessary for the following checks.
You need:
- Python 3.11 or later.
- Git.
- CMake 3.16 or later.
- A C++14 compiler.
- Internet access for the first dependency and toolchain installation.
The recorded build host is macOS arm64. Linux USB permissions, Windows installation and Intel Mac installation remain unverified.
For physical tests, use C124 and a USB-C data cable. ATOM Lite and AtomS3 with a display are different boards.
python3 -m venv .venv
.venv/bin/pip install -r requirements.lock
.venv/bin/pio pkg install
sh tools/check.sh
.venv/bin/python tools/check_contract.py
.venv/bin/pio run -e atoms3-lite-usb
Expected results:
- CTest reports 3/3 host suites passed.
- The contract checker accepts canonical and generated frames.
- PlatformIO reports SUCCESS.
Build output is .pio/build/atoms3-lite-usb/firmware.bin. The same directory contains ELF, bootloader and partition files.
Host tests compile the example loop with simulated board and serial APIs. These commands do not flash a board.
| Next step | Guide |
|---|---|
| Build, inspect hashes, and prepare a separate hardware test | Build, flash and recovery |
| Add your own command and state writer | Reusable library and counter example |
| Understand retries, events and reconnects | Protocol and recovery |
| Check exact board/pin provenance | Manufacturer source record |
| Review what passed and what remains open | Verification |
| Help with software, docs or hardware evidence | Contributing |
What is tested
| Path | Evidence | Remaining gate |
|---|---|---|
| Custom capabilities, strict RGB inputs, bounded retries | C++ host tests against pinned ArduinoJson | Your gadget's hardware handler |
| Canonical protocol 0.1.0 | Pinned fixtures and frame-size validation | Coordinated changes with gateway/SDK consumers |
| C124 USB consumer | Host loop plus simulated USB/gateway integration | Physical enumeration, flashing, LED/button observation |
| ESP32-S3 firmware | Pinned C124 build | Physical board acceptance |
| Wi-Fi and existing Grok Bot connection | Explicit roadmap dependencies | Authenticated reachable transport/provisioning; native invocation evidence |
The canonical gateway contract is consumed through local protocol pins. The Linux SDK targets computer applications; this SDK targets firmware on a microcontroller. Home Assistant uses its upstream MCP server directly. The source repositories document each component; no hosted device service is provided.
For common build/connection errors see Support. Report public defects through the issue chooser. Keep credentials private and use Security for vulnerabilities.
Original code is Apache-2.0; NOTICE and dependency licenses explain attribution and firmware redistribution review. Firmware binaries remain unpublished pending that review. This independent project is unaffiliated with xAI and M5Stack. Community discussion is at r/GrokGadgets, under the hub's conduct policy.
History note
Pre-publication commit dates were reconstructed across 29 September–5 October 2026 at the owner’s request. Verification records retain their actual execution dates. See the history and privacy record.