IPUAPI: reconstructing a legacy device-command protocol

IPUAPI started as a PowerShell web application for managing devices whose binary UDP command interface was reconstructed from Wireshark captures. It combined device-specific reporting-rate and firmware-update messages with request handling, job tracking, and observed-state checks.

This portfolio package preserves that original packet construction and provides a small offline demonstration. Nine original byte segments are retained verbatim. Dynamic device identifiers and firmware locations are synthetic. The runnable module contains no socket or HTTP client implementation.

Try it

Windows PowerShell 5.1, with no third-party dependencies:

.\tests\Run-Tests.ps1
.\examples\Offline-Demo.ps1

The demo simulates three commands: two reach their observed goals, and one times out. It does not contact devices, resolve endpoints, or retrieve firmware.

Import-Module .\IPUAPI.psd1
$packet = New-IpuPacket -DeviceId DEMO001 -Operation 15
ConvertTo-IpuHex $packet
$job = New-IpuJob -DeviceId DEMO001 -Operation 15
Send-IpuJob -Job $job                 # simulated; state becomes Sent

Engineering

flowchart LR
    A[Validated command] --> B[Original fixed byte segments]
    B --> C[Insert synthetic target twice]
    C --> D[Packet bytes]
    D --> E[Simulated dispatch]
    E --> F[Watchlist job]
    G[Caller-supplied device observations] --> H[Reconcile latest fresh state]
    F --> H
    H --> I[Succeeded / TimedOut / Failed]

Loading

Operation	Requested time / distance	Fixture length
15	15 seconds / 10 meters	82 bytes
30	30 seconds / 100 meters	82 bytes
300	300 seconds / 10 meters	82 bytes
SWUP	Firmware version goal	313 bytes

The original web handler selected a command template, inserted an ASCII device suffix twice, and optionally inserted a firmware location. protocol/templates.psd1 contains those nine fixed segments. The fixture tests compare every packet byte against expectations assembled independently from the original sender, rather than calling the new builder to generate its own expected results.

New-IpuJob creates validated, JSON-serializable state. Send-IpuJob simulates dispatch by default. An optional callback receives bytes and a separate command description; no live callback is supplied. A successful dispatch is not an acknowledgement that a device applied the command.

Update-IpuWatchlist accepts caller-supplied snapshots with DeviceId, ObservedAtUtc, and either TimeRateSeconds plus DistanceRateMeters, or SoftwareVersion. It selects the latest snapshot for the target, rejects data predating dispatch or occurring after the current time/deadline, and preserves terminal states. Older batches cannot overwrite a newer processed snapshot. The original 10-minute rate-change and 15-minute firmware deadlines are retained; explicit outcomes and freshness checks are modern additions. Jobs remain available for inspection instead of being silently deleted.

Historical source and modernization

Sanitized .ps1.txt files under historical/ retain the original API, standalone sender, and tracker control flow and packet literals. They are inert references, with operational strings, comments, paths, hostnames, and access/session material replaced. They are not a deployable application. See PROVENANCE.md for exact boundaries.

The runnable module is a focused extraction and modernization, not a claim that this compact module was the complete historical system. The earlier application also handled HTTP sessions, reporting, CSV watchlists, and service integration. Those production dependencies are visible structurally in the references but are not reproduced here.

Limits

• This is an outbound command encoder. It does not implement inbound IP-fragment reassembly or a general binary telemetry decoder.
• The complete vendor protocol specification is unavailable. Fixed fields, including capture-era metadata, are preserved; live interoperability and firmware acceptance have not been tested for this package.
• Device suffixes are exactly seven uppercase ASCII letters/digits. IPU- is an optional input prefix. Variable-width identifiers are rejected to protect captured framing.
• Firmware URIs must be exactly 61 printable ASCII bytes, matching the historical insertion width. The default is an example.invalid HTTP URI. Fixed length/header/checksum fields are not guessed or regenerated for arbitrary-size payloads; the URI is never fetched.
• Firmware success means an observation exactly matches the requested version string. It does not establish firmware authenticity, integrity, or installation safety.
• The state machine is a single-process demonstration. Durable transactions, concurrent-worker coordination, retries, and authenticated observations belong in a production adapter.

The offline tests cover complete byte fixtures, input validation, exact goal matching, observation freshness and ordering, timeout boundaries, terminal-state stability, dispatch failures/idempotence, and JSON roundtrips. GitHub Actions runs them with Windows PowerShell.

MIT license. Copyright Derek Poe.