MicroPythonBLEHID
A MicroPython library for implementing Bluetooth Low Energy (BLE) Human Interface Devices (HID) like keyboards, mice, and joysticks.
What is MicroPythonBLEHID?
MicroPythonBLEHID is a library that allows MicroPython firmware on ESP32 devices to emulate Bluetooth Low Energy Human Interface Devices. It implements the BLE GATT services required for HID profiles, enabling developers to create custom wireless keyboards, mice, and joysticks using MicroPython. The library solves the problem of building BLE input peripherals without deep Bluetooth protocol expertise.
Embedded developers and hobbyists working with MicroPython on ESP32 boards who need to create custom BLE input devices, such as DIY controllers, accessibility tools, or specialized wireless peripherals.
Developers choose this library because it provides a clean, extensible MicroPython-native implementation of BLE HID, reducing the complexity of Bluetooth protocol handling. Its modular design allows for easy customization of HID report descriptors, and it includes built-in support for bonding, security, and battery status.
Overview
Human Interface Device (HID) over Bluetooth Low Energy (BLE) GATT library for MicroPython.
Use Cases
Best For
- Building custom wireless keyboards with MicroPython and ESP32
- Creating DIY Bluetooth mice or trackpads for embedded projects
- Developing BLE joysticks or game controllers for IoT applications
- Prototyping accessibility input devices using MicroPython
- Adding wireless HID capabilities to existing MicroPython hardware
- Educational projects exploring BLE HID protocols on embedded systems
Not Ideal For
- Projects requiring out-of-the-box multi-device HID (e.g., keyboard and mouse combo) without custom descriptor work
- Developers needing pre-built complex HID devices like gaming mice with many buttons or specialized controllers
- Applications demanding broad cross-platform compatibility beyond Windows 10 and ESP32 hardware
- High-performance real-time HID devices where MicroPython's interpretative overhead could introduce latency
Pros & Cons
Pros
Provides well-documented, minimal base classes for keyboard, mouse, and joystick, allowing easy customization for specific needs, as outlined in the README's philosophy section.
Supports LE Secure pairing with configurable I/O capabilities and flexible key storage (JSON or NVS), ensuring persistent and secure Bluetooth connections, detailed in the class methods.
Includes standard BLE services for battery level reporting and device information (manufacturer, model, etc.), adding professionalism to HID peripherals without extra code, as mentioned in the key features.
Offers key storage options with JSONKeyStore and NVSKeyStore, facilitating secure client management across power cycles, as described in the hid_keystores.py section.
Cons
The library only provides basic HID implementations; for non-standard devices, developers must extend classes and modify HID report descriptors, which requires deep understanding and extra work, as admitted in the FAQ and philosophy.
Specifically designed for ESP32 with 512 kB SRAM and MicroPython v1.18+, and tested only on TinyPICO with Windows 10, limiting its use in other environments or with different microcontrollers.
As stated in the FAQ, using a keyboard and mouse simultaneously is not immediately supported and requires creating a new device with a multi-device HID descriptor, adding complexity.
Lacks convenience functions like string-sending for keyboards; developers must implement such logic themselves, as noted in the usage section where it says functionality like sending character strings is excluded.
Frequently Asked Questions
Found a gem we're missing?
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.