Interface control document

1. Identification

2. Scope

This document defines the two interfaces the module holds with a SonoMarc Core server, the REST resources and JSON properties it reads, the event subscription it registers, and the components and events it publishes to HEAT Capture.

The module is read-only with respect to simulation state. It issues no REST call that changes seat, asset or session state. The only writes it performs are the two requests that create and populate its own event subscription.

3. Interface inventory

4. IF-CMSONO-01 REST state interface

4.1 Transport and addressing

4.2 Endpoints

Paths are relative to the base address above.

The platform request is issued once per seat rather than once per platform, so in WholeSession mode the same platform resource is fetched as many times per cycle as it has seats.

4.3 Connection lifecycle

InitialiseModule only constructs the HTTP client; it performs no request and cannot fail on an unreachable server.

StartCapture runs four steps in order: poll sessions until a running session is found, discover platforms and seats, perform one full snapshot refresh so asset names are known, then register the event subscription described in section 5. It returns false only when the session poll ends without a session, which happens only on cancellation. Zero discovered seats is a warning, not a failure: the module starts and publishes frames that contain no entities.

StartCapture is bounded by the SDK StartupTimeout, which this module does not override, so the whole of that sequence must complete within 5 seconds. SessionPollRetryMs defaults to 5000, so if the first sessions response contains no matching running session the retry delay alone exhausts the startup budget and the module does not start. See section 4.7 for the consequence.

Each capture cycle re-polls every known seat. The seat set is fixed at StartCapture: a seat added to the SonoMarc session later is never discovered, and a seat removed continues to be polled and to log a refresh warning every cycle.

EndCapture unhooks the three receiver callbacks, stops the receiver, disposes the HTTP client, and clears the active session, the entity-id map and the seat snapshots.

4.4 Authentication

None. No credential, token, API key or client certificate is sent on any request, and no setting exists to supply one. Any host able to reach Host:Port can read the same resources.

4.5 JSON properties read

Only the properties listed here are read. Everything else in a response is ignored.

GET sessions:

GET sessions/{session}/platforms:

GET sessions/{session}/platforms/{platform}/seats:

GET sessions/{session}/platforms/{platform}/seats/{seat}:

GET sessions/{session}/platforms/{platform}/seats/{seat}/assets:

An intercom asset therefore publishes only its name, type and volume. Its frequency, band, secure and squelch fields are published as empty strings, false and 0 regardless of what the service reports for them, because the parser gates those reads on the asset being radio or relay.

GET sessions/{session}/platforms/{platform}:

The parser reads the property spelled postition_source while the comment immediately above it names position_source. If the service does not send that exact misspelling, the lookup fails, no position snapshot is produced, and the seat entity is published with no WorldPositionComponent: valid position data is silently omitted with no log line. This is audit finding SONO-01. Which spelling the service actually sends is not determinable from this module’s source and has not been confirmed against a live SonoMarc payload, so the defect is the divergence between the code and its own comment rather than a proven mismatch with the service.

4.6 Timing and cadence

4.7 Error behaviour

A stale snapshot and a fresh one are indistinguishable in the published frame: the module carries no per-seat freshness or validity flag, and the frame capture time is always the current host clock.

5. IF-CMSONO-02 Server-Sent Events interface

5.1 Transport and addressing

The colon before the subscription id in the PUT and GET paths is a literal character in the URL the module builds, not placeholder notation. Whether the SonoMarc API expects that leading colon is a service property that cannot be established from this module’s source; the vendor’s own API documentation is the authority.

5.2 Subscription registration

The POST sends an empty body with no content type and expects a JSON object with a string id property. A non-success status, a missing id, or an empty id aborts registration.

The PUT sends a flat JSON object mapping each subscribed event path to the string "enable". The paths are built from the seats and assets discovered at start:

• one seat base path, sessions/{session}/platforms/{platform}/seats/{seat}
• one path per discovered asset, sessions/{session}/platforms/{platform}/seats/{seat}/assets/{asset}

Unlike the polling calls, these path segments are inserted unescaped, so a session, platform, seat or asset name containing a slash produces a malformed subscription path and a seat key that cannot be resolved back.

5.3 Subscription set actually enabled

For every supplied path the registration code enables {path}/rx_activity and {path}/tx_activity. It enables selected, secure, squelch and ptt only inside a branch guarded by the path ending in /assets. The path builder never produces a path ending in /assets: it produces the seat base and fully qualified .../assets/{asset} paths. That branch is therefore unreachable in this revision, and the subscription set is exactly:

Push-to-talk, asset selection, secure toggling and squelch are never subscribed, so the dispatcher and mapping table entries for them are only reachable if the service pushes events that were not requested. The registration log line reports the enabled count and can be used to check this: it is twice the number of seats plus assets.

Assets discovered after StartCapture receive no subscription, because the set is registered once and never revised.

5.4 Connection lifecycle and reconnect

StartAsync registers the subscription and then runs the stream loop on a background task. If registration fails, StartAsync returns without starting the loop and never retries: the capture session runs to completion with no events at all, while REST polling continues normally.

Once the loop is running, an ended stream or any exception other than cancellation is logged as a warning and retried after SseReconnectDelayMs, default 3000 ms, indefinitely. Reconnection reuses the subscription id from the original registration and does not re-register or re-PUT the path map. Whether the service retains a subscription across a dropped stream is a service property that cannot be established from this module’s source; if it does not, reconnection produces a stream that delivers nothing.

StopAsync cancels the loop, awaits the stream task, and disposes the streaming client.

5.5 Authentication

None, on all three requests. There is no setting for a credential on this interface either.

5.6 Wire format

The reader handles two SSE fields and dispatches on a blank line:

A data: line assigns rather than appends, so a payload split across multiple data: lines is truncated to its last line. This breaks the SSE convention that multiple data: lines concatenate.

The payload must be a JSON object. Only one property is read from it on activity events:

On a virtual-platform command event the payload is instead read for virtual_platform.name, and the raw JSON text is forwarded whole.

The event path itself is parsed positionally: the segment after platforms and the segment after seats form the seat key, the last segment is the event type, and the second-to-last segment is taken as the asset name. On a seat-level path such as .../seats/{seat}/rx_activity the second-to-last segment is the seat name, so the asset lookup fails and the published event carries an empty frequency, an empty band, secure false, and a target of {platform}/{seat}/{seat}. Seat-level activity events are subscribed, so this is reachable in normal operation.

5.7 Event mapping

A value counts as on when it equals on, or when it is neither off nor empty. An empty value counts as off. The push-to-talk value is instead matched literally, and normal, priority and emergency all map to the same started event, so the priority level is lost and is not carried into the comms event either. Receive ending produces nothing at all, so a reception has a start with no end.

Values arriving on selected never reach the published data: the selected flag on the radio component is hard-coded false in the parser, and no SSE handler writes back into the snapshot.

5.8 Error behaviour

6. IF-CMSONO-03 Frame publication and data model reference

6.1 Entity model

The entity id is derived from the .NET string hash, which is seeded randomly per process. Ids are consistent within one run of HEAT Capture and change between runs for the same seat name, so they cannot be used to correlate entities across sessions. The parent id on the linked-entity component is computed the same way and stays consistent with the seat ids inside a single run.

6.2 Published components and fields

WorldPositionComponent, published only when a geographic position was resolved for the platform:

LinkedEntityComponent, published on every seat entity unconditionally:

RadioComponent, one per retained asset:

6.3 Events published

Events are enqueued when they occur and drained into the next frame, so an event can be published up to one full cycle after it happened. Each event carries its own timestamp taken at the moment it was enqueued, which is the SSE arrival time or the poll at which a fault edge was detected, not the frame capture time.

Comms and tracking events reference the seat entity id. Virtual-platform command events instead reference a hash of the platform name taken from the event path, which is not a published entity.

6.4 Polled but not published

The following are read from the service and retained in the module’s snapshot on every cycle, and then never reach a published field: the seat type, the seat binding, the seat-level volume, the SIP state, the call state, the seat-level push-to-talk value, the seat-level squelch state, and the platform callsign.

7. Units and conventions

8. Configuration affecting the interfaces

The scheme, the 10-second REST request timeout, the infinite SSE timeout, and the 5-second startup budget are not configurable. See Manage capture modules for the generic settings and the Module SDK ICD for the lifecycle contract they belong to.

9. Compatibility and versioning

There is no version negotiation on either interface. The module assumes the resource paths, JSON property names and event-path grammar documented above. It is tolerant of missing optional properties and substitutes defaults for them, which means a renamed property degrades silently rather than failing: a renamed asset frequency publishes an empty string, a renamed volume publishes 100, and a renamed position source publishes no position component. The properties read with a required accessor are the session name and state, the platform name, and the seat name, binding and type; renaming one of those produces a logged failure instead.

The event grammar is parsed positionally on the segments named platforms and seats, so a change to the service’s path structure silently redirects or drops events rather than raising an error.

10. Security considerations

Both interfaces are unauthenticated plain HTTP with no setting to change either property, so credentials, tokens and TLS cannot be introduced through configuration. Any host with network access to the SonoMarc API can read the same session, seat and asset state, register its own event subscription, and observe the same event stream. Traffic is readable and modifiable in transit by anything on the path.

Captured data includes radio frequencies, band assignments, secure-mode flags and platform positions, and the recognised text of virtual-person voice commands is carried verbatim in the published event content. Restrict the SonoMarc service to an isolated network segment and treat captured sessions according to the deployment’s own classification of that material.

11. Conformance

1. With a SonoMarc session in the Running state, start a capture session. Confirm the log records the starting mode and host, the selected session name, the discovered seat count, and the registered subscription id and path count.
2. Confirm the frame carries one entity per expected seat, named {platform}/{seat}, and that the radio components match the assets on those seats.
3. Confirm the registered path count equals twice the number of seats plus assets. Exercise push-to-talk, asset selection, secure toggling and squelch on the service and confirm that none of them produces an event, which is the observable consequence of the unreachable expansion branch in section 5.3.
4. Exercise transmit and receive and confirm the paired comms and tracking events appear. Confirm a reception produces a start with no matching end.
5. Capture the raw response of GET sessions/{session}/platforms/{platform} and inspect the spelling of the position source property. If it is not postition_source, no seat entity carries a position component, which is SONO-01. Record the observed spelling so the finding can be closed either way.
6. Where a position component is published, confirm the heading is 0 and that latitude, longitude and altitude match the service’s reported values without conversion.
7. Confirm the selected flag is false on every radio component even while an asset is selected on the service.
8. Restart HEAT Capture without changing the SonoMarc configuration and confirm the seat entity ids differ from the previous run, so that no downstream analysis keys on them across sessions.
9. Stop the SonoMarc service before starting capture. Confirm the SDK startup timeout warning and that no frames are published, then confirm whether the process continues to issue session polls, which is the abandoned startup operation described in section 4.7.
10. With capture running, interrupt the network to the service. Confirm the refresh warnings, the stream disconnect warning, and whether events resume after reconnection without a capture restart. This is the test that determines whether the service retains a subscription across a dropped stream.

12. Revision history

HEAT Capture team. Last updated 2 October 2026.