SpotBridge

SpotBridge is an independent, experimental implementation of the USB protocol used to read records from a Spot Vital Signs LXi. It includes a Swift protocol library, a macOS reader and CSV exporter, an optional local-network bridge, and an iOS companion application.

Safety And Accuracy

This software is provided as-is and makes no claim of accuracy, completeness, reliability, compatibility, or fitness for medical or clinical use. It is not a medical device and must not be used for diagnosis, treatment, monitoring, or clinical decision-making.

Before using or retaining decoded data, reconcile every value, unit, timestamp, and patient context with the source device display and any applicable source record. See DISCLAIMER.md.

Implemented Behavior

For the physically tested device and firmware, the protocol library implements:

• WACP framing with CRC-16/MCRF4XX validation
• Connection registration, keepalive, session, and disconnect exchanges
• Stored-session boundary and indexed-record requests
• Length-prefixed DMOIB object traversal with per-object CRC validation
• Capture-specific decoding for NIBP, temperature, SpO2, pulse, and timestamps
• Buffered reads for USB transfers that split or combine WACP frames

The application layer provides:

• Current-record and stored-history retrieval
• CSV export on macOS
• HealthKit conversion and stable synchronization identifiers on iOS
• An optional Bonjour bridge for the iOS companion application

Architecture

macOS:       libusb transport ─┐
portable:    libusb transport ─┴─> SpotTransport -> WACP/DMOIB -> VitalRecord

macOS app -> optional Bonjour JSON/TCP bridge -> iOS companion -> HealthKit

The protocol and record-decoding targets do not depend on libusb, Network.framework, or HealthKit. Platform targets provide those adapters.

Repository Targets

Target	Purpose	Status
SpotBridge	Protocol framing, sessions, parsing, decoded value types, CSV serialization	Tested with synthetic fixtures and physical hardware
SpotBridgeHealthKit	HealthKit sample construction	Unit tested
SpotBridgeMac	macOS UI, bundled libusb transport, CSV export, optional Bonjour server	Physically tested on arm64 macOS
SpotBridgeRemoteApp	iOS Bonjour client and HealthKit import	Requires App Store signing/configuration
SpotBridgeDaemon	Headless macOS libusb/Bonjour bridge	Physically tested on arm64 macOS

The libusb transport and protocol core are candidates for a Linux or Raspberry Pi port, but this repository does not yet contain or verify a Linux build.

Data Model

DMOIB records are traversed as length-prefixed objects rather than located by matching complete captured byte strings:

[recordSize:u32 BE]
[classID:u32 BE]
[payloadSize:u16 BE]
[version:u16 BE]
[flags:u8]
[staticLength:u16 BE]
[staticData]
[CRC-16/MCRF4XX:u16 BE]

Observed class families on the tested device are:

• 0x0005: NIBP
• 0x0003: temperature
• 0x0004: SpO2

Object boundaries and checksums are validated. Field offsets and supported payload layouts remain capture-derived and device-specific; unknown versions must not be assumed compatible.

Network Security

The Bonjour bridge is off by default. Enabling it persists that preference and starts the service on later launches.

The Mac app can optionally register itself in Login Items from Settings so it starts automatically when the user signs in and remains available from its menu-bar item.

Bridge traffic requires TLS 1.3. The remote app verifies a self-signed bridge key pinned by a one-time QR pairing code, then authenticates every request with an individually revocable random credential. Private keys and client credentials are stored in the platform Keychain. Bonjour remains an untrusted discovery mechanism: it can reveal that the service exists and can be spoofed or disrupted, but it cannot bypass key pinning or client authorization.

Pairing codes expire after five minutes and authorize one remote. Treat a visible or copied pairing code as a temporary credential. The Mac app and menu-bar daemon maintain separate bridge identities and paired-client lists.

Prerequisites

• macOS 14 or later
• Xcode 26 or a compatible Swift 6 toolchain
• XcodeGen
• An arm64 Mac for the currently configured libusb build
• Network access on the first build to download libusb 1.0.30 and the pinned Apple Swift Crypto and Certificates packages

The libusb archive is pinned by version and SHA-256. It is built from upstream source and embedded in the Mac products; no Homebrew runtime dependency is used. libusb is the current USB backend, not a protocol requirement; a conforming SpotTransport implementation can replace it.

Build And Test

Run the portable test suite:

swift test

Generate the Xcode project:

xcodegen generate

Build the macOS application:

xcodebuild -project SpotBridgeApp.xcodeproj -scheme SpotBridgeMac \
  -destination 'platform=macOS' build

Build the iOS companion application:

xcodebuild -project SpotBridgeApp.xcodeproj -scheme SpotBridgeRemoteApp \
  -destination 'generic/platform=iOS' build

Build the headless macOS bridge:

xcodebuild -project SpotBridgeApp.xcodeproj -scheme SpotBridgeDaemon \
  -destination 'platform=macOS' -derivedDataPath build/derived-daemon build

For physical integration testing, enable the bridge, generate a one-time pairing code, pair SpotBridge Remote, and exercise status, current-record, and bounded-history requests from the remote app. There is intentionally no plaintext or unauthenticated integration-test mode.

Direct Distribution And Notarization

The macOS application uses libusb and does not require a system extension. Configure a Developer ID signing identity and store notarytool credentials in a keychain profile, then run:

export NOTARYTOOL_PROFILE=spotbridge-notary
Scripts/notarize-mac.sh

The script archives with hardened runtime, submits the app for notarization, staples the result, and creates build/SpotBridgeMac.zip. The distributable ZIP also contains the corresponding libusb source archive, LGPL text, notice, and build script.

License And Trademarks

SpotBridge is available under the MIT License. See LICENSE. libusb is licensed separately under LGPL-2.1-or-later; see Vendor/libusb/COPYING and NOTICE. The Mac products dynamically link libusb so recipients can rebuild or replace that library under the LGPL. Apple Swift Crypto, Swift Certificates, and Swift ASN.1 are licensed under Apache-2.0; see NOTICE and the license files in their resolved Swift package source distributions.

No claim is made to the exclusive right to use "Welch Allyn," "Hillrom," "Baxter," "Spot Vital Signs," or "Connex" apart from the marks as shown. These names are trademarks of their respective owners. This project is not affiliated with, endorsed by, or supported by those owners or their affiliates.