Made by @adidshaft ↗

Grok Bot is made by SpaceXSI.
Grok Gadgets is an independent project.

↗

Use the library in another gadget

The ordered OLED kit is the first physical experiment. Its pins, display controller and firmware profile remain provisional. The optional C124 sketch and examples/led-button both use grok::Gadget. A second board still needs its own pins, a PlatformIO environment, and its own hardware check. This library has no Wi-Fi transport and no hosted service. The gateway device port stays on loopback. See the hosting FAQ.

On this page
Header Purpose
GrokCore.h Bounded lines, queues, and button debounce
GrokGadgets.h Capability table, RGB helpers, and ACK cache
GrokSession.h grok::Gadget: hello, poll, events, loss reports, and recovery
C124.h AtomS3 Lite pins (RGB GPIO35, button GPIO41)

Declare a global gadget

With the default eight-entry ACK cache, grok::Gadget holds about 40 KB (cache, line buffer, parse documents, and event queue). grok::Device alone is about 33 KB. Device::execute uses a 2 KB stack buffer. The Arduino loop task stack is 8 KB. Declare the gadget as a global or static object. A local with the default cache in setup() or loop() overflows that stack.

#include <GrokSession.h>

bool on = false;
grok::Gadget gadget("Generic ESP32-S3 LED and button", "0.1.0", "esp32s3");

void report(JsonObject state, void *) { state["led"]["on"] = on; }
grok::Error setLed(JsonObjectConst args, void *) {
  if (args.size() != 1 || !args["on"].is<bool>())
    return {"invalid_arguments", "Expected {\"on\": boolean}"};
  on = args["on"];
  digitalWrite(4, on ? HIGH : LOW);
  return {};
}
void setup() {
  pinMode(4, OUTPUT);
  gadget.state(report);
  gadget.command("led.set", setLed, nullptr,
                 R"({"type":"object","properties":{"on":{"type":"boolean"}},)"
                 R"("required":["on"],"additionalProperties":false})");
  gadget.event("button.held", R"({"properties":{"ms":{"type":"integer"}}})");
  gadget.button(0);
  gadget.begin();
}
void loop() { gadget.loop(); }

examples/led-button is that sketch, with a one-second hold event. pio run -e esp32s3-led-button compiles it. The pins are a documentation example: LED GPIO4, BOOT button GPIO0. They are not a hardware measurement.

Strings passed to command, event, and state must outlive the gadget. Use literals. Call them before begin().

Names, events, and schemas

Hello may list at most 16 names. The gadget always appends state and history_lost. button(pin) appends button. Custom commands and events share the remaining slots. Registration returns false for a 17th name, a duplicate, or a reserved name (button, state, history_lost).

event(name, schema) declares a custom event. Its hello schema includes "x-grok-gadgets-kind": "event". history_lost is reserved: the gadget emits it, and a sketch cannot register that name. emit(name, data) queues a declared event. The data object must be under 128 bytes. A full queue of 16 drops the new event and later reports history_lost.

command(name, handler, context, schema) registers a callable capability. The optional schema is an inline JSON object. Grok sees that object as the argument contract. rgb.set keeps the built-in RGB rules; a replacement schema is rejected.

The gateway rejects schema references, pattern and patternProperties. Use explicit properties, enum, minLength and maxLength instead. This prevents a device-supplied regular expression from blocking the gateway.

begin() calls Serial.setRxBufferSize for two full frames (4096 bytes) before Serial.begin(). The Arduino-ESP32 2.0.17 USB CDC queue otherwise stays 256 bytes and can drop a long reply. That call is unverified on hardware.

Long-poll

An idle gadget polls ten times a second. On a relay with many gadgets that is most of the relay's work (hub ADR 014). Opt in before begin():

gadget.longPoll(2500); // milliseconds, 100 up to (not including) 3000

Each poll then asks the relay to wait up to 2.5 s for a command. A command still arrives at once. Requests stay one at a time, so state and button events wait for the poll; the limit keeps the 3-second state report on time. During a signed-update download the gadget polls without waiting. A relay from before long-poll answers invalid_request once; the gadget keeps its session and polls without the field until the next boot.

Claim codes

On a relay with accounts (hub ADR 011), a person claims a gadget with a code it shows. A gadget with a display opts in before begin():

gadget.showClaimCodes();

Each hello then sends "claim": "ready". The relay answers with claimed and, while nobody owns the gadget, claim_code (XXXX-XXXX, valid 10 minutes). A fresh code or claimed: true can arrive in any poll reply. claimCode() returns the code to show, or null; claimed() says whether the relay reports an owner. A disconnect clears the code.

Call claimAfterSetup() when a phone setup has joined the gadget to Wi-Fi after a reset. The next accepted hello then says after_setup, and a claimed gadget may show a transfer code for its next owner. A relay without accounts ignores the field. A relay from before claim codes answers invalid_request; the gadget then sends its hello again without the field and stops asking until the next boot. A gadget that does not opt in sends and accepts exactly the protocol 0.1.0 frames it did before.

Limits

A reply may be one JSON object of at most 2047 bytes plus LF. The parse document is sized for a gateway-legal frame (one value per two input bytes, plus the string bytes). A command that is still too deep gets a failed ACK (invalid_command) instead of a session reset. Trailing bytes, a second object, or an embedded NUL resets the session.

The request timeout is 13 seconds, longer than the USB bridge's connect-plus-reply wait. A reply whose shape does not match the outstanding request resets the session. Protocol 0.1.0 has no request id.

Within one boot the device retains eight acknowledgements by default. The same command id and the same compact arguments return the cached result and do not run the handler again. Changed arguments return duplicate_conflict. Reboot clears the cache. A timeout means the result is uncertain: do not repeat a physical action under a new id.

ACK cache size

Set GROK_ACK_CACHE_ENTRIES to a positive integer at compile time. The default is 8; zero does not disable the cache. Add -DGROK_ACK_CACHE_ENTRIES=2 to your compiler flags for a two-entry cache. In PlatformIO, add this flag to the environment's build_flags, preserving its existing flags. Use the same value in every translation unit that includes the SDK headers.

Each entry stores a 65-byte ID and two 2048-byte buffers: 4161 bytes in total. Reducing eight entries to two saves 24,966 bytes of cache storage. Object sizes also include other members and alignment. The stack buffer size does not change.

Fewer entries retain fewer command IDs and therefore provide less replay protection. The cache replaces the oldest entry when it stores a new ID. Replaying a retained ID or reporting duplicate_conflict does not refresh or evict entries. Once an ID is evicted, receiving that command again can run its handler again. Successful and failed results use the same cache.

readRgb accepts integer r, g, and b from 0 to 255, plus boolean on. A float such as 255.0 is rejected. The gateway's own numeric check is a separate code path.

License

Original SDK code is Apache-2.0. Read the dependency notices before distributing firmware.

Source: grok-gadgets-esp32-sdk/docs/sdk.md