julian
c8a5f4cd68
ROADMAP plus granular task files per phase. Phase 1 (12 tasks + 1.13 device authority) covers Codec 8/8E/16 telemetry ingestion; Phase 2 (6 tasks) covers Codec 12/14 outbound commands; Phase 3 enumerates deferred items.
Phase 3 — Future / optional
Items that are designed-for but not committed. Each could become its own phase if the platform's needs grow that direction. None of these block Phase 1 or Phase 2 — they are clean additions thanks to the layout rules in docs/wiki/concepts/protocol-adapter.md.
Candidates
3.A — Additional vendor adapters
Trigger: Customer onboards Queclink, Concox, or other GPS hardware.
Each new vendor is a new sibling under src/adapters/. The shell stays unchanged. Phase 1's protocol-adapter discipline is the load-bearing property here — core/ does not import from any specific adapter, so a new one slots in without touching existing code.
Estimated scope per vendor: roughly Phase 1 tasks 1.4–1.9 again (framing + codec parsers + fixture suite + tests), but smaller because the shell already exists.
3.B — UDP transport for Teltonika
Trigger: Devices configured for UDP, or operational reasons to prefer UDP (lower keepalive cost on cellular).
Adds a parallel udp-server.ts in src/core/ that handles the Teltonika UDP envelope (Length 2B + Packet ID 2B + Not Usable Byte 1B + AVL Packet Header + AVL Data Array). The codec parsers themselves are unchanged — UDP only changes the framing/transport. ACK format differs (5-byte UDP ack vs. 4-byte TCP record count).
Reference: docs/wiki/concepts/avl-data-format.md § "UDP envelope".
Risk: UDP loses TCP's natural per-session stickiness, so a future Phase 2 over UDP would need a different routing model than the connection registry.
3.C — Codec 15 (0x0F)
Trigger: FMX6 professional fleet onboards.
Codec 15 is one-way device→server with both timestamp and IMEI in every frame, used only on FMX6 devices in RS232 modes. Out of scope for the deployed FMB/FMC/FMM/FMU fleet.
Implementation is a new handler in src/adapters/teltonika/codec/data/codec15.ts plus a registration in index.ts. The handshake skips IMEI exchange because it's in every frame.
3.D — SMS protocols (Codec 4 + binary SMS)
Trigger: SMS fallback connectivity becomes a requirement (e.g. devices in cellular-fringe areas).
Codec 4 carries 24 GPS positions in one SMS (bit-field compressed); separate binary-SMS protocol carries an AVL data array + IMEI. Both require an SMS gateway integration outside this service.
This is large enough to warrant its own service rather than living in tcp-ingestion/. Open question for that point: should the SMS gateway publish to the same telemetry:teltonika Redis Stream, or a separate one? Probably the same — the position-record contract is transport-agnostic.
3.E — Multi-region / NATS or Kafka migration
Trigger: Multi-region deployment, or single-Redis throughput becomes a real bottleneck.
Replace ioredis with @nats-io/nats or kafkajs. The publish interface in src/core/publish.ts should be small enough that this is a swap, not a rewrite — design Phase 1's publisher with this in mind.
How items move from here to a real phase
When one of these triggers fires:
- Create a new
phase-N-<name>/folder under.planning/. - Promote the relevant section above into a full phase plan with the same task structure as Phase 1/2.
- Update the ROADMAP with the new phase row.
- Remove the section from this README (or mark it as promoted).