Bluefruit-LE-Shield-BLE-Services

De MCHobby - Wiki
Sauter à la navigation Sauter à la recherche


MCHobby investit du temps et de l'argent dans la réalisation de traduction et/ou documentation. C'est un travail long et fastidieux réalisé dans l'esprit Open-Source... donc gratuit et librement accessible.
SI vous aimez nos traductions et documentations ALORS aidez nous à en produire plus en achetant vos produits chez MCHobby.

Services BLE

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

Le service GATT et ses caractéristiques (Adafruit, anglais) gouvernent l'organisation et l'échange de données entre les périphériques.

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");
Stop
 You must be connected to another device for this command to execute 
# 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

Gestion de la mémoire tampon de réception

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:

Bluefruit-LE-Shield-BLE-Services-00.jpg

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
Stop
 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. 
# 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
 As of firmware version 0.6.6 this command is now an alias for AT+BLEHIDEN
Stop
 You must perform a system reset (ATZ) before the changes take effect!
Stop
 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. 
# 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).

  • Codebase Revision: 0.5.0
  • Parameters: The text string (optionally including escape characters) to transmit
  • Output: None

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
# 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.

  • 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 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.

This command accepts the following ascii-encoded HEX payload, matching the way HID over GATT sends keyboard data:

  • Byte 0: Modifier
  • Byte 1: Reserved (should always be 00)
  • Bytes 2..7: Hexadecimal values for ASCII-encoded characters (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! 

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

A list of HID keyboard codes can be found here (see section 7).

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

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. 
# 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. Voir les valeurs ci-dessous.
  • Output: Normally none.

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 as parameter. A full list of 16-bit 'HID Consumer Control Key Codes' can be found here (see section 12).

Stop
 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. 
# 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:
    • 1 ou on
    • 0 ou off
  • 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:
    • Axe 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
    • Axe 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
    • Boutons: 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. 
# 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:
    • 1 ou on
    • 0 ou off
  • 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. 
# 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:
    • 1 ou on
    • 0 ou off
  • 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+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

Basé sur "Bluefruit LE Shield" d'Adafruit Industries, écrit par Kevin Townsend - Traduit en Français par shop.mchobby.be CC-BY-SA pour la traduction
Toute copie doit contenir ce crédit, lien vers cette page et la section "crédit de traduction".

Based on "Bluefruit LE Shield" from Adafruit Industries, written by Kevin Townsend - Translated to French by shop.mchobby.be CC-BY-SA for the translation
Copies must includes this credit, link to this page and the section "crédit de traduction" (translation credit).

Traduit avec l'autorisation d'AdaFruit Industries - Translated with the permission from Adafruit Industries - www.adafruit.com

Récupérée de « https://wiki.mchobby.be/index.php?title=Bluefruit-LE-Shield-BLE-Services&oldid=23610 »