v2.0

How it works

Two small controllers do the physical work. A site computer makes every decision, keeps the record and serves the screens. A camera streams over Wi-Fi.

CameraESP32-CAM, MJPEG streamplate and face Gate controllerUno R4 WiFi: card reader,servo barrier, RGB light Bay controllerUno R3: 4 IR sensors,2 RGB lights (bays A1, A2) Site computer face matching (YuNet, SFace)plate reading (OCR)decision rulesrecord (SQLite, hash chain)web serversimulator for tests and demo Operator consolelogin, live gate, bays,events, insights Driver displayfree bays, gate answer,no personal data Wi-Fi USB serial USB serial HTTP

The access decision

The rules live in one module with no input or output of its own (smartparking/policy.py), mirrored line for line in the browser demo (demo/assets/policy.js). A shared file of 19 test cases is run against both.

  • One session, one identity. The first factor seen opens a session for that registered driver. Any factor that points to a different person refuses at once and records both names.
  • Required factors. Card, plate and face by default. A site that has no permission to process faces sets REQUIRED_FACTORS=rfid,plate.
  • Time limit. All required factors within 30 seconds, or the session expires and says what was missing.
  • A bay first. The barrier lifts only if a bay the driver may use is free; that bay is held for two minutes and blinks. Accessible bays only for permit holders.
  • Lockout. Five refused attempts with one card within five minutes lock that card for five minutes.
  • Passers-by are ignored. An unknown face or plate with no session open is never stored. An unknown card is a deliberate act: it is refused and recorded, with only its last four digits shown.
  • Exact plates. A plate must match exactly after normalising; the first build accepted any plate contained in another.

Fail-safe behaviour

The safety rule sits in the gate firmware, not in the computer: the barrier closes after the hold time the computer asked for (8 seconds by default), and it closes if the computer is silent for 3 seconds, whatever the computer is doing. With no computer attached, the gate light blinks slowly red.

Status

Firmware 2.0.0 passes this on the laptop, running the real sketch against the site software. It has not yet been flashed to the model. Until it is, the model runs the first build's firmware, which has no self-close.

Serial protocol

One frame per line, readable in the Arduino Serial Monitor: $TYPE,field,field*HH, where HH is a CRC-8 (polynomial 0x07) of the text between $ and *. Damaged lines are dropped. Every command carries a sequence number and is acknowledged, and retried up to three times.

DirectionMessageMeaning
controller → computerHELLO,<GATE|PARK>,<fw>,<proto>Who I am. The computer asks every USB port WHO, so cables can go in any socket.
controller → computerHB,<uptime>,<state…>Every second, with full state: a restarted computer catches up at once.
gate → computerRFID,<uid>A card was presented (once while it stays on the reader).
gate → computerGATE,<state>,<reason>CLOSED, OPENING, OPEN, CLOSING; reason CMD, TIMEOUT, HOST_SILENT, DONE.
bays → computerSLOT,<i>,<status>,<a>,<b>VACANT, PARTIAL or OCCUPIED, after a 150 ms debounce.
computer → gateOPEN,<seq>,<hold_ms>, CLOSE, DENY, LIGHTBarrier and light. PING every second feeds the gate's silence watchdog.
computer → baysTYPE,<seq>,<i>,<S|A>, RESV,<seq>,<i>,<0|1>Standard or accessible bay; blink the bay assigned to a driver.

For bench tests by hand, the single letters O, C and D typed into the Serial Monitor still open, close and deny.

The record

Every decision, refusal and manual action goes into a local SQLite database. Each entry carries the hash of the one before it (optionally keyed with a secret), so editing or deleting any entry breaks the chain, and python -m smartparking verify-audit says where. Entries older than 180 days are removed with an anchor that keeps the rest verifiable. A sync to the first build's MySQL database is optional.

Privacy by design

  • The face check is a setting, off where the law or the site does not allow it.
  • Face templates are stored, not photographs, with the time consent was given.
  • Nothing has to leave the site: with PLATE_DETECTOR=local plate detection runs on the site computer. The cloud model the first build used is opt-in (an API key, or PLATE_DETECTOR=roboflow) and sits behind a circuit breaker.
  • The console needs a login; state changes need a CSRF token; manual gate actions record who and why.

Code layout

smartparking/      site software (Python)
  policy.py        the access decision, no I/O
  store.py         SQLite: drivers, bays, hash-chained record
  devices/         serial links to the gate and bay controllers
  vision/          camera reader, faces, plates
  sim/             software twins of both controllers
  web/             Flask: console, driver display, health, metrics
firmware/
  common/          sp_proto.h: the protocol codec, single source
  gate_control/    gate sketch + gate_fsm.h (logic)
  parking/         bay sketch + slot_fsm.h (logic)
  ESP32_CameraWebServer/
  tests/           firmware logic tests, laptop "board" runner
demo/              console and driver display (browser)
tests/             Python tests and shared test vectors
tools/             verify.sh, build_site.py, sync_proto.sh
legacy/            the first build, kept for reference
Designed, built and tested by Mohammed Ahmed Al-Julandani. Last updated 17 November 2026.