First gateway setup
End-to-end path for a new ESP32 gateway: browser flash → Wi‑Fi → claim → 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 app.jkbmsr.com
- Optional: JK-BMS UART wired later (claim works without BMS data)
Happy path (CDN flash)
- Open cdn.jkbmsr.com/flash in Chrome or Edge.
- Connect the ESP32 over USB and flash the latest firmware (
0.1.4or newer). - When Improv Serial appears, join your Wi‑Fi network on the same cable.
- The flasher redirects to
https://app.jkbmsr.com/onboard?device=…&code=…. - Sign in or create an account (the onboard URL is preserved through login/register).
- Confirm the prefilled gateway ID and claim code, then Claim gateway.
- Open the dashboard — the gateway should appear. Pack SOC/cells stay empty until UART is wired.
SoftAP fallback
If Improv is unavailable (phone-only, field install):
- After flash, the SoftAP
JKBMSR-Setup-XXXXappears (password = claim code). - Join that network and complete captive-portal Wi‑Fi setup.
- Claim at app.jkbmsr.com/onboard using the gateway ID and claim code from the serial log or 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 |
|---|---|---|
| Claim says “Invalid device credentials” right after Wi‑Fi | Gateway has not finished POST /device/register yet | Keep the form open — the dashboard retries for ~90s. Or wait and claim again. |
| 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. |
| Redirect lost after register | Opened verify email on another device | Sign in on the original browser, or reopen the onboard URL from the flasher. |
After claim
- Confirm the gateway row on app.jkbmsr.com/dashboard.
- Wire JK-BMS UART (see JK-BMS wiring and UART pinout warnings).
- Confirm live telemetry and optional OTA from gateway settings.