UL/ulapp
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

S1-b: IF-LOC v1.0 locator simulator + round-trip test

Browse Source 
Reference implementation of the frozen IF-LOC v1.0 contract
(meta/contracts/ble-device-interface.md): byte-accurate codec for the
telemetry, capture-trigger, and capture-result frames, plus a
LocatorSimulator that replays a canned locate session over a
transport-agnostic loopback link. Unblocks App development without
firmware (Risk R-3, SRS S3.1).

Plain net9.0 (not a MAUI head) so it builds/runs headless under the QA
gate without the Android/iOS workloads; qa-gate.sh auto-discovers
*.Tests.csproj under app/tests/. Round-trip test asserts field-level
fidelity (every SRS S3.1 telemetry + capture-result field), sentinels,
endianness (incl. RFC 4122 big-endian pointId), the REJECTED path, and
exactly-once capture correlation (no silent drop, SRS-LOG-7). 8/8 green.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Brent Perteet
2026-08-20 13:10:24 -05:00
parent dc3a45e699
commit 0b4fb83546
6 changed files with 785 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

216
tests/IfLoc.Sim/Frames.cs Normal file
View File

@@ -0,0 +1,216 @@
using System.Buffers.Binary;
namespace IfLoc.Sim;
// Byte-accurate codec for the frozen IF-LOC v1.0 frames.
// All multi-byte integers little-endian except pointId (RFC 4122 big-endian, §5.3).
/// <summary>§4 telemetry payload — the locate data dictionary.</summary>
public sealed record Telemetry
{
public uint LocatorUptimeMs { get; init; }
/// <summary>Depth in metres (resolution 0.01 m). Null = no depth (sentinel on wire).</summary>
public double? DepthMeters { get; init; }
/// <summary>Signal current in mA. Null = invalid.</summary>
public ushort? SignalCurrentMa { get; init; }
/// <summary>Frequency in Hz. Null = n/a.</summary>
public uint? FrequencyHz { get; init; }
public LocateMode Mode { get; init; } = LocateMode.Single;
public SignalType SignalType { get; init; } = SignalType.Active;
public byte GainDb { get; init; }
public byte SignalLevel { get; init; }
public byte DistortionQualityPct { get; init; }
public byte SignalDirection { get; init; }
public byte CompassAngleDeg { get; init; }
/// <summary>Guidance offset −1000..+1000 (negative = left). Null = n/a.</summary>
public short? GuidanceOffset { get; init; }
public WarningFlags Warnings { get; init; }
public UtilityType Utility { get; init; } = UtilityType.None;
public byte BatteryPercent { get; init; }
public StatusFlags Status { get; init; }
/// <summary>Encodes the 28-byte payload (frame offsets 4..31).</summary>
public byte[] EncodePayload()
{
var p = new byte[IfLoc.TelemetryPayloadLen];
var s = p.AsSpan();
BinaryPrimitives.WriteUInt32LittleEndian(s[0..], LocatorUptimeMs); // 4
BinaryPrimitives.WriteInt16LittleEndian(s[4..], DepthMeters is { } d ? (short)Math.Round(d * 100) : IfLoc.DepthNoValue); // 8
BinaryPrimitives.WriteUInt16LittleEndian(s[6..], SignalCurrentMa ?? IfLoc.CurrentInvalid); // 10
BinaryPrimitives.WriteUInt32LittleEndian(s[8..], FrequencyHz ?? IfLoc.FrequencyNa); // 12
s[12] = (byte)Mode; // 16
s[13] = (byte)SignalType; // 17
s[14] = GainDb; // 18
s[15] = SignalLevel; // 19
s[16] = DistortionQualityPct; // 20
s[17] = SignalDirection; // 21
s[18] = CompassAngleDeg; // 22
s[19] = 0; // 23 reserved
BinaryPrimitives.WriteInt16LittleEndian(s[20..], GuidanceOffset ?? IfLoc.GuidanceNa); // 24
BinaryPrimitives.WriteUInt16LittleEndian(s[22..], (ushort)Warnings); // 26
s[24] = (byte)Utility; // 28
s[25] = BatteryPercent; // 29
s[26] = (byte)Status; // 30
s[27] = 0; // 31 reserved
return p;
}
/// <summary>Decodes a 28-byte payload (frame offsets 4..31).</summary>
public static Telemetry DecodePayload(ReadOnlySpan<byte> p)
{
if (p.Length < IfLoc.TelemetryPayloadLen)
throw new ArgumentException($"telemetry payload must be {IfLoc.TelemetryPayloadLen} bytes");
short depth = BinaryPrimitives.ReadInt16LittleEndian(p[4..]);
ushort cur = BinaryPrimitives.ReadUInt16LittleEndian(p[6..]);
uint freq = BinaryPrimitives.ReadUInt32LittleEndian(p[8..]);
short guid = BinaryPrimitives.ReadInt16LittleEndian(p[20..]);
return new Telemetry
{
LocatorUptimeMs = BinaryPrimitives.ReadUInt32LittleEndian(p[0..]),
DepthMeters = depth == IfLoc.DepthNoValue ? null : depth / 100.0,
SignalCurrentMa = cur == IfLoc.CurrentInvalid ? null : cur,
FrequencyHz = freq == IfLoc.FrequencyNa ? null : freq,
Mode = (LocateMode)p[12],
SignalType = (SignalType)p[13],
GainDb = p[14],
SignalLevel = p[15],
DistortionQualityPct = p[16],
SignalDirection = p[17],
CompassAngleDeg = p[18],
GuidanceOffset = guid == IfLoc.GuidanceNa ? null : guid,
Warnings = (WarningFlags)BinaryPrimitives.ReadUInt16LittleEndian(p[22..]),
Utility = (UtilityType)p[24],
BatteryPercent = p[25],
Status = (StatusFlags)p[26],
};
}
/// <summary>Encodes a full 32-byte TELEMETRY frame (header + payload).</summary>
public byte[] EncodeFrame(ushort seq)
{
var f = new byte[IfLoc.TelemetryFrameLen];
Frames.WriteHeader(f, MessageType.Telemetry, seq);
EncodePayload().CopyTo(f.AsSpan(IfLoc.HeaderLen));
return f;
}
}
/// <summary>§5.1 capture-trigger frame (locator → app).</summary>
public sealed record CaptureTrigger
{
public ushort CaptureSeq { get; init; }
public TriggerType TriggerType { get; init; }
public required Telemetry Snapshot { get; init; }
public byte[] EncodeFrame(ushort seq)
{
var f = new byte[IfLoc.CaptureTriggerFrameLen];
Frames.WriteHeader(f, MessageType.CaptureTrigger, seq);
BinaryPrimitives.WriteUInt16LittleEndian(f.AsSpan(4), CaptureSeq); // 4
f[6] = (byte)TriggerType; // 6
f[7] = 0; // 7 reserved
Snapshot.EncodePayload().CopyTo(f.AsSpan(8)); // 8..35
return f;
}
public static CaptureTrigger DecodeFrame(ReadOnlySpan<byte> f)
{
Frames.Expect(f, MessageType.CaptureTrigger, IfLoc.CaptureTriggerFrameLen);
return new CaptureTrigger
{
CaptureSeq = BinaryPrimitives.ReadUInt16LittleEndian(f[4..]),
TriggerType = (TriggerType)f[6],
Snapshot = Telemetry.DecodePayload(f.Slice(8, IfLoc.TelemetryPayloadLen)),
};
}
}
/// <summary>§5.2 capture-result frame (app → locator).</summary>
public sealed record CaptureResult
{
public ushort CaptureSeq { get; init; }
public CaptureOutcome Outcome { get; init; }
public ReasonCode Reason { get; init; }
public FixType FixType { get; init; }
/// <summary>WGS84 latitude in degrees. Null = no position.</summary>
public double? Lat { get; init; }
public double? Lon { get; init; }
/// <summary>Orthometric height in metres. Null = no position.</summary>
public double? OrthometricHeightM { get; init; }
/// <summary>Horizontal RMS (1σ) in metres. Null = unknown.</summary>
public double? HrmsM { get; init; }
public double? VrmsM { get; init; }
/// <summary>Position epoch, UTC.</summary>
public DateTimeOffset? Utc { get; init; }
/// <summary>Stored point UUIDv7. All-zero on REJECTED.</summary>
public Guid PointId { get; init; }
public byte[] EncodeFrame(ushort seq)
{
var f = new byte[IfLoc.CaptureResultFrameLen];
var s = f.AsSpan();
Frames.WriteHeader(f, MessageType.CaptureResult, seq);
BinaryPrimitives.WriteUInt16LittleEndian(s[4..], CaptureSeq);
s[6] = (byte)Outcome;
s[7] = (byte)Reason;
s[8] = (byte)FixType;
s[9] = 0;
BinaryPrimitives.WriteInt32LittleEndian(s[10..], Lat is { } la ? (int)Math.Round(la * 1e7) : IfLoc.PositionNoValue);
BinaryPrimitives.WriteInt32LittleEndian(s[14..], Lon is { } lo ? (int)Math.Round(lo * 1e7) : IfLoc.PositionNoValue);
BinaryPrimitives.WriteInt32LittleEndian(s[18..], OrthometricHeightM is { } h ? (int)Math.Round(h * 1000) : IfLoc.PositionNoValue);
BinaryPrimitives.WriteUInt16LittleEndian(s[22..], HrmsM is { } hr ? (ushort)Math.Round(hr * 1000) : IfLoc.RmsUnknown);
BinaryPrimitives.WriteUInt16LittleEndian(s[24..], VrmsM is { } vr ? (ushort)Math.Round(vr * 1000) : IfLoc.RmsUnknown);
BinaryPrimitives.WriteUInt16LittleEndian(s[26..], 0); // reserved
BinaryPrimitives.WriteUInt64LittleEndian(s[28..], Utc is { } t ? (ulong)t.ToUnixTimeMilliseconds() : 0);
PointId.TryWriteBytes(s.Slice(36, 16), bigEndian: true, out _); // §5.3 RFC 4122 network order
return f;
}
public static CaptureResult DecodeFrame(ReadOnlySpan<byte> f)
{
Frames.Expect(f, MessageType.CaptureResult, IfLoc.CaptureResultFrameLen);
int lat = BinaryPrimitives.ReadInt32LittleEndian(f[10..]);
int lon = BinaryPrimitives.ReadInt32LittleEndian(f[14..]);
int h = BinaryPrimitives.ReadInt32LittleEndian(f[18..]);
ushort hr = BinaryPrimitives.ReadUInt16LittleEndian(f[22..]);
ushort vr = BinaryPrimitives.ReadUInt16LittleEndian(f[24..]);
ulong ms = BinaryPrimitives.ReadUInt64LittleEndian(f[28..]);
return new CaptureResult
{
CaptureSeq = BinaryPrimitives.ReadUInt16LittleEndian(f[4..]),
Outcome = (CaptureOutcome)f[6],
Reason = (ReasonCode)f[7],
FixType = (FixType)f[8],
Lat = lat == IfLoc.PositionNoValue ? null : lat / 1e7,
Lon = lon == IfLoc.PositionNoValue ? null : lon / 1e7,
OrthometricHeightM = h == IfLoc.PositionNoValue ? null : h / 1000.0,
HrmsM = hr == IfLoc.RmsUnknown ? null : hr / 1000.0,
VrmsM = vr == IfLoc.RmsUnknown ? null : vr / 1000.0,
Utc = ms == 0 ? null : DateTimeOffset.FromUnixTimeMilliseconds((long)ms),
PointId = new Guid(f.Slice(36, 16), bigEndian: true),
};
}
}
/// <summary>Shared header helpers.</summary>
public static class Frames
{
public static void WriteHeader(Span<byte> f, MessageType type, ushort seq)
{
f[0] = IfLoc.FrameVersion;
f[1] = (byte)type;
BinaryPrimitives.WriteUInt16LittleEndian(f[2..], seq);
}
public static MessageType PeekType(ReadOnlySpan<byte> f) => (MessageType)f[1];
public static void Expect(ReadOnlySpan<byte> f, MessageType type, int fixedLen)
{
if (f.Length < fixedLen)
throw new ArgumentException($"{type} frame must be ≥ {fixedLen} bytes, got {f.Length}");
if (f[0] != IfLoc.FrameVersion)
throw new ArgumentException($"unsupported frameVersion 0x{f[0]:X2}");
if ((MessageType)f[1] != type)
throw new ArgumentException($"expected {type}, got 0x{f[1]:X2}");
}
}

19
tests/IfLoc.Sim/IfLoc.Sim.csproj Normal file
View File

@@ -0,0 +1,19 @@
<Project Sdk="Microsoft.NET.Sdk">
<!--
IF-LOC locator simulator + wire codec.
Deliberately a plain net9.0 library (NOT a MAUI target head) so it builds and runs
headless in CI without the Android/iOS workloads. It is the reference implementation
of the frozen IF-LOC v1.0 contract (meta/contracts/ble-device-interface.md) and exists
to unblock App development without firmware (Risk R-3, SRS §3.1).
-->
<PropertyGroup>
<TargetFramework>net9.0</TargetFramework>
<ImplicitUsings>enable</ImplicitUsings>
<Nullable>enable</Nullable>
<LangVersion>latest</LangVersion>
<RootNamespace>IfLoc.Sim</RootNamespace>
</PropertyGroup>
</Project>

145
tests/IfLoc.Sim/LocatorSimulator.cs Normal file
View File

@@ -0,0 +1,145 @@
namespace IfLoc.Sim;
/// <summary>
/// A bidirectional in-memory link modelling the bonded BLE GATT session between the
/// locator (peripheral) and the App (central). Frames pushed toward the App surface on
/// <see cref="ToApp"/>; frames the App writes back surface on <see cref="ToLocator"/>.
/// A transport-agnostic stand-in for the real GATT characteristics — a TCP or real-BLE
/// implementation can replace it without touching the simulator or codec.
/// </summary>
public sealed class LoopbackLink
{
/// <summary>Locator → App (Telemetry / Event characteristics).</summary>
public event Action<byte[]>? ToApp;
/// <summary>App → Locator (Command / Capture Result characteristics).</summary>
public event Action<byte[]>? ToLocator;
public void PublishToApp(byte[] frame) => ToApp?.Invoke(frame);
public void WriteToLocator(byte[] frame) => ToLocator?.Invoke(frame);
}
/// <summary>Result of a replayed session, for test assertions.</summary>
public sealed record SessionReport
{
public int TelemetryFramesEmitted { get; init; }
public int CaptureTriggersEmitted { get; init; }
public int CaptureResultsReceived { get; init; }
public IReadOnlyList<CaptureResult> Results { get; init; } = Array.Empty<CaptureResult>();
/// <summary>Trigger captureSeqs still awaiting a result — must be empty (no silent-failure, SRS-LOG-7).</summary>
public IReadOnlyList<ushort> PendingCaptures { get; init; } = Array.Empty<ushort>();
}
/// <summary>
/// Replays a canned locate session over the IF-LOC contract: emits telemetry at the
/// configured rate, raises capture-triggers at scripted frames, and consumes the App's
/// capture-results — correlating each result to its trigger by captureSeq. Built purely
/// from the frozen data dictionary so App development is unblocked without firmware
/// (Risk R-3).
/// </summary>
public sealed class LocatorSimulator
{
private readonly LoopbackLink _link;
private ushort _seq;
private ushort _captureSeq;
private readonly HashSet<ushort> _pending = new();
private readonly List<CaptureResult> _results = new();
public LocatorSimulator(LoopbackLink link)
{
_link = link;
_link.ToLocator += OnAppFrame;
}
private void OnAppFrame(byte[] frame)
{
if (frame.Length < IfLoc.HeaderLen) return; // §14 ignore malformed
if (Frames.PeekType(frame) != MessageType.CaptureResult) return;
var result = CaptureResult.DecodeFrame(frame);
_results.Add(result);
_pending.Remove(result.CaptureSeq);
}
/// <summary>
/// Emits <paramref name="frames"/> telemetry frames, raising a capture-trigger at each
/// index in <paramref name="captureAtFrames"/>. When <paramref name="realTime"/> is true,
/// paces at <paramref name="rateHz"/> for a live demo; otherwise emits as fast as possible
/// for deterministic tests. Returns once all frames are emitted (results may still be
/// arriving synchronously on the loopback).
/// </summary>
public async Task<SessionReport> ReplayAsync(
int frames,
IReadOnlySet<int> captureAtFrames,
double rateHz = 5.0,
bool realTime = false,
CancellationToken ct = default)
{
int triggers = 0;
uint uptime = 0;
int stepMs = (int)Math.Round(1000.0 / rateHz);
for (int i = 0; i < frames; i++)
{
ct.ThrowIfCancellationRequested();
var tele = BuildTelemetry(i, uptime);
_link.PublishToApp(tele.EncodeFrame(_seq++));
if (captureAtFrames.Contains(i))
{
var trigger = new CaptureTrigger
{
CaptureSeq = ++_captureSeq, // locator-initiated: high bit clear (§5.1)
TriggerType = TriggerType.ButtonSingle,
Snapshot = tele,
};
_pending.Add(trigger.CaptureSeq);
triggers++;
_link.PublishToApp(trigger.EncodeFrame(_seq++));
}
uptime += (uint)stepMs;
if (realTime) await Task.Delay(stepMs, ct).ConfigureAwait(false);
}
return new SessionReport
{
TelemetryFramesEmitted = frames,
CaptureTriggersEmitted = triggers,
CaptureResultsReceived = _results.Count,
Results = _results.ToArray(),
PendingCaptures = _pending.ToArray(),
};
}
/// <summary>
/// A deterministic, physically-plausible canned telemetry frame for step <paramref name="i"/>.
/// Sweeps depth, current, and signal across their ranges and exercises a warning flag
/// and a no-depth sentinel so consumers see the full dictionary.
/// </summary>
public static Telemetry BuildTelemetry(int i, uint uptimeMs)
{
bool noDepth = i % 20 == 19; // periodically drop depth (sentinel path)
var warn = WarningFlags.None;
if (i % 25 == 12) warn |= WarningFlags.Shallow;
if (i % 40 == 30) warn |= WarningFlags.Overload;
return new Telemetry
{
LocatorUptimeMs = uptimeMs,
DepthMeters = noDepth ? null : 0.50 + 0.01 * (i % 200), // 0.50 → 2.49 m
SignalCurrentMa = (ushort)(50 + (i % 300)),
FrequencyHz = 32768,
Mode = LocateMode.Twin,
SignalType = SignalType.Active,
GainDb = (byte)(40 + (i % 60)),
SignalLevel = (byte)(60 + (i % 40)),
DistortionQualityPct = (byte)(100 - (i % 15)),
SignalDirection = 1,
CompassAngleDeg = (byte)(i % 181),
GuidanceOffset = (short)(((i % 41) - 20) * 25), // −500 → +500, negative = left
Warnings = warn,
Utility = UtilityType.Water,
BatteryPercent = (byte)Math.Max(5, 100 - i / 10),
Status = StatusFlags.Locating,
};
}
}

150
tests/IfLoc.Sim/Protocol.cs Normal file
View File

@@ -0,0 +1,150 @@
namespace IfLoc.Sim;
// Reference constants for the frozen IF-LOC v1.0 contract.
// Source of truth: meta/contracts/ble-device-interface.md. Keep the two in lockstep;
// enum values and message-type ids are append-only once frozen.
/// <summary>Wire message-type ids (frame header byte 1).</summary>
public enum MessageType : byte
{
Telemetry = 0x01,
CaptureTrigger = 0x02,
CaptureResult = 0x03,
Alert = 0x04,
Ack = 0x05,
CmdRequestSnapshot = 0x10,
CmdSetFrequency = 0x11,
CmdSetMode = 0x12,
CmdSetTelemetryRate = 0x13,
CmdTimeSync = 0x14,
CmdSetUtility = 0x15,
OtaBegin = 0x20,
OtaData = 0x21,
OtaEnd = 0x22,
UsageLogRequest = 0x30,
UsageLogRecord = 0x31,
UsageLogEnd = 0x32,
ClaimChallenge = 0x40,
ClaimAssertion = 0x41,
ClaimCertReq = 0x42,
ClaimCert = 0x43,
}
/// <summary>§4.1 locateMode.</summary>
public enum LocateMode : byte
{
Single = 0, Twin = 1, Null = 2, Sweep = 3, TwinSweep = 4, Omni = 5, TwinOmni = 6,
NotAvailable = 0xFF,
}
/// <summary>§4.2 signalType.</summary>
public enum SignalType : byte
{
Active = 0, LineDropActive = 1, Power = 2, GroupedPower = 3, Cathodic = 4,
Sonde = 5, Radio = 6, FaultFind = 7, NotAvailable = 0xFF,
}
/// <summary>§4.4 utilityType (APWA-aligned).</summary>
public enum UtilityType : byte
{
None = 0, Gas = 1, Power = 2, Communications = 3, Water = 4, Sewer = 5, Fiber = 6,
Other = 7, NotAvailable = 0xFF,
}
/// <summary>§4.3 warningFlags bitfield.</summary>
[Flags]
public enum WarningFlags : ushort
{
None = 0,
Shallow = 1 << 0,
Overload = 1 << 1,
SwingTilt = 1 << 2,
DepthInvalid = 1 << 3,
CurrentInvalid = 1 << 4,
OutOfRange = 1 << 5,
DistortionHigh = 1 << 6,
LowBattery = 1 << 7,
}
/// <summary>§4.5 statusFlags bitfield.</summary>
[Flags]
public enum StatusFlags : byte
{
None = 0,
Locating = 1 << 0,
MenuActive = 1 << 1,
TimeSynced = 1 << 2,
DepthModeAuto = 1 << 3,
}
/// <summary>§5.1 triggerType.</summary>
public enum TriggerType : byte
{
ButtonSingle = 0, ButtonHold = 1, OffsetRequest = 2, AppInitiated = 3,
}
/// <summary>§5.2 outcome — the deterministic capture outcome (SRS-LOG-7).</summary>
public enum CaptureOutcome : byte
{
Stored = 0, StoredFlagged = 1, Rejected = 2,
}
/// <summary>§5.4 reasonCode / gateStatus.</summary>
public enum ReasonCode : byte
{
Ok = 0,
FixTypeTooLow = 1,
HrmsExceeded = 2,
VrmsExceeded = 3,
CorrectionAgeExceeded = 4,
NoActiveTicket = 5,
ImuCalibrationInvalid = 6,
HeadingConfidenceLow = 7,
BufferFull = 8,
NoPosition = 9,
WaiverRequired = 10,
Other = 255,
}
/// <summary>§5.2 fixType (GGA-quality mapping; 3 reserved).</summary>
public enum FixType : byte
{
NoFix = 0, Autonomous = 1, Dgps = 2, RtkFixed = 4, RtkFloat = 5,
}
/// <summary>Frozen wire constants and sentinels.</summary>
public static class IfLoc
{
public const byte FrameVersion = 0x01;
// Fixed frame lengths (Appendix A).
public const int HeaderLen = 4;
public const int TelemetryFrameLen = 32;
public const int TelemetryPayloadLen = 28; // offsets 4..31
public const int CaptureTriggerFrameLen = 36;
public const int CaptureResultFrameLen = 52;
// Sentinels (§1).
public const short DepthNoValue = unchecked((short)0x8000);
public const ushort CurrentInvalid = 0xFFFF;
public const uint FrequencyNa = 0xFFFFFFFF;
public const short GuidanceNa = unchecked((short)0x8000);
public const int PositionNoValue = unchecked((int)0x80000000);
public const ushort RmsUnknown = 0xFFFF;
// GATT (§2) — recommended UUIDs the App builds against.
public const string BaseUuidFormat = "A9E1{0:X4}-1B4C-4F9A-9B7E-2D6F0C3A5E11";
public static string LocateServiceUuid => string.Format(BaseUuidFormat, 0x0001);
public static string ProtocolInfoUuid => string.Format(BaseUuidFormat, 0x0002);
public static string TelemetryUuid => string.Format(BaseUuidFormat, 0x0003);
public static string EventUuid => string.Format(BaseUuidFormat, 0x0004);
public static string CommandUuid => string.Format(BaseUuidFormat, 0x0005);
public static string CaptureResultUuid => string.Format(BaseUuidFormat, 0x0006);
public static string LinkStateUuid => string.Format(BaseUuidFormat, 0x0007);
public static string BulkOtaUuid => string.Format(BaseUuidFormat, 0x0008);
public static string ClaimUuid => string.Format(BaseUuidFormat, 0x0009);
}