Backend connection
Pre-filled with this page's own address — nginx forwards
/api to the backend internally, so this works
whether you're on the LAN over http:// or behind
an HTTPS reverse proxy. Leave it as-is unless you're
intentionally pointing at a different host. Stored only in
this browser's local storage. The key matches the
ADMIN_API_KEY you set in the backend's
.env.
Flash firmware
Build firmware
Every controller runs the same image — set these once and every
(re)build bakes them in. No editing config.h by hand.
The backend/MQTT host is whatever LAN IP or hostname a device on
your WiFi can reach this homelab at — the same value goes to
both BACKEND_HOST and MQTT_HOST. MQTT
credentials and the provisioning key are pulled from the
backend's own .env automatically.
Flash a controller
Chrome or Edge only. This page must be served over HTTPS, or opened as http://localhost — a plain http://<lan-ip> address won't be allowed to access the device's serial port.
- Plug the ESP32 in via USB.
- Click Install firmware below and pick its serial port when Chrome asks.
- Once flashed, it reboots and joins your WiFi automatically — the credentials are baked into this firmware image, nothing to type in.
- Open the Controllers tab — the device appears under "Unclaimed devices" within a few seconds of joining WiFi. Assign it to a door there.
Flashes whatever Save & build firmware above most
recently produced. Prefer the CLI instead? See
firmware/build_web_flash.sh and
firmware/src/config.h.example for the manual path.
Provisioning
User Provisioning Server
Connection to the district's RapidIdentity Connect feed — pulls
changed staff records to populate the Updates tab. Server address is
the base REST-points URL (e.g.
https://your-tenant.rapididentity.com/api/rest/restpoints/yourproject).
Consumer key/secret are issued per project under RapidIdentity
Connect > OAuth1 Consumers.
Always uses the feed's one-off resync mode (records changed since this date) — never the bare delta call, which would silently consume/advance the real change cursor just to test.
Location → Group Mapping
RapidIdentity's feed only reports a bare location code per person
(e.g. 0042) — it doesn't say what building that is, so
map each code to the Group it should grant access through. Typing a
group name that doesn't exist yet creates it.
| Location code | Group |
|---|
Location code seen somewhere else (not yet reported by the feed)? Add it here.
Login & accounts
GUI login password (admin account)
Change the password for the admin GUI login
(separate from the admin API key above). Requires the admin API
key to be set and connected.
GUI accounts
Other logins for this web GUI. Admin accounts have full access, same as the primary admin login above. Approver accounts only see the Updates and Events tabs — for someone (e.g. front-office staff) who should be able to review and approve new/changed people the provisioning feed has proposed, without touching doors, controllers, settings, or creating door-access users by hand.
| Username | Role | Active | Created |
|---|
Door defaults & scheduling
Door defaults
Pre-filled unlock time when adding a new door.
Scheduling
Timezone group/user access schedules are evaluated in — not
necessarily this server's own timezone. Pick a country to
narrow the list, or type an IANA name directly (e.g.
America/Chicago) if yours isn't in the list below.
Doors
| Name | Slug | Location | Unlock (s) | Remote | |
|---|---|---|---|---|---|
| — |
Events
| Time | Door | Person | Card / action | Result |
|---|
Unclaimed devices
Flash a device with the generic firmware and plug it in — it appears here within a few seconds once it joins WiFi.
| MAC address | Last seen | Firmware | Relays | Assign to door(s) |
|---|
Claimed controllers
| MAC | Relays → Doors | Firmware | Last seen |
|---|
Groups
| Name |
|---|
Users
| Name | Credentials | Add credential | Active | Groups | Schedule |
|---|
A user can hold several credentials — a badge, a replacement
badge, a keypad PIN, etc. — any of them grants the same access.
A bare number (e.g. 4821) matches leniently —
card number only, ignoring facility code, for cards with
unknown/inconsistent facility codes. Include a facility code
(e.g. 12-4821) for an exact, strict match; PINs
always use this form under keypad facility code 99 (e.g.
99-4821), since that code is fixed and known.
Once a lenient credential has been seen on a real swipe, its
true facility code shows next to it as a small "fc:" hint —
useful once you're ready to switch it to strict. Assign groups
from the Groups tab.
People from the provisioning feed
New or changed people RapidIdentity has reported. Approving a new person creates their door-access record and, if you type in a card number here, a matching badge + PIN credential too (PIN assumed to match the card's number — no separate PIN entry needed). Approving a changed person updates their name and, if their location code changed, swaps their group membership to match — the group they're leaving shows in red. Dismissing just discards the suggestion for now.
| Person | Location / change | Group | Card # |
|---|