Interface control document

1. Identification

This document covers behavior in AntPLUSModule.cs, AntDataCollector.cs and Config/AntPLUSSettings.cs at the source revision above.

2. Scope

The module discovers ANT+ devices through an attached USB radio, selects one heart-rate monitor by its ANT device number, retains its latest common heart-rate data and publishes that data through HEAT Capture.

The implementation is in-process. It calls the managed SmallEarthTech.AntPlus, SmallEarthTech.AntRadioInterface and SmallEarthTech.AntUsbStick assemblies, which in turn use the packaged ANT native libraries. There is no AntPlusBridge.exe, named pipe or module-defined network protocol in this revision.

Out of scope:

• pairing, configuring or controlling an ANT+ sensor;
• capturing ANT+ device profiles other than heart rate;
• ANT channel encryption or authentication;
• exposing manufacturer, battery, capabilities or accumulated-event-time data;
• guaranteeing delivery, replay or persistence after publication to HEAT Capture.

3. Interface inventory

4. IF-CMANTPLUS-01 Settings-time device discovery

4.1 Trigger and result

DeviceID uses ScanAntDevices as its asynchronous values source. Opening or refreshing that setting creates a new AntRadio and AntDeviceCollection, starts scanning, then waits:

1. until the collection contains at least one device; or
2. until 30 seconds have elapsed.

The wait checks collection count every 100 ms. After it ends, the method returns only devices whose ANT device class is HeartRate.DeviceClass (120).

Each returned option has:

The setting UI therefore does not list bike, cadence, muscle-oxygen, stride or fitness-equipment devices. ScanAntDevices contains display-name mappings for those classes, but its heart-rate filter excludes them from the returned list.

4.2 Discovery limitation

The wait condition is any discovered device, not any discovered heart-rate device. If another ANT+ device appears first, the scan can stop waiting and return an empty list before a heart-rate monitor is discovered. Refresh the setting after ensuring the intended monitor is awake and broadcasting.

4.3 Resource behavior

The discovery method does not expose cancellation, radio selection or scan progress. This revision also does not dispose the temporary AntRadio or AntDeviceCollection after returning.

5. IF-CMANTPLUS-02 Session heart-rate collection

5.1 Device selection

During module initialization, DeviceID is copied into a new AntDataCollector. The active collector accepts a device only when both conditions hold:

DeviceID defaults to 0. It is an identifier, not a wildcard. The module does not select the first available monitor.

Changing DeviceID does not change an already-created collector. Stop and start the module so that initialization creates a collector with the new value.

5.2 Start and connection

StartCapture calls AntDataCollector.StartAsync. The collector schedules its collection loop and returns immediately. A successful module start means the worker was scheduled; it does not mean a radio opened or the configured sensor connected.

The loop:

1. creates an AntRadio and AntDeviceCollection;
2. starts scanning;
3. searches the collection every 100 ms for the exact device class and number;
4. logs Device {deviceId} connected. after a match;
5. copies the device’s latest CommonHeartRateData every 100 ms while it remains present.

An ANT radio StartupMessage, including one caused by a radio reset, triggers another StartScanning call.

5.3 Measurement snapshot

CommonHeartRateData supplies three values:

The units above are defined by the SmallEarthTech.AntPlus heart-rate profile API. The module does not receive or publish a wall-clock sensor timestamp, ANT page number, sequence number, device number, manufacturer data, signal strength or battery state.

5.4 Device loss

When AntDeviceCollection.Contains no longer finds the selected device, the loop:

1. logs Device {deviceId} lost. Waiting for reconnection.;
2. clears its retained heart-rate value;
3. returns to the 100 ms exact-device search.

No stale-value grace period or disconnect event is published. Frame publication stops until the same device number appears again.

5.5 Stop and restart

EndCapture requests collector cancellation. AntDataCollector.StopAsync does not wait for the collection task to exit. The module host then marks the module uninitialized, so the next host-level start creates a new collector.

A fast stop/start can therefore overlap old and new collector loops briefly. It does not reuse the old collector’s cached reading, but radio teardown is not complete before the new collector tries to open the radio. Treat a successful restart as provisional until new frames arrive.

6. IF-CMANTPLUS-03 Capture-frame publication and data model reference

6.1 Publication condition

Each HEAT Capture module tick reads HeartRateData. When no selected device data is retained, HandleCapture returns null and publishes no frame.

When data exists, the module publishes one SimulationFrame containing one EntityState and one BiometricSensorComponent.

6.2 Frame fields

The entity has no published name or device-number field. Its generated ID can change when the module process or instance is recreated. Consumers must not use it as a durable identity for the physical monitor.

Publication cadence follows the generic module Interval, not the sensor’s ANT message cadence. Multiple ticks can publish the same retained measurement. Intermediate sensor updates can be overwritten before a capture tick and are not queued.

6.3 Events and ordering

The module publishes no EntityEvent. It provides no measurement sequence number, sensor timestamp, duplicate marker, acknowledgement, retry or replay contract.

7. Units, frames and conventions

Heart rate uses beats per minute and RR interval uses milliseconds. The frame timestamp uses UTC Unix milliseconds. Identifiers are dimensionless. This interface carries no spatial vectors or transforms, so no coordinate frame or handedness convention applies. The ANT+ libraries parse radio page layout and byte order before the module receives these values.

8. Error behavior

No structured fault state is sent to HEAT Capture. Operational health must be inferred from logs and whether fresh frames arrive.

9. Configuration affecting the interfaces

Only DeviceID is module-specific.

10. Compatibility and versioning

This revision targets .NET 10 and references HEAT.Capture.ModuleSDK 2.0.5. Its package must keep the following runtime files together:

No runtime protocol-version negotiation exists. Validate a package update against its exact managed and native library set and against the target HEAT Capture Module SDK.

11. Security considerations

ANT+ traffic is local radio traffic but is not authenticated by this module. DeviceID is a filter, not proof of device identity. A radio-visible transmitter using the same class and device number can be accepted. This interface supplies no encryption, integrity check, access-control decision or remote network listener.

Run HEAT Capture under an account that trusts the installed native DLL set. Replace packaged radio libraries only through a verified module package.

12. Conformance

1. Attach a supported ANT USB radio and confirm Windows enumerates it.
2. Wake one ANT+ heart-rate monitor and refresh DeviceID.
   • The list contains Heart Rate (<device number>).
   • It contains no non-heart-rate devices.
3. Select that device number and start a HEAT Capture session.
   • The log contains Device <device number> connected.
   • Frames begin only after measurement data is available.
4. Inspect a frame.
   • It contains one entity with HeartRate in beats/min and RR in ms.
   • capture_time.timestamp_ms is host UTC time.
   • No sensor timestamp, ANT device number or ANT page metadata is present.
5. Stop the monitor or move it out of range.
   • The device-lost warning appears.
   • Frame publication stops; prior values are not republished.
6. Restore the same monitor.
   • The module reconnects without changing DeviceID.
   • Frame publication resumes with current data.
7. Stop and immediately start capture.
   • Treat start success as provisional.
   • Verify fresh frames arrive; a successful lifecycle response alone is insufficient.

13. Revision history

HEAT Capture team. Last updated 2 October 2026.