{"id":24985880,"url":"https://github.com/samjuk/heartrate-sensor","last_synced_at":"2026-02-12T13:37:02.417Z","repository":{"id":173674026,"uuid":"646948392","full_name":"SamJUK/heartrate-sensor","owner":"SamJUK","description":"BLE Heart Rate Broadcast Receiver","archived":false,"fork":false,"pushed_at":"2025-01-22T06:13:04.000Z","size":865,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-11T22:42:53.881Z","etag":null,"topics":["ble","bluetooth","btle","fitness","garmin","garmin-watch","heart-rate","heartrate","heartrate-analysis","heartrate-monitor","heartratemonitor","twitch","websocket-server","websockets"],"latest_commit_sha":null,"homepage":"https://www.samdjames.uk/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SamJUK.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-05-29T17:59:51.000Z","updated_at":"2024-12-15T17:15:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"9a709b38-c593-48c2-9092-213530830d21","html_url":"https://github.com/SamJUK/heartrate-sensor","commit_stats":null,"previous_names":["samjuk/heartrate-sensor"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/SamJUK/heartrate-sensor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamJUK%2Fheartrate-sensor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamJUK%2Fheartrate-sensor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamJUK%2Fheartrate-sensor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamJUK%2Fheartrate-sensor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SamJUK","download_url":"https://codeload.github.com/SamJUK/heartrate-sensor/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SamJUK%2Fheartrate-sensor/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29367302,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T08:51:36.827Z","status":"ssl_error","status_checked_at":"2026-02-12T08:51:26.849Z","response_time":55,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ble","bluetooth","btle","fitness","garmin","garmin-watch","heart-rate","heartrate","heartrate-analysis","heartrate-monitor","heartratemonitor","twitch","websocket-server","websockets"],"created_at":"2025-02-04T10:59:22.662Z","updated_at":"2026-02-12T13:37:02.402Z","avatar_url":"https://github.com/SamJUK.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HR Sensor\n\nA Monorepo of a BLE Heart Rate Broadcast Receiver. Containing isolated library code, and two interfaces in the form of a CLI tool and a websocket server for further integration into web applications.\n\n## CLI Tool\nThe CLI tooling offers the ability to identify nearby devices, and inspect what servers / characteristics they expose. It can also monitor the Heartrate and expose that data via multiple outputs, such as STDOUT or via FILE.\nThe FILE output, can then be read in as a stream to software such as OBS to provide realtime HR tracking overlays onto Live Video.\n\n![CLI Tooling Screenshot](images/cli.png)\n\n#### Example Usage\n```shell\n# Scan nearby discoverable devices, and list of the found device name \u0026 device address\npython src/cli.py scan\n\n# Monitor Heart Rate broadcasted from a specific device\npython src/cli.py monitor -d \u003cDEVICE_ADDR\u003e\n\n# Monitor Heart Rate broadcasted from a specific device, and write to file (for use by other programs)\npython src/cli.py monitor -d \u003cDEVICE_ADDR\u003e -o file\n\n# (DEV) List out services/characteristics of a device\npython src/cli.py describe -d \u003cDEVICE_ADDR\u003e\n```\n\n## Websocket Server\nThe websocket server, allows for interacting with the BLE devices from web applications. Providing much richer user experiences, and removes the locality bottleneck of BLE. Users across the world, can issue commands or monitor data sent out by the device.\n\n![Websocket Server](images/websocket.png)\n\n#### Websocket CLI Interface\nThe websocket server interface is fairly simple, it exposes 2 parameters:\n\nPurpose | Parameter | Short Flag | Data Type | Default\n--- | --- | --- | --- | ---\nHost the server will listen on | `--host` | `-H` | String | `0.0.0.0`\nPort the server will listen on | `--port` | `-P` | Int | `8765`\n\n\n#### Commands To The Websocket Server\nCommand | Example Return Structure | Description\n--- | --- | ---\n`scan` | Scanned Devices | This scans for all nearby devices\n`connect:\u003cDEVICE_ADDR\u003e` | HR Reading |  This connects to a specific device, and adds a listener for broadcasts HR readings\n`disconnect:\u003cDEVICE_ADDR\u003e` | N/A | This disconnects from a specific device | N/A\n\n#### Responses To The Clients\nEvent | Example Structure | Description\n--- | --- | ---\nHR Reading | `{action: 'hr', hr: 75, date: '2024-02-02T02:02:02'}` | Heart Rate reading broadcasts from the device\nScanned Devices | `{ action: 'devices', devices: [...]}` | Devices found in the device scan\n\n\n\n#### Examples\n```shell\n# Start the server\npython src/websocket.py \n\n# Start the server on a custom port\npython src/websocket.py -p 8080\n```\n\n## Example - Website\nThis is a small Vue application, that interacts with the websocket server. To provide tracking and graphing of multiple BLE devices. See more information in the README file in the example directory\n\n![Web Application Screenshot](images/web.png)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamjuk%2Fheartrate-sensor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamjuk%2Fheartrate-sensor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamjuk%2Fheartrate-sensor/lists"}