Skip to content
HostelHive

Configure and flash

You’ll need an ESP32 board wired as described in Wiring and parts, a USB cable, and an Admin account on a running backend.

Register the scanner

Section titled “Register the scanner”

Every gate gets its own credential. As an Admin, register the scanner by name:

POST /api/v1/scanner-devices
Content-Type: application/json


{ "name": "Gate-01" }

The response includes the device’s id and a credential that looks like hhd1.<device-uuid>.<secret>. Copy the credential now. It’s only ever shown in this response. If you lose it, rotate it with POST /api/v1/scanner-devices/{id}/rotate-credential, which also kills the old one.

Then tell the backend which way this gate faces, IN for an entrance or OUT for an exit:

PUT /api/v1/scanner-devices/{id}/direction
Content-Type: application/json


{ "direction": "IN" }

Until it has a direction, every scan is refused with GATE NOT CONFIGURED. You can check a credential without scanning anything by calling GET /api/v1/device/check with it.

Put the credential in the firmware

Section titled “Put the credential in the firmware”

  1. Clone the firmware and copy the secrets template.

    Terminal window
    git clone https://github.com/Hostel-Hive/hostelhive-hardware.git
    cd hostelhive-hardware
    cp include/secrets.example.h include/secrets.h

  2. Edit include/secrets.h, which Git ignores. Set WIFI_SSID and WIFI_PASSWORD for the gate’s network. Set API_BASE_URL to the backend’s https:// address with no path. Paste the root certificate of the backend’s TLS chain into API_ROOT_CA as PEM. Put the hhd1. credential in DEVICE_CREDENTIAL. If you’re not in Sri Lanka, change GMT_OFFSET_SEC too.

  3. Connect the ESP32 over USB, then build the firmware and flash it with the production profile:

    Terminal window
    pio run -e esp32prod
    pio run -e esp32prod --target upload
    pio device monitor --speed 115200

On boot the screen joins Wi-Fi, syncs the clock and then shows SCAN ID.

There are three build profiles. esp32prod is for real gates: HTTPS only, and no QR input from USB. esp32dev is for development. native_test runs the unit tests on your computer.

Tests

Section titled “Tests”
Terminal window
python test/run_tests.py
pio test -e native_test

The first needs nothing installed. The second runs the Unity tests for QR parsing, the cooldown, and the open-or-stay-locked decision.

Looking after scanners

Section titled “Looking after scanners”

GET /api/v1/scanner-devices lists them. POST /api/v1/scanner-devices/{id}/rotate-credential issues a new credential and POST /api/v1/scanner-devices/{id}/deactivate retires one. Only active Admins can do any of this, and a scanner credential only works on the two /api/v1/device/ routes.