My Homepage Has a Pulse

There is a small red heart on my homepage now that beats. The number next to it is my actual heart rate, and the heart pulses at that frequency: 48 bpm means one thump every 1.25 seconds, 80 bpm means one every 0.75. I wrote this up because I wanted to, and because the design ended up containing more interesting decisions than I expected. The watch I wear a Garmin Descent Mk3i , 43 mm, carbon gray DLC titanium. I bought it as my primary dive computer, alongside my Shearwater Perdix 2, because you need redundancy in technical diving and overhead environments like caves and wrecks. If a computer dies at 75 m inside a cave, you can’t just surface and charge it. Cave divers have backups for their backups. Since April 2025 it has been on 400+ dives with me, including to 100 m. I don’t take it off unless I’m charging it or showering. Between dives it tracks my heart rate, sleep score, HRV, steps, calories, and a dozen other vitals around the clock, and syncs everything to the Garmin Connect app on my Pixel 9 Pro. My gym and streetlifting sessions get logged on it too. Which means Garmin already holds a continuous, granular physiological record of my life. I just needed the data out of Garmin and onto my homepage. A more personal “online” status indicator Old messaging apps had the green dot. Facebook Messenger, Gchat before it: a small indicator that said this person is here right now. I remember seeing it in HexChat in 2012, before I moved to Irssi. I wanted that for this site, except the green dot always felt like a statement about a socket instead of a person. A heartbeat is the least abstract “online” there is. It’s the difference between “his browser has a connection open” and “he is alive, and here is the proof”. In the end it’s just a number on a page, I get that. But it is my number, from my chest, and that makes it the most personal thing on the site. It might be a little cringe to a lot of you, but I like the idea :P. The longer-term goal, when I get around to it, is a section of this site that shows a granular ledger of my life made public: workouts, sleep, HRV, calories burned, steps walked, etc. I understand what that leaks. All-day heart rate reveals when I sleep and wake. Gaps and timezone shifts reveal travel. A resting heart rate that jumps 8 bpm flags illness, stress, or last night’s drinks. HRV trends are a decent proxy for mental state, and a regular gym schedule advertises exactly when I am not home. I have sat with all of that and decided I am fine with it. I consent to it, and if you have a problem with it, that is your problem, not mine ¯\ (ツ) /¯. Surely someone has done this. Yup, they have. My first thought was that this must already exist, and I was right. Twitch streamers have been putting live heart rate on screen for years through services like Pulsoid and HypeRate , and both support Garmin watches. They work by putting the wearable into its broadcast heart rate mode, where it streams over BLE/ANT+ to a phone app that relays the number to their servers. Seemed promising at first, but it was a deadend for me. Garmin’s manuals warn that broadcasting decreases battery life, and this watch is my dive computer. I’m not going to trade dive-day battery for a website widget. And broadcast is a mode you switch on and stay in range of. Seems like too much of a chore to me. Plus, I like that I charge the watch once a week and it lasts for 10 days. I don’t want to charge it every night just to keep a widget alive. The browser itself can speak Bluetooth, which briefly seemed promising. The Web Bluetooth API can read the standard heart rate GATT service directly from a nearby device. Still a no-go because it connects the visitor’s browser to a device near the visitor. It would only ever work on my own machine, in a Chromium browser, with the watch in the broadcast mode. Surely then there is a real API. There is: Garmin’s Health API serves this data, BUT access is gated behind a business application and review. It is built for companies integrating wearables into products. What about a guy who wants a heart on his homepage? Fahhhh (╯’□’)╯︵ ┻━┻. At this point I did what I should have done first and searched GitHub and Reddit. Two projects kept surfacing in Reddit threads. GarminDB downloads your entire Garmin history into a local SQLite database and gives you analysis and plots on top. Cool, but wrong for this. An archive with a schema seems like overkill… I probably just want one day of heart rate as JSON every morning. python-garminconnect is the right tool because it is a Python client that speaks the same private API the Garmin Connect app uses. It lets you log in the way the app does and calls the same endpoints as the app. It exposes essentially everything I can see on my phone, which incidentally solves the someday-in-the-future-project problem, because workouts, sleep, and HRV are all reachable from the same client. Nice, thank you @cyberjunky ! Why not live? Live was never actually on the table, but I didn’t know that at the start. The watch does not stream anywhere by default: all-day heart rate accumulates on the wrist and reaches Garmin’s servers in batches, whenever the watch↔phone sync happens. Without broadcast mode there is no feed to subscribe to. And my site is static, Astro built once and served as files from GitHub Pages. There’s no server to hold a websocket open, so even if the watch did stream, I didn’t figure out a way to relay it to visitors. The only option is to fetch the data once a day and replay it. So the compromise is that the widget replays yesterday. When you load my homepage at 14:32 your time, you see my heart rate at 14:32 yesterday, interpolated from real samples. The “live” label is a white lie, but it’s mine to tell. But at least the lie is precise: the offset is exactly 24 hours, the data is real, and nothing is made up beyond drawing straight lines between measurements. A one-time login (for a year) python-garminconnect logs in with an email and password, but what it hands back is a pair of OAuth tokens. The OAuth1 token is the long-lived one, good for about a year. The OAuth2 token is what actually authorizes API calls, and it expires after a few hours. The library signs every request with the OAuth2 token, and whenever that one expires, it uses the OAuth1 token to generate a fresh one behind the scenes (my limited understanding). So my creds get typed once on my laptop, and never go anywhere near CI. CI only holds tokens which refresh themselves for a year. The one-time part looks like this: python3 -m venv .venv source .venv/bin/activate.fish pip3 install garminconnect python3 scripts/garmin_login.py garmin_login.py is a short script that prompts for credentials and handles the token plumbing. The interesting part: garmin = Garmin( email = email, password = password, return_on_mfa = True ) status, client_state = garmin.login() if status == "needs_mfa" : mfa = input ( "MFA code: " ) garmin.resume_login(client_state, mfa) garmin.client.dump( str (tokendir)) # token files -> ~/.garminconnect b64_path.write_text(garmin.client.dumps()) # same tokens, one base64 string return_on_mfa=True makes the library pause and hand control back instead of dying when Garmin asks for a two-factor code, and resume_login finishes the handshake with whatever I type. At the end the tokens land in two forms: as files in ~/.garminconnect for local runs, and as a single base64 blob ( client.dumps() serializes the whole token store into one string) that becomes a GitHub Actions secret: gh secret set GARMINTOKENS_BASE64 --repo snehankekre/snehankekre.github.io < ~/.garminconnect.b64 I had problems with the login. Garmin rate-limited my IP mid-attempt, even though I rotated through Mullvad’s servers. The library tries a chain of login strategies, and the first two ( mobile+cffi , then mobile+requests ) both came back with a 429 (“IP rate limited by Garmin”). Thankfully the library’s fallback strategy further down the chain…