Grok Gadgets ESP32 SDK
Build USB and Wi-Fi gadgets for your Grok Bot with an Arduino sketch. Declare commands and events with grok::Gadget.
The gateway connects your gadget to Grok Bot.
The owner tested one ESP32-S3 OLED kit over USB and Wi-Fi. Experimental alpha: see the
project status.
Independent project, not affiliated with SpaceXSI.
On this page
Start here
| Path | Next step |
|---|---|
| Use the tested kit | Wire and check the OLED kit |
| Build a gadget | Declare commands, state and events |
| Connect Grok Bot | Use the current Grok Bot connection |
First physical experiment
The delivered kit uses a YD-ESP32-23 v1.3, ESP32-S3 N16R8 board and a 1.3-inch SH1106 OLED. It includes the ApTechDeals breadboard and jumper wires. The delivered display differs from the ordered 0.96-inch module. Build the tested kit with the first experiment. Without hardware, start with the host checks below. The SDK supports custom gadgets. This kit is the tested example; AtomS3 Lite is an optional example with build evidence only.
Writing style: ASD-STE100-inspired English. Use short sentences, active verbs and one instruction per step. This is not certified compliance.
Quickstart
You need Python 3.11+, CMake 3.16+, Git and a C++14 compiler. No board or account.
git clone https://github.com/adidshaft/grok-gadgets-esp32-sdk.git
cd grok-gadgets-esp32-sdk
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: nine host test suites pass, four sketch transcripts pass the contract check, and the optional C124 firmware compiles: build verified, hardware pending. Next, create your own gadget.
What a gadget looks like
#include <GrokSession.h>
bool on = false;
grok::Gadget gadget("Desk LED", "0.1.0", "esp32s3");
void report(JsonObject state, void *) { state["led"]["on"] = on; }
grok::Error setLed(JsonObjectConst args, void *) {
on = args["on"];
digitalWrite(4, on ? HIGH : LOW); // your hardware
return {};
}
void setup() {
pinMode(4, OUTPUT);
gadget.state(report);
gadget.command("led.set", setLed, nullptr,
R"({"description":"Turn the desk LED on or off","type":"object",)"
R"("properties":{"on":{"type":"boolean"}},"required":["on"]})");
gadget.button(0);
gadget.begin();
}
void loop() { gadget.loop(); }
The schema's description tells the model what the command does. Declare the gadget as a
global (it uses about 40 KB). The full version is examples/led-button;
names, events and limits are in the library guide.
Flash a board
The gadget talks over USB to a bridge on your computer, and the bridge talks to the
gateway. The first experiment describes the tested kit.
Optional C124 build, flash and recovery
covers flash offsets, the device ID, grok-gadgets-gateway enroll, usb-bridge and unplug
recovery for C124. Use the OLED example for the tested ESP32-S3 kit. We welcome independent test results.
Grok Bot today
The owner used Grok Bot to run grok-gadgets-gateway rehearse on the Mac.
The gateway log and the owner's display observation confirmed the Wi-Fi command (record).
That was a local shell-command route. On 13 October 2026 Grok Bot also called the tools natively from the Mac and the iPhone. It showed text on this kit (record, how to connect).
A USB charger powers the wireless board. An always-on relay can keep it available without the Mac.
The kit passed relay checks.
Phone setup passed on iPhone and Android on 14 October. Grok Bot calls from Android remain untested.
See the phone setup record.
A button press does not wake Grok Bot. See the roadmap.
The kit passed local-name, address-change and Mac login recovery checks. See
always-on setup.
A second builder has not yet reproduced the kit: report your result.
Learn more
| Topic | Guide |
|---|---|
| Commands, events and limits | Library |
| Retries, loss reports and reconnects | Protocol and recovery |
Optional C124 pins, and the GPIO48 RGB_BUILTIN trap |
Board sources |
| What was checked, and what is still open | Verification and build-checksums.json |
| Dependency licenses before you share firmware | Dependencies and NOTICE |
Host tests compile the sketches against a simulated board; they never open a serial port.
Community
Show your build, ask for help and share ideas on
Grok Gadgets community on X. Report bugs through the
issue chooser. New
here? Pick a good first issue
and read CONTRIBUTING. Build errors: SUPPORT.
Vulnerabilities: SECURITY.
Contribute on the dev branch; main holds tagged stable releases (branches).
License and affiliation
Apache-2.0; see LICENSE and NOTICE. Grok Gadgets is an independent open-source project. It is not affiliated with, endorsed by or sponsored by SpaceXSI or xAI, which make Grok and Grok Bot, nor with M5Stack. We reconstructed the pre-publication commit dates; see the history record.
Project discussion
Ask questions and share gadget ideas in hub Discussions. Use this repository's issue forms for defects.