30 017
modifications
Modifications
Sauter à la navigation
Sauter à la recherche
Bluefruit-LE-Shield-BLE-GATT (voir la source)
Version du 22 juin 2017 à 13:34
, 22 juin 2017 à 13:34Page créée avec « {{Bluefruit-LE-Shield-NAV}} == GATT BLE == [https://learn.adafruit.com/introduction-to-bluetooth-low-energy/gatt GATT], which standards for the ''Generic ATTribute Profil... »
{{Bluefruit-LE-Shield-NAV}}
== GATT BLE ==
[https://learn.adafruit.com/introduction-to-bluetooth-low-energy/gatt GATT], which standards for the ''Generic ATTribute Profile'', governs data organization and data exchanges between connected devices. One device (the peripheral) acts as a GATT Server, which stores data in Attribute records, and the second device in the connection (the central) acts as a GATT Client, requesting data from the server whenever necessary.
The following commands can be used to create custom GATT services and characteristics on the BLEFriend, which are used to store and exchange data.
Please note that any characteristics that you define here will automatically be saved to non-volatile FLASH config memory on the device and re-initialised the next time the device starts.
{{ambox|text=You need to perform a system reset via 'ATZ' before most of the commands below will take effect!}}
== Limitations de GATT ==
The commands below have the following limitations due to SRAM and resource availability, which should be kept in mind when creating or working with customer GATT services and characteristics.
These values apply to firmware 0.7.0 and higher:
* Maximum number of services: 10
* Maximum number of characteristics: 30
* Maximum buffer size for each characteristic: 32 bytes
* Maximum number of CCCDs: 16
If you want to clear any previous config value, enter the ''AT+FACTORYRESET'' command before working on a new peripheral configuration.
== AT+GATTCLEAR ==
Clears any custom GATT services and characteristics that have been defined on the device.
* Codebase Revision: 0.3.0
* Parameters: None
* Response: None
<nowiki>AT+GATTCLEAR
OK</nowiki>
== AT+GATTADDSERVICE ==
Adds a new custom service definition to the device.
* Codebase Revision: 0.3.0
* Parameters: This command accepts a set of comma-separated key-value pairs that are used to define the service properties. The following key-value pairs can be used:
** '''UUID''': The 16-bit UUID to use for this service. 16-bit values should be in hexadecimal format (0x1234).
** '''UUID128''': The 128-bit UUID to use for this service. 128-bit values should be in the following format: 00-11-22-33-44-55-66-77-88-99-AA-BB-CC-DD-EE-FF
* Réponse: The index value of the service in the custom GATT service lookup table. (It's important to keep track of these index values to work with the service later.)
{{ambox-stop|text=Note: Key values are not case-sensitive}}
{{ambox-stop|text=Only one UUID type can be entered for the service (either UUID or UUID128)}}
<nowiki># Clear any previous custom services/characteristics
AT+GATTCLEAR
OK
# Add a battery service (UUID = 0x180F) to the peripheral
AT+GATTADDSERVICE=UUID=0x180F
1
OK
# Add a battery measurement characteristic (UUID = 0x2A19), notify enabled
AT+GATTADDCHAR=UUID=0x2A19,PROPERTIES=0x10,MIN_LEN=1,VALUE=100
1
OK</nowiki>
<nowiki># Clear any previous custom services/characteristics
AT+GATTCLEAR
OK
# Add a custom service to the peripheral
AT+GATTADDSERVICE=UUID128=00-11-00-11-44-55-66-77-88-99-AA-BB-CC-DD-EE-FF
1
OK
# Add a custom characteristic to the above service (making sure that there
# is no conflict between the 16-bit UUID and bytes 3+4 of the 128-bit service UUID)
AT+GATTADDCHAR=UUID=0x0002,PROPERTIES=0x02,MIN_LEN=1,VALUE=100
1
OK</nowiki>
== AT+GATTADDCHAR ==
Adds a custom characteristic to the last service that was added to the peripheral (via AT+GATTADDSERVICE).
{{ambox-stop|text= AT+GATTADDCHAR must be run AFTER AT+GATTADDSERVICE, and will add the new characteristic to the last service definition that was added.}}
{{ambox|text= As of version 0.6.6 of the Bluefruit LE firmware you can now use custom 128-bit UUIDs with this command. See the example at the bottom of this command description.}}
* Codebase Revision : 0.3.0
* Parameters : This command accepts a set of comma-separated key-value pairs that are used to define the characteristic properties. The following key-value pais can be used:
** '''UUID''' : The 16-bit UUID to use for the characteristic (which will be insert in the 3rd and 4th bytes of the parent services 128-bit UUID). This value should be entered in hexadecimal format (ex. 'UUID=0x1234'). This value must be unique, and should not conflict with bytes 3+4 of the parent service's 128-bit UUID.
** '''PROPERTIES''' : The 8-bit characteristic properties field, as defined by the Bluetooth SIG. The following values can be used:
*** 0x02 - Read
*** 0x04 - Write Without Response
*** 0x08 - Write
*** 0x10 - Notify
*** 0x20 - Indicate
** '''MIN_LEN''' : The minimum size of the values for this characteristic (in bytes, min = 1, max = 20, default = 1)
** '''MAX_LEN''' : The maximum size of the values for the characteristic (in bytes, min = 1, max = 20, default = 1)
** '''VALUE''' : The initial value to assign to this characteristic (within the limits of 'MIN_LEN' and 'MAX_LEN'). Value can be an integer ("-100", "27"), a hexadecimal value ("0xABCD"), a byte array ("aa-bb-cc-dd") or a string ("GATT!").
** '''>=0.7.0 - DATATYPE''' : This argument indicates the data type stored in the characteristic, and is used to help parse data properly. It can be one of the following values:
*** AUTO (0, default)
*** STRING (1)
*** BYTEARRAY (2)
*** INTEGER (3)
** '''>=0.7.0 - DESCRIPTION''': Adds the specified string as the characteristic description entry
** '''>=0.7.0 - PRESENTATION''': Adds the specified value as the characteristic presentation format entry
* '''Response''': The index value of the characteristic in the custom GATT characteristic lookup table. (It's important to keep track of these characteristic index values to work with the characteristic later.)
{{ambox-stop|text=Note: Key values are not case-sensitive}}
{{ambox-stop|text=Make sure that the 16-bit UUID is unique and does not conflict with bytes 3+4 of the 128-bit service UUID}}
<nowiki># Clear any previous custom services/characteristics
AT+GATTCLEAR
OK
# Add a battery service (UUID = 0x180F) to the peripheral
AT+GATTADDSERVICE=UUID=0x180F
1
OK
# Add a battery measurement characteristic (UUID = 0x2A19), notify enabled
AT+GATTADDCHAR=UUID=0x2A19,PROPERTIES=0x10,MIN_LEN=1,VALUE=100
1
OK</nowiki>
<nowiki># Clear any previous custom services/characteristics
AT+GATTCLEAR
OK
# Add a custom service to the peripheral
AT+GATTADDSERVICE=UUID128=00-11-00-11-44-55-66-77-88-99-AA-BB-CC-DD-EE-FF
1
OK
# Add a custom characteristic to the above service (making sure that there
# is no conflict between the 16-bit UUID and bytes 3+4 of the 128-bit service UUID)
AT+GATTADDCHAR=UUID=0x0002,PROPERTIES=0x02,MIN_LEN=1,VALUE=100
1
OK</nowiki>
Version '''0.6.6''' of the Bluefruit LE firmware added the ability to use a new "'''UUID128'''" flag to add custom 128-bit UUIDs that aren't related to the parent service UUID (which is used when passing the 16-bit "'''UUID'''" flag).
To specify a 128-bit UUID for your customer characteristic, enter a value resembling the following syntax:
<nowiki># Add a custom characteristic to the above service using a
# custom 128-bit UUID
AT+GATTADDCHAR=UUID128=00-11-22-33-44-55-66-77-88-99-AA-BB-CC-DD-EE-FF,PROPERTIES=0x02,MIN_LEN=1,VALUE=100
1
OK</nowiki>
Version '''0.7.0''' of the Bluefruit LE firmware added the new '''DESCRIPTION''' and '''PRESENTATION''' keywoards, corresponding the the GATT [https://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.characteristic_user_description.xml Characteristic User Description] and the GATT [https://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.characteristic_presentation_format.xml Characteristic Presentation Format] Descriptors.
The '''DESCRIPTION''' field is a string that contains a short text description of the characteristic. Some apps may not display this data, but it should be visible using something like the Master Control Panel application from Nordic on iOS and Android.
The '''PRESENTATION''' field contains a 7-byte payload that encapsulates the characteristic presentation format data. It requires a specific set of bytes and values to work properly. See the following link for details on how to format the payload: https://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.characteristic_presentation_format.xml
The following example shows how you might use both of these new fields:
<nowiki>AT+GATTADDCHAR=UUID=0x2A37, PROPERTIES=0x10, MIN_LEN=2, MAX_LEN=3, VALUE=00-40,
DESCRIPTION=HRM Measurement, PRESENTATION=17-00-AC-27-01-00-00</nowiki>
For the Characteristic Presentation Format we have:
* Format = IEEE-11073 32-bit FLOAT (Decimal 23, Hex 0x17)
* Exponent = 0/None
* Unit = Thermodynamic temperature: Degrees Fahrenheit (0x27AC) - Bluetooth LE Unit List
* Namespace = Bluetooth SIG Assigned Number (0x01)
* Description = None (0x0000)
The results from Nordic's Master Control Panel app can be seen below:
{{Bluefruit-LE-Shield-TRAILER}}
== GATT BLE ==
[https://learn.adafruit.com/introduction-to-bluetooth-low-energy/gatt GATT], which standards for the ''Generic ATTribute Profile'', governs data organization and data exchanges between connected devices. One device (the peripheral) acts as a GATT Server, which stores data in Attribute records, and the second device in the connection (the central) acts as a GATT Client, requesting data from the server whenever necessary.
The following commands can be used to create custom GATT services and characteristics on the BLEFriend, which are used to store and exchange data.
Please note that any characteristics that you define here will automatically be saved to non-volatile FLASH config memory on the device and re-initialised the next time the device starts.
{{ambox|text=You need to perform a system reset via 'ATZ' before most of the commands below will take effect!}}
== Limitations de GATT ==
The commands below have the following limitations due to SRAM and resource availability, which should be kept in mind when creating or working with customer GATT services and characteristics.
These values apply to firmware 0.7.0 and higher:
* Maximum number of services: 10
* Maximum number of characteristics: 30
* Maximum buffer size for each characteristic: 32 bytes
* Maximum number of CCCDs: 16
If you want to clear any previous config value, enter the ''AT+FACTORYRESET'' command before working on a new peripheral configuration.
== AT+GATTCLEAR ==
Clears any custom GATT services and characteristics that have been defined on the device.
* Codebase Revision: 0.3.0
* Parameters: None
* Response: None
<nowiki>AT+GATTCLEAR
OK</nowiki>
== AT+GATTADDSERVICE ==
Adds a new custom service definition to the device.
* Codebase Revision: 0.3.0
* Parameters: This command accepts a set of comma-separated key-value pairs that are used to define the service properties. The following key-value pairs can be used:
** '''UUID''': The 16-bit UUID to use for this service. 16-bit values should be in hexadecimal format (0x1234).
** '''UUID128''': The 128-bit UUID to use for this service. 128-bit values should be in the following format: 00-11-22-33-44-55-66-77-88-99-AA-BB-CC-DD-EE-FF
* Réponse: The index value of the service in the custom GATT service lookup table. (It's important to keep track of these index values to work with the service later.)
{{ambox-stop|text=Note: Key values are not case-sensitive}}
{{ambox-stop|text=Only one UUID type can be entered for the service (either UUID or UUID128)}}
<nowiki># Clear any previous custom services/characteristics
AT+GATTCLEAR
OK
# Add a battery service (UUID = 0x180F) to the peripheral
AT+GATTADDSERVICE=UUID=0x180F
1
OK
# Add a battery measurement characteristic (UUID = 0x2A19), notify enabled
AT+GATTADDCHAR=UUID=0x2A19,PROPERTIES=0x10,MIN_LEN=1,VALUE=100
1
OK</nowiki>
<nowiki># Clear any previous custom services/characteristics
AT+GATTCLEAR
OK
# Add a custom service to the peripheral
AT+GATTADDSERVICE=UUID128=00-11-00-11-44-55-66-77-88-99-AA-BB-CC-DD-EE-FF
1
OK
# Add a custom characteristic to the above service (making sure that there
# is no conflict between the 16-bit UUID and bytes 3+4 of the 128-bit service UUID)
AT+GATTADDCHAR=UUID=0x0002,PROPERTIES=0x02,MIN_LEN=1,VALUE=100
1
OK</nowiki>
== AT+GATTADDCHAR ==
Adds a custom characteristic to the last service that was added to the peripheral (via AT+GATTADDSERVICE).
{{ambox-stop|text= AT+GATTADDCHAR must be run AFTER AT+GATTADDSERVICE, and will add the new characteristic to the last service definition that was added.}}
{{ambox|text= As of version 0.6.6 of the Bluefruit LE firmware you can now use custom 128-bit UUIDs with this command. See the example at the bottom of this command description.}}
* Codebase Revision : 0.3.0
* Parameters : This command accepts a set of comma-separated key-value pairs that are used to define the characteristic properties. The following key-value pais can be used:
** '''UUID''' : The 16-bit UUID to use for the characteristic (which will be insert in the 3rd and 4th bytes of the parent services 128-bit UUID). This value should be entered in hexadecimal format (ex. 'UUID=0x1234'). This value must be unique, and should not conflict with bytes 3+4 of the parent service's 128-bit UUID.
** '''PROPERTIES''' : The 8-bit characteristic properties field, as defined by the Bluetooth SIG. The following values can be used:
*** 0x02 - Read
*** 0x04 - Write Without Response
*** 0x08 - Write
*** 0x10 - Notify
*** 0x20 - Indicate
** '''MIN_LEN''' : The minimum size of the values for this characteristic (in bytes, min = 1, max = 20, default = 1)
** '''MAX_LEN''' : The maximum size of the values for the characteristic (in bytes, min = 1, max = 20, default = 1)
** '''VALUE''' : The initial value to assign to this characteristic (within the limits of 'MIN_LEN' and 'MAX_LEN'). Value can be an integer ("-100", "27"), a hexadecimal value ("0xABCD"), a byte array ("aa-bb-cc-dd") or a string ("GATT!").
** '''>=0.7.0 - DATATYPE''' : This argument indicates the data type stored in the characteristic, and is used to help parse data properly. It can be one of the following values:
*** AUTO (0, default)
*** STRING (1)
*** BYTEARRAY (2)
*** INTEGER (3)
** '''>=0.7.0 - DESCRIPTION''': Adds the specified string as the characteristic description entry
** '''>=0.7.0 - PRESENTATION''': Adds the specified value as the characteristic presentation format entry
* '''Response''': The index value of the characteristic in the custom GATT characteristic lookup table. (It's important to keep track of these characteristic index values to work with the characteristic later.)
{{ambox-stop|text=Note: Key values are not case-sensitive}}
{{ambox-stop|text=Make sure that the 16-bit UUID is unique and does not conflict with bytes 3+4 of the 128-bit service UUID}}
<nowiki># Clear any previous custom services/characteristics
AT+GATTCLEAR
OK
# Add a battery service (UUID = 0x180F) to the peripheral
AT+GATTADDSERVICE=UUID=0x180F
1
OK
# Add a battery measurement characteristic (UUID = 0x2A19), notify enabled
AT+GATTADDCHAR=UUID=0x2A19,PROPERTIES=0x10,MIN_LEN=1,VALUE=100
1
OK</nowiki>
<nowiki># Clear any previous custom services/characteristics
AT+GATTCLEAR
OK
# Add a custom service to the peripheral
AT+GATTADDSERVICE=UUID128=00-11-00-11-44-55-66-77-88-99-AA-BB-CC-DD-EE-FF
1
OK
# Add a custom characteristic to the above service (making sure that there
# is no conflict between the 16-bit UUID and bytes 3+4 of the 128-bit service UUID)
AT+GATTADDCHAR=UUID=0x0002,PROPERTIES=0x02,MIN_LEN=1,VALUE=100
1
OK</nowiki>
Version '''0.6.6''' of the Bluefruit LE firmware added the ability to use a new "'''UUID128'''" flag to add custom 128-bit UUIDs that aren't related to the parent service UUID (which is used when passing the 16-bit "'''UUID'''" flag).
To specify a 128-bit UUID for your customer characteristic, enter a value resembling the following syntax:
<nowiki># Add a custom characteristic to the above service using a
# custom 128-bit UUID
AT+GATTADDCHAR=UUID128=00-11-22-33-44-55-66-77-88-99-AA-BB-CC-DD-EE-FF,PROPERTIES=0x02,MIN_LEN=1,VALUE=100
1
OK</nowiki>
Version '''0.7.0''' of the Bluefruit LE firmware added the new '''DESCRIPTION''' and '''PRESENTATION''' keywoards, corresponding the the GATT [https://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.characteristic_user_description.xml Characteristic User Description] and the GATT [https://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.characteristic_presentation_format.xml Characteristic Presentation Format] Descriptors.
The '''DESCRIPTION''' field is a string that contains a short text description of the characteristic. Some apps may not display this data, but it should be visible using something like the Master Control Panel application from Nordic on iOS and Android.
The '''PRESENTATION''' field contains a 7-byte payload that encapsulates the characteristic presentation format data. It requires a specific set of bytes and values to work properly. See the following link for details on how to format the payload: https://developer.bluetooth.org/gatt/descriptors/Pages/DescriptorViewer.aspx?u=org.bluetooth.descriptor.gatt.characteristic_presentation_format.xml
The following example shows how you might use both of these new fields:
<nowiki>AT+GATTADDCHAR=UUID=0x2A37, PROPERTIES=0x10, MIN_LEN=2, MAX_LEN=3, VALUE=00-40,
DESCRIPTION=HRM Measurement, PRESENTATION=17-00-AC-27-01-00-00</nowiki>
For the Characteristic Presentation Format we have:
* Format = IEEE-11073 32-bit FLOAT (Decimal 23, Hex 0x17)
* Exponent = 0/None
* Unit = Thermodynamic temperature: Degrees Fahrenheit (0x27AC) - Bluetooth LE Unit List
* Namespace = Bluetooth SIG Assigned Number (0x01)
* Description = None (0x0000)
The results from Nordic's Master Control Panel app can be seen below:
{{Bluefruit-LE-Shield-TRAILER}}