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.

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.