From AWS back to a device
How a lock or unlock reaches a device, and how we know it actually happened.
The admin shows "pending" from the moment a command is queued until the device's report arrives.
Who can ask for a lock or unlock
- The owner, at the end of the first unlock in the web app.
- Staff, with Lock and Unlock in the admin app.
- The trust ladder, when it asks the owner to verify again, or after they pass.
- The school-zone model, entering or leaving a zone during school hours.
A device is locked if any reason applies. A command only goes out when that combined answer changes.
The outbox
Nobody talks to a device directly. Every request becomes a row in the outbox table, written in the same database transaction as the decision behind it, so a command is never lost or sent for a change that didn’t happen.
- Commands are numbered. Only the newest pending command per device is sent; older ones are marked superseded.
- SMS to owners go through the same outbox.
Delivery: device-commander
- A Lambda that runs every minute. It takes pending rows and writes each one to the device’s shadow as the desired lock state.
- When a person is waiting (the owner’s unlock, a staff Lock/Unlock), the app wakes it right away, so the command reaches the shadow in about a second. Trust-ladder commands wait for the next minute.
- Runs take turns, and a row is never sent twice, so commands for one device can’t arrive out of order. A failed write is retried on the next run, up to 5 times.
The device answers
- AWS IoT tells the device its shadow changed. A device that was offline can read its shadow when it reconnects, so a lock sent meanwhile still applies.
- The device applies the lock state and writes it back as reported.
- That change reaches ingest through the shadow documents rule, like any other message. Only then does the database’s lock state change.
The lock state we store always follows what the device reports, never what we asked for. If the two disagree, the admin says so.
On dev and staging, a stand-in Lambda (mock-firmware) answers for the fleet simulator’s emul-* devices, the way firmware would. It never answers for anything else.