parking_solution/wiki/entities/dingtian-dt008-reader.md

type, tags, sources, updated, status

type	tags	sources	updated	status
entity	parking hardware readers qr dingtian	dingtian-dt008	2026-07-04	open

Dingtian DT-008 (QR/RFID access reader)

The project's QR / barcode / RFID reader — Dingtian DT-008, the same vendor as the dingtian-relay (which is why it integrates the same HTTP-push way). A static optical + card scanner for QR / barcode (simple) and ID/IC/NFC cards. This is the ticket-encoding scanner (read at the pay station / exit lane) and a path for QR or RFID subscription credentials. Product page: dingtian-tech.com/en_us/qr_code_reader.html. (See dingtian-dt008 / raw/.)

Naming correction (2026-06-28). Through most of this project this reader was wrongly called "GEE" / "GEE/Fondvision" / "GEE-QR-ER80" — a bad early assumption. There is no GEE device; it is the Dingtian DT-008. The driver id was renamed gee-qr-reader → dingtian-qr-reader (migration 0015 rewrites existing rows). All protocol/behaviour facts below were observed on the real hardware and remain correct — only the device identity was wrong.

What it is

• QR/barcode + card. Reads QR / simple barcode AND ID/IC/NFC cards (~0.2 s, 0–10 cm). (An earlier note guessed "ER80-EM = 125 kHz EM4100 prox" — that was part of the same mis-id.)
• Interfaces: Wiegand 26/34, TCP/IP, USB, RS485. (NOT RS-232 — that was a fictional-datasheet claim.) For our integration it talks HTTP over TCP/IP; Wiegand is the reader's output line on a valid read, not the host transport.
• Power 9–16 V DC, 800 mA; 86×86×42 mm; −30…70 °C. Fits the disk-os-hardening.

How it integrates — HTTP-GET push, server replies the verdict (confirmed via SDK)

The protocol is settled by the qrcode-sdk (not serial as first guessed). The reader is configured (Windows tool QRCode_v1_6_5.exe) with a server IP/port and a "server language" (only picks the URL path, e.g. /qa/mcardsea.php). On each scan it HTTP-GETs the host:

GET /qa/mcardsea.php?cardid=<QR>&mjihao=<devId>&cjihao=<devSN>&status=<2 chars>&time=<utc>

cardid = scanned data; status low digit = direction (1=in / 0=out). The host replies JSON {data:[{cardid,cjihao,mjihao,status,time,output}],code:0} where reply status 1=valid (beep 2×) / 0=invalid (beep 1×), output 0=Access/1=WG26/2=WG34, time syncs the clock.

This is host-in-the-loop and SYNCHRONOUS: the GET is the access query and our reply is the decision — it drives the reader's beep + output. So unlike a fire-and-forget reader, the endpoint must decide (valid/invalid, direction from status) and reply, then also emit a DeviceReadEvent on the read bus for the entry/exit/permit flows (parking-session, subscription) to open the barrier. (device-input-flow is the analogous push pattern; this one also returns a verdict.)

This explains the "no beep": feedback comes from the server's JSON reply, not locally. A non-JSON / missing reply ⇒ no beep even though the scan worked. So "no beep" ≠ "didn't scan."

• Pushes over plain HTTP to our 10.0.10.x host (on the device subnet); no serial wiring, no Wiegand-decode hardware. Suits the host-in-the-loop model; autonomy is moot anyway (dingtian-relay has no onboard ACL).
• Default IP 192.168.1.99 (set its server IP/port to this host in the vendor tool).

Resolved (2026-06-16)

• Protocol = HTTP GET poll + JSON verdict (above). The earlier "serial/Wiegand, find the baud" open questions are moot — it's HTTP. Wiegand is the reader's output line on a valid read (the reply output field), not the host transport.

As-built (2026-06-16)

• Endpoint GET/POST /qa/mcardsea.php (apps/server/src/routes/qr-reader.ts, public — the reader has no auth, sits on the device subnet). Parses cardid/mjihao/cjihao/status/time, runs the scan through the read dispatcher (permit match → permit flow; else transient exit), and replies the SDK verdict: status 1=valid(beep 2×)/0=invalid(beep 1×), output 0, time.
• The read flows were refactored to return a ReadOutcome { accepted, direction, reason } so the endpoint's reply reflects the real accept/reject (the dispatcher decides AND opens the barrier via the flows). A fire-and-forget reader ignores the outcome.
• Reader identity: the endpoint matches the device serial (cjihao) against each reader's config.serial to find its devices row; the dispatcher then resolves the relay that row is bound to (config.controllerId + relay) and opens it. See entry-exit-points.
• Verified via inject: valid permit QR → status:1 + open; re-scan → permit exit (still valid); unknown QR → status:0; reader on a barrier-less lane → status:0.

Verified on hardware (2026-06-16)

Captured a real scan (vendor-emulator logger on :3000). The reader does scan, send, and beep — the earlier "no beep" was simply that no server was answering on :3000 with valid JSON. Real GET:

GET /qa/mcardsea.jsp?cardid=52020056&mjihao=1&cjihao=H05M2AFA&status=11&time=1781634494
from 10.0.10.7   (referer: http://www.fondvision.com — the OEM is Fondvision)

• PATH carries the configured "server language" EXTENSION: this unit is set to JSP, so it GETs /qa/mcardsea.jsp — NOT .php. Our endpoint was registered at .php only → it would have 404'd the real reader. Fixed: the route now registers php/jsp/asp/aspx/cgi.
• cjihao = H05M2AFA is the device serial — the value our endpoint matches against the reader's config.serial. So assign the reader with config.serial = "H05M2AFA" and bind it to a controller relay.
• mjihao = 1 (device id). cardid = the scanned barcode (52020056). status=11.
• The reader beeped on the vendor reply with status:0 — so it acts on the reply; 0 = invalid/1-beep as documented. A matching permit/session will return status:1 → 2-beep accept.

Assignment (as-built 2026-06-16)

A dedicated dingtian-qr-reader driver (device-registry, reader category) models the push reader: its one config field is serial (the cjihao the device reports). The admin assigns it in the first-run-setup like any device (normal UUID row id), enters the serial, and binds it to a controller relay. The QR endpoint resolves the reader by matching config.serial to the scan's cjihao — not by row id — so no DB hand-editing. Set the reader's server IP/port to this host in the vendor tool; assign + enter its serial + bind it here.

• Verified via inject: assign dingtian-qr-reader {serial:"H05M2AFA"} bound to an access relay → a .jsp scan with that serial + a matching permit QR → status:1 (2-beep accept) + open; re-scan → permit exit; unknown card → status:0; unassigned serial → status:0 (no relay, graceful).
• Note tcpip-reader is the WRONG model for this device (host-connects-out, a stub) — use dingtian-qr-reader.

Open / next

• Re-test on hardware against the real app (now .jsp-aware + serial-resolved): scan → expect a status:1 2-beep when the QR matches a permit/open session.
• output is replied as 0 (Access). Confirm on hardware whether the reader needs 1/2 (WG26/34) to drive its access line, vs. 0.

Channel tagging — output prefixes close the printed-card-clone hole (2026-07-04)

The push carries ONE opaque cardid whether the optical engine decoded a QR/barcode or the RF engine read a card — the server couldn't tell. And SubscriptionFlow.match matched by value only (the stored rf/qr kind was a label). Consequence: printing a card's UID (often written on the card face, e.g. 86A158) as a barcode and holding it up cloned the RF card — the optical decode matched the RF credential and opened the barrier. In-threat-model and cheap.

Fix (both sides):

• Reader (vendor tool, both units): set QRCode Output Prefix = Q: and Card Output Prefix = K: (env-overridable server-side: READER_QR_PREFIX / READER_CARD_PREFIX).
• Server: routes/qr-reader.ts strips the prefix and tags the read's confirmed channel (DeviceReadEvent.channel: "optical"|"rf"; kind qr/card). Enrollment capture stores the bare value. SubscriptionFlow.match then requires channel agreement: an optical read may not claim an rf credential (and vice versa) — a mismatch is refused AND signs a sub.refused.channelMismatch anomaly (a clone attempt is a fraud signal). An unprefixed read keeps the legacy untagged shape and matches as before — enforcement only bites where prefixes are deployed, so an unconfigured reader never breaks.
• Bonus: every READ log line now carries ch=optical|rf, which permanently attributes any future phantom (see below) to its engine.

⚠️ Two device-side settings are now part of the credential contract (they live ON the reader, not in our DB — re-apply after any factory reset/swap): the two output prefixes (must match the server's expected Q:/K:), and Card Input format (currently 6H) — it defines the UID shape we enroll; changing it later silently orphans every enrolled card.

⚠️ Phantom optical decodes from sunlight patterns (park-buzi, 2026-07-04)

With the site EMPTY (pre-opening, verified live + by snapshot), the exit reader (cjihao=H05MA5B0) pushed spontaneous scans at random afternoon times (observed 16:38–18:14, low-western-sun hours): cardid values like 997492, 389861, 024358, 192793 — and once a lone C. Server logs (READ serial= lines) confirm the pushes carry the reader's own serial and resolve to its assigned row, so this is the physical reader decoding, not a network source.

Diagnosis: the scan engine ships with many 1D symbologies enabled, some with weak/no checksums. Six-digit all-numeric strings are the signature of Interleaved 2-of-5 (even-length, digits-only, no checksum — any high-contrast stripe pattern of the right proportions "decodes"); a lone C is a Code39/Codabar artifact (Codabar start/stop chars are A–D). Low sun creates exactly such patterns at a gate: the striped barrier arm, fence/railing shadows sweeping as the sun moves, glare bands. RFID noise would instead give repeating UID-shaped values.

Impact: noise, not risk. Every phantom was REFUSED fail-closed; a phantom can never match a ticket (ticket-encoding ids are 11-digit + Luhn, so a 6-digit read has nothing to match).

Feed filter (2026-07-04 — supersedes the earlier "do not filter" position). Initially each phantom signed an exit.refused.noSession anomaly (#52–58 in the feed) and the position was to keep it that way. The operator overruled it, correctly: red "who is trying to exit?" rows for NOBODY train the operator to ignore the signed feed — alarm fatigue is the adversary's friend. read-dispatch.ts now drops a no-match value that cannot possibly be a credential we issue to UNSIGNED telemetry (device_events, unrecognizedRead:true — still auditable). "Possibly ours" is deliberately WIDE and everything in it still signs the normal refusal anomaly: Luhn-valid ticket shapes (a forged ticket is a real probe), SUB-/SUBSESS- prefixes, ANY read on a confirmed-RF channel (a physical card is a real event, never sun noise), and plates (never shape-filtered). The filter also works pre-prefix (legacy untagged reads). Still fix at the source too:

Fix (vendor tool, per reader — config lives ON THE DEVICE, not in our DB): disable every symbology except QR + Code128 (all our credentials); if offered, set minimum decode length ≥ 10 and require checksums. Apply to BOTH readers. ⚠️ A factory reset or a swapped unit silently re-enables the phantom symbologies — re-apply after any reset/replacement. Physical fallback if any noise survives: hood/visor the window, tilt it down, avoid facing the striped arm.

⚠️ Reply MUST set Connection: close (verified on hardware)

The reader sends Connection: keep-alive but only acts on the verdict (beep/output) once the TCP socket CLOSES. Fastify's default keeps the connection alive → the reader waits out a ~10 s keep-alive timeout before beeping, even though the server replied in ~15 ms. Every vendor demo replies Connection: close and shuts the socket. Fix: the endpoint sets reply.header("connection","close"). Symptom if regressed: correct accept/reject but a ~10 s lag before the beep. (The request arrives fast; the delay is entirely the reader waiting for close.)