Robo.Fish Wiki - User contributions [en]

Fischertechnik Maker Kit Car

2025-05-20T18:15:43Z

Kai: /* Traction and Steering */

The ''fischertechnik Maker Kit Car'' is a toy-sized vehicle platform constructed of plastic molded parts from the fischertechnik parts library, combined with a low-rpm brushed DC motor and a tiny servo motor for powering the rear-wheel drive and front-wheel steering, respectively.

== Unboxing and Assembling ==

[[File:ft-mkc-1.jpg | x350px | a look inside the box]] [[File:ft-mkc-2.jpg | x350px | box contents laid out]]

== Traction and Steering ==

[[Media:ft-mkc-moving.mov]]

Fischertechnik Maker Kit Car

2025-05-20T18:12:53Z

Kai:

Fischertechnik Maker Kit Car

2025-05-20T18:11:29Z

Kai: /* Unboxing and Assembling */

Fischertechnik Maker Kit Car

2025-05-20T16:28:50Z

Kai: /* Unboxing and Assembling */

The ''fischertechnik Maker Kit Car'' is a toy-sized vehicle platform constructed of plastic molded parts from the fischertechnik parts library, combined with a low-rpm brushed DC motor and a tiny servo motor for powering the rear-wheel drive and front-wheel steering, respectively.

== Unboxing and Assembling ==

[[File:ft-mkc-1.jpg| x350 | a look inside the box]]

[[File:ft-mkc-2.jpg| x350 | box contents laid out]]

File:Ft-mkc-2.jpg

2025-05-20T16:28:14Z

Kai:

File:Ft-mkc-1.jpg

2025-05-20T16:27:46Z

Kai:

Fischertechnik Maker Kit Car

2025-05-20T16:26:38Z

Kai: Created page with "The ''fischertechnik Maker Kit Car'' is a toy-sized vehicle platform constructed of plastic molded parts from the fischertechnik parts library, combined with a low-rpm brushed DC motor and a tiny servo motor for powering the rear-wheel drive and front-wheel steering, respectively. == Unboxing and Assembling == a look inside the box box contents laid out"

The ''fischertechnik Maker Kit Car'' is a toy-sized vehicle platform constructed of plastic molded parts from the fischertechnik parts library, combined with a low-rpm brushed DC motor and a tiny servo motor for powering the rear-wheel drive and front-wheel steering, respectively.

== Unboxing and Assembling ==

[[File:ft-mkc-1.jpg| x400 | a look inside the box]]

[[File:ft-mkc-2.jpg| x400 | box contents laid out]]

LT2

2025-05-20T16:16:17Z

Kai: Created page with "The LT2 uses the toy-sized fischertechnik Maker Kit Car molded-plastic vehicle platform that is rear-wheel driven and front-wheel steered, like a full-sized car. Motor control therefore differs from the Arexx RP5 used in the LT1. == Hardware Components == * Raspberry Pi Pico W 2 microcontroller as RSA * Raspberry Pi Compute Module 5 as RTC * Raspberry Pi Camera Module 3 * HC-SR04 ultrasonic range sensor..."

The LT2 uses the toy-sized [[fischertechnik Maker Kit Car]] molded-plastic vehicle platform that is rear-wheel driven and front-wheel steered, like a full-sized car. Motor control therefore differs from the [[Arexx RP5]] used in the [[LT1]].

== Hardware Components ==
* Raspberry Pi Pico W 2 microcontroller as [[Robot State Agent | RSA]]
* Raspberry Pi Compute Module 5 as [[Robot Task Controller | RTC]]
* Raspberry Pi Camera Module 3
* [[HC-SR04]] ultrasonic range sensor
* [[fischertechnik Maker Kit Car]] chassis

Main Page

2025-05-20T15:53:04Z

Kai:

<div class="row">
<div class="medium-6 columns">
<div class="row">
<div class="small-offset-2 small-8 columns" style="margin: 0; padding: 0">
<div style="background-color:#bbb; color:white;text-align:center; display:block">
Products
</div>
<div style="border: 0px solid black">
* [[FishNet]]
* [[Underwater Data | Underwater]]
* [[RFX]]
</div>
</div>
</div>
</div>
<div class="medium-6 columns">
<div class="row">
<div class="small-offset-2 small-8 columns" style="margin: 0; padding: 0">
<div style="background-color:#bbb; color:white; text-align:center">
Milestones
</div>
<div>
* [[Core Module]]
* land trainer [[LT0]]
* land trainer [[LT1]]
* land trainer [[LT2]]
* robo fish [[RF0]]
* robo fish [[RF1]]
</div>
</div>
</div>
</div>
</div>

<div class="row">
<div class="medium-6 columns">
<div class="row">
<div class="small-offset-2 small-8 columns" style="margin: 0; padding: 0">
<div style="background-color:#bbb; color:white;text-align:center">
"How To" Notes
</div>
<div>
* [[Computer Vision]]
* [[Artificial Intelligence]]
* [[Robotics]]
* [[Circuit Design]]
* [[3D Printing]]
* [[Build Engineering]]
</div>
</div>
</div>
</div>
<div class="medium-6 columns">
<div class="row">
<div class="small-offset-2 small-8 columns" style="margin: 0; padding: 0">
<div style="background-color:#bbb; color:white; text-align:center">
Third Party
</div>
<div>
* [[Third-Party Software]]
* [[Publications | Collected Publications]]
</div>
</div>
</div>
</div>
</div>

<br />
<br />

<div class="row">
<div class="small-centered small-4 medium-centered medium-3 large-centered large-3 columns">[[File:splash.png]]</div>
</div>

GATT Profile Data in Bluetooth Low Energy

2025-05-10T08:27:41Z

Kai: /* Property Flags */

This article explains the binary structure of the GATT attributes data array that many Bluetooth Low Energy application frameworks, like [https://bluekitchen-gmbh.com/btstack BTstack], expect as setup input.

= GATT characteristic attribute (descriptor) types =

== Characteristic declaration ==

Let's have a look at an ATT attribute that declares a GATT characteristic. Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification].

== Characteristic value ==

<pre>
0x16, 0x00, 0x02, 0x03, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right as follows:
* 2 bytes for the length of the attribute: 0x0016 (= 22 bytes)
* 2 bytes for the combined properties and access permissions bitmasks of the attribute: 0x0302 (= read-only, dynamic, 128-bit UUID)
* 2 bytes for the handle of the attribute: 0x0009
* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101

The bitmask the determines the access permissions (or properties) for the value have an effect on the performance the communication between GATT client and server. A write operation that does not require waiting for an acknowledgement from the server is better suited, for example, for applications in which the client sends a stream of values to the server and it does not matter if some of the values are lost or overwritten by by the next value before the server can respond.

==== Access Permission Flags ====
The following table (from the Bluetooth 5.4 specification) defines the flags for the 8-bit ''access permissions'' bitmask:
{| class="wikitable" style="margin:right"
|-
! Property !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

==== Property Flags ====
This table lists the flags for the 8-bit ''properties'' bitmask (the higher byte that is grouped with the access permissions byte), the contents of which are not part of the Bluetooth Core Specification. These can be used Bluetooth frameworks for implementation-specific features.

{| class="wikitable" style="margin:right"
|-
! Property !! Value !! Description
|-
| Dynamic || 0x01 || indicates in BTstack that read/write operations are implemented by custom user code
|-
| Long UUID || 0x02 || indicates that the UUID of the associated characteristic is 128 bits long (instead of 16 bits)
|-
|}

== Characteristic Client Configuration ==

The client configuration attribute of a GATT characteristic allows the GATT client to change the notify (or indicate) behavior for value write operations. Let us examine the sections of this example attribute:
<pre>
0x0a, 0x00, 0x0e, 0x01, 0x0e, 0x00, 0x02, 0x29, 0x00, 0x00
</pre>
From left to right, there are
* 2 bytes for the length of the attribute: 0x000a (= 10 bytes)
* 2 bytes for the permissions of this attribute: 0x010e (indicates read | write | write_without_response, dynamic)
* 2 bytes for the handle of this attribute: 0x000e
* 2 bytes for the short 16-bit UUID of this attribute: 0x2902 (the UUID for client characteristic configuration)
* 2 bytes that indicate whether notification or indication messages are enabled: 0x0000 (both type of messages are disabled)

For the last two bytes, the following options are possible, depending on the requests from the GATT client to enable or disable notification or indication messages (when the value of the associated characteristic changes):
{| class="wikitable" style="margin:right"
|-
| bit 0 || the least significant bit indicates whether sending notifications is enabled (1) or disabled (0)
|-
| bit 1 || the next significant bit indicates whether sending indications is enabled (1) or not (0)
|-
|}
All other bits are reserved for use in future changes to the GATT protocol.

== User description ==

Here is an example binary sequence for a GATT user description attribute.
<pre>
0x08, 0x00, 0x0a, 0x01, 0x0a, 0x00, 0x01, 0x29
</pre>

Let's break down the byte grouping from left to right:
* 2 bytes for the length of this attribute: 0x0008 (= 8 bytes)
* 2 bytes for permissions: 0x010a (= read, write, dynamic)
* 2 bytes for the handle of this attribute
* 2 bytes for the 16-bit short UUID that indicates a user description attribute: 0x2901
where the order of the bytes in each group needs to be reversed before analyzing.

The attribute declaration does not include the user description text itself. User description text is always "dynamic", meaning that it is served to the client on demand on the basis of the attribute handle. In BTstack, the implementation of the read callback is responsible for returning the UTF-8 bytes for the text string corresponding the attribute handle.

GATT Profile Data in Bluetooth Low Energy

2025-05-10T07:18:45Z

Kai:

This article explains the binary structure of the GATT attributes data array that many Bluetooth Low Energy application frameworks, like [https://bluekitchen-gmbh.com/btstack BTstack], expect as setup input.

= GATT characteristic attribute (descriptor) types =

== Characteristic declaration ==

Let's have a look at an ATT attribute that declares a GATT characteristic. Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification].

== Characteristic value ==

<pre>
0x16, 0x00, 0x02, 0x03, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right as follows:
* 2 bytes for the length of the attribute: 0x0016 (= 22 bytes)
* 2 bytes for the combined properties and access permissions bitmasks of the attribute: 0x0302 (= read-only, dynamic, 128-bit UUID)
* 2 bytes for the handle of the attribute: 0x0009
* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101

The bitmask the determines the access permissions (or properties) for the value have an effect on the performance the communication between GATT client and server. A write operation that does not require waiting for an acknowledgement from the server is better suited, for example, for applications in which the client sends a stream of values to the server and it does not matter if some of the values are lost or overwritten by by the next value before the server can respond.

==== Access Permission Flags ====
The following table (from the Bluetooth 5.4 specification) defines the flags for the 8-bit ''access permissions'' bitmask:
{| class="wikitable" style="margin:right"
|-
! Property !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

==== Property Flags ====
This table lists the flags for the 8-bit ''properties'' bitmask (the higher byte that is grouped with the access permissions byte)

{| class="wikitable" style="margin:right"
|-
! Property !! Value !! Description
|-
| Dynamic || 0x01 || indicates to the BLE framework (e.g., BTstack) that read/write operations are implemented by custom user code
|-
| Long UUID || 0x02 || indicates that the UUID of the associated characteristic is 128 bits long (instead of 16 bits)
|-
|}

== Characteristic Client Configuration ==

The client configuration attribute of a GATT characteristic allows the GATT client to change the notify (or indicate) behavior for value write operations. Let us examine the sections of this example attribute:
<pre>
0x0a, 0x00, 0x0e, 0x01, 0x0e, 0x00, 0x02, 0x29, 0x00, 0x00
</pre>
From left to right, there are
* 2 bytes for the length of the attribute: 0x000a (= 10 bytes)
* 2 bytes for the permissions of this attribute: 0x010e (indicates read | write | write_without_response, dynamic)
* 2 bytes for the handle of this attribute: 0x000e
* 2 bytes for the short 16-bit UUID of this attribute: 0x2902 (the UUID for client characteristic configuration)
* 2 bytes that indicate whether notification or indication messages are enabled: 0x0000 (both type of messages are disabled)

For the last two bytes, the following options are possible, depending on the requests from the GATT client to enable or disable notification or indication messages (when the value of the associated characteristic changes):
{| class="wikitable" style="margin:right"
|-
| bit 0 || the least significant bit indicates whether sending notifications is enabled (1) or disabled (0)
|-
| bit 1 || the next significant bit indicates whether sending indications is enabled (1) or not (0)
|-
|}
All other bits are reserved for use in future changes to the GATT protocol.

== User description ==

Here is an example binary sequence for a GATT user description attribute.
<pre>
0x08, 0x00, 0x0a, 0x01, 0x0a, 0x00, 0x01, 0x29
</pre>

Let's break down the byte grouping from left to right:
* 2 bytes for the length of this attribute: 0x0008 (= 8 bytes)
* 2 bytes for permissions: 0x010a (= read, write, dynamic)
* 2 bytes for the handle of this attribute
* 2 bytes for the 16-bit short UUID that indicates a user description attribute: 0x2901
where the order of the bytes in each group needs to be reversed before analyzing.

The attribute declaration does not include the user description text itself. User description text is always "dynamic", meaning that it is served to the client on demand on the basis of the attribute handle. In BTstack, the implementation of the read callback is responsible for returning the UTF-8 bytes for the text string corresponding the attribute handle.

GATT Profile Data in Bluetooth Low Energy

2025-05-10T07:17:11Z

Kai: /* Property Flags */

This article explains the binary structure of the GATT attributes data array that many Bluetooth Low Energy application frameworks, like BTstack, expect as setup input.

= GATT characteristic attribute (descriptor) types =

== Characteristic declaration ==

Let's have a look at an ATT attribute that declares a GATT characteristic. Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification].

== Characteristic value ==

<pre>
0x16, 0x00, 0x02, 0x03, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right as follows:
* 2 bytes for the length of the attribute: 0x0016 (= 22 bytes)
* 2 bytes for the combined properties and access permissions bitmasks of the attribute: 0x0302 (= read-only, dynamic, 128-bit UUID)
* 2 bytes for the handle of the attribute: 0x0009
* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101

The bitmask the determines the access permissions (or properties) for the value have an effect on the performance the communication between GATT client and server. A write operation that does not require waiting for an acknowledgement from the server is better suited, for example, for applications in which the client sends a stream of values to the server and it does not matter if some of the values are lost or overwritten by by the next value before the server can respond.

==== Access Permission Flags ====
The following table (from the Bluetooth 5.4 specification) defines the flags for the 8-bit ''access permissions'' bitmask:
{| class="wikitable" style="margin:right"
|-
! Property !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

==== Property Flags ====
This table lists the flags for the 8-bit ''properties'' bitmask (the higher byte that is grouped with the access permissions byte)

{| class="wikitable" style="margin:right"
|-
! Property !! Value !! Description
|-
| Dynamic || 0x01 || indicates to the BLE framework (e.g., BTstack) that read/write operations are implemented by custom user code
|-
| Long UUID || 0x02 || indicates that the UUID of the associated characteristic is 128 bits long (instead of 16 bits)
|-
|}

== Characteristic Client Configuration ==

The client configuration attribute of a GATT characteristic allows the GATT client to change the notify (or indicate) behavior for value write operations. Let us examine the sections of this example attribute:
<pre>
0x0a, 0x00, 0x0e, 0x01, 0x0e, 0x00, 0x02, 0x29, 0x00, 0x00
</pre>
From left to right, there are
* 2 bytes for the length of the attribute: 0x000a (= 10 bytes)
* 2 bytes for the permissions of this attribute: 0x010e (indicates read | write | write_without_response, dynamic)
* 2 bytes for the handle of this attribute: 0x000e
* 2 bytes for the short 16-bit UUID of this attribute: 0x2902 (the UUID for client characteristic configuration)
* 2 bytes that indicate whether notification or indication messages are enabled: 0x0000 (both type of messages are disabled)

For the last two bytes, the following options are possible, depending on the requests from the GATT client to enable or disable notification or indication messages (when the value of the associated characteristic changes):
{| class="wikitable" style="margin:right"
|-
| bit 0 || the least significant bit indicates whether sending notifications is enabled (1) or disabled (0)
|-
| bit 1 || the next significant bit indicates whether sending indications is enabled (1) or not (0)
|-
|}
All other bits are reserved for use in future changes to the GATT protocol.

== User description ==

Here is an example binary sequence for a GATT user description attribute.
<pre>
0x08, 0x00, 0x0a, 0x01, 0x0a, 0x00, 0x01, 0x29
</pre>

Let's break down the byte grouping from left to right:
* 2 bytes for the length of this attribute: 0x0008 (= 8 bytes)
* 2 bytes for permissions: 0x010a (= read, write, dynamic)
* 2 bytes for the handle of this attribute
* 2 bytes for the 16-bit short UUID that indicates a user description attribute: 0x2901
where the order of the bytes in each group needs to be reversed before analyzing.

The attribute declaration does not include the user description text itself. User description text is always "dynamic", meaning that it is served to the client on demand on the basis of the attribute handle. In BTstack, the implementation of the read callback is responsible for returning the UTF-8 bytes for the text string corresponding the attribute handle.

GATT Profile Data in Bluetooth Low Energy

2025-05-10T07:09:12Z

Kai: /* Characteristic value */

This article explains the binary structure of the GATT attributes data array that many Bluetooth Low Energy application frameworks, like BTstack, expect as setup input.

= GATT characteristic attribute (descriptor) types =

== Characteristic declaration ==

Let's have a look at an ATT attribute that declares a GATT characteristic. Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification].

== Characteristic value ==

<pre>
0x16, 0x00, 0x02, 0x03, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right as follows:
* 2 bytes for the length of the attribute: 0x0016 (= 22 bytes)
* 2 bytes for the combined properties and access permissions bitmasks of the attribute: 0x0302 (= read-only, dynamic, 128-bit UUID)
* 2 bytes for the handle of the attribute: 0x0009
* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101

The bitmask the determines the access permissions (or properties) for the value have an effect on the performance the communication between GATT client and server. A write operation that does not require waiting for an acknowledgement from the server is better suited, for example, for applications in which the client sends a stream of values to the server and it does not matter if some of the values are lost or overwritten by by the next value before the server can respond.

==== Access Permission Flags ====
The following table (from the Bluetooth 5.4 specification) defines the flags for the 8-bit ''access permissions'' bitmask:
{| class="wikitable" style="margin:right"
|-
! Property !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

==== Property Flags ====
This table lists the flags for the 8-bit ''properties'' bitmask (the higher byte that is grouped with the access permissions byte)

{| class="wikitable" style="margin:right"
|-
! Property !! Value !! Description
|-
| Dynamic || 0x01 || indicates that the read and write operations need to be implemented by custom application code in the GATT server
|-
| Long UUID || 0x02 || indicates that the UUID of the associated characteristic is 128 bits long (instead of 16 bits)
|-
|}

== Characteristic Client Configuration ==

The client configuration attribute of a GATT characteristic allows the GATT client to change the notify (or indicate) behavior for value write operations. Let us examine the sections of this example attribute:
<pre>
0x0a, 0x00, 0x0e, 0x01, 0x0e, 0x00, 0x02, 0x29, 0x00, 0x00
</pre>
From left to right, there are
* 2 bytes for the length of the attribute: 0x000a (= 10 bytes)
* 2 bytes for the permissions of this attribute: 0x010e (indicates read | write | write_without_response, dynamic)
* 2 bytes for the handle of this attribute: 0x000e
* 2 bytes for the short 16-bit UUID of this attribute: 0x2902 (the UUID for client characteristic configuration)
* 2 bytes that indicate whether notification or indication messages are enabled: 0x0000 (both type of messages are disabled)

For the last two bytes, the following options are possible, depending on the requests from the GATT client to enable or disable notification or indication messages (when the value of the associated characteristic changes):
{| class="wikitable" style="margin:right"
|-
| bit 0 || the least significant bit indicates whether sending notifications is enabled (1) or disabled (0)
|-
| bit 1 || the next significant bit indicates whether sending indications is enabled (1) or not (0)
|-
|}
All other bits are reserved for use in future changes to the GATT protocol.

== User description ==

Here is an example binary sequence for a GATT user description attribute.
<pre>
0x08, 0x00, 0x0a, 0x01, 0x0a, 0x00, 0x01, 0x29
</pre>

Let's break down the byte grouping from left to right:
* 2 bytes for the length of this attribute: 0x0008 (= 8 bytes)
* 2 bytes for permissions: 0x010a (= read, write, dynamic)
* 2 bytes for the handle of this attribute
* 2 bytes for the 16-bit short UUID that indicates a user description attribute: 0x2901
where the order of the bytes in each group needs to be reversed before analyzing.

The attribute declaration does not include the user description text itself. User description text is always "dynamic", meaning that it is served to the client on demand on the basis of the attribute handle. In BTstack, the implementation of the read callback is responsible for returning the UTF-8 bytes for the text string corresponding the attribute handle.

GATT Profile Data in Bluetooth Low Energy

2025-05-10T06:17:44Z

Kai:

This article explains the binary structure of the GATT attributes data array that many Bluetooth Low Energy application frameworks, like BTstack, expect as setup input.

= GATT characteristic attribute (descriptor) types =

== Characteristic declaration ==

Let's have a look at an ATT attribute that declares a GATT characteristic. Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification].

== Characteristic value ==

<pre>
0x16, 0x00, 0x02, 0x03, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right as follows:
* 2 bytes for the length of the attribute: 0x0016 (= 22 bytes)
* 2 bytes for the permissions (properties) of the attribute: 0x0302 (= read-only, dynamic, 128-bit UUID)
* 2 bytes for the handle of the attribute: 0x0009
* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101

The permission/property flags for the value have an effect on the performance the communication between GATT client and server. A write operation that does not require waiting for an acknowledgement from the server is better suited, for example, for applications in which the client sends a stream of values to the server and it does not matter if some of the values are lost or overwritten by by the next value before the server can respond.

The following table (from the Bluetooth 5.4 specification) defines the flags that can be combined to set the properties of an attribute:
{| class="wikitable" style="margin:right"
|-
! Property !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

== Characteristic Client Configuration ==

The client configuration attribute of a GATT characteristic allows the GATT client to change the notify (or indicate) behavior for value write operations. Let us examine the sections of this example attribute:
<pre>
0x0a, 0x00, 0x0e, 0x01, 0x0e, 0x00, 0x02, 0x29, 0x00, 0x00
</pre>
From left to right, there are
* 2 bytes for the length of the attribute: 0x000a (= 10 bytes)
* 2 bytes for the permissions of this attribute: 0x010e (indicates read | write | write_without_response, dynamic)
* 2 bytes for the handle of this attribute: 0x000e
* 2 bytes for the short 16-bit UUID of this attribute: 0x2902 (the UUID for client characteristic configuration)
* 2 bytes that indicate whether notification or indication messages are enabled: 0x0000 (both type of messages are disabled)

For the last two bytes, the following options are possible, depending on the requests from the GATT client to enable or disable notification or indication messages (when the value of the associated characteristic changes):
{| class="wikitable" style="margin:right"
|-
| bit 0 || the least significant bit indicates whether sending notifications is enabled (1) or disabled (0)
|-
| bit 1 || the next significant bit indicates whether sending indications is enabled (1) or not (0)
|-
|}
All other bits are reserved for use in future changes to the GATT protocol.

== User description ==

Here is an example binary sequence for a GATT user description attribute.
<pre>
0x08, 0x00, 0x0a, 0x01, 0x0a, 0x00, 0x01, 0x29
</pre>

Let's break down the byte grouping from left to right:
* 2 bytes for the length of this attribute: 0x0008 (= 8 bytes)
* 2 bytes for permissions: 0x010a (= read, write, dynamic)
* 2 bytes for the handle of this attribute
* 2 bytes for the 16-bit short UUID that indicates a user description attribute: 0x2901
where the order of the bytes in each group needs to be reversed before analyzing.

The attribute declaration does not include the user description text itself. User description text is always "dynamic", meaning that it is served to the client on demand on the basis of the attribute handle. In BTstack, the implementation of the read callback is responsible for returning the UTF-8 bytes for the text string corresponding the attribute handle.

GATT Profile Data in Bluetooth Low Energy

2025-05-10T05:32:26Z

Kai:

This article explains the binary structure of the GATT attributes data array that many Bluetooth Low Energy application frameworks, like BTstack, expect as setup input.

= GATT characteristic attribute (descriptor) types =

== Characteristic declaration ==

Let's have a look at an ATT attribute that declares a GATT characteristic. Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification]. That section also lists the characteristics permissions (or properties):
{| class="wikitable" style="margin:auto"
|-
! Properties !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

== Characteristic value ==

<pre>
0x16, 0x00, 0x02, 0x03, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right as follows:
* 2 bytes for the length of the attribute: 0x0016 (= 22 bytes)
* 2 bytes for the permissions (properties) of the attribute: 0x0302 (= read-only, dynamic, 128-bit UUID)
* 2 bytes for the handle of the attribute: 0x0009
* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101

== Characteristic Client Configuration ==

The client configuration attribute of a GATT characteristic allows the GATT client to change the notify (or indicate) behavior for value write operations. Let us examine the sections of this example attribute:
<pre>
0x0a, 0x00, 0x0e, 0x01, 0x0e, 0x00, 0x02, 0x29, 0x00, 0x00
</pre>
From left to right, there are
* 2 bytes for the length of the attribute: 0x000a (= 10 bytes)
* 2 bytes for the permissions of this attribute: 0x010e (indicates read | write | write_without_response, dynamic)
* 2 bytes for the handle of this attribute: 0x000e
* 2 bytes for the short 16-bit UUID of this attribute: 0x2902 (the UUID for client characteristic configuration)
* 2 bytes that indicate whether notification or indication messages are enabled: 0x0000 (both type of messages are disabled)

For the last two bytes, the following options are possible, depending on the requests from the GATT client to enable or disable notification or indication messages (when the value of the associated characteristic changes):
{| class="wikitable" style="margin:right"
|-
| bit 0 || the least significant bit indicates whether sending notifications is enabled (1) or disabled (0)
|-
| bit 1 || the next significant bit indicates whether sending indications is enabled (1) or not (0)
|-
|}
All other bits are reserved for use in future changes to the GATT protocol.

== User description ==

Here is an example binary sequence for a GATT user description attribute.
<pre>
0x08, 0x00, 0x0a, 0x01, 0x0a, 0x00, 0x01, 0x29
</pre>

Let's break down the byte grouping from left to right:
* 2 bytes for the length of this attribute: 0x0008 (= 8 bytes)
* 2 bytes for permissions: 0x010a (= read, write, dynamic)
* 2 bytes for the handle of this attribute
* 2 bytes for the 16-bit short UUID that indicates a user description attribute: 0x2901
where the order of the bytes in each group needs to be reversed before analyzing.

The attribute declaration does not include the user description text itself. User description text is always "dynamic", meaning that it is served to the client on demand on the basis of the attribute handle. In BTstack, the implementation of the read callback is responsible for returning the UTF-8 bytes for the text string corresponding the attribute handle.

GATT Profile Data in Bluetooth Low Energy

2025-05-10T05:28:56Z

Kai: /* GATT characteristic client configuration attribute */

This article explains the binary structure of the GATT attributes data array that many Bluetooth Low Energy application frameworks, like BTstack, expect as setup input.

== GATT characteristic declaration attribute ==

Let's have a look at an ATT attribute that declares a GATT characteristic. Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification]. That section also lists the characteristics permissions (or properties):
{| class="wikitable" style="margin:auto"
|-
! Properties !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

== GATT characteristic value attribute ==

<pre>
0x16, 0x00, 0x02, 0x03, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right as follows:
* 2 bytes for the length of the attribute: 0x0016 (= 22 bytes)
* 2 bytes for the permissions (properties) of the attribute: 0x0302 (= read-only, dynamic, 128-bit UUID)
* 2 bytes for the handle of the attribute: 0x0009
* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101

== GATT characteristic client configuration attribute ==

The client characteristic configuration attribute (descriptor) of a GATT characteristic allows the GATT client to change the notify (or indicate) behavior for value write operations. Let us examine the sections of this example attribute:
<pre>
0x0a, 0x00, 0x0e, 0x01, 0x0e, 0x00, 0x02, 0x29, 0x00, 0x00
</pre>
From left to right, there are
* 2 bytes for the length of the attribute: 0x000a (= 10 bytes)
* 2 bytes for the permissions of this attribute: 0x010e (indicates read | write | write_without_response, dynamic)
* 2 bytes for the handle of this attribute: 0x000e
* 2 bytes for the short 16-bit UUID of this attribute: 0x2902 (the UUID for client characteristic configuration)
* 2 bytes that indicate whether notification or indication messages are enabled: 0x0000 (both type of messages are disabled)

For the last two bytes, the following options are possible, depending on the requests from the GATT client to enable or disable notification or indication messages (when the value of the associated characteristic changes):
{| class="wikitable" style="margin:right"
|-
| bit 0 || the least significant bit indicates whether sending notifications is enabled (1) or disabled (0)
|-
| bit 1 || the next significant bit indicates whether sending indications is enabled (1) or not (0)
|-
|}
All other bits are reserved for use in future changes to the GATT protocol.

== GATT characteristic user description attribute ==

Here is an example binary sequence for a GATT user description attribute.
<pre>
0x08, 0x00, 0x0a, 0x01, 0x0a, 0x00, 0x01, 0x29
</pre>

Let's break down the byte grouping from left to right:
* 2 bytes for the length of this attribute: 0x0008 (= 8 bytes)
* 2 bytes for permissions: 0x010a (= read, write, dynamic)
* 2 bytes for the handle of this attribute
* 2 bytes for the 16-bit short UUID that indicates a user description attribute: 0x2901
where the order of the bytes in each group needs to be reversed before analyzing.

The attribute declaration does not include the user description text itself. User description text is always "dynamic", meaning that it is served to the client on demand on the basis of the attribute handle. In BTstack, the implementation of the read callback is responsible for returning the UTF-8 bytes for the text string corresponding the attribute handle.

Raspberry Pi Microcontrollers

2025-05-09T23:08:31Z

Kai: /* GATT Profiles, Services, Characteristics, and Descriptors */

GATT Profile Data in Bluetooth Low Energy

2025-05-09T23:05:15Z

Kai:

This article explains the binary structure of the GATT attributes data array that many Bluetooth Low Energy application frameworks, like BTstack, expect as setup input.

== GATT characteristic declaration attribute ==

Let's have a look at an ATT attribute that declares a GATT characteristic. Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification]. That section also lists the characteristics permissions (or properties):
{| class="wikitable" style="margin:auto"
|-
! Properties !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

== GATT characteristic value attribute ==

<pre>
0x16, 0x00, 0x02, 0x03, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right as follows:
* 2 bytes for the length of the attribute: 0x0016 (= 22 bytes)
* 2 bytes for the permissions (properties) of the attribute: 0x0302 (= read-only, dynamic, 128-bit UUID)
* 2 bytes for the handle of the attribute: 0x0009
* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101

== GATT characteristic client configuration attribute ==

The client configuration attribute (descriptor) of a GATT characteristic allows the GATT client to change the notify (or indicate) behavior for value write operations.

== GATT characteristic user description attribute ==

Here is an example binary sequence for a GATT user description attribute.
<pre>
0x08, 0x00, 0x0a, 0x01, 0x0a, 0x00, 0x01, 0x29
</pre>

Let's break down the byte grouping from left to right:
* 2 bytes for the length of this attribute: 0x0008 (= 8 bytes)
* 2 bytes for permissions: 0x010a (= read, write, dynamic)
* 2 bytes for the handle of this attribute
* 2 bytes for the 16-bit short UUID that indicates a user description attribute: 0x2901
where the order of the bytes in each group needs to be reversed before analyzing.

The attribute declaration does not include the user description text itself. User description text is always "dynamic", meaning that it is served to the client on demand on the basis of the attribute handle. In BTstack, the implementation of the read callback is responsible for returning the UTF-8 bytes for the text string corresponding the attribute handle.

GATT Profile Data in Bluetooth Low Energy

2025-05-09T22:47:43Z

Kai: /* GATT Profile Data */

This article explains the binary structure of the GATT attributes data array that many Bluetooth Low Energy application frameworks, like BTstack, expect as setup input.

== GATT characteristic declaration attribute ==

Let's have a look at an ATT attribute that declares a GATT characteristic. Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification]. That section also lists the characteristics permissions (or properties):
{| class="wikitable" style="margin:auto"
|-
! Properties !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

== GATT characteristic value attribute ==

<pre>
0x16, 0x00, 0x02, 0x03, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right as follows:
* 2 bytes for the length of the attribute: 0x0016 (= 22 bytes)
* 2 bytes for the permissions (properties) of the attribute: 0x0302 (= read-only, dynamic, 128-bit UUID)
* 2 bytes for the handle of the attribute: 0x0009
* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101

== GATT characteristic user description attribute ==

Here is an example binary sequence for a GATT user description attribute.
<pre>
0x08, 0x00, 0x0a, 0x01, 0x0a, 0x00, 0x01, 0x29
</pre>

Let's break down the byte grouping from left to right:
* 2 bytes for the length of this attribute: 0x0008 (= 8 bytes)
* 2 bytes for permissions: 0x010a (= read, write, dynamic)
* 2 bytes for the handle of this attribute
* 2 bytes for the 16-bit short UUID that indicates a user description attribute: 0x2901
where the order of the bytes in each group needs to be reversed before analyzing.

The attribute declaration does not include the user description text itself. User description text is always "dynamic", meaning that it is served to the client on demand on the basis of the attribute handle. In BTstack, the implementation of the read callback is responsible for returning the UTF-8 bytes for the text string corresponding the attribute handle.

GATT Profile Data in Bluetooth Low Energy

2025-05-09T22:47:12Z

Kai: Created page with "= GATT Profile Data = This article explains the binary structure of the GATT attributes data array that many Bluetooth Low Energy application frameworks, like BTstack, expect as setup input. == GATT characteristic declaration attribute == Let's have a look at an ATT attribute that declares a GATT characteristic. Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0..."

= GATT Profile Data =

This article explains the binary structure of the GATT attributes data array that many Bluetooth Low Energy application frameworks, like BTstack, expect as setup input.

== GATT characteristic declaration attribute ==

Let's have a look at an ATT attribute that declares a GATT characteristic. Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification]. That section also lists the characteristics permissions (or properties):
{| class="wikitable" style="margin:auto"
|-
! Properties !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

== GATT characteristic value attribute ==

<pre>
0x16, 0x00, 0x02, 0x03, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right as follows:
* 2 bytes for the length of the attribute: 0x0016 (= 22 bytes)
* 2 bytes for the permissions (properties) of the attribute: 0x0302 (= read-only, dynamic, 128-bit UUID)
* 2 bytes for the handle of the attribute: 0x0009
* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101

== GATT characteristic user description attribute ==

Here is an example binary sequence for a GATT user description attribute.
<pre>
0x08, 0x00, 0x0a, 0x01, 0x0a, 0x00, 0x01, 0x29
</pre>

Let's break down the byte grouping from left to right:
* 2 bytes for the length of this attribute: 0x0008 (= 8 bytes)
* 2 bytes for permissions: 0x010a (= read, write, dynamic)
* 2 bytes for the handle of this attribute
* 2 bytes for the 16-bit short UUID that indicates a user description attribute: 0x2901
where the order of the bytes in each group needs to be reversed before analyzing.

The attribute declaration does not include the user description text itself. User description text is always "dynamic", meaning that it is served to the client on demand on the basis of the attribute handle. In BTstack, the implementation of the read callback is responsible for returning the UTF-8 bytes for the text string corresponding the attribute handle.

Raspberry Pi Microcontrollers

2025-05-09T22:31:28Z

Kai: /* Bluetooth with BTstack */

Raspberry Pi Microcontrollers

2025-05-09T22:12:43Z

Kai: Adds description of the binary sequence of a GATT attribute for a characteristic value

= Pico Series =
* Raspberry Pi Pico and Pico W
** Dual [https://developer.arm.com/Processors/Cortex-M0-Plus Arm Cortex-M0+] with Armv6-M programming model, up to 133 MHz
* Raspberry Pi Pico 2 and Pico 2 W
** Dual [https://developer.arm.com/Processors/Cortex-M33 Arm Cortex-M33] with Armv8-M programming model, up to 150 MHz

== Development Setup ==

=== Using the Raspberry Pi Debug Probe ===
The Debug Probe is a RP2040 based USB-to-UART/SWD board for connecting the USB slot of a development machine to the SWD or UART pins of a target device.

=== Using A Pico To Debug Another Pico ===
A Pico can be used to debug another Pico (a.k.a. target device) by flashing it with the [https://github.com/raspberrypi/debugprobe debugprobe] binary and wiring to the target Pico as shown below.

[[File:Wiring_rpi_pico_as_debugger.png | x320 px | A Raspberry Pi Pico wired to debug another Pico]]

From the debugger Pico to the target Pico,
* pin #4 (GP2) connects to pin SWCLK,
* pin #5 (GP3) connects to SWDIO,
* pin #6 (GP4, UART1 TX) connects to pin #2 (GP1, UART0 RX),
* pin #7 (GP5, UART1 RX) connects to pin #1 (GP0, UART0, TX).

The debugger Pico serves both as a USB-to-SWD and USB-to-UART bridge to the target device. The development machine, therefore, needs to be connected via USB only to the debugger Pico. Console output on the target Pico is relayed through the debugger. It is possible, though, to connect a second USB cable from the development machine to the target device for (simultaneous) direct access to the console output. This debugger setup works not just with Pico targets but with any microcontroller that supports the CMSIS-DAP protocol over SWD.

=== Software Tools for Debugging ===
Whether we use the Raspberry Pi Debug Probe or a spare Pico as debug probe, the software tools used for debugging are the same:
* openocd

== Notes on Programming with the C SDK ==

=== Async Context ===
In the C SDK, an [https://www.raspberrypi.com/documentation/pico-sdk/high_level.html#group_pico_async_context async_context] is used in concurrent programming to make sure that functions are executed on the same thread and in the order they were submitted, similar to dispatch queues in Apple's [https://developer.apple.com/documentation/dispatch?language=objc Dispatch framework]. The ''async_context'' data structure is a container of linked lists of worker functions that are executed within a single thread of a single processor core.

=== Bluetooth with BTstack ===

The C SDK integrates the third-party [https://bluekitchen-gmbh.com/btstack BTstack] framework as its Bluetooth API that interfaces with the Infineon CYW43 wireless communication module (on Pico W models) via the Host-Controller Interface (HCI) protocol.

==== Setup ====

Before we can call any BTstack functions (and hope for some meaningful outcome), we need to add a '''btstack_config.h''' header file to our project. In it, we add all the compile-time switches that fit our application. On a microcontroller, a frequent use case for BTstack is to implement a BLE peripheral. For this we, our config header should look something like this:

<syntaxhighlight lang="C">
#ifndef MY_BTSTACK_CONFIG_H
#define MY_BTSTACK_CONFIG_H

#ifndef ENABLE_BLE
#error In CMakeLists.txt add the 'pico_btstack_ble' library to target_link_libraries(...)
#endif

// logging
#define ENABLE_LOG_INFO
#define ENABLE_LOG_ERROR
#define ENABLE_PRINTF_HEXDUMP // required for hci_dump_init()

#if 1 // configure as peripheral (GATT server)
#define ENABLE_LE_PERIPHERAL
#define MAX_NR_GATT_CLIENTS 0
#else // configure as central (GATT client)
#define ENABLE_LE_CENTRAL
#define MAX_NR_GATT_CLIENTS 1
//#define ENABLE_GATT_CLIENT_PAIRING
#endif

// Setting various buffer sizes related to HCI communication
#define HCI_OUTGOING_PRE_BUFFER_SIZE 4
#define HCI_ACL_PAYLOAD_SIZE (255 + 4)
#define HCI_ACL_CHUNK_SIZE_ALIGNMENT 4
#define MAX_NR_HCI_CONNECTIONS 1
#define MAX_NR_SM_LOOKUP_ENTRIES 3
#define MAX_NR_WHITELIST_ENTRIES 16
#define MAX_NR_LE_DEVICE_DB_ENTRIES 16

// Choosing a fixed-size attributes table over using malloc.
// We want to use BTstack without heap memory allocations.
#if 1
#define MAX_ATT_DB_SIZE 512
#else
#define HAVE_MALLOC
#endif

// Enabling timers
#if 1
#define HAVE_EMBEDDED_TIME_MS
#else
#define HAVE_EMBEDDED_TICK
#endif

// Limiting the amount of nonvolatile (flash) memory used for storing peer bonding information
#define NVM_NUM_DEVICE_DB_ENTRIES 16
#define NVM_NUM_LINK_KEYS 16

// Configuring HCI Controller-to-Host flow control and related buffers to avoid overrunning the cyw43 shared bus
#define ENABLE_HCI_CONTROLLER_TO_HOST_FLOW_CONTROL
#define HCI_HOST_ACL_PACKET_LEN (255+4)
#define HCI_HOST_ACL_PACKET_NUM 3
#define HCI_HOST_SCO_PACKET_LEN 120
#define HCI_HOST_SCO_PACKET_NUM 3
#define MAX_NR_CONTROLLER_SCO_PACKETS 3
#define MAX_NR_CONTROLLER_ACL_BUFFERS 3

// Enabling btstack_assert, acting just like normal assert()
#define HAVE_ASSERT

// Setting HCI resend timeout in case the Bluetooth module needs more time to response.
#define HCI_RESET_RESEND_TIMEOUT_MS 800

// Configuring security
#define ENABLE_SOFTWARE_AES128
#define ENABLE_MICRO_ECC_FOR_LE_SECURE_CONNECTIONS

#endif // MY_BTSTACK_CONFIG_H
</syntaxhighlight>

==== GATT Profiles, Services, Characteristics, and Descriptors ====

A Bluetooth Low Energy Peripheral organizes the served data in a linear attributes table or database, referred to as ATT. The GATT (Generic Attributes) profile used in BLE is, contrary to what the name suggests, a specific organizational structure imposed on the ATT table, where the data table as a whole is referred to as "profile". The profile attributes can be broken down into consecutive "service" attributes, the service attributes into "characteristic" attributes, the characteristics into "descriptor" attributes. So, all in all there linear ATT table becomes a tree structure with four levels in GATT. A BLE peripheral, acting as a GATT server when connected to, will advertise its profile over GAP. A BLE central, acting as a GATT client after establishing a connection to the peripheral, can read the complete GATT hierarchy to find out about the profile contents.

BTstack allows defining a GATT table as a human-readable text file. The translation of that file into a C header by a Python script is a build step that can be included in ''CMakeLists.txt'' using the function ''pico_btstack_make_gatt_header()''. The generated C header contains the GATT table as an array of hex-coded bytes, laid out one line per attribute, with comments between the lines for orientation. Application code that needs to access the GATT table data then simply "#include"s this generated header file.

When defining the GATT table in BTstack's text format, we can use the following keywords for the attribute permissions of a characteristic:
* READ
* WRITE
* WRITE_WITH_RESPONSE
* NOTIFY: Adds a ''Client Configuration'' descriptor to the characteristic that allows a GATT client to control whether a notification is to be sent to the client each time the value of the characteristic changes.
* DYNAMIC: Indicates that reading and writing to this characteristic requires adding this case to the read and write callbacks.

===== BTStack Python script output for a GATT characteristic declaration attribute =====

Let's have a look at the output of the BTstack Python script that converts the .gatt file to a C header and let's narrow it down to just the characteristic attributes (descriptors).

Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification]. That section also lists the characteristics permissions (or properties):
{| class="wikitable" style="margin:auto"
|-
! Properties !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

===== BTStack Python script output for a GATT characteristic value attribute =====

<pre>
0x16, 0x00, 0x02, 0x03, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right as follows:
* 2 bytes for the length of the attribute: 0x0016 (= 22 bytes)
* 2 bytes for the permissions (properties) of the attribute: 0x0302 (= read-only, dynamic, 128-bit UUID)
* 2 bytes for the handle of the attribute: 0x0009
* 16 bytes for the UUID of the characteristic that the value is associated with: 0xb0b0f155b0b0b0b0b0b0b0b000000101

===== BTStack Python script output for a GATT characteristic user description attribute =====

<pre>
0x08, 0x00, 0x0a, 0x01, 0x0a, 0x00, 0x01, 0x29
</pre>

The bytes are grouped from left to right as follows:
* 2 bytes for the length of this attribute: 0x0008 (= 8 bytes)
* 2 bytes for permissions: 0x010a (= read, write, dynamic)
* 2 bytes for the handle of this attribute
* 2 bytes for the 16-bit short UUID that indicates a user description attribute: 0x2901
where the order of the bytes in each group needs to be reversed before analyzing.

The attribute declaration does not include the user description text itself. User description text is always "dynamic", meaning that it is served to the client on demand on the basis of the attribute handle. In BTstack, the implementation of the read callback is responsible for returning the UTF-8 bytes for the text string corresponding the attribute handle.

==== The BTstack runloop ====

The following articles by Hunter Adams offer a detailed analysis of how BTstack works on the Pico:
# [https://vanhunteradams.com/Pico/BLE/BTStack_HCI.html BTstack and RP2040: HCI (Host Controller Interface)].<br />This article delves, among other things, into how the BTstack runloop is executed inside a Pico [[#Async_Context | async_context]].<br /><blockquote>[...] we have just one ''when_pending_worker'' in our async_context. This worker is called ''cyw43_poll_worker'', and its ''do_work'' function points to ''cyw43_poll_func()'', listed above. This function ends up calling ''btstack_run_loop_poll_data_sources_from_irq()'', about which we'll learn more shortly. This worker gets marked as pending in a GPIO interrupt. So, this provides a mechanism by which the CYW43 can tell the RP2040 to run ''btstack_run_loop_poll_data_sources_from_irq()'' which, as we're going to learn, goes and gets data from the device.</blockquote>
# [https://vanhunteradams.com/Pico/BLE/GATT_Server.html Building a Bluetooth GATT Server on the Pi Pico W]

==== GATT Characteristic read and write operations ====

The struct <code>att_service_handler_t</code> represents a GATT service. After the fields of the struct have been filled in by the application code, it holds all the information needed for the BLE peripheral to make it available to the BLE central. Some of the fields of the struct hold the ATT handles that define the start and end of the collection of characteristics belonging to the service. Other fields of the struct (<code>read_callback</code> and <code>write_callback</code>) hold pointers to functions that handle reading from and writing to characteristic values.

Note that the ''read'' callback for a descriptor of a GATT characteristic (i.e., an ATT attribute) is called twice. In the first call, the buffer pointer passed to the callback function is NULL. In the second call, it's a valid pointer. The first call is made by BTstack to query the size of the data that will be returned by the second call. BTstack needs to make sure its transmission buffers can hold the amount of data before making the second call.

At the end of a writing operation, if the characteristic was configured to send back notifications to the BLE peer, one more callback function comes into play. It is part of another struct, <code>btstack_context_callback_registration_t</code>, that is used for the deferred sending of characteristic update notification to the BLE central. In this callback, <code>att_server_notify()</code> is called to finally send the write notification to the peer.

Raspberry Pi Microcontrollers

2025-05-09T20:49:23Z

Kai: /* BTStack Python script output for a GATT user description declaration attribute */

= Pico Series =
* Raspberry Pi Pico and Pico W
** Dual [https://developer.arm.com/Processors/Cortex-M0-Plus Arm Cortex-M0+] with Armv6-M programming model, up to 133 MHz
* Raspberry Pi Pico 2 and Pico 2 W
** Dual [https://developer.arm.com/Processors/Cortex-M33 Arm Cortex-M33] with Armv8-M programming model, up to 150 MHz

== Development Setup ==

=== Using the Raspberry Pi Debug Probe ===
The Debug Probe is a RP2040 based USB-to-UART/SWD board for connecting the USB slot of a development machine to the SWD or UART pins of a target device.

=== Using A Pico To Debug Another Pico ===
A Pico can be used to debug another Pico (a.k.a. target device) by flashing it with the [https://github.com/raspberrypi/debugprobe debugprobe] binary and wiring to the target Pico as shown below.

[[File:Wiring_rpi_pico_as_debugger.png | x320 px | A Raspberry Pi Pico wired to debug another Pico]]

From the debugger Pico to the target Pico,
* pin #4 (GP2) connects to pin SWCLK,
* pin #5 (GP3) connects to SWDIO,
* pin #6 (GP4, UART1 TX) connects to pin #2 (GP1, UART0 RX),
* pin #7 (GP5, UART1 RX) connects to pin #1 (GP0, UART0, TX).

The debugger Pico serves both as a USB-to-SWD and USB-to-UART bridge to the target device. The development machine, therefore, needs to be connected via USB only to the debugger Pico. Console output on the target Pico is relayed through the debugger. It is possible, though, to connect a second USB cable from the development machine to the target device for (simultaneous) direct access to the console output. This debugger setup works not just with Pico targets but with any microcontroller that supports the CMSIS-DAP protocol over SWD.

=== Software Tools for Debugging ===
Whether we use the Raspberry Pi Debug Probe or a spare Pico as debug probe, the software tools used for debugging are the same:
* openocd

== Notes on Programming with the C SDK ==

=== Async Context ===
In the C SDK, an [https://www.raspberrypi.com/documentation/pico-sdk/high_level.html#group_pico_async_context async_context] is used in concurrent programming to make sure that functions are executed on the same thread and in the order they were submitted, similar to dispatch queues in Apple's [https://developer.apple.com/documentation/dispatch?language=objc Dispatch framework]. The ''async_context'' data structure is a container of linked lists of worker functions that are executed within a single thread of a single processor core.

=== Bluetooth with BTstack ===

The C SDK integrates the third-party [https://bluekitchen-gmbh.com/btstack BTstack] framework as its Bluetooth API that interfaces with the Infineon CYW43 wireless communication module (on Pico W models) via the Host-Controller Interface (HCI) protocol.

==== Setup ====

Before we can call any BTstack functions (and hope for some meaningful outcome), we need to add a '''btstack_config.h''' header file to our project. In it, we add all the compile-time switches that fit our application. On a microcontroller, a frequent use case for BTstack is to implement a BLE peripheral. For this we, our config header should look something like this:

<syntaxhighlight lang="C">
#ifndef MY_BTSTACK_CONFIG_H
#define MY_BTSTACK_CONFIG_H

#ifndef ENABLE_BLE
#error In CMakeLists.txt add the 'pico_btstack_ble' library to target_link_libraries(...)
#endif

// logging
#define ENABLE_LOG_INFO
#define ENABLE_LOG_ERROR
#define ENABLE_PRINTF_HEXDUMP // required for hci_dump_init()

#if 1 // configure as peripheral (GATT server)
#define ENABLE_LE_PERIPHERAL
#define MAX_NR_GATT_CLIENTS 0
#else // configure as central (GATT client)
#define ENABLE_LE_CENTRAL
#define MAX_NR_GATT_CLIENTS 1
//#define ENABLE_GATT_CLIENT_PAIRING
#endif

// Setting various buffer sizes related to HCI communication
#define HCI_OUTGOING_PRE_BUFFER_SIZE 4
#define HCI_ACL_PAYLOAD_SIZE (255 + 4)
#define HCI_ACL_CHUNK_SIZE_ALIGNMENT 4
#define MAX_NR_HCI_CONNECTIONS 1
#define MAX_NR_SM_LOOKUP_ENTRIES 3
#define MAX_NR_WHITELIST_ENTRIES 16
#define MAX_NR_LE_DEVICE_DB_ENTRIES 16

// Choosing a fixed-size attributes table over using malloc.
// We want to use BTstack without heap memory allocations.
#if 1
#define MAX_ATT_DB_SIZE 512
#else
#define HAVE_MALLOC
#endif

// Enabling timers
#if 1
#define HAVE_EMBEDDED_TIME_MS
#else
#define HAVE_EMBEDDED_TICK
#endif

// Limiting the amount of nonvolatile (flash) memory used for storing peer bonding information
#define NVM_NUM_DEVICE_DB_ENTRIES 16
#define NVM_NUM_LINK_KEYS 16

// Configuring HCI Controller-to-Host flow control and related buffers to avoid overrunning the cyw43 shared bus
#define ENABLE_HCI_CONTROLLER_TO_HOST_FLOW_CONTROL
#define HCI_HOST_ACL_PACKET_LEN (255+4)
#define HCI_HOST_ACL_PACKET_NUM 3
#define HCI_HOST_SCO_PACKET_LEN 120
#define HCI_HOST_SCO_PACKET_NUM 3
#define MAX_NR_CONTROLLER_SCO_PACKETS 3
#define MAX_NR_CONTROLLER_ACL_BUFFERS 3

// Enabling btstack_assert, acting just like normal assert()
#define HAVE_ASSERT

// Setting HCI resend timeout in case the Bluetooth module needs more time to response.
#define HCI_RESET_RESEND_TIMEOUT_MS 800

// Configuring security
#define ENABLE_SOFTWARE_AES128
#define ENABLE_MICRO_ECC_FOR_LE_SECURE_CONNECTIONS

#endif // MY_BTSTACK_CONFIG_H
</syntaxhighlight>

==== GATT Profiles, Services, Characteristics, and Descriptors ====

A Bluetooth Low Energy Peripheral organizes the served data in a linear attributes table or database, referred to as ATT. The GATT (Generic Attributes) profile used in BLE is, contrary to what the name suggests, a specific organizational structure imposed on the ATT table, where the data table as a whole is referred to as "profile". The profile attributes can be broken down into consecutive "service" attributes, the service attributes into "characteristic" attributes, the characteristics into "descriptor" attributes. So, all in all there linear ATT table becomes a tree structure with four levels in GATT. A BLE peripheral, acting as a GATT server when connected to, will advertise its profile over GAP. A BLE central, acting as a GATT client after establishing a connection to the peripheral, can read the complete GATT hierarchy to find out about the profile contents.

BTstack allows defining a GATT table as a human-readable text file. The translation of that file into a C header by a Python script is a build step that can be included in ''CMakeLists.txt'' using the function ''pico_btstack_make_gatt_header()''. The generated C header contains the GATT table as an array of hex-coded bytes, laid out one line per attribute, with comments between the lines for orientation. Application code that needs to access the GATT table data then simply "#include"s this generated header file.

When defining the GATT table in BTstack's text format, we can use the following keywords for the attribute permissions of a characteristic:
* READ
* WRITE
* WRITE_WITH_RESPONSE
* NOTIFY: Adds a ''Client Configuration'' descriptor to the characteristic that allows a GATT client to control whether a notification is to be sent to the client each time the value of the characteristic changes.
* DYNAMIC: Indicates that reading and writing to this characteristic requires adding this case to the read and write callbacks.

===== BTStack Python script output for a GATT characteristic declaration attribute =====

Let's have a look at the output of the BTstack Python script that converts the .gatt file to a C header and let's narrow it down to just the characteristic declarations.

Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification]. That section also lists the characteristics permissions (or properties):
{| class="wikitable" style="margin:auto"
|-
! Properties !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

===== BTStack Python script output for a GATT user description declaration attribute =====

<pre>
0x08, 0x00, 0x0a, 0x01, 0x0a, 0x00, 0x01, 0x29
</pre>

The bytes are grouped from left to right as follows:
* 2 bytes for the length of this attribute: 0x0008 (= 8 bytes)
* 2 bytes for permissions: 0x010a (= read, write, dynamic)
* 2 bytes for the handle of this attribute
* 2 bytes for the 16-bit short UUID that indicates a user description attribute: 0x2901
where the order of the bytes in each group needs to be reversed before analyzing.

The attribute declaration does not include the user description text itself. User description text is always "dynamic", meaning that it is served to the client on demand on the basis of the attribute handle. In BTstack, the implementation of the read callback is responsible for returning the UTF-8 bytes for the text string corresponding the attribute handle.

==== The BTstack runloop ====

The following articles by Hunter Adams offer a detailed analysis of how BTstack works on the Pico:
# [https://vanhunteradams.com/Pico/BLE/BTStack_HCI.html BTstack and RP2040: HCI (Host Controller Interface)].<br />This article delves, among other things, into how the BTstack runloop is executed inside a Pico [[#Async_Context | async_context]].<br /><blockquote>[...] we have just one ''when_pending_worker'' in our async_context. This worker is called ''cyw43_poll_worker'', and its ''do_work'' function points to ''cyw43_poll_func()'', listed above. This function ends up calling ''btstack_run_loop_poll_data_sources_from_irq()'', about which we'll learn more shortly. This worker gets marked as pending in a GPIO interrupt. So, this provides a mechanism by which the CYW43 can tell the RP2040 to run ''btstack_run_loop_poll_data_sources_from_irq()'' which, as we're going to learn, goes and gets data from the device.</blockquote>
# [https://vanhunteradams.com/Pico/BLE/GATT_Server.html Building a Bluetooth GATT Server on the Pi Pico W]

==== GATT Characteristic read and write operations ====

The struct <code>att_service_handler_t</code> represents a GATT service. After the fields of the struct have been filled in by the application code, it holds all the information needed for the BLE peripheral to make it available to the BLE central. Some of the fields of the struct hold the ATT handles that define the start and end of the collection of characteristics belonging to the service. Other fields of the struct (<code>read_callback</code> and <code>write_callback</code>) hold pointers to functions that handle reading from and writing to characteristic values.

Note that the ''read'' callback for a descriptor of a GATT characteristic (i.e., an ATT attribute) is called twice. In the first call, the buffer pointer passed to the callback function is NULL. In the second call, it's a valid pointer. The first call is made by BTstack to query the size of the data that will be returned by the second call. BTstack needs to make sure its transmission buffers can hold the amount of data before making the second call.

At the end of a writing operation, if the characteristic was configured to send back notifications to the BLE peer, one more callback function comes into play. It is part of another struct, <code>btstack_context_callback_registration_t</code>, that is used for the deferred sending of characteristic update notification to the BLE central. In this callback, <code>att_server_notify()</code> is called to finally send the write notification to the peer.

Raspberry Pi Microcontrollers

2025-05-09T20:21:13Z

Kai: /* BTStack Python script output for a GATT user description declaration attribute */

= Pico Series =
* Raspberry Pi Pico and Pico W
** Dual [https://developer.arm.com/Processors/Cortex-M0-Plus Arm Cortex-M0+] with Armv6-M programming model, up to 133 MHz
* Raspberry Pi Pico 2 and Pico 2 W
** Dual [https://developer.arm.com/Processors/Cortex-M33 Arm Cortex-M33] with Armv8-M programming model, up to 150 MHz

== Development Setup ==

=== Using the Raspberry Pi Debug Probe ===
The Debug Probe is a RP2040 based USB-to-UART/SWD board for connecting the USB slot of a development machine to the SWD or UART pins of a target device.

=== Using A Pico To Debug Another Pico ===
A Pico can be used to debug another Pico (a.k.a. target device) by flashing it with the [https://github.com/raspberrypi/debugprobe debugprobe] binary and wiring to the target Pico as shown below.

[[File:Wiring_rpi_pico_as_debugger.png | x320 px | A Raspberry Pi Pico wired to debug another Pico]]

From the debugger Pico to the target Pico,
* pin #4 (GP2) connects to pin SWCLK,
* pin #5 (GP3) connects to SWDIO,
* pin #6 (GP4, UART1 TX) connects to pin #2 (GP1, UART0 RX),
* pin #7 (GP5, UART1 RX) connects to pin #1 (GP0, UART0, TX).

The debugger Pico serves both as a USB-to-SWD and USB-to-UART bridge to the target device. The development machine, therefore, needs to be connected via USB only to the debugger Pico. Console output on the target Pico is relayed through the debugger. It is possible, though, to connect a second USB cable from the development machine to the target device for (simultaneous) direct access to the console output. This debugger setup works not just with Pico targets but with any microcontroller that supports the CMSIS-DAP protocol over SWD.

=== Software Tools for Debugging ===
Whether we use the Raspberry Pi Debug Probe or a spare Pico as debug probe, the software tools used for debugging are the same:
* openocd

== Notes on Programming with the C SDK ==

=== Async Context ===
In the C SDK, an [https://www.raspberrypi.com/documentation/pico-sdk/high_level.html#group_pico_async_context async_context] is used in concurrent programming to make sure that functions are executed on the same thread and in the order they were submitted, similar to dispatch queues in Apple's [https://developer.apple.com/documentation/dispatch?language=objc Dispatch framework]. The ''async_context'' data structure is a container of linked lists of worker functions that are executed within a single thread of a single processor core.

=== Bluetooth with BTstack ===

The C SDK integrates the third-party [https://bluekitchen-gmbh.com/btstack BTstack] framework as its Bluetooth API that interfaces with the Infineon CYW43 wireless communication module (on Pico W models) via the Host-Controller Interface (HCI) protocol.

==== Setup ====

Before we can call any BTstack functions (and hope for some meaningful outcome), we need to add a '''btstack_config.h''' header file to our project. In it, we add all the compile-time switches that fit our application. On a microcontroller, a frequent use case for BTstack is to implement a BLE peripheral. For this we, our config header should look something like this:

<syntaxhighlight lang="C">
#ifndef MY_BTSTACK_CONFIG_H
#define MY_BTSTACK_CONFIG_H

#ifndef ENABLE_BLE
#error In CMakeLists.txt add the 'pico_btstack_ble' library to target_link_libraries(...)
#endif

// logging
#define ENABLE_LOG_INFO
#define ENABLE_LOG_ERROR
#define ENABLE_PRINTF_HEXDUMP // required for hci_dump_init()

#if 1 // configure as peripheral (GATT server)
#define ENABLE_LE_PERIPHERAL
#define MAX_NR_GATT_CLIENTS 0
#else // configure as central (GATT client)
#define ENABLE_LE_CENTRAL
#define MAX_NR_GATT_CLIENTS 1
//#define ENABLE_GATT_CLIENT_PAIRING
#endif

// Setting various buffer sizes related to HCI communication
#define HCI_OUTGOING_PRE_BUFFER_SIZE 4
#define HCI_ACL_PAYLOAD_SIZE (255 + 4)
#define HCI_ACL_CHUNK_SIZE_ALIGNMENT 4
#define MAX_NR_HCI_CONNECTIONS 1
#define MAX_NR_SM_LOOKUP_ENTRIES 3
#define MAX_NR_WHITELIST_ENTRIES 16
#define MAX_NR_LE_DEVICE_DB_ENTRIES 16

// Choosing a fixed-size attributes table over using malloc.
// We want to use BTstack without heap memory allocations.
#if 1
#define MAX_ATT_DB_SIZE 512
#else
#define HAVE_MALLOC
#endif

// Enabling timers
#if 1
#define HAVE_EMBEDDED_TIME_MS
#else
#define HAVE_EMBEDDED_TICK
#endif

// Limiting the amount of nonvolatile (flash) memory used for storing peer bonding information
#define NVM_NUM_DEVICE_DB_ENTRIES 16
#define NVM_NUM_LINK_KEYS 16

// Configuring HCI Controller-to-Host flow control and related buffers to avoid overrunning the cyw43 shared bus
#define ENABLE_HCI_CONTROLLER_TO_HOST_FLOW_CONTROL
#define HCI_HOST_ACL_PACKET_LEN (255+4)
#define HCI_HOST_ACL_PACKET_NUM 3
#define HCI_HOST_SCO_PACKET_LEN 120
#define HCI_HOST_SCO_PACKET_NUM 3
#define MAX_NR_CONTROLLER_SCO_PACKETS 3
#define MAX_NR_CONTROLLER_ACL_BUFFERS 3

// Enabling btstack_assert, acting just like normal assert()
#define HAVE_ASSERT

// Setting HCI resend timeout in case the Bluetooth module needs more time to response.
#define HCI_RESET_RESEND_TIMEOUT_MS 800

// Configuring security
#define ENABLE_SOFTWARE_AES128
#define ENABLE_MICRO_ECC_FOR_LE_SECURE_CONNECTIONS

#endif // MY_BTSTACK_CONFIG_H
</syntaxhighlight>

==== GATT Profiles, Services, Characteristics, and Descriptors ====

A Bluetooth Low Energy Peripheral organizes the served data in a linear attributes table or database, referred to as ATT. The GATT (Generic Attributes) profile used in BLE is, contrary to what the name suggests, a specific organizational structure imposed on the ATT table, where the data table as a whole is referred to as "profile". The profile attributes can be broken down into consecutive "service" attributes, the service attributes into "characteristic" attributes, the characteristics into "descriptor" attributes. So, all in all there linear ATT table becomes a tree structure with four levels in GATT. A BLE peripheral, acting as a GATT server when connected to, will advertise its profile over GAP. A BLE central, acting as a GATT client after establishing a connection to the peripheral, can read the complete GATT hierarchy to find out about the profile contents.

BTstack allows defining a GATT table as a human-readable text file. The translation of that file into a C header by a Python script is a build step that can be included in ''CMakeLists.txt'' using the function ''pico_btstack_make_gatt_header()''. The generated C header contains the GATT table as an array of hex-coded bytes, laid out one line per attribute, with comments between the lines for orientation. Application code that needs to access the GATT table data then simply "#include"s this generated header file.

When defining the GATT table in BTstack's text format, we can use the following keywords for the attribute permissions of a characteristic:
* READ
* WRITE
* WRITE_WITH_RESPONSE
* NOTIFY: Adds a ''Client Configuration'' descriptor to the characteristic that allows a GATT client to control whether a notification is to be sent to the client each time the value of the characteristic changes.
* DYNAMIC: Indicates that reading and writing to this characteristic requires adding this case to the read and write callbacks.

===== BTStack Python script output for a GATT characteristic declaration attribute =====

Let's have a look at the output of the BTstack Python script that converts the .gatt file to a C header and let's narrow it down to just the characteristic declarations.

Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification]. That section also lists the characteristics permissions (or properties):
{| class="wikitable" style="margin:auto"
|-
! Properties !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

===== BTStack Python script output for a GATT user description declaration attribute =====

<pre>
0x08, 0x00, 0x0a, 0x01, 0x0a, 0x00, 0x01, 0x29,
</pre>

The bytes are grouped from left to right as follows:
* 2 bytes for the length of this attribute: 0x0008 (= 8 bytes)
* 2 bytes for permissions: 0x010a (= read, write, dynamic)
* 2 bytes for the handle of this attribute
* 2 bytes for the 16-bit short UUID that indicates a user description attribute: 0x2901

==== The BTstack runloop ====

The following articles by Hunter Adams offer a detailed analysis of how BTstack works on the Pico:
# [https://vanhunteradams.com/Pico/BLE/BTStack_HCI.html BTstack and RP2040: HCI (Host Controller Interface)].<br />This article delves, among other things, into how the BTstack runloop is executed inside a Pico [[#Async_Context | async_context]].<br /><blockquote>[...] we have just one ''when_pending_worker'' in our async_context. This worker is called ''cyw43_poll_worker'', and its ''do_work'' function points to ''cyw43_poll_func()'', listed above. This function ends up calling ''btstack_run_loop_poll_data_sources_from_irq()'', about which we'll learn more shortly. This worker gets marked as pending in a GPIO interrupt. So, this provides a mechanism by which the CYW43 can tell the RP2040 to run ''btstack_run_loop_poll_data_sources_from_irq()'' which, as we're going to learn, goes and gets data from the device.</blockquote>
# [https://vanhunteradams.com/Pico/BLE/GATT_Server.html Building a Bluetooth GATT Server on the Pi Pico W]

==== GATT Characteristic read and write operations ====

The struct <code>att_service_handler_t</code> represents a GATT service. After the fields of the struct have been filled in by the application code, it holds all the information needed for the BLE peripheral to make it available to the BLE central. Some of the fields of the struct hold the ATT handles that define the start and end of the collection of characteristics belonging to the service. Other fields of the struct (<code>read_callback</code> and <code>write_callback</code>) hold pointers to functions that handle reading from and writing to characteristic values.

Note that the ''read'' callback for a descriptor of a GATT characteristic (i.e., an ATT attribute) is called twice. In the first call, the buffer pointer passed to the callback function is NULL. In the second call, it's a valid pointer. The first call is made by BTstack to query the size of the data that will be returned by the second call. BTstack needs to make sure its transmission buffers can hold the amount of data before making the second call.

At the end of a writing operation, if the characteristic was configured to send back notifications to the BLE peer, one more callback function comes into play. It is part of another struct, <code>btstack_context_callback_registration_t</code>, that is used for the deferred sending of characteristic update notification to the BLE central. In this callback, <code>att_server_notify()</code> is called to finally send the write notification to the peer.

Raspberry Pi Microcontrollers

2025-05-09T19:24:53Z

Kai: BTstack Python output for a GATT user description declaration attribute

= Pico Series =
* Raspberry Pi Pico and Pico W
** Dual [https://developer.arm.com/Processors/Cortex-M0-Plus Arm Cortex-M0+] with Armv6-M programming model, up to 133 MHz
* Raspberry Pi Pico 2 and Pico 2 W
** Dual [https://developer.arm.com/Processors/Cortex-M33 Arm Cortex-M33] with Armv8-M programming model, up to 150 MHz

== Development Setup ==

=== Using the Raspberry Pi Debug Probe ===
The Debug Probe is a RP2040 based USB-to-UART/SWD board for connecting the USB slot of a development machine to the SWD or UART pins of a target device.

=== Using A Pico To Debug Another Pico ===
A Pico can be used to debug another Pico (a.k.a. target device) by flashing it with the [https://github.com/raspberrypi/debugprobe debugprobe] binary and wiring to the target Pico as shown below.

[[File:Wiring_rpi_pico_as_debugger.png | x320 px | A Raspberry Pi Pico wired to debug another Pico]]

From the debugger Pico to the target Pico,
* pin #4 (GP2) connects to pin SWCLK,
* pin #5 (GP3) connects to SWDIO,
* pin #6 (GP4, UART1 TX) connects to pin #2 (GP1, UART0 RX),
* pin #7 (GP5, UART1 RX) connects to pin #1 (GP0, UART0, TX).

The debugger Pico serves both as a USB-to-SWD and USB-to-UART bridge to the target device. The development machine, therefore, needs to be connected via USB only to the debugger Pico. Console output on the target Pico is relayed through the debugger. It is possible, though, to connect a second USB cable from the development machine to the target device for (simultaneous) direct access to the console output. This debugger setup works not just with Pico targets but with any microcontroller that supports the CMSIS-DAP protocol over SWD.

=== Software Tools for Debugging ===
Whether we use the Raspberry Pi Debug Probe or a spare Pico as debug probe, the software tools used for debugging are the same:
* openocd

== Notes on Programming with the C SDK ==

=== Async Context ===
In the C SDK, an [https://www.raspberrypi.com/documentation/pico-sdk/high_level.html#group_pico_async_context async_context] is used in concurrent programming to make sure that functions are executed on the same thread and in the order they were submitted, similar to dispatch queues in Apple's [https://developer.apple.com/documentation/dispatch?language=objc Dispatch framework]. The ''async_context'' data structure is a container of linked lists of worker functions that are executed within a single thread of a single processor core.

=== Bluetooth with BTstack ===

The C SDK integrates the third-party [https://bluekitchen-gmbh.com/btstack BTstack] framework as its Bluetooth API that interfaces with the Infineon CYW43 wireless communication module (on Pico W models) via the Host-Controller Interface (HCI) protocol.

==== Setup ====

Before we can call any BTstack functions (and hope for some meaningful outcome), we need to add a '''btstack_config.h''' header file to our project. In it, we add all the compile-time switches that fit our application. On a microcontroller, a frequent use case for BTstack is to implement a BLE peripheral. For this we, our config header should look something like this:

<syntaxhighlight lang="C">
#ifndef MY_BTSTACK_CONFIG_H
#define MY_BTSTACK_CONFIG_H

#ifndef ENABLE_BLE
#error In CMakeLists.txt add the 'pico_btstack_ble' library to target_link_libraries(...)
#endif

// logging
#define ENABLE_LOG_INFO
#define ENABLE_LOG_ERROR
#define ENABLE_PRINTF_HEXDUMP // required for hci_dump_init()

#if 1 // configure as peripheral (GATT server)
#define ENABLE_LE_PERIPHERAL
#define MAX_NR_GATT_CLIENTS 0
#else // configure as central (GATT client)
#define ENABLE_LE_CENTRAL
#define MAX_NR_GATT_CLIENTS 1
//#define ENABLE_GATT_CLIENT_PAIRING
#endif

// Setting various buffer sizes related to HCI communication
#define HCI_OUTGOING_PRE_BUFFER_SIZE 4
#define HCI_ACL_PAYLOAD_SIZE (255 + 4)
#define HCI_ACL_CHUNK_SIZE_ALIGNMENT 4
#define MAX_NR_HCI_CONNECTIONS 1
#define MAX_NR_SM_LOOKUP_ENTRIES 3
#define MAX_NR_WHITELIST_ENTRIES 16
#define MAX_NR_LE_DEVICE_DB_ENTRIES 16

// Choosing a fixed-size attributes table over using malloc.
// We want to use BTstack without heap memory allocations.
#if 1
#define MAX_ATT_DB_SIZE 512
#else
#define HAVE_MALLOC
#endif

// Enabling timers
#if 1
#define HAVE_EMBEDDED_TIME_MS
#else
#define HAVE_EMBEDDED_TICK
#endif

// Limiting the amount of nonvolatile (flash) memory used for storing peer bonding information
#define NVM_NUM_DEVICE_DB_ENTRIES 16
#define NVM_NUM_LINK_KEYS 16

// Configuring HCI Controller-to-Host flow control and related buffers to avoid overrunning the cyw43 shared bus
#define ENABLE_HCI_CONTROLLER_TO_HOST_FLOW_CONTROL
#define HCI_HOST_ACL_PACKET_LEN (255+4)
#define HCI_HOST_ACL_PACKET_NUM 3
#define HCI_HOST_SCO_PACKET_LEN 120
#define HCI_HOST_SCO_PACKET_NUM 3
#define MAX_NR_CONTROLLER_SCO_PACKETS 3
#define MAX_NR_CONTROLLER_ACL_BUFFERS 3

// Enabling btstack_assert, acting just like normal assert()
#define HAVE_ASSERT

// Setting HCI resend timeout in case the Bluetooth module needs more time to response.
#define HCI_RESET_RESEND_TIMEOUT_MS 800

// Configuring security
#define ENABLE_SOFTWARE_AES128
#define ENABLE_MICRO_ECC_FOR_LE_SECURE_CONNECTIONS

#endif // MY_BTSTACK_CONFIG_H
</syntaxhighlight>

==== GATT Profiles, Services, Characteristics, and Descriptors ====

A Bluetooth Low Energy Peripheral organizes the served data in a linear attributes table or database, referred to as ATT. The GATT (Generic Attributes) profile used in BLE is, contrary to what the name suggests, a specific organizational structure imposed on the ATT table, where the data table as a whole is referred to as "profile". The profile attributes can be broken down into consecutive "service" attributes, the service attributes into "characteristic" attributes, the characteristics into "descriptor" attributes. So, all in all there linear ATT table becomes a tree structure with four levels in GATT. A BLE peripheral, acting as a GATT server when connected to, will advertise its profile over GAP. A BLE central, acting as a GATT client after establishing a connection to the peripheral, can read the complete GATT hierarchy to find out about the profile contents.

BTstack allows defining a GATT table as a human-readable text file. The translation of that file into a C header by a Python script is a build step that can be included in ''CMakeLists.txt'' using the function ''pico_btstack_make_gatt_header()''. The generated C header contains the GATT table as an array of hex-coded bytes, laid out one line per attribute, with comments between the lines for orientation. Application code that needs to access the GATT table data then simply "#include"s this generated header file.

When defining the GATT table in BTstack's text format, we can use the following keywords for the attribute permissions of a characteristic:
* READ
* WRITE
* WRITE_WITH_RESPONSE
* NOTIFY: Adds a ''Client Configuration'' descriptor to the characteristic that allows a GATT client to control whether a notification is to be sent to the client each time the value of the characteristic changes.
* DYNAMIC: Indicates that reading and writing to this characteristic requires adding this case to the read and write callbacks.

===== BTStack Python script output for a GATT characteristic declaration attribute =====

Let's have a look at the output of the BTstack Python script that converts the .gatt file to a C header and let's narrow it down to just the characteristic declarations.

Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification]. That section also lists the characteristics permissions (or properties):
{| class="wikitable" style="margin:auto"
|-
! Properties !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

===== BTStack Python script output for a GATT user description declaration attribute =====

<pre>
0x08, 0x00, 0x0a, 0x01, 0x0a, 0x00, 0x01, 0x29,
</pre>

==== The BTstack runloop ====

The following articles by Hunter Adams offer a detailed analysis of how BTstack works on the Pico:
# [https://vanhunteradams.com/Pico/BLE/BTStack_HCI.html BTstack and RP2040: HCI (Host Controller Interface)].<br />This article delves, among other things, into how the BTstack runloop is executed inside a Pico [[#Async_Context | async_context]].<br /><blockquote>[...] we have just one ''when_pending_worker'' in our async_context. This worker is called ''cyw43_poll_worker'', and its ''do_work'' function points to ''cyw43_poll_func()'', listed above. This function ends up calling ''btstack_run_loop_poll_data_sources_from_irq()'', about which we'll learn more shortly. This worker gets marked as pending in a GPIO interrupt. So, this provides a mechanism by which the CYW43 can tell the RP2040 to run ''btstack_run_loop_poll_data_sources_from_irq()'' which, as we're going to learn, goes and gets data from the device.</blockquote>
# [https://vanhunteradams.com/Pico/BLE/GATT_Server.html Building a Bluetooth GATT Server on the Pi Pico W]

==== GATT Characteristic read and write operations ====

The struct <code>att_service_handler_t</code> represents a GATT service. After the fields of the struct have been filled in by the application code, it holds all the information needed for the BLE peripheral to make it available to the BLE central. Some of the fields of the struct hold the ATT handles that define the start and end of the collection of characteristics belonging to the service. Other fields of the struct (<code>read_callback</code> and <code>write_callback</code>) hold pointers to functions that handle reading from and writing to characteristic values.

Note that the ''read'' callback for a descriptor of a GATT characteristic (i.e., an ATT attribute) is called twice. In the first call, the buffer pointer passed to the callback function is NULL. In the second call, it's a valid pointer. The first call is made by BTstack to query the size of the data that will be returned by the second call. BTstack needs to make sure its transmission buffers can hold the amount of data before making the second call.

At the end of a writing operation, if the characteristic was configured to send back notifications to the BLE peer, one more callback function comes into play. It is part of another struct, <code>btstack_context_callback_registration_t</code>, that is used for the deferred sending of characteristic update notification to the BLE central. In this callback, <code>att_server_notify()</code> is called to finally send the write notification to the peer.

Raspberry Pi Microcontrollers

2025-05-09T19:22:36Z

Kai: /* BTStack Python script output for different attribute permission combinations */

= Pico Series =
* Raspberry Pi Pico and Pico W
** Dual [https://developer.arm.com/Processors/Cortex-M0-Plus Arm Cortex-M0+] with Armv6-M programming model, up to 133 MHz
* Raspberry Pi Pico 2 and Pico 2 W
** Dual [https://developer.arm.com/Processors/Cortex-M33 Arm Cortex-M33] with Armv8-M programming model, up to 150 MHz

== Development Setup ==

=== Using the Raspberry Pi Debug Probe ===
The Debug Probe is a RP2040 based USB-to-UART/SWD board for connecting the USB slot of a development machine to the SWD or UART pins of a target device.

=== Using A Pico To Debug Another Pico ===
A Pico can be used to debug another Pico (a.k.a. target device) by flashing it with the [https://github.com/raspberrypi/debugprobe debugprobe] binary and wiring to the target Pico as shown below.

[[File:Wiring_rpi_pico_as_debugger.png | x320 px | A Raspberry Pi Pico wired to debug another Pico]]

From the debugger Pico to the target Pico,
* pin #4 (GP2) connects to pin SWCLK,
* pin #5 (GP3) connects to SWDIO,
* pin #6 (GP4, UART1 TX) connects to pin #2 (GP1, UART0 RX),
* pin #7 (GP5, UART1 RX) connects to pin #1 (GP0, UART0, TX).

The debugger Pico serves both as a USB-to-SWD and USB-to-UART bridge to the target device. The development machine, therefore, needs to be connected via USB only to the debugger Pico. Console output on the target Pico is relayed through the debugger. It is possible, though, to connect a second USB cable from the development machine to the target device for (simultaneous) direct access to the console output. This debugger setup works not just with Pico targets but with any microcontroller that supports the CMSIS-DAP protocol over SWD.

=== Software Tools for Debugging ===
Whether we use the Raspberry Pi Debug Probe or a spare Pico as debug probe, the software tools used for debugging are the same:
* openocd

== Notes on Programming with the C SDK ==

=== Async Context ===
In the C SDK, an [https://www.raspberrypi.com/documentation/pico-sdk/high_level.html#group_pico_async_context async_context] is used in concurrent programming to make sure that functions are executed on the same thread and in the order they were submitted, similar to dispatch queues in Apple's [https://developer.apple.com/documentation/dispatch?language=objc Dispatch framework]. The ''async_context'' data structure is a container of linked lists of worker functions that are executed within a single thread of a single processor core.

=== Bluetooth with BTstack ===

The C SDK integrates the third-party [https://bluekitchen-gmbh.com/btstack BTstack] framework as its Bluetooth API that interfaces with the Infineon CYW43 wireless communication module (on Pico W models) via the Host-Controller Interface (HCI) protocol.

==== Setup ====

Before we can call any BTstack functions (and hope for some meaningful outcome), we need to add a '''btstack_config.h''' header file to our project. In it, we add all the compile-time switches that fit our application. On a microcontroller, a frequent use case for BTstack is to implement a BLE peripheral. For this we, our config header should look something like this:

<syntaxhighlight lang="C">
#ifndef MY_BTSTACK_CONFIG_H
#define MY_BTSTACK_CONFIG_H

#ifndef ENABLE_BLE
#error In CMakeLists.txt add the 'pico_btstack_ble' library to target_link_libraries(...)
#endif

// logging
#define ENABLE_LOG_INFO
#define ENABLE_LOG_ERROR
#define ENABLE_PRINTF_HEXDUMP // required for hci_dump_init()

#if 1 // configure as peripheral (GATT server)
#define ENABLE_LE_PERIPHERAL
#define MAX_NR_GATT_CLIENTS 0
#else // configure as central (GATT client)
#define ENABLE_LE_CENTRAL
#define MAX_NR_GATT_CLIENTS 1
//#define ENABLE_GATT_CLIENT_PAIRING
#endif

// Setting various buffer sizes related to HCI communication
#define HCI_OUTGOING_PRE_BUFFER_SIZE 4
#define HCI_ACL_PAYLOAD_SIZE (255 + 4)
#define HCI_ACL_CHUNK_SIZE_ALIGNMENT 4
#define MAX_NR_HCI_CONNECTIONS 1
#define MAX_NR_SM_LOOKUP_ENTRIES 3
#define MAX_NR_WHITELIST_ENTRIES 16
#define MAX_NR_LE_DEVICE_DB_ENTRIES 16

// Choosing a fixed-size attributes table over using malloc.
// We want to use BTstack without heap memory allocations.
#if 1
#define MAX_ATT_DB_SIZE 512
#else
#define HAVE_MALLOC
#endif

// Enabling timers
#if 1
#define HAVE_EMBEDDED_TIME_MS
#else
#define HAVE_EMBEDDED_TICK
#endif

// Limiting the amount of nonvolatile (flash) memory used for storing peer bonding information
#define NVM_NUM_DEVICE_DB_ENTRIES 16
#define NVM_NUM_LINK_KEYS 16

// Configuring HCI Controller-to-Host flow control and related buffers to avoid overrunning the cyw43 shared bus
#define ENABLE_HCI_CONTROLLER_TO_HOST_FLOW_CONTROL
#define HCI_HOST_ACL_PACKET_LEN (255+4)
#define HCI_HOST_ACL_PACKET_NUM 3
#define HCI_HOST_SCO_PACKET_LEN 120
#define HCI_HOST_SCO_PACKET_NUM 3
#define MAX_NR_CONTROLLER_SCO_PACKETS 3
#define MAX_NR_CONTROLLER_ACL_BUFFERS 3

// Enabling btstack_assert, acting just like normal assert()
#define HAVE_ASSERT

// Setting HCI resend timeout in case the Bluetooth module needs more time to response.
#define HCI_RESET_RESEND_TIMEOUT_MS 800

// Configuring security
#define ENABLE_SOFTWARE_AES128
#define ENABLE_MICRO_ECC_FOR_LE_SECURE_CONNECTIONS

#endif // MY_BTSTACK_CONFIG_H
</syntaxhighlight>

==== GATT Profiles, Services, Characteristics, and Descriptors ====

A Bluetooth Low Energy Peripheral organizes the served data in a linear attributes table or database, referred to as ATT. The GATT (Generic Attributes) profile used in BLE is, contrary to what the name suggests, a specific organizational structure imposed on the ATT table, where the data table as a whole is referred to as "profile". The profile attributes can be broken down into consecutive "service" attributes, the service attributes into "characteristic" attributes, the characteristics into "descriptor" attributes. So, all in all there linear ATT table becomes a tree structure with four levels in GATT. A BLE peripheral, acting as a GATT server when connected to, will advertise its profile over GAP. A BLE central, acting as a GATT client after establishing a connection to the peripheral, can read the complete GATT hierarchy to find out about the profile contents.

BTstack allows defining a GATT table as a human-readable text file. The translation of that file into a C header by a Python script is a build step that can be included in ''CMakeLists.txt'' using the function ''pico_btstack_make_gatt_header()''. The generated C header contains the GATT table as an array of hex-coded bytes, laid out one line per attribute, with comments between the lines for orientation. Application code that needs to access the GATT table data then simply "#include"s this generated header file.

When defining the GATT table in BTstack's text format, we can use the following keywords for the attribute permissions of a characteristic:
* READ
* WRITE
* WRITE_WITH_RESPONSE
* NOTIFY: Adds a ''Client Configuration'' descriptor to the characteristic that allows a GATT client to control whether a notification is to be sent to the client each time the value of the characteristic changes.
* DYNAMIC: Indicates that reading and writing to this characteristic requires adding this case to the read and write callbacks.

===== BTStack Python script output for a GATT characteristic declaration =====

Let's have a look at the output of the BTstack Python script that converts the .gatt file to a C header and let's narrow it down to just the characteristic declarations.

Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification]. That section also lists the characteristics permissions (or properties):
{| class="wikitable" style="margin:auto"
|-
! Properties !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

==== The BTstack runloop ====

The following articles by Hunter Adams offer a detailed analysis of how BTstack works on the Pico:
# [https://vanhunteradams.com/Pico/BLE/BTStack_HCI.html BTstack and RP2040: HCI (Host Controller Interface)].<br />This article delves, among other things, into how the BTstack runloop is executed inside a Pico [[#Async_Context | async_context]].<br /><blockquote>[...] we have just one ''when_pending_worker'' in our async_context. This worker is called ''cyw43_poll_worker'', and its ''do_work'' function points to ''cyw43_poll_func()'', listed above. This function ends up calling ''btstack_run_loop_poll_data_sources_from_irq()'', about which we'll learn more shortly. This worker gets marked as pending in a GPIO interrupt. So, this provides a mechanism by which the CYW43 can tell the RP2040 to run ''btstack_run_loop_poll_data_sources_from_irq()'' which, as we're going to learn, goes and gets data from the device.</blockquote>
# [https://vanhunteradams.com/Pico/BLE/GATT_Server.html Building a Bluetooth GATT Server on the Pi Pico W]

==== GATT Characteristic read and write operations ====

The struct <code>att_service_handler_t</code> represents a GATT service. After the fields of the struct have been filled in by the application code, it holds all the information needed for the BLE peripheral to make it available to the BLE central. Some of the fields of the struct hold the ATT handles that define the start and end of the collection of characteristics belonging to the service. Other fields of the struct (<code>read_callback</code> and <code>write_callback</code>) hold pointers to functions that handle reading from and writing to characteristic values.

Note that the ''read'' callback for a descriptor of a GATT characteristic (i.e., an ATT attribute) is called twice. In the first call, the buffer pointer passed to the callback function is NULL. In the second call, it's a valid pointer. The first call is made by BTstack to query the size of the data that will be returned by the second call. BTstack needs to make sure its transmission buffers can hold the amount of data before making the second call.

At the end of a writing operation, if the characteristic was configured to send back notifications to the BLE peer, one more callback function comes into play. It is part of another struct, <code>btstack_context_callback_registration_t</code>, that is used for the deferred sending of characteristic update notification to the BLE central. In this callback, <code>att_server_notify()</code> is called to finally send the write notification to the peer.

Raspberry Pi Microcontrollers

2025-05-09T19:18:57Z

Kai: Expanding on the GATT attribute that declares a characteristic

= Pico Series =
* Raspberry Pi Pico and Pico W
** Dual [https://developer.arm.com/Processors/Cortex-M0-Plus Arm Cortex-M0+] with Armv6-M programming model, up to 133 MHz
* Raspberry Pi Pico 2 and Pico 2 W
** Dual [https://developer.arm.com/Processors/Cortex-M33 Arm Cortex-M33] with Armv8-M programming model, up to 150 MHz

== Development Setup ==

=== Using the Raspberry Pi Debug Probe ===
The Debug Probe is a RP2040 based USB-to-UART/SWD board for connecting the USB slot of a development machine to the SWD or UART pins of a target device.

=== Using A Pico To Debug Another Pico ===
A Pico can be used to debug another Pico (a.k.a. target device) by flashing it with the [https://github.com/raspberrypi/debugprobe debugprobe] binary and wiring to the target Pico as shown below.

[[File:Wiring_rpi_pico_as_debugger.png | x320 px | A Raspberry Pi Pico wired to debug another Pico]]

From the debugger Pico to the target Pico,
* pin #4 (GP2) connects to pin SWCLK,
* pin #5 (GP3) connects to SWDIO,
* pin #6 (GP4, UART1 TX) connects to pin #2 (GP1, UART0 RX),
* pin #7 (GP5, UART1 RX) connects to pin #1 (GP0, UART0, TX).

The debugger Pico serves both as a USB-to-SWD and USB-to-UART bridge to the target device. The development machine, therefore, needs to be connected via USB only to the debugger Pico. Console output on the target Pico is relayed through the debugger. It is possible, though, to connect a second USB cable from the development machine to the target device for (simultaneous) direct access to the console output. This debugger setup works not just with Pico targets but with any microcontroller that supports the CMSIS-DAP protocol over SWD.

=== Software Tools for Debugging ===
Whether we use the Raspberry Pi Debug Probe or a spare Pico as debug probe, the software tools used for debugging are the same:
* openocd

== Notes on Programming with the C SDK ==

=== Async Context ===
In the C SDK, an [https://www.raspberrypi.com/documentation/pico-sdk/high_level.html#group_pico_async_context async_context] is used in concurrent programming to make sure that functions are executed on the same thread and in the order they were submitted, similar to dispatch queues in Apple's [https://developer.apple.com/documentation/dispatch?language=objc Dispatch framework]. The ''async_context'' data structure is a container of linked lists of worker functions that are executed within a single thread of a single processor core.

=== Bluetooth with BTstack ===

The C SDK integrates the third-party [https://bluekitchen-gmbh.com/btstack BTstack] framework as its Bluetooth API that interfaces with the Infineon CYW43 wireless communication module (on Pico W models) via the Host-Controller Interface (HCI) protocol.

==== Setup ====

Before we can call any BTstack functions (and hope for some meaningful outcome), we need to add a '''btstack_config.h''' header file to our project. In it, we add all the compile-time switches that fit our application. On a microcontroller, a frequent use case for BTstack is to implement a BLE peripheral. For this we, our config header should look something like this:

<syntaxhighlight lang="C">
#ifndef MY_BTSTACK_CONFIG_H
#define MY_BTSTACK_CONFIG_H

#ifndef ENABLE_BLE
#error In CMakeLists.txt add the 'pico_btstack_ble' library to target_link_libraries(...)
#endif

// logging
#define ENABLE_LOG_INFO
#define ENABLE_LOG_ERROR
#define ENABLE_PRINTF_HEXDUMP // required for hci_dump_init()

#if 1 // configure as peripheral (GATT server)
#define ENABLE_LE_PERIPHERAL
#define MAX_NR_GATT_CLIENTS 0
#else // configure as central (GATT client)
#define ENABLE_LE_CENTRAL
#define MAX_NR_GATT_CLIENTS 1
//#define ENABLE_GATT_CLIENT_PAIRING
#endif

// Setting various buffer sizes related to HCI communication
#define HCI_OUTGOING_PRE_BUFFER_SIZE 4
#define HCI_ACL_PAYLOAD_SIZE (255 + 4)
#define HCI_ACL_CHUNK_SIZE_ALIGNMENT 4
#define MAX_NR_HCI_CONNECTIONS 1
#define MAX_NR_SM_LOOKUP_ENTRIES 3
#define MAX_NR_WHITELIST_ENTRIES 16
#define MAX_NR_LE_DEVICE_DB_ENTRIES 16

// Choosing a fixed-size attributes table over using malloc.
// We want to use BTstack without heap memory allocations.
#if 1
#define MAX_ATT_DB_SIZE 512
#else
#define HAVE_MALLOC
#endif

// Enabling timers
#if 1
#define HAVE_EMBEDDED_TIME_MS
#else
#define HAVE_EMBEDDED_TICK
#endif

// Limiting the amount of nonvolatile (flash) memory used for storing peer bonding information
#define NVM_NUM_DEVICE_DB_ENTRIES 16
#define NVM_NUM_LINK_KEYS 16

// Configuring HCI Controller-to-Host flow control and related buffers to avoid overrunning the cyw43 shared bus
#define ENABLE_HCI_CONTROLLER_TO_HOST_FLOW_CONTROL
#define HCI_HOST_ACL_PACKET_LEN (255+4)
#define HCI_HOST_ACL_PACKET_NUM 3
#define HCI_HOST_SCO_PACKET_LEN 120
#define HCI_HOST_SCO_PACKET_NUM 3
#define MAX_NR_CONTROLLER_SCO_PACKETS 3
#define MAX_NR_CONTROLLER_ACL_BUFFERS 3

// Enabling btstack_assert, acting just like normal assert()
#define HAVE_ASSERT

// Setting HCI resend timeout in case the Bluetooth module needs more time to response.
#define HCI_RESET_RESEND_TIMEOUT_MS 800

// Configuring security
#define ENABLE_SOFTWARE_AES128
#define ENABLE_MICRO_ECC_FOR_LE_SECURE_CONNECTIONS

#endif // MY_BTSTACK_CONFIG_H
</syntaxhighlight>

==== GATT Profiles, Services, Characteristics, and Descriptors ====

A Bluetooth Low Energy Peripheral organizes the served data in a linear attributes table or database, referred to as ATT. The GATT (Generic Attributes) profile used in BLE is, contrary to what the name suggests, a specific organizational structure imposed on the ATT table, where the data table as a whole is referred to as "profile". The profile attributes can be broken down into consecutive "service" attributes, the service attributes into "characteristic" attributes, the characteristics into "descriptor" attributes. So, all in all there linear ATT table becomes a tree structure with four levels in GATT. A BLE peripheral, acting as a GATT server when connected to, will advertise its profile over GAP. A BLE central, acting as a GATT client after establishing a connection to the peripheral, can read the complete GATT hierarchy to find out about the profile contents.

BTstack allows defining a GATT table as a human-readable text file. The translation of that file into a C header by a Python script is a build step that can be included in ''CMakeLists.txt'' using the function ''pico_btstack_make_gatt_header()''. The generated C header contains the GATT table as an array of hex-coded bytes, laid out one line per attribute, with comments between the lines for orientation. Application code that needs to access the GATT table data then simply "#include"s this generated header file.

When defining the GATT table in BTstack's text format, we can use the following keywords for the attribute permissions of a characteristic:
* READ
* WRITE
* WRITE_WITH_RESPONSE
* NOTIFY: Adds a ''Client Configuration'' descriptor to the characteristic that allows a GATT client to control whether a notification is to be sent to the client each time the value of the characteristic changes.
* DYNAMIC: Indicates that reading and writing to this characteristic requires adding this case to the read and write callbacks.

===== BTStack Python script output for different attribute permission combinations =====

Let's have a look at the output of the BTstack Python script that converts the .gatt file to a C header and let's narrow it down to just the characteristic declarations.

Here is the binary sequence (in hex representation) generated for an attribute that declares a GATT characteristic with attribute UUID ''B0B0F155-B0B0-B0B0-B0B0-B0B000000101'' and permissions ''READ | DYNAMIC''
<pre>
0x1b, 0x00, 0x02, 0x00, 0x08, 0x00, 0x03, 0x28, 0x02, 0x09, 0x00, 0x01, 0x01, 0x00, 0x00, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0xb0, 0x55, 0xf1, 0xb0, 0xb0
</pre>
The bytes are grouped from left to right according to this scheme:
* 2 bytes for the length of this attribute definition: 0x001b (= 27 bytes)
* 2 bytes for the access permission of this attribute: 0x0002 (= read-only)
* 2 bytes for the attribute handle: 0x0008
* 2 bytes for the attribute type: 0x2803 (short 16-bit UUID that indicates a characteristic declaration)
* 1 byte for the access permissions of the declared characteristic: 0x02 (= read-only)
* 2 bytes for the attribute handle of the characteristic value: 0x0009
* 16 bytes for the 128-bit UUID of the characteristic: 0xb0b0f155b0b0b0b0b0b0b0b000000101
where '''the bytes in each group are in reverse order'''!

For the official specification of the Bluetooth 5.4 GATT characteristic declaration refer to section 3.3.1 in the [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html in the Bluetooth 5.4 Core Specification]. That section also lists the characteristics permissions (or properties):
{| class="wikitable" style="margin:auto"
|-
! Properties !! Value !! Description
|-
| Broadcast || 0x01 || If set, permits broadcasts of the Characteristic Value using Server Characteristic Configuration Descriptor. If set, the Server Characteristic Configuration Descriptor shall exist.
|-
| Read || 0x02 || If set, permits reads of the Characteristic Value using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-66cf484d-50cd-199f-dd0d-d0d02ad02ce0 Section 4.8]
|-
| Write Without Response || 0x04 || If set, permit writes of the Characteristic Value without response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9f1c2e38-8fbe-f60c-d885-076707c88a43 Section 4.9.1].
|-
| Write || 0x08 || If set, permits writes of the Characteristic Value with response using procedures defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-ba4b856a-6994-01e4-97f6-357f9be40990 Section 4.9.3] or [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-6ab738ad-6d26-1da1-7417-e83da50e90c5 Section 4.9.4].
|-
| Notify || 0x10 || If set, permits notifications of a Characteristic Value without acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-74673cc2-e704-a2fa-14bb-d175c27193ab Section 4.10]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Indicate || 0x20 || If set, permits indications of a Characteristic Value with acknowledgment using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-615ed0ff-f42b-827d-6427-6474fc21737c Section 4.11]. If set, the Client Characteristic Configuration Descriptor shall exist.
|-
| Authenticated Signed Writes || 0x40 || If set, permits signed writes to the Characteristic Value using the procedure defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-516bd731-2079-87f9-8002-c3ca92fbed4b Section 4.9.2].
|-
| Extended Properties || 0x80 || If set, additional characteristic properties are defined in the Characteristic Extended Properties Descriptor defined in [https://www.bluetooth.com/wp-content/uploads/Files/Specification/HTML/Core-54/out/en/host/generic-attribute-profile--gatt-.html#UUID-9154505c-6e2d-a35a-3f30-1da0383a2425 Section 3.3.3.1]. If set, the Characteristic Extended Properties Descriptor shall exist.
|-
|}

==== The BTstack runloop ====

The following articles by Hunter Adams offer a detailed analysis of how BTstack works on the Pico:
# [https://vanhunteradams.com/Pico/BLE/BTStack_HCI.html BTstack and RP2040: HCI (Host Controller Interface)].<br />This article delves, among other things, into how the BTstack runloop is executed inside a Pico [[#Async_Context | async_context]].<br /><blockquote>[...] we have just one ''when_pending_worker'' in our async_context. This worker is called ''cyw43_poll_worker'', and its ''do_work'' function points to ''cyw43_poll_func()'', listed above. This function ends up calling ''btstack_run_loop_poll_data_sources_from_irq()'', about which we'll learn more shortly. This worker gets marked as pending in a GPIO interrupt. So, this provides a mechanism by which the CYW43 can tell the RP2040 to run ''btstack_run_loop_poll_data_sources_from_irq()'' which, as we're going to learn, goes and gets data from the device.</blockquote>
# [https://vanhunteradams.com/Pico/BLE/GATT_Server.html Building a Bluetooth GATT Server on the Pi Pico W]

==== GATT Characteristic read and write operations ====

The struct <code>att_service_handler_t</code> represents a GATT service. After the fields of the struct have been filled in by the application code, it holds all the information needed for the BLE peripheral to make it available to the BLE central. Some of the fields of the struct hold the ATT handles that define the start and end of the collection of characteristics belonging to the service. Other fields of the struct (<code>read_callback</code> and <code>write_callback</code>) hold pointers to functions that handle reading from and writing to characteristic values.

Note that the ''read'' callback for a descriptor of a GATT characteristic (i.e., an ATT attribute) is called twice. In the first call, the buffer pointer passed to the callback function is NULL. In the second call, it's a valid pointer. The first call is made by BTstack to query the size of the data that will be returned by the second call. BTstack needs to make sure its transmission buffers can hold the amount of data before making the second call.

At the end of a writing operation, if the characteristic was configured to send back notifications to the BLE peer, one more callback function comes into play. It is part of another struct, <code>btstack_context_callback_registration_t</code>, that is used for the deferred sending of characteristic update notification to the BLE central. In this callback, <code>att_server_notify()</code> is called to finally send the write notification to the peer.

Raspberry Pi Microcontrollers

2025-05-08T21:19:15Z

Kai: Adding information about BLE GATT tables and BTstack's GATT files.

Raspberry Pi Microcontrollers

2025-05-08T08:44:53Z

Kai: /* Setup */

Raspberry Pi Microcontrollers

2025-05-08T07:36:16Z

Kai: Note on why BTstack calls the read callback twice.

Raspberry Pi Microcontrollers

2025-05-07T17:25:08Z

Kai: /* Bluetooth with BTstack */

Raspberry Pi Microcontrollers

2025-05-07T17:04:13Z

Kai: /* Bluetooth with BTstack */

Raspberry Pi Microcontrollers

2025-05-07T16:11:53Z

Kai: /* Bluetooth */

Raspberry Pi Microcontrollers

2025-05-06T06:36:44Z

Kai: /* Bluetooth */

Raspberry Pi Microcontrollers

2025-05-06T06:28:22Z

Kai: /* Bluetooth */

Raspberry Pi Microcontrollers

2025-05-06T06:17:12Z

Kai:

LT1

2025-05-03T06:57:15Z

Kai: /* RSA application */

<br />
LT1 is the land training platform for learning vehicle maneuvering skills.
=== Software Components ===
==== RSA application ====
Software stack
* [https://gitlab.com/robo.fish/edc EDC] library for controlling electronic devices.
* Raspberry Pi Pico C SDK
* [https://bluekitchen-gmbh.com/btstack BTstack] for Bluetooth LE communication

==== RTC application ====
* Uses the Core library.
* Operating environment based on Yocto 5.0 (Scarthgap)
* Uses the ROS 2 library.
=== Hardware Components ===
* [[Raspberry_Pi_Microcontrollers#Raspberry_Pi_Pico_Series | Raspberry Pi Pico W]] based [[Robot_State_Agent | RSA]] unit that controls the sensors and motors and provides remote control capabilities.
* [https://www.raspberrypi.com/products/compute-module-4/ Raspberry Pi Compute Module 4] based [[Robot_Task_Controller | RTC]] unit for computer vision and ROS integration.
* [https://www.waveshare.com/product/raspberry-pi/boards-kits/compute-module-4-4s-cat/cm4-nano-b.htm Waveshare Nano Base Board (B)] for Raspberry Pi Compute Module 4
* [https://www.raspberrypi.com/products/camera-module-v2 Raspberry Pi Camera Module 2]
* [[Arexx RP5]] tracked vehicle chassis with 2 DC motors.
* 7.4 V lithium-polymer battery
* Sensors
** [[HC-SR04]] ultrasonic range sensor
<br />
The design of LT1 is open. The project files are available [https://gitlab.com/robo.fish/robots/LT1 on GitLab].
<br />
<br />

=== Roadmap ===
* <span style="color:#888">Structural design</span>
* <span style="color:#888">Electrical design</span>
* <span style="color:#888">Manufacturing</span>
* <span style="color:#888">Basic functional software</span>
* <span style="color:#888">Testing and debugging</span>

LT1

2025-05-02T22:06:12Z

Kai: /* Hardware Components */

<br />
LT1 is the land training platform for learning vehicle maneuvering skills.
=== Software Components ===
==== RSA application ====
* Uses the EDC library for controlling electronic devices.
* Uses the Raspberry Pi Pico C SDK
==== RTC application ====
* Uses the Core library.
* Operating environment based on Yocto 5.0 (Scarthgap)
* Uses the ROS 2 library.
=== Hardware Components ===
* [[Raspberry_Pi_Microcontrollers#Raspberry_Pi_Pico_Series | Raspberry Pi Pico W]] based [[Robot_State_Agent | RSA]] unit that controls the sensors and motors and provides remote control capabilities.
* [https://www.raspberrypi.com/products/compute-module-4/ Raspberry Pi Compute Module 4] based [[Robot_Task_Controller | RTC]] unit for computer vision and ROS integration.
* [https://www.waveshare.com/product/raspberry-pi/boards-kits/compute-module-4-4s-cat/cm4-nano-b.htm Waveshare Nano Base Board (B)] for Raspberry Pi Compute Module 4
* [https://www.raspberrypi.com/products/camera-module-v2 Raspberry Pi Camera Module 2]
* [[Arexx RP5]] tracked vehicle chassis with 2 DC motors.
* 7.4 V lithium-polymer battery
* Sensors
** [[HC-SR04]] ultrasonic range sensor
<br />
The design of LT1 is open. The project files are available [https://gitlab.com/robo.fish/robots/LT1 on GitLab].
<br />
<br />

=== Roadmap ===
* <span style="color:#888">Structural design</span>
* <span style="color:#888">Electrical design</span>
* <span style="color:#888">Manufacturing</span>
* <span style="color:#888">Basic functional software</span>
* <span style="color:#888">Testing and debugging</span>

LT1

2025-05-02T21:54:12Z

Kai: /* Hardware Components */

<br />
LT1 is the land training platform for learning vehicle maneuvering skills.
=== Software Components ===
==== RSA application ====
* Uses the EDC library for controlling electronic devices.
* Uses the Raspberry Pi Pico C SDK
==== RTC application ====
* Uses the Core library.
* Operating environment based on Yocto 5.0 (Scarthgap)
* Uses the ROS 2 library.
=== Hardware Components ===
* [[Raspberry_Pi_Microcontrollers#Raspberry_Pi_Pico_Series | Raspberry Pi Pico W]] based [[Robot_State_Agent | RSA]] unit that controls the sensors and motors and provides remote control capabilities.
* [https://www.raspberrypi.com/products/compute-module-4/ Raspberry Pi Compute Module 4] based [[Robot_Task_Controller | RTC]] unit for computer vision and ROS integration.
* [https://www.waveshare.com/product/raspberry-pi/boards-kits/compute-module-4-4s-cat/cm4-nano-b.htm Waveshare Nano Base Board (B)] for Raspberry Pi Compute Module 4
* [[Arexx RP5]] tracked vehicle chassis with 2 DC motors.
* 7.4 V lithium-polymer battery
* Sensors
** [[HC-SR04]] ultrasonic range sensor
<br />
The design of LT1 is open. The project files are available [https://gitlab.com/robo.fish/robots/LT1 on GitLab].
<br />
<br />

=== Roadmap ===
* <span style="color:#888">Structural design</span>
* <span style="color:#888">Electrical design</span>
* <span style="color:#888">Manufacturing</span>
* <span style="color:#888">Basic functional software</span>
* <span style="color:#888">Testing and debugging</span>

LT1

2025-05-02T18:50:58Z

Kai:

<br />
LT1 is the land training platform for learning vehicle maneuvering skills.
=== Software Components ===
==== RSA application ====
* Uses the EDC library for controlling electronic devices.
* Uses the Raspberry Pi Pico C SDK
==== RTC application ====
* Uses the Core library.
* Operating environment based on Yocto 5.0 (Scarthgap)
* Uses the ROS 2 library.
=== Hardware Components ===
* Raspberry Pi Pico W based [[Robot_State_Agent | RSA]] unit that controls the sensors and motors and provides remote control capabilities.
* Raspberry Pi 5 or 6 based [[Robot_Task_Controller | RTC]] unit for computer vision and ROS integration.
* [[Arexx RP5]] tracked vehicle chassis with 2 DC motors.
* 7.4 V lithium-polymer battery
* Sensors
** [[HC-SR04]] ultrasonic range sensor
<br />
The design of LT1 is open. The project files are available [https://gitlab.com/robo.fish/robots/LT1 on GitLab].
<br />
<br />
=== Roadmap ===
* <span style="color:#888">Structural design</span>
* <span style="color:#888">Electrical design</span>
* <span style="color:#888">Manufacturing</span>
* <span style="color:#888">Basic functional software</span>
* <span style="color:#888">Testing and debugging</span>

LT1

2025-05-02T18:29:28Z

Kai:

<br />
LT1 is the land training platform that the Core can be connected to in order to learn typical land vehicle maneuvering skills. It consists of
* [[Core Module | Core]]
* [[Arexx RP5]] tracked vehicle chassis with 2 DC motors.
* 7.4 V lithium-polymer battery
* Raspberry Pi Pico W based [[Robot_State_Agent | RSA]] unit that controls the sensors and motors and provides remote control capabilities.
* Raspberry Pi 5 or 6 based [[Robot_Task_Controller | RTC]] unit for computer vision and ROS integration.
* Sensors
** [[HC-SR04]] ultrasonic range sensor
<br />
The design of LT1 is open. The project files are available [https://gitlab.com/robo.fish/robots/LT1 on GitLab].
<br />
<br />
=== Roadmap ===
* <span style="color:#888">Structural design</span>
* <span style="color:#888">Electrical design</span>
* <span style="color:#888">Manufacturing</span>
* <span style="color:#888">Basic functional software</span>
* <span style="color:#888">Testing and debugging</span>

File:RP5 Chassis 3D Model.png

2025-05-02T18:17:55Z

Kai:

Arexx RP5

2025-05-02T18:17:35Z

Kai:

[[File:RP5_Chassis.jpg | x380px ]]

The RP5 is a toy-sized barebones chassis for home robotics projects. It includes 2 DC motors, optical encoder wheels attached to the traction wheel axis, and a battery holder for 6 Mignon batteries. The RP5 is an obsolete product and has not been on sale for many years now.

== RP6 ==
The RP6 was a tracked vehicle robot built on top of the RP5. It was designed by the company Arexx Engineering and sold in Germany by Conrad Electronics in the late 2010s. Arexx Engineering have since stopped operating their original website (http:arexx.com). Detailed information about the RP6 and the improved version ''RP6v2'' is still available on these websites:
* https://rn-wissen.de/wiki/index.php?title=RP6
* https://rn-wissen.de/wiki/index.php?title=RP6v2

== 3D Models ==
A [https://www.freecad.org FreeCAD] model of the RP5 is available [https://gitlab.com/robo.fish/robots/hardware-design-library/-/blob/master/FreeCAD/RP5_CHASSIS.FCStd?ref_type=heads here].

[[File:RP5_Chassis_3D_Model.png | x380px ]]

Arexx RP5

2025-05-02T18:09:50Z

Kai:

Arexx RP5

2025-05-02T18:03:56Z

Kai:

[[File:RP5_Chassis.jpg | x380px ]]

== RP5 and RP6 ==
The RP5 is the barebones chassis part of the Arexx ''RP6''. The RP6 was a toy-sized tracked vehicle robotics kit designed by the company Arexx Engineering and sold by Conrad Electronics in Germany in 2018. Arexx Engineering have since stopped operating their original website (http:arexx.com). Detailed information about the RP6 and the improved version ''RP6v2'' is still available on these websites:
* https://rn-wissen.de/wiki/index.php?title=RP6
* https://rn-wissen.de/wiki/index.php?title=RP6v2

== 3D Models ==
A [https://www.freecad.org FreeCAD] model of the RP5 is available [https://gitlab.com/robo.fish/robots/hardware-design-library/-/blob/master/FreeCAD/RP5_CHASSIS.FCStd?ref_type=heads here].

File:RP5 Chassis.jpg

2025-05-02T18:03:18Z

Kai:

Arexx RP5

2025-05-02T18:00:57Z

Kai: Adds image at the top

[[File:RP5_Chassis.jpg | x400px ]]

== RP5 and RP6 ==
The RP5 is the barebones chassis part of the Arexx ''RP6''. The RP6 was a toy-sized tracked vehicle robotics kit designed by the company Arexx Engineering and sold by Conrad Electronics in Germany in 2018. Arexx Engineering have since stopped operating their original website (http:arexx.com). Detailed information about the RP6 and the improved version ''RP6v2'' is still available on these websites:
* https://rn-wissen.de/wiki/index.php?title=RP6
* https://rn-wissen.de/wiki/index.php?title=RP6v2

== 3D Models ==
A [https://www.freecad.org FreeCAD] model of the RP5 is available [https://gitlab.com/robo.fish/robots/hardware-design-library/-/blob/master/FreeCAD/RP5_CHASSIS.FCStd?ref_type=heads here].

LT1

2025-05-02T17:58:34Z

Kai:

<br />
LT1 is the land training platform that the Core can be connected to in order to learn typical land vehicle maneuvering skills. It consists of
* [[Core Module | Core]]
* [[Arexx RP5]] tracked vehicle chassis with 2 DC motors.
* 11.1 V lithium-polymer battery
* Arduino-based power and motor control circuitry
* [[HC-SR04]] ultrasonic range sensor
<br />
The design of LT1 is open. The project files are available [https://gitlab.com/robo.fish/robots/LT1 on GitLab]. At the moment, there is only a FreeCAD model of the RP5.
<br />
<br />
=== Roadmap ===
* <span style="color:#888">Structural design</span>
* <span style="color:#888">Electrical design</span>
* <span style="color:#888">Manufacturing</span>
* <span style="color:#888">Basic functional software</span>
* <span style="color:#888">Testing and debugging</span>

Arexx RP5

2025-05-02T17:55:36Z

Kai: Created page with "== RP5 and RP6 == The RP5 is the barebones chassis part of the Arexx ''RP6''. The RP6 was a toy-sized tracked vehicle robotics kit designed by the company Arexx Engineering and sold by Conrad Electronics in Germany in 2018. Arexx Engineering have since stopped operating their original website (http:arexx.com). Detailed information about the RP6 and the improved version ''RP6v2'' is still available on these websites: * https://rn-wissen.de/wiki/index.php?title=RP6 * https..."

== RP5 and RP6 ==
The RP5 is the barebones chassis part of the Arexx ''RP6''. The RP6 was a toy-sized tracked vehicle robotics kit designed by the company Arexx Engineering and sold by Conrad Electronics in Germany in 2018. Arexx Engineering have since stopped operating their original website (http:arexx.com). Detailed information about the RP6 and the improved version ''RP6v2'' is still available on these websites:
* https://rn-wissen.de/wiki/index.php?title=RP6
* https://rn-wissen.de/wiki/index.php?title=RP6v2

== 3D Models ==
A [https://www.freecad.org FreeCAD] model of the RP5 is available [https://gitlab.com/robo.fish/robots/hardware-design-library/-/blob/master/FreeCAD/RP5_CHASSIS.FCStd?ref_type=heads here].

HC-SR04

2025-05-02T17:39:56Z

Kai: /* Wiring and Voltage Levels */

<br />
[[File:sensor_HC-SR04_wiring.jpg | x600px ]]
<br />
<p style="text-align:justify; margin-top:1em">
The information here about the HC-SR04 ultrasonic distance sensor is based on vendor datasheets and various online sources, including [http://www.modmypi.com/blog/hc-sr04-ultrasonic-range-sensor-on-the-raspberry-pi a ModMyPi article] for Raspberry Pi and [http://www.elecfreaks.com/store/download/product/Sensor/HC-SR04/HC-SR04_Ultrasonic_Module_User_Guide.pdf the Elecfreaks user guide] for integration into Arduino.
</p>
=== Sensor Properties ===
{|
| Operating Voltage || 5 V DC
|-
| Operating Current || 15 mA
|-
| Operating Frequency || 40 kHz
|-
| Nearest Range || 3 cm
|-
| Farthest Range || 4 m
|-
| Beam Angle || 15 degrees
|-
| Input Trigger Signal || 10 μs TTL pulse (low: 0-0.8 V, high: 2 V to VCC, where VCC = 5 V ±10%)
|-
| Output Echo Signal || Output TTL level signal, proportional to range
|}

=== Wiring and Voltage Levels ===
The sensor module is connected via the four header pins on the board:

[[File:sensor_HC-SR04_pin_assignment.png | 120px]]

* ''Vcc'' for the 5 V supply voltage,
* ''Trig'' for the ultrasonic burst trigger signal input,
* ''Echo'' for the ultrasonic echo output signal, and
* ''Gnd'' for Ground.

<p style="text-align:justify; margin-top:1em">
The sensor circuit is designed for TTL-level signals (0 V for LOW and 5 V for HIGH) while the GPIO pins of most microcontrollers and single-board-computers (SBC) are designed for 3.3 V. We definitely need to drop the signal coming from the ''Echo'' pin to 3.3 V, otherwise we risk damaging the connected GPIO input. One would assume that we also need to transform the 3.3 V trigger signal from the GPIO to 5 V before feeding it to the ''Trig'' pin. Such a circuit is depicted below, where a simple voltage divider is used on ''Echo'' and a BJT transistor is used to step up the voltage for ''Trig''.
</p>
[[File:Sensor_HC-SR04_schematic_full_level_shifting.png | x250px ]]
<p>
It turns out that we don't need to shift the 3.3 V trigger GPIO output to 5 V. The ''Trig'' input of the HC-SR04 can be connected directly to the GPIO pin of the microcontroller or SBC because the HIGH voltage of the trigger pulse just needs to be higher than 2 V. The simplified circuit below, with just the voltage divider is our preferred solution then.
<p>
[[File:Sensor_HC-SR04_schematic_voltage_divider_only.png | x250px ]]

=== Operation ===
The controller starts the range measurement by raising pin ''Trig'' to 5 V for at least 10 μs and thereby triggering eight 40 kHz ultrasonic pulses (beyond the 20 kHz high frequency limit of human hearing). The pulse waves bounce off any nearby objects and some are reflected back to the sensor. The sensor detects these reflected waves and raises the ''Echo'' pin to 5 V for a duration proportional to the distance of the objects that the waves are reflected from.
</p>
[[File:sensor_HC-SR04_timing.png | 450px]]
<p style="text-align:justify; margin-top:2em;">
A single range measurement is therefore performed like this:
* Initialize by setting the ''Trig'' and ''Echo'' pins to LOW.
* Raise the ''Trig'' pin to HIGH for at least 10 μs.
* Wait for a rising edge on the ''Echo'' pin, start a timer when detected.
* Wait for the falling edge on the ''Echo'' pin, stop the timer when detected.
* Calculate the distance from the time that the ultrasonic waves spent travelling in air (distance = time * velocity / 2, where the velocity of ultrasonic waves in air is 340 m/s).
</p>
<p style="margin-top: 2em">
This capture from an oscilloscope shows the short trigger pulse (blue), and the following long echo pulse (green) for an object placed approximately 12 cm in front of the sensor.
</p>
[[File:Sensor_HC-SR04_signals.png | x400px ]]

=== Limitations ===
The ultrasonic sensor is not able to measure distances to objects with highly diffuse surfaces or surfaces that are angled so that most incoming waves are reflected away from the sensor.

=== Programming Examples ===
==== For Raspberry Pi, using Python ====

Before trying out the code example below, make sure that Raspberry Pi GPIO support for the Python programming environment is installed via
<pre class="terminal>
sudo apt install python-rpi.gpio
</pre>
<p>
The code below assumes that the output to the sensor's ''Trig'' pin is connected to GPIO pin #23 and the input from the sensor's ''Echo'' pin is connected to GPIO pin #24.
</p>

<syntaxhighlight lang="python">
import RPi.GPIO as GPIO
import time
GPIO.setmode(GPIO.BCM)

TRIG = 23
ECHO = 24

print "Distance Measurement In Progress"

GPIO.setup(TRIG,GPIO.OUT)
GPIO.setup(ECHO,GPIO.IN)

GPIO.output(TRIG, False)
print "Waiting For Sensor To Settle"
time.sleep(0.25)

GPIO.output(TRIG, True)
time.sleep(0.00001)
GPIO.output(TRIG, False)

while GPIO.input(ECHO)==0:
pulse_start = time.time()

while GPIO.input(ECHO)==1:
pulse_end = time.time()

pulse_duration = pulse_end - pulse_start

distance = pulse_duration * 17150
distance = round(distance, 2)
print "Distance:",distance,"cm"

GPIO.cleanup()
</syntaxhighlight>

==== For Raspberry Pi Pico, using the C SDK ====

<syntaxhighlight lang="C++">
#include <hardware/gpio.h>
#include <pico/stdlib.h>
#include <pico/types.h>
#include <pico/time.h>

// GPIO pins
const uint TRIG = 6;
const uint ECHO = 9;

const uint64_t SpeedOfSound = 34300; // centimeters per second

/// @return distance in centimeters, or -1 if there was an error
int measure()
{
// configuring GPIO pins
gpio_init(TRIG);
gpio_set_dir(TRIG, GPIO_OUT);
gpio_put(TRIG, false);

gpio_init(ECHO);
gpio_set_dir(ECHO, GPIO_IN);
gpio_set_input_enabled(ECHO, true);

absolute_time_t echoRiseTime = nil_time;
absolute_time_t echoFallTime = nil_time;
absolute_time_t echoTimeoutTime = nil_time;

// sending the trigger pulse
gpio_put(TRIG, true);
sleep_us(20); // must be at least 10 microseconds
gpio_put(TRIG, false);
echoTimeoutTime = make_timeout_time_ms(500); // 0.5 second

// waiting for the echo signal
while (echoFallTime == nil_time) {
sleep_us(3);
auto now = get_absolute_time();
if (now > echoTimeoutTime) {
return -1;
}
bool const echoIsHigh = gpio_get(ECHO);
if (echoRiseTime == nil_time) {
if (echoIsHigh) {
echoRiseTime = now;
}
} else if (echoIsHigh == false) {
echoFallTime = now;
}
}

if (echoRiseTime == nil_time || echoFallTime == nil_time || (echoRiseTime >= echoFallTime)) {
return -1;
}

// calculating the distance
auto duration = echoFallTime - echoRiseTime;
auto distance = (int)(duration * SpeedOfSound / 2 / 1000000);
return distance;
}
</syntaxhighlight>