First gateway setup
End-to-end path for a new ESP32 gateway: sign in → browser flash → Wi‑Fi → automatic account binding → dashboard.
Use this for the first physical board. Encrypted / Secure Boot prototypes are a separate path (idf-secure); start with the public CDN build.
What you need
- ESP32 (USB-C) and a Chrome or Edge browser
- Wi‑Fi credentials for a 2.4 GHz network
- A JKBMSR account at jkbmsr.com
- Optional: JK-BMS UART wired later (claim works without BMS data)
Happy path (browser flash)
- Open jkbmsr.com/flash in Chrome or Edge and sign in when prompted.
- Connect the ESP32 over USB and flash the latest firmware (
0.1.4or newer) — the flasher shows a live progress bar and serial console throughout. - Enter the target 2.4 GHz Wi‑Fi credentials in the flasher. They are sent directly to the gateway over USB.
- Keep the page open while the gateway registers with JKBMSR Cloud. The flasher securely binds it to the signed-in account using its per-device claim code.
- Select Open gateway. Pack SOC/cells stay empty until UART is wired.
Field install (no USB at all)
Same SoftAP step as above, just without ever plugging in over USB — hold BOOT ~5s on an already-flashed board to re-enter SoftAP mode, then join JKBMSR-Setup-XXXX and claim at jkbmsr.com/onboard using the gateway ID and claim code from the gateway label.
Serial log cues (USB monitor @ 115200)
Expect lines that include:
- Gateway ID
- Claim code
- SoftAP name
JKBMSR-Setup-XXXXwhen Wi‑Fi is not configured - Successful cloud register after Wi‑Fi joins
Common races
| Symptom | Cause | What to do |
|---|---|---|
| “Adding gateway” remains visible after Wi‑Fi | Gateway has not finished POST /device/register yet | Keep the flasher open — it retries for ~90s. Restart the gateway and select Try adding again if it times out. |
| Claim says verify your email (403) | Email verification is enabled in production | Open the verification link, then sign in (return path is preserved when possible). |
| Gateway online, SOC 0%, no cells | Claim succeeded; BMS UART not wired or BMS asleep | Wire UART, check baud/pins in gateway settings. |
| Setup asks you to sign in again | The saved browser session expired | Sign in on the same computer, return to /flash, and restart the setup flow. |
After claim
- Confirm the gateway row on jkbmsr.com/dashboard.
- Wire JK-BMS UART (see JK-BMS wiring and UART pinout warnings).
- Confirm live telemetry and optional OTA from gateway settings.