{"id":14967270,"url":"https://github.com/heerkog/micropythonblehid","last_synced_at":"2025-04-12T18:38:37.098Z","repository":{"id":41362414,"uuid":"348060965","full_name":"Heerkog/MicroPythonBLEHID","owner":"Heerkog","description":"Human Interface Device (HID) over Bluetooth Low Energy (BLE) GATT library for MicroPython.","archived":false,"fork":false,"pushed_at":"2025-01-27T15:13:48.000Z","size":99,"stargazers_count":269,"open_issues_count":0,"forks_count":40,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-03T20:12:33.979Z","etag":null,"topics":["hid","joystick","keyboard","library","micropython","mouse"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Heerkog.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}},"created_at":"2021-03-15T17:22:09.000Z","updated_at":"2025-03-23T14:24:23.000Z","dependencies_parsed_at":"2025-01-08T08:01:51.029Z","dependency_job_id":"1918d4b2-5869-4e47-b0c1-4d93095f3997","html_url":"https://github.com/Heerkog/MicroPythonBLEHID","commit_stats":{"total_commits":42,"total_committers":3,"mean_commits":14.0,"dds":0.1428571428571429,"last_synced_commit":"29296d567ab69c28b09db06ca4f5893039544f2f"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heerkog%2FMicroPythonBLEHID","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heerkog%2FMicroPythonBLEHID/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heerkog%2FMicroPythonBLEHID/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Heerkog%2FMicroPythonBLEHID/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Heerkog","download_url":"https://codeload.github.com/Heerkog/MicroPythonBLEHID/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248615975,"owners_count":21133983,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["hid","joystick","keyboard","library","micropython","mouse"],"created_at":"2024-09-24T13:37:45.872Z","updated_at":"2025-04-12T18:38:37.072Z","avatar_url":"https://github.com/Heerkog.png","language":"Python","readme":"\u003cdiv id=\"top\"\u003e\u003c/div\u003e\n\n\n\u003c!-- PROJECT SHIELDS --\u003e\n[![Contributors][contributors-shield]][contributors-url]\n[![Forks][forks-shield]][forks-url]\n[![Stargazers][stars-shield]][stars-url]\n[![Issues][issues-shield]][issues-url]\n[![GPL License][license-shield]][license-url]\n[![Website][website-shield]][website-url]\n\n\n\u003c!-- PROJECT HEADER --\u003e\n\u003cbr /\u003e\n\u003cdiv align=\"center\"\u003e\n\u003ch3 align=\"center\"\u003eMicroPython Human Interface Device library\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    A library that offers implementations of Human Interface Devices (HID) over Bluetooth Low Energy (BLE) GATT for MicroPython.\n  \u003c/p\u003e\n\u003c/div\u003e\n\n\n\n\u003c!-- TABLE OF CONTENTS --\u003e\n\u003cdetails\u003e\n  \u003csummary\u003eTable of Contents\u003c/summary\u003e\n  \u003col\u003e\n    \u003cli\u003e\u003ca href=\"#about-the-project\"\u003eAbout The Project\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#requirements\"\u003eRequirements\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#getting-started\"\u003eGetting Started\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#usage\"\u003eUsage\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#contact\"\u003eContact\u003c/a\u003e\u003c/li\u003e\n    \u003cli\u003e\u003ca href=\"#acknowledgments\"\u003eAcknowledgments\u003c/a\u003e\u003c/li\u003e\n  \u003c/ol\u003e\n\u003c/details\u003e\n\n\n\n\u003c!-- ABOUT THE PROJECT --\u003e\n## About The Project\nThis library offers implementations of Human Interface Devices (HID) over Bluetooth Low Energy (BLE) GATT for MicroPython.\nThe library has been tested using an ESP32 development board ([TinyPICO](https://tinypico.com)) as the peripheral and Windows 10 as the central.\nExamples and basic implementations of HID devices are available for\n\n- Keyboard,\n- Mouse, and\n- Joystick.\n\nThis library is NOT intended to offer functionality for every possible HID device configuration.\nInstead, the library is designed to offer basic well-documented classes that you can extend to fit your HID device needs.\nFor example, the Mouse class offers a three button mouse with vertical scroll wheel.\nIf you plan on developing a gaming mouse with eight buttons and both vertical and horizontal wheels, you will need to extend the Mouse class and overwrite the required functions to include a new HID report descriptor.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!-- REQUIREMENTS --\u003e\n## Requirements\n\nThe following is required to use this library:\n- ESP32 chip with \n  - Bluetooth\n  - 512 kB SRAM or more\n- Micropython v1.18 or higher\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!-- GETTING STARTED --\u003e\n## Getting Started\n\nTo get a local copy simply clone this repository.\n\n   ```sh\n   git clone https://github.com/heerkog/MicroPythonBLEHID.git\n   ```\n\nThe repository is structured as followed:\n\n* `examples/` directory containing some examples.\n  * `async/` directory containing asynchronous examples.\n    * `joystick_example.py`\n    * `keyboard_example.py`\n    * `mouse_example.py`\n  * `simple/` directory containing simple examples.\n    * `joystick_example.py`\n    * `keyboard_example.py`\n    * `mouse_example.py`\n  * `tinypico/` directory containing TinyPICO specific examples. These are mostly personal projects.\n* `hid_services.py` the library.\n* `LICENSE` the license.\n* `readme.md`\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- USAGE EXAMPLES --\u003e\n## Usage\n\nThe library offers functionality for creating HID services, advertising them, and setting and notifying the central of HID events.\nThe library does not offer functionality to, for example, send a string of characters to the central using the keyboard service (eventhough this is included in the keyboard example).\nThe reason for this is that such functionality is entirely dependent on the intended use of the services and should be kept outside of this library.\n\nThe library consists of five classes with the following functions:\n\n* `HumanInterfaceDevice` (superclass for the HID service classes, implements the Device Information and Battery services, and sets up BLE and advertisement)\n  * `__init__(device_name)` (Initialize the superclass)\n  * `ble_irq(event, data)` (Internal callback function that catches BLE interrupt requests)\n  * `start()` (Starts Device Information and Battery services)\n  * `stop()` (Stops Device Information and Battery services)\n  * `write_service_characteristics(handles)` (Writes Device Information and Battery service characteristics)\n  * `load_secrets()` (Loads stored secrets for Bluetooth bonding)\n  * `save_secrets()` (Saves secrets for Bluetooth bonding)\n  * `start_advertising()` (Starts Bluetooth advertisement)\n  * `stop_advertising()` (Stops Bluetooth advertisement)\n  * `is_running()` (Returns `True` if services are running, otherwise `False`)\n  * `is_connected()` (Returns `True` if a central is connected, otherwise `False`)\n  * `is_advertising()` (Returns `True` if advertising, otherwise `False`)\n  * `set_state(state)` (Sets one of the `HumanInterfaceDevice` constants `DEVICE_STOPPED`, `DEVICE_IDLE`, `DEVICE_ADVERTISING`, or `DEVICE_CONNECTED`. Doesn't change the actual function. Used internally)\n  * `get_state()` (Returns one of the `HumanInterfaceDevice` constants `DEVICE_STOPPED`, `DEVICE_IDLE`, `DEVICE_ADVERTISING`, or `DEVICE_CONNECTED`)\n  * `set_state_change_callback(callback)` (Sets a callback function that is called when the `HumanInterfaceDevice` state changes between constants `DEVICE_STOPPED`, `DEVICE_IDLE`, `DEVICE_ADVERTISING`, or `DEVICE_CONNECTED`))\n  * `get_device_name()` (Returns the device name)\n  * `get_services_uuids()` (Returns the service UUIDs)\n  * `get_appearance()` (Returns the device appearance id)\n  * `get_battery_level()` (Returns the battery level)\n  * `set_device_information(manufacture_name, model_number, serial_number)` (Sets the basic Device Information characteristics. Must be called before calling `start()`)\n  * `set_device_revision(firmware_revision, hardware_revision, software_revision)` (Sets the Device Information revision characteristics. Must be called before calling `start()`)\n  * `set_device_pnp_information(pnp_manufacturer_source, pnp_manufacturer_uuid, pnp_product_id, pnp_product_version)` (Sets the Device Information PnP characteristics. Must be called before calling `start()`)\n  * `set_bonding(bond)` (Set whether to use Bluetooth bonding)\n  * `set_le_secure(le_secure)` (Set whether to use LE secure pairing)\n  * `set_io_capability(io_capability)` (Set input/output capability of this device Determines the pairing procedure, e.g., accept connection/passkey entry/just works. Must be called before calling `start()`)\n  * `set_passkey_callback(passkey_callback)` (Set callback function for pairing events. Callback function should return boolean to accept connection or passkey depending on I/O capability used)\n  * `set_passkey(passkey)` (Set the passkey to use for pairing)\n  * `set_battery_level(level)` (Sets the battery level internally)\n  * `notify_battery_level()` (Notifies the central of the current battery level. Call after setting battery level)\n  * `notify_hid_report()` (Function for subclasses to override)\n\n* `Joystick` (subclass of `HumanInterfaceDevice`, implements joystick service)\n  * `__init__(name)` (Initialize the joystick)\n  * `start()` (Starts the HID service using joystick characteristics. Calls `HumanInterfaceDevice.start()`)\n  * `write_service_characteristics(handles)` (Writes the joystick HID service characteristics.  Calls `HumanInterfaceDevice.write_service_characteristics(handles)`)\n  * `notify_hid_report()` (Notifies the central of the internal HID joystick status)\n  * `set_axes(x, y)` (Sets the joystick axes internally)\n  * `set_buttons(b1, b2, b3, b4, b5, b6, b7, b8)` (Sets the joystick buttons internally)\n\n* `Mouse` (subclass of `HumanInterfaceDevice`, implements mouse service)\n  * `__init__(name)` (Initialize the mouse)\n  * `start()` (Starts the HID service using mouse characteristics. Calls `HumanInterfaceDevice.start()`)\n  * `write_service_characteristics(handles)` (Writes the mouse HID service characteristics.  Calls `HumanInterfaceDevice.write_service_characteristics(handles)`)\n  * `notify_hid_report()` (Notifies the central of the internal HID mouse status)\n  * `set_axes(x, y)` (Sets the mouse axes movement internally)\n  * `set_wheel(w)` (Sets the mouse wheel movement internally)\n  * `set_buttons(b1, b2, b3)` (Sets the mouse buttons internally)\n\n* `Keyboard` (subclass of `HumanInterfaceDevice`, implements keyboard service)\n  * `__init__(name)`  (Initialize the keyboard)\n  * `start()` (Starts the HID service using keyboard characteristics. Calls `HumanInterfaceDevice.start()`)\n  * `write_service_characteristics(handles)` (Writes the keyboard HID service characteristics.  Calls `HumanInterfaceDevice.write_service_characteristics(handles)`)\n  * `notify_hid_report()` (Notifies the central of the internal HID keyboard status)\n  * `set_modifiers(right_gui, right_alt, right_shift, right_control, left_gui, left_alt, left_shift, left_control)` (Sets the keyboard modifier keys internally)\n  * `set_keys(k0, k1, k2, k3, k4, k5)` (Sets a list of key codes to press internally. Call without keys to release.)\n  * `ble_irq(event, data)` (Internal callback function that catches BLE keyboard interrupt requests)\n  * `set_kb_callback(kb_callback)` (Sets a callback function that is called on a keyboard event)\n\n* `Advertiser` (from the [MicroPython Bluetooth examples](https://github.com/micropython/micropython), used internally by `HumanInterfaceDevice` class)\n  * `__init__(ble, services, appearance, name)`\n  * `advertising_payload(limited_disc, br_edr, name, services, appearance)`\n  * `decode_field(payload, adv_type)`\n  * `decode_name(payload)`\n  * `decode_services(payload)`\n  * `start_advertising()` (Used internally)\n  * `stop_advertising()` (Used internally)\n\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\u003c!-- CONTRIBUTING --\u003e\n## Contributing\n\nContributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are **greatly appreciated**.\n\nIf you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag \"enhancement\".\nDon't forget to give the project a star! Thanks again!\n\n1. Fork the Project\n2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)\n3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)\n4. Push to the Branch (`git push origin feature/AmazingFeature`)\n5. Open a Pull Request\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- LICENSE --\u003e\n## License\n\nDistributed under the GNU General Public License. See `LICENSE` for more information.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- CONTACT --\u003e\n## Contact\n\nHeerko Groefsema - [@HeerkoG](https://twitter.com/heerkog) - [hgroefsema.nl](https://hgroefsema.nl)\n\nProject Link: [https://github.com/heerkog/MicroPythonBLEHID](https://github.com/heerkog/MicroPythonBLEHID)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- ACKNOWLEDGMENTS --\u003e\n## Acknowledgments\nThe following resources were of interest during development:\n\n* Bluetooth HID\n  * [Bluetooth Low Energy Specifications](https://www.bluetooth.com/specifications/specs/)\n  * [Bluetooth assigned numbers list](https://www.bluetooth.com/specifications/assigned-numbers/)\n  * [Bluetooth device class list](http://domoticx.com/bluetooth-class-of-device-lijst-cod/)\n* USB HID\n  * [USB HID specification](https://www.usb.org/document-library/device-class-definition-hid-111)\n  * [USB report descriptor tool](https://www.usb.org/document-library/hid-descriptor-tool)\n  * [USB HID report descriptor tutorial](https://eleccelerator.com/tutorial-about-usb-hid-report-descriptors/)\n* Micropython\n  * [Bluetooth examples](https://github.com/micropython/micropython/tree/master/examples/bluetooth)\n  * [BLE HID examples](https://github.com/micropython/micropython/pull/6559)\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n\n\n\n\u003c!-- MARKDOWN LINKS \u0026 IMAGES --\u003e\n\u003c!-- https://www.markdownguide.org/basic-syntax/#reference-style-links --\u003e\n[contributors-shield]: https://img.shields.io/github/contributors/heerkog/MicroPythonBLEHID.svg?style=for-the-badge\n[contributors-url]: https://github.com/heerkog/MicroPythonBLEHID/graphs/contributors\n[forks-shield]: https://img.shields.io/github/forks/heerkog/MicroPythonBLEHID.svg?style=for-the-badge\n[forks-url]: https://github.com/heerkog/MicroPythonBLEHID/network/members\n[stars-shield]: https://img.shields.io/github/stars/heerkog/MicroPythonBLEHID.svg?style=for-the-badge\n[stars-url]: https://github.com/heerkog/MicroPythonBLEHID/stargazers\n[issues-shield]: https://img.shields.io/github/issues/heerkog/MicroPythonBLEHID.svg?style=for-the-badge\n[issues-url]: https://github.com/heerkog/MicroPythonBLEHID/issues\n[license-shield]: https://img.shields.io/github/license/heerkog/MicroPythonBLEHID.svg?style=for-the-badge\n[license-url]: https://github.com/heerkog/MicroPythonBLEHID/blob/master/LICENSE.txt\n\n[website-shield]: https://img.shields.io/badge/Website-H-black.svg?style=for-the-badge\u0026colorB=2A638C\n[website-url]: https://hgroefsema.nl\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheerkog%2Fmicropythonblehid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fheerkog%2Fmicropythonblehid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fheerkog%2Fmicropythonblehid/lists"}