Skip to content

getting-started.md

Latest commit

 

History

History
197 lines (146 loc) · 8.26 KB

getting-started.md

File metadata and controls

197 lines (146 loc) · 8.26 KB
Raw

Getting Started

Use this guide to connect an ESP32 board from this repository to an existing OpenClaw gateway.

What You Need

  • OpenClaw installed and openclaw available on PATH
  • An OpenClaw gateway the board can reach
  • The ESP-IDF revision and patch set required by your chosen example; follow the Tab5 SDK compatibility procedure rather than selecting an unmodified release tag
  • An ESP32 board with Wi-Fi
  • A serial connection or board-specific flashing path, depending on the example

Commands below assume the default OpenClaw install. If you use a named profile, add --profile <profile> to the openclaw commands.

Choose An Example

The historical room-node source-build record reports ESP-IDF 5.5.5. The Tab5 manifest still requires that version value, but the current compatibility procedure also requires SDK source 362a1776ec212788fda95f75b733bfdde3a0c394 and its tracked patches. Tab5 CI pins the qualified container image and records the actual SDK and patch identities in firmware provenance; this is not pristine release 5.5.5. Other examples retain their own dependency requirements. An accepted SDK version or successful build does not establish hardware qualification.

Choose A Delivery Source

These example instructions describe a repository checkout. Room examples use local component overrides and pinned submodules; initialize the submodules before building:

git submodule update --init --recursive

Registry packages and prebuilt firmware are separate delivery sources. Record the resolved package version and archive digest, or the firmware image digest and associated source commit, rather than assuming they match the checkout. The v1.1.1 source release includes the session and surface APIs described here. The matching espressif/esp-openclaw-node registry version contains only the core component; use the source checkout for room examples and Talk. Verify the registry archive's version and embedded source identity with the release checker. The historical 1.0.0 registry archive predates these APIs. Use the documentation shipped with the selected artifact rather than assuming it matches current source.

Prepare The Gateway

If the board will connect over Wi-Fi to a gateway running on another machine, set gateway.bind to lan first. The default loopback bind is only reachable from the gateway host itself.

Before pairing a board, set gateway.nodes.commands.allow for the example you are using. Each example README lists the commands to allow.

openclaw config set gateway.bind lan
openclaw config set gateway.nodes.commands.allow '<json-array-from-example>' --strict-json
openclaw gateway restart
openclaw gateway status --probe --json

If the gateway stays on loopback, the board cannot reach it over Wi-Fi. If the gateway does not allow the example's commands, the node can connect and still show commands: [].

Build And Flash

Use the commands from the example README for the board you are using. The general flow is:

. ~/esp-idf/export.sh
cd /path/to/example
idf.py set-target <target>
idf.py build
idf.py -p <serial-port> flash monitor

Pair The Board With The Gateway

Use a setup code for the first connection, or one of the other explicit auth commands described below.

Generate one on the gateway host:

openclaw qr \
  --url ws://<gateway-host-ip>:<gateway-port> \
  --setup-code-only

The command prints a single setup code:

<setup-code>

Sample setup code:

eyJ1cmwiOiJ3czovLzE5Mi4xNjguMS4xMDoxODc4OSIsImJvb3RzdHJhcFRva2VuIjoib2NfYm9vdHN0cmFwX2V4YW1wbGVfdG9rZW4ifQ

If the installed gateway already resolves the correct LAN URL, you can omit --url.

For a room or watch profile with Talk, add --voice-node to the QR command. That pairing profile grants the node's separate operator connection the operator.read and operator.talk scopes needed to configure and start calls. Generate a separate setup code for each device.

After flashing, open the serial console for the board and use the REPL:

openclaw> status
openclaw> wifi scan
openclaw> wifi set <ssid> <passphrase>
openclaw> gateway setup-code <setup-code>
openclaw> status

Each example README calls out the console path for that board and the commands it exposes after pairing.

  • Use wifi set <ssid> for an open network, or wifi set <ssid> <passphrase> for a secured network.
  • wifi scan lists up to 16 visible networks supported by the board. To scan after connecting, run wifi disconnect first; wifi connect resumes the saved connection afterward.
  • The setup code contains a short-lived bootstrapToken, not the gateway's shared token. gateway setup-code <setup-code> requests one explicit connect
    attempt.
  • If Wi-Fi is still coming up, the REPL waits for the board to obtain an
    IP before it submits that attempt.
  • After a successful hello-ok, the node stores the issued { gateway_uri, device_token } reconnect session and uses it on later gateway connect attempts.

Other first-connect options from the REPL are:

  • gateway token <ws://host:port> <token>
  • gateway password <ws://host:port> <password>
  • gateway no-auth <ws://host:port>

gateway connect is only for reconnecting with a saved session that already exists on the board.

Approve A Manual Connection

Setup codes normally complete the required approvals. A first connection with gateway token, gateway password, or gateway no-auth can leave two separate requests: one for the device identity and one for its node command surface.

On the Gateway host, find the device request for this board and approve it:

openclaw devices list --json
openclaw devices approve <device-request-id> --json

If the first connection ended while waiting for approval, repeat the original gateway token, gateway password, or gateway no-auth command on the board. Then inspect the node request and approve its advertised capabilities and commands:

openclaw nodes pending --json
openclaw nodes approve <node-request-id> --json

Match each request to the intended board before approving it. A connected node can advertise commands while its command surface is still awaiting approval; invocations can then fail with PAIRING_CHANGED or node pairing changed while invocation was active. See pending approvals.

Each Gateway owns its approvals. Repeat this check when moving a board to a new Gateway. After a successful connection has saved a session, use gateway connect to reconnect.

Check The Node From The Gateway

openclaw nodes status --json
openclaw nodes invoke --node <node-id> --command device.info --json

Then run one of the commands from the README for the board you are using.

For room nodes, complete the hardware qualification checklist before treating a successful build or connection as a qualified device.

If pairing did not complete as expected, use Troubleshooting.

Troubleshooting And Reference