Bluetooth devices

Slug bluetooth. Heart rate straps, blood pressure cuffs, scales, glucose meters, thermometers and pulse oximeters that speak the standard Bluetooth health profiles send their readings straight to your own server: no vendor account, no partner program, no phone in the middle.

The clients never decode: each value goes up as the bytes the device sent, with the time it arrived, and the server decodes it. The raw store keeps the bytes, so a decoder fix re-maps stored data.

1. DevicesCopy Anchor Link

A device works when it implements one of these Bluetooth SIG services. Vendor apps and proprietary protocols are not used.

ohs-bridge scan lists the nearby devices that advertise one of these services. Garmin, COROS and other watches also sync their activities without a phone: mounted over USB, their FIT files go to the activity files route (ohs-bridge files).

Not supported: continuous glucose monitors, fitness machines (FTMS), cycling power and running speed sensors, and devices that only speak a vendor protocol (Withings, Oura, WHOOP, Xiaomi bands). Those reach Open Health Sync through their own connector or a phone store.

2. PairingCopy Anchor Link

Most cuffs and meters need a bond: pair them once with the operating system (System Settings, Bluetooth on macOS; bluetoothctl then pair on Linux; Settings on iOS and Android, or the system prompt the app triggers). Straps, scales and thermometers usually need none.

On a shared scale or cuff, each person holds a user index (often 1 or 2, chosen on the device). Set it on the client (ohs-bridge run --device-user 1, or the SDK's deviceUser) so the other person's readings are not stored in this account.

3. Auth flowCopy Anchor Link

No OAuth and no operator keys: the connector is always on. The client uploads with a user token (ohs_ut_) that has the upload scope, minted by your backend or with POST /v1/users/{id}/tokens. The token cannot read anything back.

4. Rate limitsCopy Anchor Link

Nothing is pulled from a vendor. Uploads share the instance's limit of uploads in flight with the other device routes (503 with Retry-After above it). ohs-bridge and the SDKs queue parts and retry 408, 429, 5xx and network errors with backoff.

5. Backfill and updatesCopy Anchor Link

What the device keeps in memory is the backfill: a cuff or a scale sends its stored readings when it connects, and a glucose meter answers the Record Access Control Point. ohs-bridge and the SDK ask a meter for the records after the last sequence number they stored, and all records the first time. Live values (heart rate, continuous SpO2) are only there while connected.

6. Upload contractCopy Anchor Link

POST /v1/ingest/bluetooth works like the Apple Health upload: a user token with the upload scope, the headers X-OHS-Type (always gatt), X-OHS-Day, X-OHS-Batch and X-OHS-Part, and a gzip NDJSON body of at most 64 MiB. One line per value received:

{"at":"2026-10-16T21:04:05.120+02:00","char":"2a37","value":"1048000433030004","session":"9f2c4e1a7b3d5c60","device":{"name":"Polar H10","manufacturer":"Polar Electro Oy","model":"H10","firmware":"5.0.0"}}

Never send a device address or a serial number: the format has no field for them. Many devices advertise a name that ends in a serial (Polar H10 0A1B2C3D): ohs-bridge and the SDKs drop a last word of at least six hex digits, or four with a letter among them, and the server applies the same rule to what it stores (Edge 1040 is kept). ohs-bridge sends X-OHS-Day as the UTC day of a part's first line, a batch bt1-<install id>-<sequence> and part 0, and keeps each part's bytes until it gets a 200, so a retry is answered duplicate: true.

The part is refused with 400, and nothing is stored, when a line is not a JSON object of this format (a field missing, at without an offset, value not hex), X-OHS-Type is not gatt, or the part holds no line. A value that does not decode (shorter than its flags say) is a failed record of its own line, shown in sync health; the other lines are kept. A characteristic not in the mapping (battery level, a vendor service) is stored and not mapped.

7. MappingCopy Anchor Link

Values are read as the GATT Specification Supplement lays them out (little endian; SFLOAT and FLOAT are the IEEE 11073-20601 16-bit and 32-bit floats, whose NaN, NRes and infinity values give no sample).

• Pulse oximeter status: data for demonstration or testing, measurement unavailable and invalid measurement give no sample; early estimated data and questionable measurement are kept and listed in measurement_status.
• Shared devices: with device_user on the line, a blood pressure, weight or body composition value that carries another user index is not mapped. The "unknown user" index (255) is mapped.
• A body composition measurement split over two packets is mapped packet by packet.
• Glucose specimen interstitial_fluid is coded in FHIR with its own LOINC, as for Dexcom.
• Every sample carries metadata gatt_characteristic, session, clock, utc_offset_minutes, timezone (an Etc/GMT zone when the offset is a whole hour), firmware and device_user when known.

8. TimeCopy Anchor Link

• Heart rate, RR and continuous SpO2 have no time of their own: they are stamped with at. The RR intervals of one notification end at at, the last beat then, each earlier beat at the next one minus the next interval.
• Other measurements may carry the device's clock (a wall time without zone). It is read in the offset of at and used when it is a full date, not before 2000-01-01, not more than 10 minutes after at, and not flagged by the device as unset (pulse oximeter) or faulty (glucose). Otherwise the sample is stamped at. Metadata clock says which: device or received.
• Glucose: the base time plus the time offset field.
• ohs-bridge and the SDKs set the device's clock through the Current Time service when the device allows it, so stored readings carry a right time.

9. Provenance, and other sources of the same readingCopy Anchor Link

• Provider bluetooth. Source slug from the manufacturer, then the device name: polar, garmin, wahoo, omron, withings, beurer, and (A&D), ihealth, nonin, masimo, roche, ascensia, coros, suunto, scosche, decathlon; otherwise bluetooth.
• device is the vendor and model (Polar H10), device_model the model number, source_name the advertised name without a serial-like last word. was_user_entered is false.
• Readings are hashed on user, provider, source, type, time and value. A cuff that sends its memory again on the next connection, or a meter asked for all records, gives the same rows.
• The same reading may also reach the server through a vendor cloud (OMRON, Withings, Polar) or a phone store (Apple Health, Health Connect). Each provider keeps its copy; the merged view (view=merged, the default) shows the best ranked source, in the user's source priorities or the defaults.

10. TestingCopy Anchor Link

go test ./connectors/bluetooth/ runs the mapping tests: byte vectors built from the GATT Specification Supplement layouts with invented readings, for every flag that adds or moves a field, both unit systems, the float special values, device clocks, shared device indexes, glucose control solution and pulse oximeter status bits, and truncated values. test/contract uploads a part to a running server and reads the samples and RR intervals back. No test uses a capture from a person.