FREE Reverse Engineering Self-Study Course HERE

Re-Flock

An educational, end-to-end reverse engineering of a deployed edge ALPR "smart feeder" camera and its cellular telemetry return channel. It runs a YOLOv8n + EasyOCR pipeline and POSTs JSON over an RC7611 LTE modem to an AWS ingest server.

Quickstart (one click, no webcam, no model)

Renders a synthetic AAA-BBB plate image, OCR-scans it, builds the telemetry payload, spawns the mock cloud ingest server, posts the payload through the mock client, and prints the full roundtrip transcript:

python3 -m reflock --quickstart
# or, after `pip install -e .`:
reflock-quickstart

This exercises the same pipeline the device runs in the real world: capture, OCR (conf 0.92), telemetry construction, cellular transmit over wwan0, and the AWS ingest 201 response. No YOLO model, no GPU, no camera needed.

Requirements

• Python 3.10 or newer.
• Core: Ultralytics (YOLOv8n), EasyOCR, OpenCV, requests.
• Dev extras (tests, flake8): pip install -e ".[dev]".

Setup

git clone <repo> re-flock && cd re-flock
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python3 -m reflock --help

CLI

python3 -m reflock [SOURCE] [--demo] [--debug] [--crop=...] [--burst=N]

Flag	Default	Description
SOURCE	/dev/video0	Camera index or device path
--demo	off	EasyOCR-only (no YOLO)
--crop=x1,y1,x2,y2	none	Crop ROI before OCR
--burst=N	1	Frames to scan, deduped
--debug	off	Raw OCR boxes in demo mode
--quickstart	off	One-click sample pipeline (see above)

Environment (all optional):

Variable	Default	Description
REFLOCK_ENDPOINT_URL	empty	Ingest URL; empty = offline backlog
REFLOCK_CAMERA_ID	FALCON_EDU_001	Device identity
REFLOCK_GPS_LAT/LON	36.91/-76.05	Device GPS
REFLOCK_MIN_CONF	0.5	OCR confidence floor

Step 1 - Frame Acquisition & AI Processing

When the PIR motion sensor fires, the camera wakes and grabs a frame. The edge runs a two-stage pipeline: YOLOv8n finds the plate bounding box, then EasyOCR reads the crop (demo mode skips YOLO and OCRs the frame directly). Task sources: reflock/{detector,ocr}.py.

Step 2 - Constructing the Telemetry Payload

reflock/telemetry.py:build_payload assembles a JSON payload with the plate read, confidence, bounding box, device identity, GPS, modem diagnostics (reflock/modem.py, RC7611 AT+CSQ -> dBm), and hardware telemetry. Reads below MIN_PLATE_CHARS / without a dash are rejected.

Step 3 - Cellular IoT Transmission

The device POSTs the payload over the RC7611 LTE Cat-4 modem (bands 2/4/12/14) through reflock/telemetry.py:transmit_payload to REFLOCK_ENDPOINT_URL. Offline, the payload is saved to a local JSONL backlog instead.

Step 4 - The Offline Backlog Queue

In LTE dead zones, save_to_local_backlog appends the payload to reflock_backlog.jsonl. When the link returns, reflock/telemetry.py:flush_backlog replays every queued line.

Mock Server & Client Demo

# terminal 1: mock AWS ingest on port 8765
python3 -m reflock.ingest

# terminal 2: post the canonical AAA-BBB payload, print the reply
python3 -m reflock.client

How the Flock Works (End-to-End)

Motion -> wake -> capture frame
  -> YOLOv8n plate bbox -> EasyOCR crop read
  -> validate plate -> build_payload
  -> transmit_payload over RC7611 (wwan0) -> POST to AWS ingest
  -> 201 accepted | offline -> reflock_backlog.jsonl -> flush_backlog on link

Modules

Module	Responsibility
constants	Model path, thresholds, OCR config, env vars
detector	PlateDetector YOLOv8n single-class detector
ocr	PlateReader EasyOCR reader; demo-mode text location
telemetry	build_payload, transmit_payload, flush_backlog
modem	Rc7611Modem mock LTE diagnostics (AT+CSQ -> dBm)
ingest	CaptureHandler, run_server mock AWS ingest HTTP server
client	post_sample mock client posting canonical payloads
quickstart	One-click sample-plate end-to-end pipeline

Outputs

• Endpoint set: prints JSON telemetry payload; sent: true on 201.
• Offline: writes reflock_backlog.jsonl; sent: false.
• Demo debug: prints raw OCR detections.

Design Notes

• Single-class YOLO: every high-confidence box is a plate, no NMS clutter.
• OCR-first demo: the two-stage pipeline runs without a model file.
• Cheap plate validation filters OCR noise before a payload is built.
• Everything is configurable via REFLOCK_* env vars.
• The backlog is the antenna: offline is buffering, not failure.
• Mock-first cloud: standard-library ingest server, zero cloud cost.

Secret Hygiene

This repo ships a mandatory guardrail skill at .opencode/skills/repo-secret-hygiene/. Before any commit or push:

python3 .opencode/skills/repo-secret-hygiene/scan_secrets.py --tree
python3 .opencode/skills/repo-secret-hygiene/scan_secrets.py --staged
python3 .opencode/skills/repo-secret-hygiene/scan_secrets.py --history

Install the pre-commit hook: cp .../pre-commit .git/hooks/pre-commit.

Tests

python3 -m pytest tests/ -q
python3 -m flake8 reflock/ tests/ --max-line-length=79

The suite runs with no model download and no camera: synthetic fixtures cover detection, OCR, telemetry, ingest endpoints, the offline backlog, CLI parsing, and the one-click quickstart.

License

MIT - see LICENSE.