Skip to main content

Install and Pair a Device

The first-time setup for any agent device.

What you need​

  • An ESP-Private-Agents-compatible device (see Supported Boards).
  • A phone running iOS or Android.
  • The Wi-Fi network name (SSID) and password you want the device on.
  • The device's QR code — shown on the device's screen when it powers up, or printed on the packaging for boards without a screen.

Steps​

1. Install the app​

Install ESP RainMaker Home:

2. Sign in (or sign up)​

The app uses your Espressif (RainMaker) account. If you've used any RainMaker product before, your existing login works. Otherwise, sign up with email.

3. Power on the device​

Plug it in. Within a few seconds, the device's screen shows a QR code. (For boards without a screen, the QR is on the packaging.)

4. Grant permissions​

The app asks for Bluetooth and Location permissions when you start setup. Both are required:

  • Bluetooth — the app talks to the unpaired device over BLE.
  • Location — Android requires it for any BLE scan.

Approve both.

5. Add the device​

  • Tap the + icon at the top right of the home screen.
  • Choose Scan QR Code.
  • Point the camera at the device's QR.

The app finds the device over BLE and starts the configuration flow.

6. Enter Wi-Fi credentials​

The app asks for the Wi-Fi SSID and password. The device joins the network you select.

7. Wait for the device to connect​

The device reboots, joins Wi-Fi, registers with the platform, and pulls down its agent configuration. This takes 10–30 seconds.

When done, the device is ready to talk to. By default it's running its built-in agent (e.g., Friend for voice chat boards). To swap agents, see Assign an Agent.

Talk to your device​

Wake it by saying "Hi, ESP" — the device chimes when it's listening. Then ask your question or give a command.

You can also wake the device by tapping anywhere on the screen.

After about 15 seconds of silence, the device goes back to sleep.

Troubleshooting​

SymptomLikely cause
App can't find the deviceBluetooth or Location permission was denied. Grant both in your phone's settings, then retry.
"Device disconnected during configuration"Wi-Fi credentials wrong, or the device is too far from the router. Move closer; double-check the password.
QR code doesn't scanThe device screen is dim or scratched. Try in better light, or use the manual entry path in the app.
Device boots but doesn't respond to "Hi, ESP"Mic muted on the board, or wake-word model not loaded. Restart the device; if still failing, re-flash.

Factory reset​

If something is wrong and you want to start over:

  • From the app: device tile → Settings → Factory Reset.
  • From the device: touch and hold the top of the screen for ~10 seconds (where supported by the board).

After reset, repeat the steps above to re-pair.

On this page