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
# 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:
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
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.
# 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.
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
# 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
# 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:
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:
# 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
# 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
# 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
# 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.
# 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).
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
# 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).
# 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
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
# 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).
# 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.
# Set the battery level to 72% AT+BLEBATTVAL=72 OK
Page last edited March 08, 2024
Text editor powered by tinymce.
