|
Coming soon |
1. STM32WB - Bluetooth® Low Energy (BLE) AT Server Overview
This page describes the set of AT commands to control the STM32WB Series. AT commands are instructions used to control a modem. AT is the abbreviation of ATtention. For this concept, the Cortex®-M4 application microcontroller contains an AT project able to manage the concepts of GAP, GATT, Security and low-power. This document explains how to interface with the STM32WB Series microcontroller to manage multi Bluetooth® Low Energy-BLE apps handling (such as AT P2P server, AT Heart Rate) and GAP/GATT custom applications using AT instructions.
The BLE_AT_Server application is available by downloading STM32CubeWB[1] release
This project implements a set of AT commands used to build GAP/GATT custom server or client, peripheral or central application. It also implements P2P Server or Heart Rate applications that could be directly selected. The objective is to have an intermediate abstraction layer in order to allow a user to develop a basic application with a limited sets of commands to send.
The following sections contain the interface description, the AT commands definition, and the description of some use cases.
1.1. AT commands
The AT instruction set is a standard developed by Hayes to control modems. The command set consists in a series of short text strings for performing operations:
- at GAP level such as advertising, discovery, connection, security.
- at GATT level such as services and characteristics management and discovery, and operation on characteristics.
The AT instructions are transfered through Cortex®-M4 application microcontroller low-power UART (LPUART) without flow control.
The STM32WB Series microcontroller can be controlled either through a terminal emulator such as Tera Term or Termite, or through an embedded microcontroller AT client module.
The terminal emulator must be configured with the following parameters:
• Baud rate: 9600 • Data: 8 bits • Parity: none • Stop: 1 bit • Flow control: none • Each frame is delimited by a \n character
- AT command is composed of SET and QUERY operations.
- A single operation can be executed at a time.
The format of these operations is defined as follow:
- Set operation (a,b input parameters)
- AT+CMD=a,b
- OK
- Query operation (a,b return parameters)
- AT+CMD?
- +CMD:a,b
- OK
An event can be sent asynchronously by the server with following format:
- Events (a,b event parameters)
- <EVT=a,b
1.2. General commands
List of commands: initialization commands
| GAP Command | Description | Comments |
|---|---|---|
| BLE_RSThttps://wiki.st.com/stm32mcu/index.php?title=Wireless:STM32WB_-_BLE_AT_Server&action=edit§ion=5 | Sets the default values | |
| BLE_PUB_ADDR | Initializes public address | If needed, to be done before BLE_INIT |
| BLE_CONN_INT | Updates the connection interval | To send after link establishment if needed |
| BLE_CLEAR_DB | Clears the security database | |
| BLE_PERIPH_SEC_REQ | Sends a peripheral security request to the central | If needed, to be done before BLE_INIT |
| BLE_RF_POWER | Sets the TX power level of the device | Entered in dBm. See available values |
| BLE_INIT | Initializes public and random addresses, TX power level, name of the device: default values are used if not defined with previous AT commands. Sets default init values for the security | Default security values can be modified with BLE_IO_CAPA and BLE_SET_AUTHEN_REQ |
| BLE_IO_CAPA | Sets IO capability | Can be done before or after BLE_INIT |
| BLE_SET_AUTHEN_REQ | Sets authentication requirement of the device | Can be done before or after BLE_INIT |
| BLE_SVC | Initializes a predefined service (P2P server or Heart Rate) | BLE_SVC=1 creates service and characteristics for P2P_server service and starts advertising. BLE_SVC=2 creates service and characteristics for Heart_Rate service and starts advertising. |
List of commands: GAP commands
| GAP Command | Description | Comments |
|---|---|---|
| BLE_ADV_PARAM | Sets advertising parameters | |
| BLE_ADV | Starts, stops advertising | If no new defined advertising parameter, use of default parameters |
| BLE_CONN_INT | Updates the connection interval | To send after link establishment if needed |
| BLE_CLEAR_DB | Clears the security database | |
| BLE_PERIPH_SEC_REQ | Sends a peripheral security request to the central | To send after link establishment if needed |
| BLE_PAIRING_CONFIRM | Allows the user to confirm or the numeric comparison value showed through BLE_EVT_VALUE_CONFIRM | Used to answer BLE_EVT_VALUE_CONFIRM event |
| BLE_PASSKEY_RESP | Sends the passkey that will be used during the pairing process, in response to BLE_EVT_PASSKEY_REQ | Used to answer BLE_EVT_PASSKEY_REQ event |
List of commands: GATT commands
| GAP Command | Description | Comments |
|---|---|---|
| BLE_SVC | Initialize a service | BLE_SVC=3 to 5 creates a custom service |
| BLE_CHAR_ADD | Add a characteristic | Applicable to a custom service |
| BLE_NOTIF_VAL | Sets the characteristic value to be notified | value sent from the server to the client |
| BLE_INDIC_VAL | Sets the characteristic value to be indicated | value sent from the server to the client |
List of events: GAP events
| GAP Command | Description | Comments |
|---|---|---|
| BLE_EVT_CONN | After connection/disconnection | |
| BLE_EVT_UPD_CONN | After connection update | |
| BLE_EVT_PASSKEY_REQ | After pairing request (legacy pairing) | Needs to be answered with BLE_PASSKEY_RESP |
| BLE_EVT_VALUE_CONFIRM | After pairing request (Secure Connection) | Needs to be answered with BLE_PAIRING_CONFIRM |
| BLE_EVT_PAIRING | AT the end of pairing process | Returns status and reason parameters |
List of events: GATT events
| GAP Command | Description | Comments |
|---|---|---|
| BLE_EVT_WRITE | After characteristic write | Sent when a client writes a characteristic |
1.3. Initialization commands
1.3.1. Initialization - reset - BLE_RST
SET: 1
QUERY: No query for this command, it will return an error.
Example:
AT+BLE_RST=1 OK
1.3.2. Initialization - public address - BLE_PUB_ADDR
SET: <address>
public_addr: • 6 bytes address
QUERY: < public_addr >
Example:
AT+BLE_PUB_ADDR=0x112233445566 OK AT+BLE_PUB_ADDR? + BLE_PUB_ADDR: 0x112233445566 OK
1.3.3. Initialization – use of default random address – BLE_CFG_RAND_ADDR
SET: 1
QUERY: < default_rand_addr >
Example:
AT+BLE_CFG_RAND_ADDR=1 OK AT+BLE_RAND_ADDR? +BLE_ RAND_ADDR: 0x000000000000 AT+BLE_INIT=1 AT+BLE_RAND_ADDR? +BLE_RAND_ADDR: 0xC122aabbccdd (if CFG_STATIC_RANDOM_ADDRESS is defined in app_conf.h) OK AT+BLE_INIT? +BLE_INIT:0xC122aabbccdd,AT server,-0.15
1.3.4. Initialization – random address – BLE_RAND_ADDR
SET: <address>
random_addr:
- 6 bytes address
QUERY: < random_addr >
Example:
AT+BLE_RAND_ADDR=0xFF11223344CC OK AT+BLE_RAND_ADDR? + BLE_RAND_ADDR: 0xFF11223344CC OK
1.3.5. Initialization – name – BLE_NAME
SET: <name>
Name:
- String of characters (8 characters max)
QUERY: <name> (default name if no new name set)
Example:
AT+BLE_NAME=WB_ATCMD OK
1.3.6. Initialization – Tx power – BLE_RF_POWER
SET: <txpower>
txpower:
- From -40 dBm to 6 dBm (IC level)
List of supported values in dBm:
-40 -20,85 -19,75 -18,85 -17,6 -16,5 -15,25 -14,1 -13,15 -12,05 -10,9 -9,9 -8,85 -7,8 -6,9 -5,9 -4,95 -4 -3,15 -2,45 -1,8 -1,3 -0,85 -0,5 -0,15 0 1 2 3 4 5 6
QUERY: <txpower>
Example:
AT+BLE_RF_POWER=1 OK AT+BLE_RF_POWER? + BLE_RF_POWER:1 OK
1.3.7. Initialization – BLE_INIT
BLE_INIT to be used in case of custom application. If AT+BLE_INIT=1 is the first sent command, initialization of the following parameters is done: Public address, random address, device name, RF Tx power, security parameters. The default values applied in this case are: Public address: based on the company ID, the device ID and the Unique Device Number (UDN)
bit[47:24] : 24bits (OUI) equal to the company ID bit[23:16] : Device ID. bit[15:0] : The last 16bits from the UDN
Random address: based on the UDN and a defined value (0x0000ED6E) to fit the requirements of a random address. Device name: AT SERVER RF Tx power: -0.15 dBm IO Capability: IO_CAP_KEYBOARD_DISPLAY (4) Authentication requirements: no bonding mode (0), MITM (1), SC support supported but optional (1), no use of fixed pin (1), fixed pin (111111), public address (0)
If the public address, the random address, the name or the tx output power needs to be changed, send associated AT commands, BLE_PUB_ADDR, BLE_RAND_ADDR, BLE_NAME, BLE_RF_POWER before BLE_INIT.
If IO capability, authentication requirements parameters need to be changed, send BLE_IO_CAPA, BLE_SET_AUTHEN_REQ before or after BLE_INIT out of any link establishment.
SET: 1
Use default BD address, default name, default Tx Power if no new parameter has been defined.
Default initialization in case security (pairing) is started after link establishment:
These values could be changed when no link is established with BLE_IO_CAPA and BLE_SET_AUTHEN_REQ (commands described later)
If BLE_PUB_ADDR, BLE_RAND_ADDR, BLE_NAME or BLE_RF_POWER have been sent previously, the new parameters are taken into account.
QUERY: <public_addr>, <random_addr>, <name>, <txpower>
public_addr:
- Default PUB_BD_addr or new PUB_BD_addr if BLE_PUB_ADDR has been sent
random_addr:
- Default RAND_BD_addr or new RAND_BD_addr if BLE_RAND_ADDR has been sent
name:
- Default name or new name if BLE_NAME has been sent
txpower:
- Default txpower or new txpower if BLE_RF_POWER has been sent
Example:
AT+BLE_PUB_ADDR=0x112233332211 OK AT+BLE_INIT=1 OK AT+BLE_INIT? + BLE_INIT:0x112233332211, default_name, 0 OK
1.3.8. Initialization – IO capability - BLE_IO_CAPA
SET: <io_capability>
io_capability:
- 0: IO_CAP_DISPLAY_ONLY
- 1: IO_CAP_DISPLAY_YES_NO
- 2: IO_CAP_KEYBOARD_ONLY
- 3: IO_CAP_NO_INPUT_NO_OUTPUT
- 4: IO_CAP_KEYBOARD_DISPLAY
QUERY: <io_capability>
Example:
AT+BLE_IO_CAPA=1 OK AT+BLE_IO_CAPA? +BLE_IO_CAPA:1 OK
1.3.9. Initialization – authentication requirement - BLE_SET_AUTHEN_REQ
SET: <bonding_mode>, < mitm>, < sc_support>, < use_fixed_pin>, < fixed_pin>
bonding_mode:
- 0: no bonding mode’
- 1: bonding mode
mitm:
- 0: no MITM
- 1: MITM
sc_support:
- 0: SC pairing not supported
- 1: SC pairing supported but optional
- 2: SC pairing mandatory
use_fixed_pin:
- 0: use a fixed pin
- 1: do not use a fixed pin
fixed_pin:
- 0 to 999999
QUERY: <bonding_mode>, < mitm>, < sc_support>, < use_fixed_pin>, < fixed_pin>,< identity_address_type>
1.3.10. Initialization commands – P2P_server or Heart rate service creation – BLE_SVC
If BLE_SVC=1 or BLE_SVC=2 is sent, no need to send BLE_INIT. BLE_SVC=1 creates service and characteristics for P2P_server service and starts advertising BLE_SVC=2 creates service and characteristics for Heart_Rate service and starts advertising Use a phone with ST BLE Sensor to connect with WB55 and P2P server or Heart rate application. Available on Play store for Android and Apple store for IOS.
SET: <svc_id>
svc_id
- 0: no service
- 1: P2P service
- 2: Heart Rate
QUERY: <svc_id>
Example:
AT+BLE_SVC=1 – creates P2P_server service and starts advertising, returns OK AT+BLE_SVC=2 – creates Heart Rate service and starts advertising, returns OK AT+BLE_SVC? Returns the active service +BLE_SVC:2 OK
1.4. GAP commands
1.4.1. GAP command - Advertising set parameters – BLE_ADV_PARAM
SET: <entry_nb>
entry_nb:
- 1: 0,20ms,30ms,0
- 2: 0,180ms,200ms,0
- 3: 0,1s,2.5s,0
- 0, <adv_type>, <adv_int_min>, <adv_int_max>
adv_type:
- 0: connectable undirected advertising
- 1: connectable directed advertising
- 2: scannable undirected advertising
- 3: not connectable undirected advertising
adv_int_min:
- From 20 ms to 10240 ms (must be multiple of 0.625 ms)
adv_int_max:
- From 20 ms to 10240 ms (must be multiple of 0.625 ms)
QUERY: <adv_type>, <adv_int_min>, <adv_int_max>, <own_addr_type>
Example 1:
AT+BLE_ADV_PARAM=2 OK AT+BLE_ADV_PARAM? + BLE_ADV_PARAM:0,180,200,0,0 OK
Example 2:
AT+BLE_ADV_PARAM=0,0,32,48,0 OK AT+BLE_ADV_PARAM? + BLE_ADV_PARAM:0,32,48,0 OK
1.4.2. GAP command - Start/stop advertising – BLE_ADV
SET: <enable>
enable:
- 0: stop advertising
- 1: start advertising
If no param entered, use default values (config 1) If predefined config, use (1,2 or 3) If param entered, use the new parameters
QUERY: <enable>
Example:
AT+BLE_ADV=1 – starts advertising OK AT+BLE_ADV? +BLE_ADV:1 OK
1.4.3. GAP command - Connection update – BLE_CONN_INT
SET: <conn_int_min>,<conn_int_max>
conn_int_min:
- From 7,5 ms to 4000 ms (must be multiple of 1.25 ms)
conn_int_max:
- From 7,5 ms to 4000 ms (must be multiple of 1.25 ms)
QUERY: <conn_int_min>,<conn_int_max>
Example:
AT+BLE_CONN_INT=125,150 – asks for a new connection interval OK AT+BLE_CONN_INT? +BLE_CONN_INT:150,150 OK
1.4.4. GAP command - Clear the security database – BLE_CLEAR_DB
SET: 1
QUERY: No query for this command, it will return an error.
Example:
AT+BLE_CLEAR_DB = 1 OK
1.4.5. GAP command - Sends a peripheral security request to the central – BLE_PERIPH_SEC_REQ
SET: 1
QUERY: No query for this command, it will return an error.
Example:
AT+BLE_PERIPH_SEC_REQ = 1 OK
1.4.6. GAP command - Confirms or not the numeric comparison value in Secure Connection - BLE_PAIRING_CONFIRM
SET: <confirm_yes_no>
Confirm_yes_no:
- 0: no
- 1: yes
No query available. On reception of BLE_EVT_VALUE_CONFIRM, send AT+BLE_PAIRING_CONFIRM=<confirm_yes_no>
1.4.7. GAP command - Sends the passkey that will be used during the pairing process in Legacy pairing - BLE_PASSKEY_RESP
SET: <passkey>
passkey:
- passkey: 0 to 999999
No query available.
On reception of BLE_EVT_PASSKEY_REQ, send AT+BLE_PASSKEY_RESP=<passkey>
When the pairing is complete, reception of BLE_EVT_PAIRING With 2 parameters: status, reason.
Status:
- 0: pairing status success
- 1: pairing status timeout
- 2: pairing failed
- 3: encryption failed
Reason:
- 1: passkey entry failed
- 2: OOB not available
- 3: authentication request cannot be met
- 4: confirm value failed
- 5: pairing not supported
- 6: insufficient encryption key size
- 7: command not supported
- 8: unspecified reason
- 9: very early next attempt
- 10: invalid parameters
- 11: SC DHKEY check failed
- 12: SC numeric comparison failed
1.5. GATT commands
1.5.1. GATT command - Custom service creation - BLE_SVC
For the creation of a custom service, the command BLE_INIT is mandatory. Use a phone with ST BLE Toolbox to connect with WB55 and a custom service. Available on Play store for Android and Apple store for IOS.
SET: <svc_id>, <svc_uuid_type>, <uuid_16b>, <max_attr_record>
svc_id:
- 0: no service
- 3 to 5: custom service
svc_uuid_type:
- 1: 16 bits
- 2: 128 bits
uuid_16b:
- 16 bits service uuid
max_attr_record:
- 2 * nb_of_char + 1
QUERY: <svc_id>
If svc_uuid_type = 1, a range of UUID values has been pre-allocated, it is the Bluetooth Base UUID and has the value 00000000-0000-1000-8000- 00805F9B34FB. If svc_uuid_type = 2, the user enters 16 bits service uuid. The 128 bits service uuid is completed in BLE_AT_SERVER application with the following value 00000000-CC7A-482A-984A-7F2ED5B3E58F.
Example1:
- AT+BLE_INIT=1
- OK
- AT+BLE_SVC=3,1,0xAABB,10
- AT+BLE_ADV=1
- OK
Example2:
- AT+BLE_INIT=1
- OK
- AT+BLE_SVC=3,2,0xAABB,10
- AT+BLE_ADV=1
- OK
AT_SERVER: default complete local name 00:80:E1:26:F6:5B: default public BD address
Up to three custom services could be defined.
1.5.2. GATT command - Characteristic creation - BLE_CHAR_ADD
SET: <svc_id>, <char_id>, <char_uuid_type>, <char_uuid_16b>, <char_value_len>, <char_prop>, <sec_permission>, <gatt_evt_mask>
svc_id:
- 3: service id on which characteristic is added
char_id:
- 1 to 5: characteristic id
char_uuid_type:
- 1: 16 bits
- 2: 128 bits
char_uuid_16b:
- 16 bits char uuid
char_value_len:
- 1 to 245
char_prop:
- 0x00: CHAR_PROP_NONE
- 0x01: CHAR_PROP_BROADCAST
- 0x02: CHAR_PROP_READ
- 0x04: CHAR_PROP_WRITE_WITHOUT_RESP
- 0x08: CHAR_PROP_WRITE
- 0x10: CHAR_PROP_NOTIFY
- 0x20: CHAR_PROP_INDICATE
- 0x40: CHAR_PROP_SIGNED_WRITE
- 0x80: CHAR_PROP_EXT
sec_permission:
- 0x00: None
- 0x01: AUTHEN_READ
- 0x02: AUTHOR_READ
- 0x04: ENCRY_READ
- 0x08: AUTHEN_WRITE
- 0x10: AUTHOR_WRITE
- 0x20: ENCRY_WRITE
gatt_evt_mask:
- 0x00: GATT_DONT_NOTIFY_EVENTS
- 0x01: GATT_NOTIFY_ATTRIBUTE_WRITE
- 0x02: GATT_NOTIFY_WRITE_REQ_AND_WAIT_FOR_APPL_RESP
- 0x04: GATT_NOTIFY_READ_REQ_AND_WAIT_FOR_APPL_RESP
QUERY: No query for this command, it will return an error.
If char_uuid_type = 1, a range of UUID values has been pre-allocated, it is the Bluetooth Base UUID and has the value 00000000-0000-1000-8000- 00805F9B34FB
If char_uuid_type = 2, the user enters 16 bits characteristic uuid. The 128 bits service uuid is completed in BLE_AT_SERVER application with the following value 00000000-8E22-4541-9D4C-21EDAE82ED19.
Example 1:
- AT+BLE_CHAR_ADD=3,1,1,0x3344,2,26,0,1
- OK
Example 2:
- AT+BLE_CHAR_ADD=3,1,2,0x3344,2,10,0,1
- OK
1.5.3. GATT command - Setting of the characteristic value to notify - BLE_NOTIF_VAL
SET: <svc_id>, <char_id>, <char_val>
svc_id:
- 1 to 5: service id corresponding to the characteristic to be notified
char_id:
- 1 to 5: characteristic id to be notified
char_val:
- value to be notified
QUERY: No query for this command, it will return an error.
Example:
- AT+BLE_NOTIF_VAL=2,1,70 – sets HeartRate characteristic value to 70
By default, Energy expended value is set to 0, it is not displayed on phone.
- AT+BLE_NOTIF_VAL=1,2,1 – sets Button characteristic status, 0 and 1 are displayed alternatively (char_val = 0 has no effect)
1.5.4. GATT command - Setting of the characteristic value to indicate - BLE_INDIC_VAL
SET: <svc_id>, <char_id>, <char_val>
svc_id:
- 1 to 5: service id corresponding to the characteristic to be notified
char_id:
- 1 to 5: characteristic id to be notified
char_val:
- value to be notified
QUERY: No query for this command, it will return an error.
Example:
- AT+BLE_INDIC_VAL=3,1,10
1.5.5. Events generation
An event is an information received either from the remote device either from the local device to inform the application about status change or data received.
1.5.6. Security
The BLE security model includes 5 security features:
Pairing: process for creating one or more shared secret keys. Bonding: act of storing the keys created during pairing for use in subsequent connections in order to form a trusted device pair. Device authentication: verification that the two devices have the same keys. Encryption: provides message confidentiality. Message integrity: protects against fake messages.(4 bytes Message Integrity Check MIC)
BLE uses 2 security levels:
- Legacy Pairing – Short Temporary Key (STK). STK will be created to encrypt connection. Then, if bonding, LTK will be used for subsequent connections.
- Secure Connection – Long Term Key (LTK). LTK will be created to encrypt connection.
1.5.6.1. Legacy pairing and no fixed pin (initiated by the central)
Default initialization values can be changed when no link is established with: BLE_IO_CAPA=4 BLE_SET_AUTHEN_REQ=0,1,0,1,111111 (fixed pin is not used)
1.5.6.2. Legacy pairing and fixed pin (111111) (initiated by the central)
Default initialization values can be changed when no link is established with:
BLE_IO_CAPA=0 BLE_SET_AUTHEN_REQ=0,0,0,0,111111 (fixed pin = 111111 is used)
1.5.6.3. Secure connection (initiated by the central)
Use of default values when BLE_INIT is sent:
io_capability = 4 bonding_mode = 0 mitm = 1 sc_support = 1 use_fixed_pin = 1 fixed_pin = 111111 identity_address_type = 0
1.5.7. BLE_SVC=1 P2P_server
1.5.8. BLE_SVC=2 Heart Rate
1.5.9. BLE_SVC=3 Custom service
Add a characteristic with properties equal to write, read, notify Add a characteristic with properties equal to write, read, indicate
Write characteristics, enable notification and indication
Initialization sequence with specific parameters, change of connection interval
Initialization sequence with random address defined by the user
Initialization sequence with default random address (CFG_STATIC_RANDOM_ADDRESS defined in app_conf.h)
Initialization sequence with default random address generated with random generator (CFG_STATIC_RANDOM_ADDRESS not defined in app_conf.h)
Initialization sequence with a new name
