Bluefruit-LE-Shield-BLE-Services
Services BLE
En cours de traduction/élaboration. |
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)
NOTE SUR LES SEQUENCES D'ECHAPPEMENT: Si vous essayez d'envoyer les séquences d'échappement dans le code par l'intermédiaire d'une instruction telle que 'ble.print("...");' prenez note qu'il vous vaudra utiliser des double-back-slash pour le code d'échappement d'une commande AT. Par exemple: ble.println("AT+BLEUARTTX=Some Test\\r\\n"); |
Vous devez être connecté sur un autre périphérique pour que cette commande s'éxécute. |
# 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:
Note: La vérification complète de la mémoire tampon FIFO d'émission sera réalisé pour chaque transaction GATT (jusqu'à 20 octets de donnée par transaction), par conséquent, les importants transferts de donnée peuvent rencontrer plusieurs fois des délais d'attente de 200ms. |
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
Lors de grand transfert de donnée, il est possible qu'une partie du payload soit transmit, et que la commande produise une erreur si la mémoire tampon FIFO d'émission ne se vide pas dans les temps au milieu du processus de transfert des données (les données sont transmissent par paquet de 20 octets).
Vous devriez toujours vérifier la taille de la mémoire tampon FIFO d'émission si vous désirez assurer un transfert fiable. La commande AT+BLEUARTFIFO permet de connaître cette taille. Si la taille n'est pas suffisante pour inclure votre payload alors introduisez un délai d'attente dans votre programme pour laisser l'opportunité à la mémoire tampon de se vider. De simples commande AT+BLEUARTTX peuvent tenir dans le FIFO, mais de multiple instance de cette commande (avec donnée) peuvent remplir le FIFO en cours de transfert. |
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
Cette commande fait un dump de la mémoire tampon de réception du service UART sur l'écran (si le service UART à reçu des données pendant l'exécution en mode de commande). Les données seront retirée de la mémoire tampon une fois affichées en utilisant cette commande.
Tout caractère laissé dans la mémoire tampon en repassant en mode Data provoquera l'affichage des caractères de la mémoire tampon dès la fin du changement de mode (dans les limites de l'espace disponible dans la mémoire tampon, qui est de 1024 octets --ou 160 octets pour pour la première génération des cartes BLEFriend).
- Codebase Revision: 0.3.0
- Paramètres: Aucun
- Sortie: Le contenu de la mémoire tampon en réception (RX buffer) s'il y en a des données disponibles. Sinon rien.
Vous pouvez également utiliser la commande AT+BLEUARTFIFO=RX pour voir s'il n'y a des données disponibles. |
# Résultat de la commande lorsqu'il y en a de disponible AT+BLEUARTRX Sent from Android OK # Résultat de la commande lorsqu'il n'y a pas de donnée disponible AT+BLEUARTRX OK
AT+BLEUARTFIFO
Cette commande retournera l'espace disponible dans les FIFOs de l'UART BLE (les mémoires tampons TX et RX). Si vous transmettez de grandes quantités de données, vous pourriez avoir besoin de vérifier si vous avez assez d'espace libre dans la mémoire tampon FIFO TX avant l'émission. Gardez à l'esprit que les paquet GATT individuels peuvent chacun contenir 20 octets (données utilisateur).
- Codebase Revision: 0.6.7
- Paramètre: exécuter cette commande sans paramètre retournera les valeurs (séparée par des virgules) indiquant l'espace disponible dans la mémoire tampon de d'émission (buffer TX), suivit de la mémoire tampon en réception (RX buffer). Pour faire une requête sur une mémoire tampon spécifique, vous pouvez exécuter la commande avec soit la valeur "TX" ou "RX" (Par exemple: "AT+BLEUARTFIFO=TX").
- Sortie: L'espace libre dans les mémoires tampons en émission et réception (TX and RX FIFO buffer). S'il y a un paramètre complémentaire, seul le buffer concerné retourna l'information souhaitée.
AT+BLEUARTFIFO 1024,1024 OK AT+BLEUARTFIFO=TX 1024 OK AT+BLEUARTFIFO=RX 1024 OK
AT+BLEKEYBOARDEN
Cette commande va activer le support "GATT over HID" (GoH) - le support clavier, ce qui vous permet d'émuler un clavier sur les périphériques iOS et Android.
Par défaut, ce support clavier HID est désactivé. Par conséquent fixez BLEKEYBOARDEN à 1 puis effectuez une réinitialisation système avant que le "clavier" soit énuméré et apparaisse dans les préférences Bluetooth de votre téléphone (où il pourra être lié comme clavier BLE).
- Codebase Revision: 0.5.0
- Paramètres: 1 ou 0 (1 = activer, 0 = désactiver)
- Sortie: Aucun
Depuis le firmware 0.6.6 cette commande est un alias pour AT+BLEHIDEN |
Vous devez effectuer une réinitialisation système (ATZ) avant que les changements soient effectifs! |
Avant de pouvoir utiliser votre clavier "HID over GATT", vous aurez besoin de lier le module Bluefruit LE avec votre mobile (dans le panneau des préférences Bluetooth). |
# Activer le support clavier BLE puis réinitialisation AT+BLEKEYBOARDEN=1 OK ATZ OK # Désactive le support clavier puis réinitialisation AT+BLEKEYBOARDEN=0 OK ATZ OK
AT+BLEKEYBOARD
En cours de traduction/élaboration. |
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).
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