qmk_firmware/docs/feature_bluetooth.md
chipperdoodles 914d42acd0 Update Bluetooth docs (#4062)
* syncing upstream

* Bluetooth Doc update

More Description in bluetooth section, Addition to Config options rules.mk section.

* merge upstream

chibios

* lib/chibios checkout

* Additional EZ key Section

added back EZ-Key diy link, Cleaned up some errors
2018-10-07 11:23:41 -07:00

3.6 KiB

Bluetooth

Bluetooth Known Supported Hardware

Currently Bluetooth support is limited to AVR based chips. For Bluetooth 2.1 Qmk has support for RN-42 HID Firmware and Bluefruit EZ Key the later of which is not produced anymore. For more recent BLE protocols currently only the Adafruit Bluefruit SPI friend is directly supported. BLE is needed to connect to iOS devices. Note iOS does not support Mouse Input.

Board Bluetooth Protocol Connection Type Rules.mk Bluetooth Chip
Adafruit EzKey HID Bluetooth Classic UART BLUETOOTH = AdafruitEZKey
Rover Networks RN-42 (Sparkfun Bluesmirf) Bluetooth Classic UART BLUETOOTH = RN42 RN-42
Bluefruit LE SPI Friend Bluetooth Low Energy SPI BLUETOOTH = AdafruitBLE nRF5182

Not Supported Yet but possible:

Adafruit BLE SPI Friend

Currently The only bluetooth chipset supported by QMK is the Adafruit Bluefruit SPI Friend. It's a Nordic nRF5182 based chip running Adafruit's custom firmware. Data is transmitted via Adafruit's SDEP over Hardware SPI. The Feather 32u4 Bluefruit LE is supported as it's an AVR mcu connected via SPI to the Nordic BLE chip with Adafruit firmware. If Building a custom board with the SPI friend it would be easiest to just use the pin selection that the 32u4 feather uses but you can change the pins in the config.h options with the following defines:

  • #define AdafruitBleResetPin D4
  • #define AdafruitBleCSPin B4
  • #define AdafruitBleIRQPin E6

A Bluefruit UART friend can be converted to an SPI friend, however this requires some reflashing and soldering directly to the MDBT40 chip.

Adafruit EZ-Key hid

This requires some hardware changes, but can be enabled via the Makefile. The firmware will still output characters via USB, so be aware of this when charging via a computer. It would make sense to have a switch on the Bluefruit to turn it off at will.

Bluetooth Rules.mk Options

Use only one of these

  • BLUETOOTH_ENABLE = yes (Legacy Option)
  • BLUETOOTH = RN42
  • BLUETOOTH = AdafruitEZKey
  • BLUETOOTH = AdafruitBLE

Bluetooth Keycodes

This is used when multiple keyboard outputs can be selected. Currently this only allows for switching between USB and Bluetooth on keyboards that support both.

Name Description
OUT_AUTO Automatically switch between USB and Bluetooth
OUT_USB USB only
OUT_BT Bluetooth only