Tracker ingest (phimi-ingest)

One Tokio task per TCP connection.

1. Framing: bytes go through a frame decoder (4 KiB limit, resynchronises on the next 0x7E after an oversized frame).
2. Packet: checksum, length and encryption bits are verified. A frame with a bad checksum gets no reply, because its header cannot be trusted.
3. Identity: the first valid packet binds the connection to a terminal id. A different id on the same connection closes it.
4. Allowlist: a terminal not in PHIMI_DEVICE_ALLOWLIST receives 0x8100 result 4 (unknown terminal) and is disconnected.
5. Registration (0x0100) returns an auth code: the first 12 bytes of HMAC-SHA256(PHIMI_AUTH_SECRET, terminal id), hex encoded. It is deterministic, so a tracker that re-authenticates after a restart without registering again still works.
6. Authentication (0x0102) with the right code registers the session. A wrong code gets 0x8001 failure.
7. Reports before authentication get 0x8001 failure (a conforming terminal then authenticates or registers again) and are not emitted.
8. Authenticated reports are acknowledged with 0x8001 success and published as events. A frame with the same message id, serial and checksum as one of the last 64 is acknowledged again and flagged as a duplicate.

A newer connection for a terminal replaces the older one, so downlink commands always reach the live socket.

Configuration

Variable	Default	Meaning
PHIMI_AUTH_SECRET / _FILE	required	at least 16 characters
PHIMI_DEVICE_ALLOWLIST	required	comma-separated terminal ids
PHIMI_ALLOW_ANY_DEVICE	false	development and simulator only
PHIMI_INGEST_BIND	0.0.0.0:8888	tracker TCP port
PHIMI_INGEST_HTTP_BIND	0.0.0.0:9090	probes, metrics, sessions (cluster internal)
PHIMI_DEVICE_UTC_OFFSET_MINUTES	480	device clock offset
PHIMI_IDLE_TIMEOUT_SECS	1200	close silent connections
PHIMI_MAX_CONNECTIONS	64	concurrent connections

HTTP endpoints (port 9090, not exposed publicly)

• GET /healthz, GET /readyz
• GET /metrics: connections, rejected frames, duplicates, auth failures, unknown devices, unauthenticated messages, downlinks, messages per id.
• GET /internal/sessions: connected terminals and since when.

Simulator

phimi-simulator --addr 127.0.0.1:8888 --devices 4 --hold 60

Each virtual tracker registers, authenticates with the code it receives, sends the vendor's GPS, Wi-Fi, LBS, batch and heartbeat frames under its own terminal id, then optionally stays connected, sends heartbeats and answers 0x8900/0x8300 commands.