---
name: wearable-reader
description: Read your own Bluetooth wearable (heart-rate strap, fitness band, ring) from a Mac without the vendor's app, then keep the data in a local database with a background collector, a localhost dashboard and encrypted backups. Use this whenever someone wants to get live heart rate or stored history off a device they own, find a wearable over Bluetooth LE, work out what a device sends, pull their own history through the vendor's official API, or run a personal health-data service on their own machine. The worked example is a WHOOP 4.0.
---

# Wearable reader, end to end

A recipe for reading a wearable you own, from first scan to a service that runs by itself. It was written from one working session on a WHOOP 4.0 and a MacBook. The order matters: each step is the cheapest thing that can tell you where the data is.

Ground rules before anything else:

- Only the user's own device and the user's own account. Ask if it is not clear.
- History that lives in the vendor's cloud comes through the vendor's official API with OAuth. Do not scrape or sidestep it.
- This is not a medical device and the output is not a diagnosis. Say so in the README and in the final message.
- Stay away from commands that write to the device's firmware, erase its storage or reboot it. Reading is enough.

## Step 1: Look at what is plugged in

If the device or its charger connects by USB, check what the computer sees (`ioreg -p IOUSB -l`, `ls /dev/cu.*`). A USB-to-serial chip (FTDI, CP210x) means a serial port. Listen passively across common baud rates (9600 to 921600) for a few seconds each and log raw bytes and hex.

Expect little. On the WHOOP the port belongs to the battery pack and sends a 6-byte frame every 15 seconds at 19200 baud. It is not a console. Give this step ten minutes, write down what you saw, and move on.

## Step 2: Find the device over Bluetooth LE

Use `bleak` in a Python venv. Scan for 10 to 15 seconds and print, per device: name, address, signal strength, advertised service UUIDs and manufacturer data.

- **Do not trust the name.** A phone and a strap can advertise the same name. In the session two devices were both called `TMS`: one was an iPhone.
- **Trust the service UUID.** Vendors use their own 128-bit base. WHOOP 4.0 advertises `61080001-8d6d-82b8-614a-1c8cb0f8dcc6`.
- **Confirm by reading.** Connect and read Device Information (`0x180A`): manufacturer name and model. `Apple Inc.` means you have the wrong device.
- A process may lack Bluetooth permission on macOS. If the scan returns nothing at all, say that, do not report "no device".

## Step 3: Map every service

Connect and list every service and characteristic with its properties (read, write, notify). Read everything readable. Subscribe to everything that notifies and log 15 seconds of it.

What to look for:

| You see                                                   | It means                                                                  |
| --------------------------------------------------------- | ------------------------------------------------------------------------- |
| Heart Rate service `0x180D`, characteristic `0x2A37`      | Standard live heart rate. Any app can read it once the device broadcasts. |
| Battery `0x180F` / `0x2A19`                               | Battery percentage, one byte.                                             |
| One vendor characteristic with write, several with notify | A command channel and its answer channels. This is the vendor protocol.   |

A silent device is normal. Most straps send nothing until they are worn or told to start.

## Step 4: Read what others already worked out

Search for the service UUID and the device name plus "BLE protocol". For popular hardware someone has usually published the frame format. Read the code, not the README, and prefer projects whose tests use packets from real hardware.

Then check it yourself. Take captured frames from those projects and recompute every checksum. In the session two write-ups described a custom CRC. Both were wrong: the frames use plain CRC-8 over the length and standard CRC-32 over the payload, which matched 15 of 17 captured frames (the other two were copy errors).

WHOOP 4.0 frame, for reference:

```
[0]     0xAA
[1:3]   length, uint16 LE = len(inner) + 4
[3]     CRC-8 (poly 0x07) over the two length bytes
[4:n]   inner = [type][seq][command][data...]
[-4:]   CRC-32 (binascii.crc32) over inner, uint32 LE
```

Write a frame builder, and test it byte for byte against captured frames before sending anything.

## Step 5: Get one live number

Send the smallest documented command that turns on a stream, and watch all notify channels. On the WHOOP, command `0x0E` with data `01` turns on the standard heart-rate broadcast.

Parse `0x2A37` properly:

- byte 0 is flags. Bit 0 set means heart rate is 16-bit. Bit 4 set means RR intervals follow.
- RR intervals are uint16 in units of 1/1024 s. Multiply by 1000/1024 for milliseconds.

Stop here and show the user the number. A real reading from their own wrist is the checkpoint for everything after it.

## Step 6: Pull what is stored on the device

Query battery and firmware version first, they are harmless and prove responses decode. Then request the history. Rules that matter:

- **Save every raw frame before you parse it.** Decoders improve later, lost frames do not come back.
- **Commit to disk before you acknowledge.** Many devices free a batch once it is acknowledged. A crash between the two loses data for good.
- **Use an idle timeout,** not a fixed one. A long backlog takes longer than you guess.
- **Resync on bad bytes.** Skip to the next start byte and drop frames whose checksum fails.
- **Label only what you can verify.** Keep unknown fields raw. Firmware log packets are often plain ASCII and tell you the chips, the battery level and why data is missing.
- **Warn about the official app.** Draining and acknowledging may leave nothing for the vendor's app to upload. If the user still uses that app, drain without acknowledging or not at all.

## Step 7: Get the scored history through the official API

Scores such as recovery, strain and sleep stages are computed in the vendor's cloud. They are not on the device.

1. The user creates a developer app in the vendor's portal. Redirect URL `http://localhost:8765/callback`, read-only scopes, plus offline access for a refresh token.
2. The user puts the client ID and secret into a gitignored `.env` themselves. Never ask for them in chat. If they paste them anyway, tell them to rotate the secret.
3. Run the OAuth code flow with a tiny local HTTP server on that port. Store tokens in a file with mode 600, written to a temp file and renamed, with a lock so two syncs cannot both spend a rotating refresh token.
4. Page through every endpoint into the database. Keep a watermark per endpoint, and re-fetch the last 7 days each run so late scores are picked up.

## Step 8: Make it a service

- **One SQLite database** with tables for API records, live heart rate, raw frames and decoded device logs.
- **A collector on a schedule** (launchd, hourly): API sync, device drain if in range, decode, backup. Check it works when started by launchd, since Bluetooth permission differs there.
- **A live streamer** that holds the connection, reconnects, and takes a lock file so the collector does not fight it.
- **A dashboard on localhost** kept up by launchd. Bundle the chart library locally. Show the date of the newest data so stale data is obvious.
- **Backups:** timestamped snapshots, encrypted (AES-256, key in a mode-600 file), keep the last 30, prune every file of a pruned snapshot. Tell the user to store the key somewhere safe.
- **Keep health data out of git:** ignore the database, backups, exports, tokens, keys and logs before the first commit.
- **Put runtime data in a stable place** such as `~/Library/Application Support/<name>/`, not in a temporary checkout.

## Step 9: Get a second read

Ask a different session or model to review the service without your notes. Ask it one question: where can this lose data? Fix those first.

## What to tell the user at the end

- What works, with one real reading as proof.
- Which numbers come from the device and which from the vendor's API.
- What is running in the background and how to stop it.
- What you could not verify, and which secrets they should rotate.
- That this is for personal tracking and is no substitute for a doctor.
