BLE Services

The following commands allow you to interact with various GATT services present on Bluefruit LE modules when running in Command Mode.

AT+BLEUARTTX

This command will transmit the specified text message out via the UART Service while you are running in Command Mode.

Codebase Revision: 0.3.0

Parameters: The message payload to transmit. The payload can be up to 240 characters (since AT command strings are limited to a maximum of 256 bytes total).

Output: This command will produce an ERROR message if you are not connected to a central device, or if the internal TX FIFO on the Bluefruit LE module is full.

As of firmware release 0.6.2 and higher, AT+BLEUARTTX can accept a limited set of escape code sequences:

  • \r = carriage return
  • \n = new line
  • \t = tab
  • \b = backspace
  • \\ = backward slash

As of firmware release 0.6.7 and higher, AT+BLEUARTTX can accept the following escape code sequence since AT+BLEUARTTX=? has a specific meaning to the AT parser:

  • \? = transmits a single question mark

As of firmware release 0.7.6 and higher, AT+BLEUARTTX can accept the following escape code sequence:

  • \+ = transmit a single '+' character without having to worry about `+++` mode switch combinations
ESCAPE SEQUENCE NOTE: If you are trying to send escape sequences in code via something like 'ble.print("...");' please note that you will need to send a double back-slash for the escape code to arrive as-intended in the AT command. For example: ble.println("AT+BLEUARTTX=Some Test\\r\\n");
You must be connected to another device for this command to execute
Download: file
# Send a string when connected to another device
AT+BLEUARTTX=THIS IS A TEST
OK
  
# Send a string when not connected
AT+BLEUARTTX=THIS IS A TEST
ERROR

TX FIFO Buffer Handling

Starting with firmware version 0.6.7, when the TX FIFO buffer is full a 200ms blocking delay will be used to see if any free space becomes available in the FIFO before returning ERROR. The exact process is detailed in the flow chart below:

Note: The TX FIFO full check will happen for each GATT transaction (of up to 20 bytes of data each), so large data transfers may have multiple 200ms wait states.

You can use the AT+BLEUARTFIFO=TX command to check the size of the TX FIFO before sending data to ensure that you have enough free space available in the buffer.

The TX FIFO has the following size, depending on the firmware version used:

  • Firmware <=0.6.6: 160 characters wide
  • Firmware >=0.6.7: 1024 characters wide
It IS possible with large data transfers that part of the payload can be transmitted, and the command can still produce an ERROR if the FIFO doesn't empty in time in the middle of the payload transfer (since data is transmitted in maximum 20 byte chunks). If you need to ensure reliable data transfer, you should always check the TX FIFO size before sending data, which you can do using the AT+BLEUARTFIFO command. If not enough space is available for the entire payload, add a SW delay until enough space is available. Any single AT+BLEUARTTX command can fit into the FIFO, but multiple large instances of this command may cause the FIFO to fill up mid transfer.

AT+BLEUARTTXF

This is a convenience function the serves the same purpose as AT+BLEUARTTX, but data is immediately sent in a single BLE packet ('F' for force packet). This command will accept a maximum of 20 characters, which is the limit of what can be send in a single packet.

Codebase Revision: 0.7.6

Parameters: See AT+BLEUARTTX

Output: See AT+BLEUARTTX

AT+BLEUARTRX

This command will dump the UART service's RX buffer to the display if any data has been received from from the UART service while running in Command Mode. The data will be removed from the buffer once it is displayed using this command.

Any characters left in the buffer when switching back to Data Mode will cause the buffered characters to be displayed as soon as the mode switch is complete (within the limits of available buffer space, which is 1024 bytes on current black 32KB SRAM devices, or 160 bytes for the blue first generation BLEFriend board based on 16KB SRAM parts).

Codebase Revision: 0.3.0

Parameters: None

Output: The RX buffer's content if any data is available, otherwise nothing.

You can also use the AT+BLEUARTFIFO=RX command to check if any incoming data is available or not.
Download: file
# Command results when data is available
AT+BLEUARTRX
Sent from Android
OK
  
# Command results when no data is available
AT+BLEUARTRX
OK

AT+BLEUARTFIFO

This command will return the free space available in the BLE UART TX and RX FIFOs.  If you are transmitting large chunks of data, you may want to check if you have enough free space in the TX FIFO before sending, keeping in mind that individual GATT packets can contain up to 20 user bytes each.

Codebase Revision: 0.6.7

Parameters: Running this command with no parameters will return two comma-separated values indicating the free space in the TX buffer, following by the RX buffer.  To request a specific buffer, you can execute the command with either a "TX" or "RX" value (For example: "AT+BLEUARTFIFO=TX").

Output: The free space remaining in the TX and RX FIFO buffer if no parameter is present, otherwise the free space remaining in the specified FIFO buffer.

Download: file
AT+BLEUARTFIFO
1024,1024
OK

AT+BLEUARTFIFO=TX
1024
OK

AT+BLEUARTFIFO=RX
1024
OK

AT+BLEKEYBOARDEN

This command will enable GATT over HID (GoH) keyboard support, which allows you to emulate a keyboard on supported iOS and Android devices.  By default HID keyboard support is disabled, so you need to set BLEKEYBOARDEN to 1 and then perform a system reset before the keyboard will be enumerated and appear in the Bluetooth preferences on your phone, where if can be bonded as a BLE keyboard.

Codebase Revision: 0.5.0

Parameters: 1 or 0 (1 = enable, 0 = disable)

Output: None

As of firmware version 0.6.6 this command is now an alias for AT+BLEHIDEN
You must perform a system reset (ATZ) before the changes take effect!
Before you can use your HID over GATT keyboard, you will need to bond your mobile device with the Bluefruit LE module in the Bluetooth preferences panel.
Download: file
# Enable BLE keyboard support then reset
AT+BLEKEYBOARDEN=1
OK
ATZ
OK
  
# Disable BLE keyboard support then reset
AT+BLEKEYBOARDEN=0
OK
ATZ
OK

AT+BLEKEYBOARD

Sends text data over the BLE keyboard interface (if it has previously been enabled via AT+BLEKEYBOARDEN).

Any valid alpha-numeric character can be sent, and the following escape sequences are also supported:

  • \r - Carriage Return
  • \n - Line Feed
  • \b - Backspace
  • \t - Tab
  • \\ - Backslash

As of version 0.6.7 you can also use the following escape code when sending a single character ('AT+BLEKEYBOARD=?' has another meaning for the AT parser):

  • \? - Question mark

Codebase Revision: 0.5.0

Parameters: The text string (optionally including escape characters) to transmit

Output: None

Download: file
# Send a URI with a new line ending to execute in Chrome, etc.
AT+BLEKEYBOARD=http://www.adafruit.com\r\n
OK
  
# Send a single question mark (special use case, 0.6.7+)
AT+BLEKEYBOARD=\?
OK

AT+BLEKEYBOARDCODE

Sends a raw hex sequence of USB HID keycodes to the BLE keyboard interface including key modifiers and up to six alpha-numeric characters.

This command accepts the following string-encoded byte array payload, matching the way HID over GATT sends keyboard data:

  • Byte 0: Modifier
  • Byte 1: Reserved (should always be 00)
  • Bytes 2..7: Hexadecimal value(s) corresponding to the HID keys (if no character is used you can enter '00' or leave trailing characters empty)

After a keycode sequence is sent with the AT+BLEKEYBOARDCODE command, you must send a second AT+BLEKEYBOARDCODE command with at least two 00 characters to indicate the keys were released!

Modifier Values

The modifier byte can have one or more of the following bits set:

  • Bit 0 (0x01): Left Control
  • Bit 1 (0x02): Left Shift
  • Bit 2 (0x04): Left Alt
  • Bit 3 (0x08): Left Window
  • Bit 4 (0x10): Right Control
  • Bit 5 (0x20): Right Shift
  • Bit 6 (0x40): Right Alt
  • Bit 7 (0x80): Right Window

Codebase Revision: 0.5.0

Parameters: A set of hexadecimal values separated by a hyphen ('-').  Note that these are HID scan code values, not standard ASCII values!

Output: None

HID Keyboard Codes

A list of hexademical-format HID keyboard codes can be found here (see section 7), and are listed below for convenience sake:

HID key code values don't correspond to ASCII key codes! For example, 'a' has an HID keycode value of '04', and there is no keycode for an upper case 'A' since you use the modifier to set upper case values. For details, google 'usb hid keyboard scan codes', and see the example below.
Download: file
0x00	Reserved (no event indicated)
0x01	Keyboard ErrorRollOver
0x02	Keyboard POSTFail
0x03	Keyboard ErrorUndefined
0x04	Keyboard a and A
0x05	Keyboard b and B
0x06	Keyboard c and C
0x07	Keyboard d and D
0x08	Keyboard e and E
0x09	Keyboard f and F
0x0A	Keyboard g and G
0x0B	Keyboard h and H
0x0C	Keyboard i and I
0x0D	Keyboard j and J
0x0E	Keyboard k and K
0x0F	Keyboard l and L
0x10	Keyboard m and M
0x11	Keyboard n and N
0x12	Keyboard o and O
0x13	Keyboard p and P
0x14	Keyboard q and Q
0x15	Keyboard r and R
0x16	Keyboard s and S
0x17	Keyboard t and T
0x18	Keyboard u and U
0x19	Keyboard v and V
0x1A	Keyboard w and W
0x1B	Keyboard x and X
0x1C	Keyboard y and Y
0x1D	Keyboard z and Z
0x1E	Keyboard 1 and !
0x1F	Keyboard 2 and @
0x20	Keyboard 3 and #
0x21	Keyboard 4 and $
0x22	Keyboard 5 and %
0x23	Keyboard 6 and ^
0x24	Keyboard 7 and &
0x25	Keyboard 8 and *
0x26	Keyboard 9 and (
0x27	Keyboard 0 and )
0x28	Keyboard Return (ENTER)
0x29	Keyboard ESCAPE
0x2A	Keyboard DELETE (Backspace)
0x2B	Keyboard Tab
0x2C	Keyboard Spacebar
0x2D	Keyboard - and (underscore)
0x2E	Keyboard = and +
0x2F	Keyboard [ and {
0x30	Keyboard ] and }
0x31	Keyboard \ and |
0x32	Keyboard Non-US # and ~
0x33	Keyboard ; and :
0x34	Keyboard ' and "
0x35	Keyboard Grave Accent and Tilde
0x36	Keyboard, and <
0x37	Keyboard . and >
0x38	Keyboard / and ?
0x39	Keyboard Caps Lock
0x3A	Keyboard F1
0x3B	Keyboard F2
0x3C	Keyboard F3
0x3D	Keyboard F4
0x3E	Keyboard F5
0x3F	Keyboard F6
0x40	Keyboard F7
0x41	Keyboard F8
0x42	Keyboard F9
0x43	Keyboard F10
0x44	Keyboard F11
0x45	Keyboard F12
0x46	Keyboard PrintScreen
0x47	Keyboard Scroll Lock
0x48	Keyboard Pause
0x49	Keyboard Insert
0x4A	Keyboard Home
0x4B	Keyboard PageUp
0x4C	Keyboard Delete Forward
0x4D	Keyboard End
0x4E	Keyboard PageDown
0x4F	Keyboard RightArrow
0x50	Keyboard LeftArrow
0x51	Keyboard DownArrow
0x52	Keyboard UpArrow
0x53	Keypad Num Lock and Clear
0x54	Keypad /
0x55	Keypad *
0x56	Keypad -
0x57	Keypad +
0x58	Keypad ENTER
0x59	Keypad 1 and End
0x5A	Keypad 2 and Down Arrow
0x5B	Keypad 3 and PageDn
0x5C	Keypad 4 and Left Arrow
0x5D	Keypad 5
0x5E	Keypad 6 and Right Arrow
0x5F	Keypad 7 and Home
0x60	Keypad 8 and Up Arrow
0x61	Keypad 9 and PageUp
0x62	Keypad 0 and Insert
0x63	Keypad . and Delete
0x64	Keyboard Non-US \ and |
0x65	Keyboard Application
0x66	Keyboard Power
0x67	Keypad =
0x68	Keyboard F13
0x69	Keyboard F14
0x6A	Keyboard F15
0x6B	Keyboard F16
0x6C	Keyboard F17
0x6D	Keyboard F18
0x6E	Keyboard F19
0x6F	Keyboard F20
0x70	Keyboard F21
0x71	Keyboard F22
0x72	Keyboard F23
0x73	Keyboard F24
0x74	Keyboard Execute
0x75	Keyboard Help
0x76	Keyboard Menu
0x77	Keyboard Select
0x78	Keyboard Stop
0x79	Keyboard Again
0x7A	Keyboard Undo
0x7B	Keyboard Cut
0x7C	Keyboard Copy
0x7D	Keyboard Paste
0x7E	Keyboard Find
0x7F	Keyboard Mute
0x80	Keyboard Volume Up
0x81	Keyboard Volume Down
0x82	Keyboard Locking Caps Lock
0x83	Keyboard Locking Num Lock
0x84	Keyboard Locking Scroll Lock
0x85	Keypad Comma
0x86	Keypad Equal Sign
0x87	Keyboard International1
0x88	Keyboard International2
0x89	Keyboard International3
0x8A	Keyboard International4
0x8B	Keyboard International5
0x8C	Keyboard International6
0x8D	Keyboard International7
0x8E	Keyboard International8
0x8F	Keyboard International9
0x90	Keyboard LANG1
0x91	Keyboard LANG2
0x92	Keyboard LANG3
0x93	Keyboard LANG4
0x94	Keyboard LANG5
0x95	Keyboard LANG6
0x96	Keyboard LANG7
0x97	Keyboard LANG8
0x98	Keyboard LANG9
0x99	Keyboard Alternate Erase
0x9A	Keyboard SysReq/Attention
0x9B	Keyboard Cancel
0x9C	Keyboard Clear
0x9D	Keyboard Prior
0x9E	Keyboard Return
0x9F	Keyboard Separator
0xA0	Keyboard Out
0xA1	Keyboard Oper
0xA2	Keyboard Clear/Again
0xA3	Keyboard CrSel/Props
0xA4	Keyboard ExSel
0xE0	Keyboard LeftControl
0xE1	Keyboard LeftShift
0xE2	Keyboard LeftAlt
0xE3	Keyboard Left GUI
0xE4	Keyboard RightControl
0xE5	Keyboard RightShift
0xE6	Keyboard RightAlt
0xE7	Keyboard Right GUI

The following example shows how you can use this command:

Download: file
# send 'abc' with left shift key (0x02) --> 'ABC'
AT+BLEKEYBOARDCODE=02-00-04-05-06-00-00
OK
# Indicate that the keys were released (mandatory!)
AT+BLEKEYBOARDCODE=00-00
OK

AT+BLEHIDEN

This command will enable GATT over HID (GoH) support, which allows you to emulate a keyboard, mouse or media controll on supported iOS, Android, OSX and Windows 10 devices.  By default HID support is disabled, so you need to set BLEHIDEN to 1 and then perform a system reset before the HID devices will be enumerated and appear in on your central device.

Codebase Revision: 0.6.6

Parameters: 1 or 0 (1 = enable, 0 = disable)

Output: None

You normally need to 'bond' the Bluefruit LE peripheral to use the HID commands, and the exact bonding process will change from one operating system to another.
If you have previously bonded to a device and need to clear the bond, you can run the AT+FACTORYRESET command which will erase all stored bond data on the Bluefruit LE module.
Download: file
# Enable GATT over HID support on the Bluefruit LE module
AT+BLEHIDEN=1
OK
  
# Reset so that the changes take effect
ATZ
OK

AT+BLEHIDMOUSEMOVE

Moves the HID mouse or scroll wheen position the specified number of ticks.

All parameters are signed 8-bit values (-128 to +127).  Positive values move to the right or down, and origin is the top left corner.

Codebase Revision: 0.6.6

Parameters: X Ticks (+/-), Y Ticks (+/-), Scroll Wheel (+/-), Pan Wheel (+/-)

Output: None

Download: file
# Move the mouse 100 ticks right and 100 ticks down
AT+BLEHIDMOUSEMOVE=100,100
OK
  
# Scroll down 20 pixels or lines (depending on context)
AT+BLEHIDMOUSEMOVE=,,20,
OK
  
# Pan (horizontal scroll) to the right (exact behaviour depends on OS)
AT+BLEHIDMOUSEMOVE=0,0,0,100

AT+BLEHIDMOUSEBUTTON

Manipulates the HID mouse buttons via the specific string(s).

Codebase Revision: 0.6.6

Parameters: Button Mask String [L][R][M][B][F], Action [PRESS][CLICK][DOUBLECLICK][HOLD]

  • L = Left Button
  • R = Right Button
  • M = Middle Button
  • B = Back Button
  • F = Forward Button
  • If the second parameter (Action) is "HOLD", an optional third parameter can be passed specifying how long the button should be held in milliseconds.

Output: None

Download: file
# Double click the left mouse button
AT+BLEHIDMOUSEBUTTON=L,doubleclick
OK

# Press the left mouse button down, move the mouse, then release L
# This is required to perform 'drag' then stop type operations
AT+BLEHIDMOUSEBUTTON=L
OK
AT+BLEHIDMOUSEMOVE=-100,50
OK
AT+BLEHIDMOUSEBUTTON=0
OK
  
# Hold the backward mouse button for 200 milliseconds (OS dependent)
AT+BLEHIDMOUSEBUTTON=B,hold,200
OK

AT+BLEHIDCONTROLKEY

Sends HID media control commands for the bonded device (adjust volume, screen brightness, song selection, etc.).

Codebase Revision: 0.6.6

Parameters: The HID control key to send, followed by an optional delay in ms to hold the button

The control key string can be one of the following values:

  • System Controls (works on most systems)
    • BRIGHTNESS+
    • BRIGHTNESS-
  • Media Controls (works on most systems)
    • PLAYPAUSE
    • MEDIANEXT
    • MEDIAPREVIOUS
    • MEDIASTOP
  • Sound Controls (works on most systems)
    • VOLUME
    • MUTE
    • BASS
    • TREBLE
    • BASS_BOOST
    • VOLUME+
    • VOLUME-
    • BASS+
    • BASS-
    • TREBLE+
    • TREBLE-
  • Application Launchers (Windows 10 only so far)
    • EMAILREADER
    • CALCULATOR
    • FILEBROWSER
  • Browser/File Explorer Controls (Firefox on Windows/Android only)
    • SEARCH
    • HOME
    • BACK
    • FORWARD
    • STOP
    • REFRESH
    • BOOKMARKS

You can also send a raw 16-bit hexadecimal value in the '0xABCD' format. A full list of 16-bit 'HID Consumer Control Key Codes' can be found here (see section 12).

Output: Normally none.

If you are not bonded and connected to a central device, this command will return ERROR. Make sure you are connected and HID support is enabled before running these commands.
Download: file
# Toggle the sound on the bonded central device
AT+BLEHIDCONTROLKEY=MUTE
OK

# Hold the VOLUME+ key for 500ms
AT+BLEHIDCONTROLKEY=VOLUME+,500
OK

# Send a raw 16-bit Consumer Key Code (0x006F = Brightness+)
AT+BLEHIDCONTROLKEY=0x006F
OK

AT+BLEHIDGAMEPADEN

Enables HID gamepad support in the HID service. By default the gamepad is disabled as of version 0.7.6 of the firmware since it causes problems on iOS and OS X and should only be used on Android and Windows based devices.

Codebase Revision: 0.7.6

Parameters: Whether the gamepad service should be enabled via one of the following values:

  • on
  • off
  • 1
  • 0

Output: If executed with no parameters, a numeric value will be returned indicating whether the battery service is enabled (1) or disabled (0).

This command requires a system reset to take effect.

AT+BLEHIDGAMEPAD

Sends a specific HID gamepad payload out over BLE

Codebase Revision: 0.7.0

Parameters: The following comma-separated parameters are available:

  • x:  LEFT, RIGHT: If X=-1 then 'LEFT' is pressed, if X=1 then 'RIGHT' is pressed, if X=0 then neither left nor right are pressed
  • y: UP, DOWN: If Y=-1 then 'UP' is pressed, if Y=1 then 'DOWN' is pressed, if Y=0 then neither up nor down are pressed
  • buttons: 0x00-0xFF, which is a bit mask for 8 button 0-7

Output: Nothing

HID gamepad is disabled by default as of version 0.7.6, and must first be enabled via AT+BLEHIDGAMEPADEN=1 before it can be used.
Note: You need to send both 'press' and 'release' events for each button, otherwise the system will think that the button is still pressed until a release state is received.
Download: file
# Press 'RIGHT' and 'Button0' at the same time
AT+BLEHIDGAMEPAD=1,0,0x01

# Press 'UP' and 'Button1' + 'Button0' at the same time
AT+BLEHIDGAMEPAD=0,-1,0x03

AT+BLEMIDIEN

Enables or disables the BLE MIDI service.

Codebase Revision: 0.7.0

Parameters: State, which can be one of:

  • on
  • off
  • 0
  • 1

Output: If executed with no parameters, it will return the current state of the MIDI service as an integer indicating if it is enabled (1) or disabled (0).

Note: This command will require a reset to take effect.
Download: file
# Check the current state of the MIDI service
AT+BLEMIDIEN
1
OK

# Enable the MIDI Service
AT+BLEMIDIEN=1
OK

AT+BLEMIDIRX

Reads an incoming MIDI character array from the buffer.

Codebase Revision: 0.7.0

Parameters: None

Output: The midi event in byte array format

Download: file
AT+BLEMIDIRX
90-3C-7F
OK

AT+BLEMIDITX

Sends a MIDI event to host.

Codebase Revision: 0.7.0

Parameters: The MIDI event in hex array format, which can be either:

  • A series of full MIDI events (up to 4 events)
  • Exactly 1 full MIDI event + several running events without status (up to 7)

Output: None

Download: file
# Send 1 event (middle C with max velocity)
AT+BLEMIDITX=90-3C-7F
OK

# Send 2 events
AT+BLEMIDITX=90-3C-7F-A0-3C-7F
OK

# Send 1 full event + running event
AT+BLEMIDITX=90-3C-7F-3C-7F
OK

AT+BLEBATTEN

Enables the Battery Service following the definition from the Bluetooth SIG.

Codebase Revision: 0.7.0

Parameters: Whether the battery service should be enabled, via on of the following values:

  • on
  • off
  • 1
  • 0

Output: If executed with no parameters, a numeric value will be returned indicating whether the battery service is enabled (1) or disabled (0).

This command requires a system reset to take effect.
Download: file
# Enable the Battery Service
AT+BLEBATTEN=1
OK

AT+BLEBATTVAL

Sets the current battery level in percentage (0..100) for the Battery Service (if enabled).

Codebase Revision: 0.7.0

Parameters: The percentage for the battery in the range of 0..100.

Output: If executed with no parameters, the current battery level stored in the characteristic.

Download: file
# Set the battery level to 72%
AT+BLEBATTVAL=72
OK
This guide was first published on Jul 07, 2015. It was last updated on Jul 07, 2015. This page (BLE Services) was last updated on Feb 01, 2018.