8.2 KiB

Raw Blame History

Device Plane Implementation Baseline

Status: PostgreSQL, Control Core and Gateway foundation are running healthy on Synology. The accepted foundation has public ingress and discovery ingest disabled. The next additive transition enables only an authenticated, quarantine-only ARUSNAVI B2 discovery path on raw TCP 9921. Command transport remains disabled.

Product boundary

The Device Manager user interface is a canonical Foundry Page Library template. Foundry owns page instances, layout, presentation and an opaque device-plane-control binding. It does not own device records, credentials, raw protocol or command delivery.

The independent NDC Device Plane owns physical-device state and direct connections:

Foundry Device Manager Page
        |
        | device-plane-control (typed server boundary)
        v
Device Control Core <-> Device PostgreSQL
        |
        v
Device Gateway <-> physical devices

Engine L2 may consume safe decoded observations and build workflows/Data Products. It does not own TCP sessions, secrets or the command transport.

Preserved production path

The existing Gelios -> Engine L2 -> External Data Plane -> Foundry Map path is outside this implementation slice. Its credentials, workflows, Data Products, bindings and map presentation must not be changed or restarted by a Device Plane artifact.

The first B2 pilot adds an NDC server route in parallel and keeps the existing Gelios route unchanged.

Source and runtime placement

Source:

platform/device-plane/
  packages/device-protocol-contract/
  packages/arusnavi-b2-adapter/
  services/device-control-core/
  services/device-gateway/
  docker-compose.device-plane.yml

Planned Synology runtime:

/volume1/docker/nodedc-device-plane

Planned Compose project and services:

nodedc-device-plane
  device-control-core
  device-gateway
  device-postgres

device-postgres is a private persistent prerequisite. Application overlays must never force-recreate it or its volume.

The canonical runner selects only device-control-core and device-gateway with --no-deps. Its health acceptance is scoped to the selected services and requires the fail-closed fields to remain disabled. A failed first activation removes only candidate stateless services and never requests volume removal. Rollback now records an explicit pre-apply service inventory in the backup; the existence of the shared Compose file does not imply that Core or Gateway existed before apply.

The exact foundation recovery validates the failed archive, journal, backup, partial live source and observed healthy image/container generations. It then publishes the matching source and performs read-only runtime acceptance. It does not build, restart, recreate or remove any service.

Network boundary

The accepted foundation publishes no device port. The reviewed pilot transition publishes 9921/TCP from Device Gateway after a port-collision check and keeps health endpoints loopback-only.

device.nodedc.ru is a DNS name, not an HTTP/TCP mode. The same name may later serve an HTTPS Control API on 443 and the B2 raw TCP protocol on 9921.

DSM HTTP/HTTPS Reverse Proxy is not a raw TCP ingress and must not be configured as 443 -> 9921.

The artifact never changes DSM firewall, DSM Router Configuration, DNS or a physical router.

Identity and onboarding

An IMEI is a claimed protocol identifier, not proof of tenant ownership.

An unknown connection produces a quarantine-only discovery.
A discovery never receives commands.
Pilot claim requires an explicit platform-admin action.
Production assignment requires authoritative pre-enrollment or an audited inventory import.
First-claim-wins by IMEI is forbidden.

The ARUSNAVI Web account login/password is used only by the human operator to configure the additional device route. It is not a Device Plane credential.

Protocol evidence

The official B2 material proves:

four simultaneous monitoring server routes;
INTERNAL, EXTERNAL, USER_AG and EGTS variants;
INTERNAL server-side identification by modem IMEI;
server route fields for DNS/IP, TCP port, protocol and optional ID;
SMS/TCP command families and a six-digit device access password.

The official ARUSNAVI INTERNAL protocol sheet now provides the first read-path framing contract:

HEADER2 for GPRS is FF 23 followed by an eight-byte little-endian IMEI;
the server confirms HEADER2 with a bounded SERVER_COM carrying Unix time;
a PACKAGE begins with 5B, carries a package number in 01..FB, contains one or more length-framed PACKET records and ends with 5D;
every PACKET checksum is verified before acknowledgement;
every valid PACKAGE is acknowledged by package number;
without acknowledgement the tracker repeats the transmission.

The pilot codec implements only that verified read/acknowledgement subset. It does not decode telemetry tags, export command builders or accept arbitrary server commands. An IMEI parsed from a valid HEADER2 remains a claimed identifier and never proves tenant ownership.

Command boundary

Outbound command transport is disabled in this baseline. No command builder is exported.

Later lifecycle:

draft -> planned -> awaiting_confirmation -> queued -> dispatched
      -> acknowledged | failed | expired | unknown

send is not success. An unknown result forbids automatic retry.

Erase, factory reset, firmware/custom firmware, physical outputs and arbitrary raw TCP remain forbidden until separate reviewed acceptance slices.

Implemented local foundation

Provider-neutral discovery, contour and opaque Foundry-binding contracts.
B2 model profile with four parallel routes and INTERNAL/IMEI evidence.
PostgreSQL migration for model profiles, contours, quarantine discoveries, claimed devices, Foundry bindings and append-only audit events.
Core health endpoint and an authenticated quarantine-ingest boundary that is disabled unless explicitly enabled with file-backed secrets.
Gateway discovery-only HEADER2/PACKAGE state machine with bounded buffers, handshake timeout, concurrent/per-source session limits and per-source connection rate limits.
Authenticated Gateway-to-Core discovery ingest. Core HMAC-hashes the full IMEI and persists only its digest, masked view and verified framing evidence.
Only HEADER2 and valid PACKAGE acknowledgements are emitted; no command builder or command transport is present.
Recursive rejection of secret-like fields, raw payloads and command-shaped input in presentation contracts.
Automated contract, adapter, migration, Core and Gateway tests.
Additive component=device-plane runner registry with exact roots, builds, services, allowlist/denylist, runner-owned secrets, health contracts and automatic source/runtime rollback.
Deterministic data-only artifact builder and positive/negative regression tests.
Compose foundation with a private internal network, preserved PostgreSQL volume, file-backed database password and loopback-only health publishing.
Exact one-time PostgreSQL bootstrap descriptor, deterministic builder and absence preflight: an existing database container or volume fails closed, and rollback never removes the volume.

Next source slice

Add the versioned B2 discovery-ingress descriptor and runner acceptance contract without weakening foundation/recovery acceptance.
Build a deterministic data-only app-overlay and promote the runner extension through the standalone root administrative gate.
Plan/apply the exact discovery-ingress artifact and independently prove: Core/Gateway/PostgreSQL health, PostgreSQL generation preservation, 127.0.0.1:9921 loopback-only publication, verified framing, quarantine-only Core ingest and disabled command transport.
Do not publish raw device TCP from the multi-service Synology. Design and independently review an isolated edge/DMZ/VPS ingress with no lateral NAS access, explicit firewall/NAT evidence, acceptance and rollback.
Only after that separate edge gate, add the NDC route to one approved B2 free server slot while preserving Gelios, then prove HEADER/discovery/PACKAGE acknowledgement. Claim and tenant assignment remain a later explicit platform-admin operation.

8.2 KiB Raw Blame History