parking_solution/wiki/concepts/entry-exit-points.md

type, tags, sources, updated

type	tags	sources	updated
concept	parking architecture devices setup		2026-06-16

Entry / Exit Points (pool-of-spaces model)

A parking lot is one pool of spaces with a flexible set of entry points and exit points — any number of each, in any combination (1 in + 1 out, 1 in + 2 out, 2 in + 1 out, …). There is no "lane" concept anywhere in the system (dropped 2026-06-16 — see below).

Direction lives on the relay, not the controller

An access controller (e.g. a dingtian-relay board) has several relays — each relay opens one barrier. Direction is a property of each relay, declared in the controller's config:

// access `devices` row — one Dingtian board
config: {
  host: "192.168.1.100",
  relays: [
    { relay: 1, direction: "entry", button: 1 },  // entry barrier; entry button on input 1
    { relay: 2, direction: "exit" }               // exit barrier; opened by a reader, no button
  ]
}

• direction: entry | exit | both (both = one barrier/relay serving in and out).
• button: the input terminal the transient entry button is wired to. Only entry/both relays have one. Absent = no button at that barrier (subscriber/reader-driven only).
• presenceInput / entryCooldownSec: the one-car-one-ticket guard for the entry button — presenceInput is the input terminal of a vehicle-presence loop (physical guard), or entryCooldownSec a fallback timer when there's no barrier feedback. See entry-double-press.

The four real layouts all fall out of this:

Layout	Controllers	Relays
1 barrier, both directions	1	{relay:1, both, button:1}
2 barriers, 1 board	1	{relay:1, entry, button:1}, {relay:2, exit}
2 barriers far apart	2	board A {relay:1, entry}, board B {relay:1, exit}
1 entry + 2 exit	3	A entry; B, C each exit

Readers / cameras BIND to a relay

A reader or camera points at the barrier it physically sits at, via its config:

config: { ...readerConfig, controllerId: "<access devices.id>", relay: 2 }

Its direction is inherited from that relay. So an exit read opens exactly that relay — no ambiguity even with multiple exit barriers ("the relay at that reader", decided 2026-06-16). Binding is optional: an unbound device falls back to a config.direction + the first relay site-wide of that direction (keeps the single-barrier case trivial). LPR is a snapshot sink — an ANPR service (opencv-anpr-service) POSTs the plate as a plate read to the reader endpoint, flowing through the same dispatcher.

Resolution (one module: apps/server/src/device-resolve.ts)

• Button press → relayForButton(controllerId, terminal) → the entry relay whose button matches → entry flow → pulseOpen(relay).
• Reader/permit/LPR read → relayForDevice(reader) → the bound relay → pulseOpen(relay); direction inherited.
• Snapshots → devicesByDirection("camera", dir) → every camera serving that direction.

A directional barrier that contradicts the car's open-session state (an exit barrier scanned by a car not inside, or an entry barrier by a car already in) is a wrong-barrier / anti-passback refusal. A both relay defers to session state.

The flows

Flow	Trigger	Opens
Transient entry	entry button press	the entry relay (button-mapped) → ticket prints
Transient exit	voucher scan at exit reader	the exit relay (reader-bound), if paid+grace
Subscriber entry	QR/RFID/plate at entry reader	the entry relay (reader-bound), if permit valid
Subscriber exit	QR/RFID/plate at exit reader	the exit relay (reader-bound), if permit valid

Every open also fires a camera snapshot (async, never blocks the open).

Why no lane

"Lane" was a leftover from a rows-of-gates mental model. It added nothing here:

• Occupancy is a site-wide fold over the ledger (entries − exits); it never grouped by lane.
• Device grouping is now done by the reader→relay binding, far more precisely than a lane key.
• Anti-fraud doesn't use it — the signed chain, the "open must match a signed event" check, and reconciliation all work on what happened, not which gate. The relay's direction already catches an exit firing an entry barrier, better than a lane number would.

Dropping it removed lane from ledger_events, device_events, sessions, and the device table (renamed lane_devices → devices). Because lane was part of the signed canonical form, this is a versioned change: the canonical array no longer includes lane, and the signer keyId bumped sw-hmac-v1 → sw-hmac-v2. v1 events won't verify under v2 — intentional, gated by each event's stored keyId (done pre-deployment, on throwaway data, so zero real cost). See append-only-event-chain.

Camera snapshots (evidence, not a gate)

Captured after the barrier opens, never awaited — a camera failure can't delay or block an open (the signed ledger is the decision). Stored as a BLOB in the snapshots table (single backed-up DB, nothing scattered on disk), in its own table so hot telemetry scans don't drag image bytes and images prune independently. Linked to the signed vehicle_entry/exit by identity. Served read-only via GET /api/snapshots/:id. Retention is unresolved — see open-questions.

Refused entry/exit ALSO snapshots (2026-06-19)

A snapshot is evidence of who was at the barrier — which matters most when the barrier is refused (a turned-away car is a fraud/dispute signal: "lot full" denial, an unpaid exit attempt, a no-session ticket, an out-of-window subscription). Originally only the OPEN paths captured; now every refusal/hold anomaly fires the directional camera too, keyed to the same identity the anomaly carries so the booth-console evidence strip finds it. Coverage: entry refused-full / held-no-ticket (a refused entry has no ticket id → mint a synthetic REFUSED-… ref to key the anomaly + photo together), exit refused closed/no-session/unpaid/grace-expired (booth and reader paths), and a refused subscription (the lane the reader sits at picks the camera). Same fire-and-forget contract — a refusal is never delayed by a camera. Failed captures still surface as "⚠ camera unreachable" tiles (see booth-console).

Related

entry-exit-readers · device-events · parking-session · anti-passback · append-only-event-chain · barrier-not-a-door · opencv-anpr-service · dingtian-relay · first-run-setup