{"id":46320426,"url":"https://github.com/fsievers22/esphome-ble-remote","last_synced_at":"2026-03-04T15:03:15.260Z","repository":{"id":44568509,"uuid":"419380811","full_name":"fsievers22/esphome-ble-remote","owner":"fsievers22","description":"ESPHome external component for a BLE HID client","archived":false,"fork":false,"pushed_at":"2025-12-31T23:43:10.000Z","size":15067,"stargazers_count":40,"open_issues_count":2,"forks_count":24,"subscribers_count":4,"default_branch":"master","last_synced_at":"2026-01-05T12:43:35.193Z","etag":null,"topics":["amazon-remote","ble","ble-client","ble-hid","esp-idf","esp32","esphome","firetv","firetv-remote","hid","hid-host","remote","shield-remote"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fsievers22.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-10-20T15:10:21.000Z","updated_at":"2025-12-31T23:43:14.000Z","dependencies_parsed_at":"2025-03-20T03:04:28.431Z","dependency_job_id":null,"html_url":"https://github.com/fsievers22/esphome-ble-remote","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/fsievers22/esphome-ble-remote","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsievers22%2Fesphome-ble-remote","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsievers22%2Fesphome-ble-remote/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsievers22%2Fesphome-ble-remote/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsievers22%2Fesphome-ble-remote/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fsievers22","download_url":"https://codeload.github.com/fsievers22/esphome-ble-remote/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fsievers22%2Fesphome-ble-remote/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30084685,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-04T13:22:36.021Z","status":"ssl_error","status_checked_at":"2026-03-04T13:20:45.750Z","response_time":59,"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":["amazon-remote","ble","ble-client","ble-hid","esp-idf","esp32","esphome","firetv","firetv-remote","hid","hid-host","remote","shield-remote"],"created_at":"2026-03-04T15:03:07.539Z","updated_at":"2026-03-04T15:03:15.208Z","avatar_url":"https://github.com/fsievers22.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ESPHome external component to read hid events from a ble client\nThe `ble_client_hid` external component foor ESPHome can be used to capture hid events like key presses from a hid device connected via Bluetooth LE.\n**Boards without internal PSRAM seem to be not compatible**\n#### Tested working with:\n- FireTV Remote of [Fire TV Stick - 3rd Gen (2020)](https://developer.amazon.com/docs/fire-tv/device-specifications-fire-tv-streaming-media-player.html?v=ftvstickgen3)\n- Nvidia Shield-Fernbedienung (2019)\n- Ruwido Model 827A (Virgin Telco 4k Spain): [Manual](https://fcc.report/FCC-ID/XYN827A)\n\n## How to Use\n### Add as external component:\nSee [External Components](https://esphome.io/components/external_components.html):\n```yaml\nexternal_components:\n  # use ble_client_hid from this master branch in GitHub\n  - source: github://fsievers22/esphome-ble-remote@master\n    components: [ ble_client_hid ]\n```\n### Component:\nMultiple `ble_client_hid` components can be configured, but at max three. (See [BLE Client](https://esphome.io/components/ble_client.html) notes for more info).\n\nThe device has to use the `esp-idf` framework:\n```yaml\nesp32:\n  board: az-delivery-devkit-v4  #modify to fit your board\n  framework:                    #only works n esp-idf framework\n    type: esp-idf\n```\nEach `ble_client_hid` component requires a `ble_client`.\n```yaml\nesp32_ble_tracker:            \n\nble_client:\n  - id: ble_client_1\n    mac_address: \"FF:FF:20:00:0F:15\"    #modify to fit your ble device\n\nble_client_hid:\n  - id: ble_client_hid_1\n    ble_client_id: ble_client_1\n```\n#### Configuration variables:\n- **id**(**Required**, ID): The ID to use for code generation, and for regerence by dependant components\n- **ble_client_id**(**Required**, ID): The ID of the `ble_client` component associated with this component can be omitted if only one `ble_client` is registered\n#### Events:\nThe component sends an event through the HomeAssistant Native API to HomeAssistant, when an hid event happens.\nThe event is named `esphome.hid_events` and contains the usage as a string and the value.\nExample:\n```yaml\ndata:\n  usage: \"KEYBOARD_EXAMPLE\"\n  value: 1\n```\nThe usage is a string describing what the value can be used for like the keycode of a keyboard button.\n\n### Battery sensor:\nThe `ble_client_hid` sensor lets you track the battery level of the BLE HID client.\n```yaml\nesp32_ble_tracker:            \n\nble_client:\n  - id: ble_client_1\n    mac_address: \"48:B0:2D:52:29:C6\"    #modify to fit your ble device\n\nble_client_hid:\n  - id: ble_client_hid_1\n    ble_client_id: ble_client_1\n\nsensor:\n  - platform: ble_client_hid\n    type: battery\n    ble_client_hid_id: ble_client_hid_1\n    name: \"Battery\"\n```\n#### Configuration variables:\n- **ble_client_hid_id**(**Required**, ID): The ID of the `ble_client_hid` component associated with this component, can be omitted if only one `ble_client_hid` is registered.\n- **id**(**Optional**, ID): Manuallyy specify the ID used for code generation\n- All other options from [Sensor](https://esphome.io/components/sensor/index.html)\n\n### last event sensors:\nThe component can expose the last received event through a combination of sensors and text sensors.\n\n```yaml\nsensor:\n  - platform: ble_client_hid\n    type: last_event_value\n    name: \"Last Event Value\"\n\ntext_sensor:\n  - platform: ble_client_hid\n    type: last_event_usage\n    name: \"Last Event Usage\"\n  - platform: ble_client_hid\n    type: last_event_code\n    name: \"Last Event Code\"\n```\n\n#### Text sensor types:\n- **last_event_usage**: The human-readable usage name (e.g., `CONSUMER_VOLUME_UP`, `KEYBOARD_A`)\n- **last_event_code**: The raw HID usage code in `{page}_{usage}` format (e.g., `12_233` for Consumer Page usage 233)\n\n#### Configuration variables:\n- **type**(**Required**, string): The type of text sensor. Either `last_event_usage` or `last_event_code`.\n- **ble_client_hid_id**(**Required**, ID): The ID of the `ble_client_hid` component associated with this component, can be omitted if only one `ble_client_hid` is registered.\n- **id**(**Optional**, ID): Manually specify the ID used for code generation\n- All other options from [Sensor](https://esphome.io/components/sensor/index.html) or [TextSensor](https://esphome.io/components/text_sensor/index.html)\n\n# Example device configuration:\n```yaml\nesp32:\n  board: az-delivery-devkit-v4  #modify to fit your board\n  framework:                    #only works n esp-idf framework\n    type: esp-idf\n\nesphome:\n  name: example-ble-hid         \n\nexternal_components:\n  # use ble_client_hid from this master branch in GitHub\n  - source: github://fsievers22/esphome-ble-remote@master\n    components: [ ble_client_hid ]\n\n# Enable logging\nlogger:\n  level: INFO\n\n# Enable Home Assistant API\napi:\n\nota:\n  password: !secret ota_password\n\nwifi:\n  ssid: !secret wifi_ssid\n  password: !secret wifi_password\n  fast_connect: on\n\nesp32_ble_tracker:            \n\nble_client:\n  - id: ble_client_1\n    mac_address: \"48:B0:2D:52:29:C6\"    #modify to fit your ble device\n\nble_client_hid:\n  - id: ble_client_hid_1\n    ble_client_id: ble_client_1\n\nsensor:\n  - platform: ble_client_hid\n    type: battery\n    ble_client_hid_id: ble_client_hid_1\n    name: \"Battery\"\n  - platform: ble_client_hid\n    type: last_event_value\n    ble_client_hid_id: ble_client_hid_1\n    name: \"Last Event Value\"\n\ntext_sensor:\n  - platform: ble_client_hid\n    type: last_event_usage\n    ble_client_hid_id: ble_client_hid_1\n    name: \"Last Event Usage\"\n  - platform: ble_client_hid\n    type: last_event_code\n    ble_client_hid_id: ble_client_hid_1\n    name: \"Last Event Code\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffsievers22%2Fesphome-ble-remote","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffsievers22%2Fesphome-ble-remote","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffsievers22%2Fesphome-ble-remote/lists"}