sensium.manual

Onboarding manual for the Sensium RFID appliance — from unboxing to a configured device linked to Sensium Admin.

Before you start what you need

A Sensium device — ESP8266 (Wemos D1 Mini) or ESP32‑C3 (Wemos C3 Mini), model A or B
A USB data cable and a computer with esptool installed (pip install esptool)
A serial terminal — mpremote (pip install mpremote), screen or similar
The credentials of a 2.4 GHz Wi‑Fi network reachable from the device location
A Sensium Admin token, if the device is to be linked to a Sensium Admin instance

The model (A / B) refers to the LCD controller variant. Flashing the wrong model firmware results in a blank or garbled display, everything else keeps working.

1. Flash the firmware

Download the image matching the chip and model from the releases folder (stable, recommended) or the snapshots page (per commit builds). Verify the download against the .sha1 / .md5 sidecar files if desired.

ESP8266 — Wemos D1 Mini (models A / B)

esptool --port /dev/ttyUSB0 erase_flash
esptool --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect 0 firmware-rboot-a.bin

Model B uses the same command with the B binary. Erase once when switching firmware lineage.

Prefer the firmware-rboot-* image — it carries the two slot layout and is the only one that can be updated over the air. The plain firmware-a-* image still works and reads cards exactly the same, it simply has to be updated over USB forever. The smaller ota-rboot-* images are what the device downloads by itself, never write those over USB.

ESP32-C3 — Wemos C3 Mini (models A / B)

esptool --chip esp32c3 --port /dev/ttyUSB0 write_flash 0x0 firmware-c3-a.bin

If the port does not enumerate, hold the BOOT button while plugging in USB, then release. Use the full firmware-c3-* image over USB, the smaller ota-c3-* images are for over-the-air updates only.

On Windows the port is COMx instead of /dev/ttyUSB0. On macOS look for /dev/tty.usbserial-* (D1 Mini) or /dev/tty.usbmodem* (C3 Mini).

2. First boot

Power the device (the USB cable is enough). The LCD backlight turns on and after a couple of seconds the boot sequence starts. On a freshly flashed device there is no configuration yet, so the boot stops with:

No config found Use serial

This is expected — the device is asking to be configured through the serial connection, which is the next step.

3. Configure over serial

With the device connected over USB, open a serial terminal at 115200 baud:

mpremote connect /dev/ttyUSB0   # or: screen /dev/ttyUSB0 115200

If the reading loop is running, press Ctrl-C to interrupt it and reach the MicroPython prompt (>>>). Then start the interactive configuration:

from sensium import config
config.run()

Answer the prompts — pressing Enter keeps the value shown in parentheses:

Prompt	Meaning
`Wi-Fi SSID`	Name of the 2.4 GHz network the device connects to
`Wi-Fi password`	Password of that network
`Target URL`	HTTP endpoint that receives each card read
`Master RFID key`	Hex sector key used to read the cards (12 hex digits)
`Admin URL`	Sensium Admin instance the device reports to (optional)
`Admin token`	Token authenticating the device in Sensium Admin (optional)
`Run in debug?`	Extra diagnostic messages on the LCD, answer `n` for normal use

The configuration is saved to the device and the Wi‑Fi connection is attempted immediately. Reboot into normal operation with:

import machine
machine.reset()

4. Link to Sensium Admin

The link to Sensium Admin is established by the Admin URL and Admin token values of the previous step. Once configured, the device reports itself to the registry every 15 seconds with its status (version, hardware, Wi‑Fi network, IP address, read count).

Open the Sensium Admin instance and check the devices list — the device should appear within seconds of booting, identified by its unique identifier.
From the admin, remote operations become available: reboot, firmware update, configuration edit, beep / LED identification, LCD messages and more.

No admin URL or token configured? The device works standalone — card reads are still sent to the target URL, only the remote management is skipped.

5. Verify

The LCD shows the welcome screen (name, version and variant), then the IP address once the Wi‑Fi connects, and settles on the card prompt: Place card before reader
From a computer on the same network, query the status API:

curl http://<device-ip>:8266/

Place a programmed card before the reader — the device beeps, contacts the server and greets the card holder on the display.

Troubleshooting

Wi-Fi never connects

Confirm the network is 2.4 GHz (neither chip supports 5 GHz) and the credentials are correct. Re-run the configuration to fix them. The device retries at boot, a power cycle after fixing the network is enough.

USB port does not show up

Use a data-capable USB cable. On the C3 Mini, hold the BOOT button while plugging the cable, then release. On the D1 Mini, install the CH340 driver if the system does not recognize the serial adapter.

Display is blank or garbled

The firmware model does not match the device — model A and B use different LCD controllers. Flash the other model binary.

Device not showing in Sensium Admin

Check the admin URL and token in the configuration and confirm the device has network access to the admin instance. The status API (curl http://<device-ip>:8266/) confirms the device itself is up.

Updates after onboarding

A configured device is updated over-the-air, no USB cable required — trigger the firmware update operation from Sensium Admin, or see the OTA section of the repository README for the equivalent commands. Both chips carry two copies of the firmware, so an update never writes over the copy that is running:

The image is streamed into the inactive slot while the device keeps reading cards from the active one.
The checksum is verified before anything is switched, so a failed download costs nothing and leaves the device on its current firmware.
The new slot is then booted tentatively. It only becomes the permanent one once the device completes a healthy boot, so an image that does not start is undone by the next reset rather than needing a visit.

ESP8266 — two flash slots

Requires the firmware-rboot-* image, which adds a small bootloader and splits the flash into two firmware slots. Once it is on the device, updates arrive over the air like on the C3.

A device carrying the plain firmware-a-* image refuses over-the-air updates, and does so on purpose. That layout holds a single copy of the firmware, so an update would have to erase the very code it is executing — which cannot complete and leaves the device unbootable. Refusing costs nothing; attempting it costs the device.

ESP32-C3 — two partitions

Works out of the box on any C3 image, the bootloader handles both the switch and the rollback. The device downloads the smaller ota-c3-* image by itself; the full firmware-c3-* one is only ever written over USB.

Moving an ESP8266 to the two slot layout

An existing device on the plain image can be migrated, but the flash layout changes, so it needs one last USB flash and loses its configuration. Save the configuration first (the config get operation in Sensium Admin shows it), then write the image and blank the filesystem region:

esptool --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect 0 firmware-rboot-a.bin
esptool --port /dev/ttyUSB0 --baud 460800 write_flash --flash_size=detect 0x100000 blank-16k.bin

Where blank-16k.bin is 16 KB of 0xFF bytes. Blanking is not optional — the filesystem moves with the new layout, and an old one left behind is reported as corrupt and stops the boot. Restore the configuration over serial as in step 3, and from then on the device updates itself.

Over-the-air URLs on the ESP8266 must be plain http://. A TLS handshake keeps the chip busy for longer than its hardware watchdog tolerates, so an https:// URL resets the device before the first byte of the image arrives.