@peerbits/device-normalizer

Normalizes raw device and health-platform payloads into canonical vital readings for fhir-observation-generator.

Category: RPM — Device & Observation Utilities · License: Apache-2.0 · Status: v2 development

1. What problem does this solve?

Remote Patient Monitoring (RPM) applications receive vital signs in disparate formats: raw Bluetooth SIG GATT byte arrays from medical peripherals, exported Apple HealthKit sample JSONs, or ad-hoc sensor JSON payloads. Transforming these diverse sources into a standard representation requires error-prone bit-shifting, IEEE-11073 SFLOAT parsing, unit standardizations, and validation.

@peerbits/device-normalizer decodes and standardizes pre-retrieved payloads from publicly documented standards into canonical DeviceReading structures that seamlessly feed @peerbits/fhir-observation-generator to produce compliant FHIR R4 Observations.

Scope note: Normalizes already-received payloads from publicly documented sources only. It does not connect to devices or vendor clouds. See Supported Formats.

2. Features

• Bluetooth SIG GATT Profile Decoders: Full IEEE-11073 16-bit SFLOAT & 32-bit FLOAT decoders for:
  • Blood Pressure Profile (0x2A35): Systolic, Diastolic, MAP, in-band unit flag (mmHg/kPa), pulse rate, user ID, status.
  • Health Thermometer Profile (0x2A1C): Celsius & Fahrenheit flag, 7-byte timestamp, temperature type site.
  • Pulse Oximeter Profile (0x2A5E / 0x2A5F): SpO2 (%) and Pulse Rate (bpm).
  • Weight Scale Profile (0x2A98): SI (kg) / Imperial (lbs) resolutions, BMI, height.
  • Glucose Profile (0x2A18): Sequence number, timestamp offset, mg/dL & mmol/L units, sample type/location.
  • CGM Profile (0x2AA7): Session-relative records, trend, quality, status, and E2E CRC.
• Platform & aggregator adapters: Apple HealthKit, Health Connect, Junction/Vital, Tenovi, Validic, Withings, iHealth, and Dexcom EGV.
• Generic JSON Fallback: Standardizes documented flat JSON vital readings.
• Automatic Detection: process(payload) selects a supported adapter from structural fingerprints.
• Health Connect & Junction: Handles core Health Connect records and Junction timeseries webhooks.
• Reliable Missing Data Rules: Never invents timestamps, patient identifiers, or measurement values.
• Structural Self-Check: Verifies normalized readings strictly satisfy @peerbits/fhir-observation-generator schema requirements before pipeline handoff.
• Zero Runtime Dependencies: Pure TypeScript with no external network or BLE stack requirements.

3. Installation

npm install @peerbits/device-normalizer

4. Demo and Quick Start

Peerbits HealthTech - Device Normalizer Demo

import { process } from "@peerbits/device-normalizer";

// 1. Raw Bluetooth SIG GATT characteristic bytes (0x2A35 Blood Pressure)
const gattPayload = {
  bytes: "00 78 00 50 00 5D 00", // 120/80 mmHg with MAP 93 mmHg
  characteristicUuid: "0x2A35",
  timestamp: "2026-08-17T12:00:00Z",
  patientRef: "Patient/p-12345",
  deviceId: "Device/omron-evolv-001",
};

const reading = process(gattPayload);

console.log(reading);
// {
//   deviceType: "blood-pressure",
//   value: { systolic: 120, diastolic: 80 },
//   unit: "mm[Hg]",
//   timestamp: "2026-08-17T12:00:00.000Z",
//   patientRef: "Patient/p-12345",
//   deviceId: "Device/omron-evolv-001",
//   source: { provider: "bluetooth-sig", format: "ble-gatt-blood-pressure", ... },
//   metadata: { bleProfile: "0x2A35", meanArterialPressure: 93 }
// }

5. End-to-End Pipeline

[ Medical BLE Device / HealthKit ]
                 │
                 ▼ (Pre-retrieved raw payload)
    ┌──────────────────────────┐
    │ @peerbits/device-normalizer │ ──> Canonical DeviceReading
    └──────────────────────────┘
                 │
                 ▼
 ┌───────────────────────────────────────┐
 │ @peerbits/fhir-observation-generator │ ──> Valid FHIR R4 Observation Resource
 └───────────────────────────────────────┘

6. Architecture

src/
├── adapters/
│   ├── ble-gatt/
│   │   ├── sfloat.ts          # IEEE-11073 16-bit SFLOAT & 32-bit FLOAT decoding
│   │   ├── blood-pressure.ts  # 0x2A35 Blood Pressure Profile
│   │   ├── thermometer.ts     # 0x2A1C Health Thermometer Profile
│   │   ├── pulse-oximeter.ts  # 0x2A5E/0x2A5F Pulse Oximeter Profile
│   │   ├── weight-scale.ts    # 0x2A98 Weight Scale Profile
│   │   └── glucose.ts         # 0x2A18 Glucose Measurement Profile
│   ├── healthkit.ts           # Apple HealthKit samples + BP correlation
│   ├── health-connect.ts      # Google Health Connect records
│   ├── junction.ts            # Junction/Vital events
│   ├── tenovi.ts              # Tenovi HWI webhooks
│   ├── validic.ts             # Validic measurements
│   ├── withings.ts            # Withings getmeas responses
│   ├── ihealth.ts             # iHealth BP webhooks
│   ├── dexcom.ts              # Dexcom EGV responses
│   └── generic-json.ts        # Flat JSON fallback
├── registry.ts                # Adapter registry and dispatcher
├── validate.ts                # Structural self-check for fhir-observation-generator
├── types.ts                   # Core TypeScript types (DeviceReading local copy)
└── index.ts                   # Library entry point

7. Examples

See /docs/examples for:

• BLE GATT to FHIR Observation Pipeline
• Apple HealthKit to FHIR Observation Pipeline

8. Roadmap

• [x] 7 Core Bluetooth SIG GATT Health Profiles
• [x] Apple HealthKit 7 vital sample types & BP correlation
• [x] Generic JSON fallback adapter
• [x] Publicly documented platform, aggregator, and OEM payload adapters
• [x] Structural self-check validator

9. Contributing

See CONTRIBUTING.md.

10. License

Apache License 2.0 — see LICENSE.

11. About Peerbits

device-normalizer is part of the Peerbits HealthTech Open Source initiative — reusable engineering components extracted from our healthcare technology work. This repository contains generalized, reusable logic only; it is not tied to any specific client engagement or commercial product.