Bluefruit-LE-Shield-BLE-Services

Services BLE

Les commandes suivantes vous permettent d'interagir avec les différents services GATT présent sur les modules Bluefruit LE lorsque celui-ci fonctionne en mode commande.

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

Cette commande transmet le message texte spécifié en paramètre via le Service UART pendant que le module fonctionne en mode commande.

• Codebase Revision: 0.3.0
• Paramètre: Le payload (données) à transmettre. Le payload peut faire jusqu'à 240 caractères (étant donné que les commandes AT sont limitées à un maximum de 256 octet).
• Sortie: Cette commande produit le message erreur ERROR s'il n'est pas possible de se connecter sur le périphérique central, ou si la mémoire tampon d'émission interne du BluFruit (internal TX FIFO) est remplie.

Sur un firmware 0.6.2 et supérieur, AT+BLEUARTTX peut accepter quelques séquences d'échappements:

• \r = retour clavier
• \n = Nouvelle ligne
• \t = Tabulation
• \b = retour en arrière (backspace)
• \\ = Anti-slash

Sur un firmware 0.6.7 et supérieur, AT+BLEUARTTX peut accepter la séquence d'échappement suivante (puisque AT+BLEUARTTX=? à une signification particulière pour le parseur AT):

• \? = transmet un simple point d'interrogation

Sur un firmware 0.7.6 et supérieur, AT+BLEUARTTX peut accepter les séquences d'échappement suivantes:

• \+ = Transmet un simple caractère '+' sans avoir à s’inquiéter de la combinaison de `+++` (changement de mode)

# Envoi une chaîne de caractère lorsqu'il 
# est connecté sur un autre périphérique
AT+BLEUARTTX=THIS IS A TEST
OK
  
# Réponse lorsque le Bluefruit n'est pas connecté 
# sur un autre périphérique
AT+BLEUARTTX=THIS IS A TEST
ERROR

Gestion de la mémoire tampon de réception

Depuis le firmware 0.6.7, lorsque la mémoire tampon FIFO d'émission est saturée (TX FIFO buffer), un délai bloquant de 200ms est utilisé pour voir si de l'espace se libère dans la pile FIFO avant de retourner une erreur (le message "ERROR"). Le processus exact est détaillé dans le graphique suivant:

Vous pouvez utiliser la commande AT+BLEUARTFIFO=TX pour vérifier la taille du buffer FIFO d'émission avant d'envoyer des donnée. Cela permet de s'assurer qu'il y a assez de place libre dans le buffer.

La mémoire tampon (buffer) d'émission à la taille suivante (la taille dépend de la version du Firmware utilisé):

• Firmware <=0.6.6: 160 caractères
• Firmware >=0.6.7: 1024 caractères

AT+BLEUARTTXF

C'est une fonction commode qui réalise la même fonction que AT+BLEUARTTX mais un envoi immédiat dans un simple packet BLE ('F' pour Forcer le paquet). Cette commande acceptera un maximum de 20 caractères, ce qui est la limite de ce qui peut être envoyé dans un seul paquet.

• Codebase Revision: 0.7.6
• Paramètres: voyez AT+BLEUARTTX
• Sortie: voyez 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).

• 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

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

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

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

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

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

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

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