13 Bluetooth Low Energy (BLE) - AWS IoT ExpressLink
Complete Peripheral Configuration Examples13.1 BLE initialization13.2 BLE CENTRAL role commands13.3 BLE PERIPHERAL role commands13.4 Pairing, Bonding and Filtering

13 Bluetooth Low Energy (BLE)

ExpressLink modules can take advantage of additional (local) connectivity capabilities, optionally available on selected SoCs. Bluetooth Low Energy (BLE) is one prominent example of such capabilities used to communicate with accessories and other modules or gateways over a local (personal) area network.

BLE interfaces can be configured by means of profiles which describe a collection of attributes used to transfer individual pieces of information between two devices. Devices can assume one of two roles:

  1. Central – a BLE device which initiates an outgoing connection request to an advertising peripheral device.

  2. Peripheral - the BLE device which accepts an incoming connection request after advertising its presence and capabilities.

A host processor can access BLE features of a capable ExpressLink module through the set of commands described in this chapter. Additionally, a set of events is available to support asynchronous communication with the host (see the BLE specific events in Table 4 - ExpressLink event codes) and the configuration parameters in the ExpressLink configuration dictionary (see Table 3 - Configuration dictionary non-persistent keys ).

BLE Central Device Configuration

In particular, BLE devices that adopt a central role require the host to initialize common configuration using the BLECentral parameter, and one or more BLECentral# parameters in order to describe the (peripheral) devices they wish to connect to. The numerical suffix # is an integer between 1 and MaxBLECentral - a value dependent on the module capabilities. (Manufacturers of ExpressLink modules are required to publish the MaxBLECentral value in the module datasheet).

BLECentral configuration parameters use JSON notation and expect the following keys:

  • filterDups (1/0) – filters duplicate broadcasts by the same device.

  • address is specified as:

    "address": {"type": type, "BDAddress":"AA:BB:CC:DD:EE:FF"}

    Where type is:

    • "Public": Public Address (Fixed IEEE MAC address assigned by vendor - default).

    • "Random": Static Random Address (Manually configured static/random address).

    • "RPAPublic": Public Identity Address (Public address but used with identity resolution).

    • "RPARandom”: Random Identity Address (Automatically generated random static address with identity resolution).

    BDAddress is specified only when type is Random or RPARandom.

  • IOCapabilities: Specifies I/O Capability of the host, used during pairing (see 13.4 Pairing, Bonding and Filtering).

    • Setting "IOCapability":{"display":0,"keyboard": 0,"YesNo": 0} implies Just Works method.

  • customFilters (JSON object) – additional vendor-defined filtering options (must be documented by the vendor on the module's datasheet).

Individual BLECentral# configuration parameters use JSON notation and expect the following keys:

  • peer mac address of a target peripheral device is specified as:

    "peer": "AA:BB:CC:DD:EE:FF"

    Where the address type is “Public” by default, or:

    "peer": type, "BDAddress":"AA:BB:CC:DD:EE:FF"}

    Where type is:

    • "Public": Public Address (Fixed IEEE MAC address assigned by vendor - default).

    • "Random": Static Random Address (Manually configured static/random address).

    • "RPAPublic": Public Identity Address (Public address but used with identity resolution).

    • "RPARandom”: Random Identity Address (Automatically generated random static address with identity resolution).

    Note

    If the peer address was found using AT+BLE GET DISCOVER (see 13.2.2 BLE GET DISCOVER   »Retrieve the collected advertising information« ), the address type should match the type reported as the last response item..

  • customFilters (JSON object) – additional vendor-defined filtering options (must be documented by the vendor on the module's datasheet).

BLE Peripheral Device Configuration

BLE devices adopting a peripheral role require the host to initialize the BLEPeripheral (single) configuration parameter in order to describe the device's connection requirements. BLEPeripheral configuration parameters use JSON notation and expect the following keys:

  • mode: Indicates advertising mode. Possible values are:

    • "LEGACY": refers to BLE specifications before 5.0. (default).

    • "EXTENDED": refers to the extended advertising as define in BLE specification 5.0 and later.

  • IOCapability: Specifies I/O Capability of the peripheral, used during pairing (see 13.4 Pairing, Bonding and Filtering), possible values are:

    • "display": 0/1 the device can interact with a user via a display (default 0)

    • "keyboard": 0/1 the device can interact with the user via a keyboard to enter numerical values (default 0)

    • "YesNo": 0/1 the device has buttons for the user to accept or reject a connection (default 0)

    Note

    "IOCapability": {"display":0,"keyboard": 0,"YesNo": 0} implies “Just Works” pairing method.

  • filterPolicy: Used to apply a filter policy using the following keys:

    • "ALLOW_LIST_SCAN": to grant scan requests to devices in the AllowList.

    • "ALLOW_LIST_CONNECT": to grant connection requests to devices in the AllowList.

  • address: is specified as:

    "address": {"type": type, "BDAddress":"AA:BB:CC:DD:EE:FF"}

    Where type is:

    • "Public": Public Address (Fixed IEEE MAC address assigned by vendor - default).

    • "Random": Static Random Address (Manually configured static/random address).

    • "RPAPublic": Public Identity Address (Public address but used with identity resolution).

    • "RPARandom”: Random Identity Address (Automatically generated random static address with identity resolution).

    BDAddress is specified only when type is Random or RPARandom.

Note

While it is possible to cancel an ongoing advertisement, by editing the advertisement configuration filterPolicy and re-advertising, it is not possible to do the same with the address type. For address type changes to take effect, you need to AT+RESET the device.

Table 8 - BLEPeripheral filterPolicy configuration options

ALLOW_LIST_CONNECT

ALLOW_LIST_SCAN

Description

0

0

Allow both scan and connection request from anyone

0

1

Allow scan requests from AllowList devices only and connection requests from anyone

1

0

Allow scan requests from anyone and connection requests from AllowList devices only

1

1

Allow scan and connection requests from AllowList devices only

  • raw is used to assign pre-encoded complete (hex) strings for the advertisement and response. (The raw data is expected as per the BLE link layer specification. It is directly sent in the same form over the air without any further processing. Thus, certain multi-octet fields need to be reversed. Please refer to the Bluetooth Core Specification: Vol 6, Part B, § 1.2 “Bit ordering” and Vol 1, Part E, § 2.9 “Type Names”).

  • appearance (string) – a 4 digit hex number that represents the type of device. (See page 28 of the Bluetooth Specification).

Example 1

AT+CONF BLEPeripheral={"mode": "LEGACY", 
    "IOCapability":{"display":0,"keyboard":0,"YesNo": 0}, 
    "filterPolicy": {"ALLOW_LIST_SCAN":0,"ALLOW_LIST_CONNECT": 0}, 
    "raw":{"advertisement":"02010603030F18", 
        "response":"0C09457870726573734C696E6B"}, 
     "address":{"type":"RPARandom"}
}
Note

Basic parsing of the JSON string happens when the CONF command is executed, hence formatting errors (ERR 4 – PARAMETER ERROR) can be immediately reported. Configuration keys/values are validated only at connection time, when a BLE peripheral initialization is attempted, and may cause it to fail (ERR27 – BLE ERROR or ERR28 – CONFIGURATION ERROR).

BLE Characteristics Configuration

Both Central and Peripheral devices require the host to initialize one or more BLEGATT# parameters in order to describe individual characteristics they wish to publish or access. The numerical suffix # is an integer between 1 and MaxBLEGATT - a value dependent on the module's capabilities. (Manufacturers of ExpressLink modules are required to publish the MaxBLEGATT value in the module datasheet).

BLEGATT# configuration parameters use JSON notation and expect the following keys:

  • service (UUID string) – the UUID of a BLE service.

  • chr (UUID string) – the UUID of a BLE characteristic.

  • write (permission bitmask in decimal) – optional

  • read (permission bitmask in decimal) – optional

  • indicate (permission bitmask in decimal) – optional

  • notify (permission bitmask in decimal) – optional

UUID strings can be in short form 4 hex-digits (for example, "20AD") for short 16-bit services and characteristics, or long form 128-bit for custom service and characteristic identifiers (for example, "00000000-0000-1000-8000-00805F9B34FB"). Long form UUID separators ("-") can be omitted. The default value for optional keys is 0. The maximum size of a characteristic value is MaxBLECharLen bytes, where MaxBLECharLen is a value (>=31) defined by the vendor and documented in the module datasheet.

Example 2: Two services composed of one characteristic each

AT+CONF BLEGATT1={"service": "1809", "chr": "2A1C" } 
    # Thermometer service, Temperature characteristic. 

AT+CONF BLEGATT2={"service": "180F", "chr": "2A19" } 
    # Battery Level service and level(%) characteristic.

Since BLEGATT# configuration parameters describe only one characteristic each, multiple parameters are required to describe a complex service composed of a number of characteristics.

Example 3: A service composed of two characteristics.

AT+CONF BLEGATT1={"service": "180D", "chr": "2A37" }
    # Heart rate service, heart rate measurement characteristic. 

AT+CONF BLEGATT2={"service": "180D", "chr": "2A38" } 
    # Heart rate service, body sensor location characteristic

Permission bitmasks are defined as decimal values computed as follows:

Table 9 - Characteristics Permissions Bitmask

Bit Position (lsb to msb)

Permission

0

On / Enabled

1

Encrypt

2

Authenticate

3

Authorize

4

Write-Without-Response

5 and higher

Reserved (must be 0)

Details:

  • Encrypted: If set, the link will be required to be encrypted.

  • Athenticate: If set, implies that Man-In-the-Middle (MITM) protection must be enabled. If the Just Works pairing method is used, any attempt to use a characteristic that sets this flag will be rejected since this pairing method does not provide MITM protection.

  • Authorize: If set, will generate an Authorize event (see Table 4 - ExpressLink event codes - ExpressLink event codes). The host is required to approve or deny access to the characteristic (see 13.3.6 BLE AUTH[#] [0/1]   »Authorize access to a characteristic« )

  • Write-Without-Response: (this applies only to the write property) If set, a write command will not generate a response (shortening the transaction).

When a module is acting as a Central, if the Peripheral on the other side has both Write and Write-Without- Response flag set on a characteristic, the module acting as BLE Central will carry out the full 'write' operation, overriding the 'write-without-response' option. Only if the peripheral has exclusively set the Write-Without-Response flag, a 'write-without-response' operation is carried out.

Table 10 - Example Values for Write property

Value (Decimal)

Binary Representation

Decoding

Notes

0

00000

Write Disable

1

00001

On

Write Enabled

3

00011

On + Encrypt

Encrypted link required for write operation

7

00111

On + Encrypt + Authenticate

Encrypted and Authenticated (MITM protected) link required for write operation

9

01001

On + Authorize

Trigger authorization event before allowing write operation for this attribute

18

10010

Encrypt + Write-Without-Resp

Encrypted but only write without response operation are allowed for this attribute

BLE Descriptors Configuration

BLE descriptors are attributes that provide additional information about a BLE characteristic, helping to describe its value and how it should be used. They essentially act as metadata for characteristics, offering details about their format, meaning, and how they can be interacted with. BLE descriptors can be configured using the same BLEGATT# configuration dictionary entries used for normal characteristics but with the following distinctions:

  • A desc key is added to provide the descriptor’s uuid-string

  • No notify, indicate or write-without-response (permission bitmask) are allowed

Example: Define the Environmental Sensing Service (0x181A) with Temperature characteristic (0x2F6A), and Presentation Format Descriptor (0x2904). Then assign a value like below to the descriptor:

  • Flags: sint16 (0x00 0x00)

  • Sampling Function: uint8 (0x02) Arithmetic Mean

  • Measurement Period: uint24 (0x000096) -> Little endian (0x96 0x00 0x00) = 150s

  • Update Interval: uint24(0x000384) -> (0x84 0x03, 0x00) = 900s

  • Application: uint8(0x04) = soil

  • Measurement Uncertainty: uint8(0xFF) = Unknown uncertainty

AT+CONF BLEGATT1={"service":"181A", "chr":"2A6E", "read":"1"} 
AT+CONF BLEGATT2={"service":"181A", "chr":"2A6E", "desc":"290C", "read":"1"} 
AT+BLE SET1 6009Big endian: 0x0960, Actual: 2400 in C/100 = 24 C) 
AT+BLE SET2 00000296000084030004FF

Complete Peripheral Configuration Examples

Example 1:

1. Configure BLE in Peripheral mode:

AT+CONF BLEPeripheral={
 "mode": "LEGACY",
 "IOCapability":{"display":0,"keyboard":0,"YesNo": 0},
 "filterPolicy":{"ALLOW_LIST_SCAN":0,"ALLOW_LIST_CONNECT":0},
 "raw":{"advertisement":"02010603030F18","response":"0C09457870726573734C696E6B"},
 "address":{"type":"RPARandom"}
}

Where:

  • "mode": "LEGACY" implies legacy advertisement mode (before BLE spec 5.0).

  • "IOCapability":{"display":0,"keyboard": 0,"YesNo": 0} the host has no special I/O capability but can perform "Just Works" pairing.

  • "filterPolicy": {"ALLOW_LIST_SCAN":0,"ALLOW_LIST_CONNECT": 0} allow both scan and connection requests from anyone

  • "raw" allows full configurability of the advertisement and response data.

  • "address":{"type":"RPARandom"} Random Identity Address (automatically generated random static address) with identity resolution.

2. Define service 180D, characteristic 2A37:

AT+CONF BLEGATT1={"service":"180D", "chr":"2A37", "write":18, "read":3}

The write bitmask (18) enables write operations but allows only write-without-response operations. The read bitmask (3) enables read operations but requires an encrypted link.

3. Define service 180D, characteristic 2A38:

AT+CONF BLEGATT2={"service":"180D", "chr":"2A38", "write":3, "read":1,"indicate":1, "notify":1}

The write bitmask (3) enables write (with response) operations but requires an encrypted link. The read bitmask (1) enables read operations and does not require an encrypted link. The indicate bitmask (1) enables indicate operations and does not require an encrypted link. The notify bitmask (1) enables notify operations and does not require an encrypted link.

4. Initialize the peripheral:

AT+BLE INIT PERIPHERAL

5. Advertise the peripheral:

AT+BLE ADVERTISE

After successful connection, you receive the event: 40 0 BLE CONNECTED. Any Central device (for example, smartphone) can now see the device and connect to it.

 

Example 2: Configuring a device as peripheral and retrieve its BDAddress.

1. Configure the device as a peripheral with automatically assigned address and identity resolution:

AT+CONF BLEPeripheral = {"address": {"type":"RPARandom"}}
OK

2. Configure characteristics and descriptors:

AT+CONF BLEGATT1={"service":"180D", "chr":"2A37", "write":1, "read":1, "indicate":1}
OK
AT+CONF BLEGATT2={"service":"180D", "chr":"FFF1", "write":1, "read":1, "notify":1}
OK
AT+CONF BLEGATT3={"service":"180D", "desc":"FFF2", "write":1, "read":1}
OK

3. Initialize the peripheral:

AT+BLE INIT PERIPHERAL
OK

4. Retrieve the automatically assigned address:

AT+CONF? BLEPeripheral
OK
{"mode":"LEGACY", "address": {"type":"RPARandom","BDAddress":"FD:15:18:24:FC:6D"}}

13.1 BLE initialization

13.1.1 BLE INIT [CENTRAL|PERIPHERAL]   »Initializing the device role«

Initialize the BLE interface to operate in the selected (GAP) role. Note how this version of the ExpressLink specification allows a device to be configured as Central or Peripheral but not both. Once a BLE interface is initialized, the only way to terminate it or change its mode of operation is to use the RESET command. However, doing so will disconnect the device (if it is connected) and will reset all internal state. Non-persistent configuration parameters (see Table 3 - Configuration dictionary non-persistent keys ) will be reinitialized, all subscriptions will be terminated, and the message queues will also be emptied.

For Central Mode:

Issuing the INIT CENTRAL command does not require (yet) any of the BLE configuration parameters to be set. One or more BLECentral# and BLEGATT# configuration parameters will be required later, before issuing an actual connection request (see the BLE CONNECT command). BLECentral# and BLEGATT# parameters are used in central mode to act as filters to identify suitable connection target devices.

For Peripheral Mode:

Issuing the INIT PERIPHERAL command requires the BLEPeripheral and one (or more) BLEGATT# configuration parameters to be set. BLEGATT keys do not need to be set in numerical order. All BLE parameters found (initialized) in the configuration dictionary will be used to define the peripheral’s GATT service. After initialization, the host may not change the BLEGATT# service composition (characteristics) without first resetting the device. The host can instead update or retrieve the latest characteristic values using the appropriate SET/GET commands (see BLE SET and BLE GET commands).

Returns:
13.1.1.1   OK{EOL}

If the command was accepted and the requested central or peripheral role is set.

13.1.1.2   ERR4 PARAMETER ERROR{EOL}

If the role parameter was not CENTRAL or PERIPHERAL.

13.1.1.3   ERR28 CONFIGURATION ERROR{EOL}

If the peripheral role was selected and the configuration dictionary does not contain the BLEPeripheral and at least one BLEGATT# parameter.

13.1.1.4   ERR25 NOT ALLOWED{EOL}

If the BLE role was already initialized.

13.1.1.5   ERR27 BLE ERROR{EOL}

Failed to initialize the BLE Stack.

13.1.1.6  

filterDups is 0 by default.

Example 1:

AT+BLE INIT CENTRAL{EOL}
OK
AT+CONF BLECENTRAL1={"peer": "a4:c1:38:12:56:5d"}{EOL}
OK

Example 2:

AT+CONF BLEPeripheral={"appearance": "4142"}{EOL}
OK
AT+CONF BLEGATT2={"service": "1809" ,"chr": "2A1C" }{EOL}
OK
AT+BLE INIT PERIPHERAL{EOL}
OK

13.2 BLE CENTRAL role commands

13.2.1 BLE[#] DISCOVER [duration|CANCEL]   »Scanning and Advertisement«

BLE capable devices can communicate with accessories without establishing permanent connections by means of a scanning and advertising protocol. This protocol is commonly used for characteristics whose value is required infrequently (device battery level, or ambient temperature sensors).

Figure 7 - BLE scanning for devices

Figure 7 - BLE scanning for devices

 

The ExpressLink module scans for advertisements from peripherals that match criteria defined in the corresponding configuration string BLECentral#. This is an asynchronous command. It returns an immediate response to confirm the process has started (or an error prevented it). During the scanning time, any advertised data received will be queued. The scanning process will stop after a set amount of time optionally configured by the duration parameter (30 seconds by default), and a BLE DISCOVER COMPLETE event (see Table 4 - ExpressLink event codes) will be produced. Queued data can then be retrieved using the BLE GET DISCOVER command.

The CANCEL parameter is used to terminate an ongoing scanning process.

13.2.1.1   Scans for all the nearby devices if BLECentral# is set to {} (an empty JSON object).

13.2.1.2   If the command is issued while a scanning process is in progress, any queued data is discarded and a new scanning process is started.

13.2.1.3   If {duration} is provided, only devices found within {duration} seconds will be captured.

13.2.1.4   Enqueues a BLE DISCOVER COMPLETE event on successful Discover complete or cancellation (see Table 4 - ExpressLink event codes).

13.2.1.5   Enqueues a BLE DISCOVER ERROR event when the discovery fails for any reason. Hint codes can be defined by the vendor to provide additional insight on the reason for the failure. (Hint codes must be documented in the module datasheet).

Returns:
13.2.1.6   OK{EOL}

If the command was accepted and the scanning sequence started.

13.2.1.7   OK{EOL}

If the CANCEL parameter is given and the cancellation request was successfully submitted. CANCEL will terminate any scanning activity in progress regardless of the # index given. However, a suffix index is required for the command to execute.

13.2.1.8   ERR4 PARAMETER ERROR{EOL}

If the parameter is 0 seconds.

13.2.1.9   ERR4 PARAMETER ERROR{EOL}

If the numerical suffix # is omitted.

13.2.1.10   ERR7 OUT OF RANGE{EOL}

If the numerical suffix # is out of bounds (0 or greater than MaxBLECentral).

13.2.1.11   ERR8 PARAMETER UNDEFINED{EOL}

If the numerical suffix # points to an empty BLECentral# string.

13.2.1.12   ERR25 NOT ALLOWED{EOL}

If Central role is not initialized or if the message queue is full.

Example 1 - Scan for any advertising device in range for a default timeout of 30 seconds:

AT+BLE DISCOVER{EOL}

   ...a BLE DISCOVER COMPLETE event occurs (see Table 4 - ExpressLink event codes)...

AT+EVENT?{EOL}				# check the event queue 
OK 31 0 DISCOVER COMPLETE{EOL}		# a BLE DISCOVER event was received

Example 2 - Scan for a specific peripheral UUID and timeout after 20 seconds: 

AT+CONF BLECentral1={ "peer": "a4:c1:38:12:56:5d", "filterDups": 1}{EOL}
       
AT+BLE1 DISCOVER 20{EOL}

   ...20 seconds later a BLE DISCOVER COMPLETE event occurs (see Table 4 - ExpressLink event codes...

Example 3 - Discover until cancelled:

AT+BLE DISCOVER{EOL}
OK

   ...a few seconds later...

AT+BLE DISCOVER CANCEL{EOL}
OK

   ...a BLE DISCOVER COMPLETE event occurs (see Table 4 - ExpressLink event codes...

13.2.2 BLE GET DISCOVER   »Retrieve the collected advertising information«

Retrieve the advertising information collected during the last discovery process.

Advertising information is stored in memory shared with MQTT messages. Collected information is also cleared when a new discovery is started. Hence, GET DISCOVER only fetches information for the devices that match the filter defined when the last DISCOVER command was issued.

Returns:
13.2.2.1   OK{EOL}

No new advertising information was collected.

13.2.2.2   OK {collected information}{EOL}

Discovered information was collected and is presented following the 'OK'.

13.2.2.3   ERR25 NOT ALLOWED{EOL}

If the BLE Central role is not initialized.

Collected information is fetched from the queue and returned as a record containing the following space-separated fields:

<peer> <connectable> <Scannable> <rssi> <advertisedData> <type>{EOL}
mac address    0/1          0/1       int     hex string   string

Example 1 - Check the BLE receive queue for any advertising data received, returning two records:

AT+BLE GET DISCOVER{EOL}
OK 3a:1a:f7:e4:11:38 0 1 -30 02011A0BFF4C00090603420A3F588B Public{EOL}

Example 2 - Repeat the GET DISCOVER request until the message queue is empty:

AT+BLE GET DISCOVER{EOL}
OK{EOL}

13.2.3 BLE[#] CONNECT   »Connect to a peripheral«

In some use cases, instead of just reading sensor data provided in the advertisement message, the host may want to inspect what type of services and characteristics a peripheral exposes. To do this, the ExpressLink module must first establish a direct connection to the BLE peripheral device (using the BLE GAP protocol).

Figure 8 - Connecting to a BLE device

Figure 8 - Connecting to a BLE device

 

When you use the BLE{#} CONNECT command, the ExpressLink module attempts to connect to a peripheral based on a specific configuration defined int the BLECentral# parameter.

Returns:
13.2.3.1   OK{EOL}

If the command was accepted and the connection request was successful.

13.2.3.2   ERR7 OUT OF RANGE{EOL}

The numerical suffix is out of bounds (0 or greater than MaxBLECentral index).

13.2.3.3   ERR28 CONFIGURATION ERROR{EOL}

The numerical suffix points to a {}, or is missing the "peer" key.

13.2.3.4   ERR8 PARAMETER UNDEFINED{EOL}

The numerical suffix points to an empty BLECentral# string or {}.

13.2.3.5   ERR25 NOT ALLOWED{EOL}

If already connected to a device.

13.2.3.6   ERR25 NOT ALLOWED{EOL}

If BLE INIT is not set to CENTRAL mode.

13.2.3.7   ERR14 UNABLE TO CONNECT{EOL}

Discovery attempted for 30 seconds before timing out and returning error.

Example 1 - Connect to a specific peripheral according to the configuration. The attempt will stop if the timeout of 30 seconds is reached. The configuration information included in this example is for demonstration purposes only:

AT+CONF BLECENTRAL1={"peer": "a4:c1:38:12:56:5d", "filterDups": 1 }{EOL}
OK{EOL}
AT+BLE INIT CENTRAL{EOL}
OK{EOL}
AT+BLE1 CONNECT{EOL}
OK{EOL}

   ...a BLE CONNECTED event occurs...

Example 2 - Connect to a second peripheral according to the configuration. The attempt will stop if the timeout of 30 seconds is reached. The configuration information included in this example is for demonstration purposes only:

AT+CONF BLECENTRAL2={"peer": "a4:c1:38:12:56:5d", "filterDups":1}{EOL} 
OK{EOL} 
AT+BLE2 CONNECT{EOL} 
OK{EOL}

   ...a BLE CONNECTED event occurs...

13.2.4 BLE[#]CONNECT?   »Connection status query«

This query command allows the host device to check if the status of the specified connection is still active. This command can also be used to confirm a successful connection after the AT+CONNECT command. Note that if the numerical suffix is not specified then the Peripheral command 13.3.1 BLE CONNECT?   »Connection status query« is invoked.

Returns:
13.2.4.1   OK 1 CONNECTED{EOL}

When connected to a Peripheral.

13.2.4.2   OK 0 DISCONNECTED{EOL}

When disconnected from a Peripheral.

13.2.4.3   ERR7 OUT OF RANGE{EOL}

The numerical suffix is out of bounds (0 or greater than MaxBLECentral index).

13.2.4.4   ERR25 NOT ALLOWED{EOL}

When the module role was not initialized as Central.

Example 1 - When connected over central config 2:

AT+BLE INIT CENTRAL{EOL}
OK{EOL}
AT+BLE2 CONNECT{EOL}
OK{EOL}

   ...a BLE CONNECTED event occurs...

AT+BLE2 CONNECT?{EOL}
OK 1 CONNECTED{EOL}

13.2.5 BLE[#]DISCONNECT   »Connection termination request«

Terminate a BLE device connection.

13.2.5.1   Disconnects from the given index's connection.

Returns:
13.2.5.2   OK{EOL}

On successful termination of connection or if there is no connection to terminate.

13.2.5.3   ERR7 OUT OF RANGE{EOL}

The numerical suffix is out of bounds (0 or greater than MaxBLECentral index).

13.2.5.4   ERR27 BLE ERROR{EOL}

If the command fails to terminate the connection.

13.2.5.5   ERR25 NOT ALLOWED{EOL}

If BLE INIT is not set to CENTRAL mode.

Example 1 - Connect to a specific peripheral according to the configuration and then disconnect. The configuration information included in this example is for demonstration purposes only:

AT+CONF BLECentral1={"peer": "a4:c1:38:12:56:5d", "filterDups": 1}{EOL}
OK{EOL}
AT+BLE INIT CENTRAL{EOL}
OK{EOL}
AT+BLE1 CONNECT{EOL}
OK{EOL}

   ...a BLE CONNECTED EVENT occurs...

AT+BLE1 DISCONNECT{EOL}
OK{EOL}

13.2.6 BLE[#} READ[#]   »Synchronous Read of a Characteristic«

The READ command allows the host to request the value of a characteristic when connected to a peripheral. The BLE (first) numerical suffix # identifies the connected device by the corresponding BLECentral# parameter. The READ (second) numerical suffix # identifies the characteristics by the corresponding BLEGATT# parameter. The maximum value that can be read from a characteristic is 31 bytes.

Figure 9 - Reading a connected BLE peripheral

Figure 9 - Reading a connected BLE peripheral

 

Returns:
13.2.6.1   OK {value}{EOL}

On a successful read, returns the characteristic value as a hex string.

13.2.6.2   OK {EOL}

On a successful read, when the characteristic value is an empty string.

13.2.6.3   ERR8 PARAMETER UNDEFINED{EOL}

When a BLECentral# configuration is not set.

13.2.6.4   ERR8 PARAMETER UNDEFINED{EOL}

When a BLEGATT# configuration is not set.

13.2.6.5   ERR7 OUT OF RANGE{EOL}

The first numerical suffix is out of bounds (0 or greater than MaxBLECentral).

13.2.6.6   ERR7 OUT OF RANGE{EOL}

The second numerical suffix is out of bounds (0 or greater than MaxBLEGATT).

13.2.6.7   ERR6 NO CONNECTION{EOL}

When not connected to a peripheral device.

13.2.6.8   ERR27 BLE ERROR{EOL}

When the read request fails.

13.2.6.9   ERR25 NOT ALLOWED{EOL}

If BLE INIT is not set to CENTRAL mode.

Example:

    # Assuming the configuration:
AT+CONF BLECentral1={"peer": "a4:c1:38:12:56:5d", "filterDups": 1}{EOL}
OK{EOL}

AT+CONF BLEGATT5={"service": "1f10", "chr": "1f1f"}{EOL}
OK{EOL}

    # BLE is initialized and a connection to a peripheral matching peer a4:c1:38:12:56:5d is established:
AT+BLE INIT CENTRAL{EOL}
OK{EOL}

AT+BLE1 CONNECT{EOL}
OK{EOL}

    # Requst the value of characteristic 0x1F1F (part of the service 0x1F10):
AT+BLE1 READ5{EOL}
OK 48656C6C6F20576F726C64{EOL}

    # Successfully retrieved the value "Hello World"!

13.2.7 BLE[#] WRITE[#] {value}   »Write to a characteristic«

The WRITE command allows the host to update the value of (writable) characteristics of a connected peripheral device. The BLE (first) numerical suffix # identifies the connected device by the corresponding BLECentral# parameter. The WRITE (second) numerical suffix #, identifies a characteristic by its corresponding BLEGATT# parameter.

The maximum value that can be written to a characteristic is MaxBLECharLen bytes, where MaxBLECharLen is a value (>=31) defined by the vendor and documented in the module datasheet.

Figure 10 - Writing to a connected BLE device

Figure 10 - Writing to a connected BLE device

 

Returns:
13.2.7.1   OK{EOL}

On a successful update of the peripheral characteristic.

13.2.7.2   ERR4 PARAMETER ERROR{EOL}

Must always take valid byte array encoded in hex as a valid parameter.

13.2.7.3   ERR8 PARAMETER UNDEFINED{EOL}

A BLEGATT# configuration was not set.

13.2.7.4   ERR7 OUT OF RANGE{EOL}

The BLE Central numerical suffix is out of bounds (0 or greater than MaxBLECentral).

13.2.7.5   ERR7 OUT OF RANGE{EOL}

The BLEGATT numerical suffix is out of bounds (0 or greater than MaxBLEGATT).

13.2.7.6   ERR6 NO CONNECTION{EOL}

When not connected to a peripheral device.

13.2.7.7   ERR25 NOT ALLOWED{EOL}

The device was not initialized as a Central.

13.2.7.8   ERR27 BLE ERROR{EOL}

When the command fails to update the characteristic.

Example:

    # Assuming the configuration:
AT+CONF BLECentral2={"peer": "a4:c1:38:12:56:5d", "filterDups": 1}{EOL}
OK{EOL}

AT+CONF BLEGATT6={"service": "1f10", "chr": "1f1f"}{EOL}
OK{EOL}

    # After initializing and connecting to a peripheral device:
AT+BLE INIT CENTRAL{EOL}
OK{EOL}

AT+BLE1 CONNECT{EOL}
OK{EOL}

    # Request to update the characteristic 0x1F1F with the new value "01A3":
AT+BLE2 WRITE6 01A3{EOL}
OK{EOL}

13.2.8 BLE[#] SUBSCRIBE[#]   »Subscribe to a connected peripheral«

The host can subscribe to receive notifications (see Table 4 - ExpressLink event codes) when connected to a peripheral and the selected characteristic is updated (it must be configured as notify or indicate). The BLE (first) numerical suffix # identifies the connected device by the corresponding BLECentral# parameter. The SUBSCRIBE (second) numerical suffix #, identifies the characteristic by its corresponding BLEGATT# parameter.

Figure 11 - Subscribing to receive peripheral notifications

Figure 11 - Subscribing to receive peripheral notifications

 

Returns:
13.2.8.1   OK{EOL}

On a successful subscription.

13.2.8.2   ERR8 PARAMETER UNDEFINED{EOL}

A BLEGATT# configuration was not set.

13.2.8.3   ERR7 OUT OF RANGE{EOL}

The first numerical suffix is out of bounds (0 or greater than MaxBLECentral).

13.2.8.4   ERR7 OUT OF RANGE{EOL}

The second numerical suffix is out of bounds (0 or greater than MaxBLEGatt).

13.2.8.5   ERR6 NO CONNECTION{EOL}

When not connected to a peripheral device.

13.2.8.6   ERR25 NOT ALLOWED{EOL}

The command can only be executed when initialized as a Central.

13.2.8.7   ERR27 BLE ERROR{EOL}

When the command fails to successfully subscribe to the indexed characteristics. ExpressLink will support a limited number of subscriptions (minimum 2). The max number of supported subscriptions (MaxBLECharLen) must be documented by the vendor in the module datasheet.

Example:

    # Assuming the configuration: 
AT+CONF BLECentral1={"peer": "a4:c1:38:12:56:5d", "filterDups": 1}{EOL} 
OK{EOL} 
AT+CONF BLEGATT7={"service":"1809", "chr":"1F1F"}{EOL} 
OK{EOL} 

    # After initializing and connecting to a peripheral device: 
AT+BLE INIT CENTRAL{EOL} 
OK{EOL} 
AT+BLE1 CONNECT{EOL} 
OK{EOL} 

    # Request to be notified to 
AT+BLE1 SUBSCRIBE7{EOL} OK 

   ...EVENT 50 101 SUBSCRIPTION RECEIVED...

13.2.9 BLE[#] GET SUBSCRIBE[#]   »Get information on Subscriptions«

After receiving the event subscribed to, the host can retrieve additional detail about the notification. The first BLE numerical suffix # identifies the connected device by the corresponding BLECentral# parameter. The SUBSCRIBE (second) numerical suffix # identifies the characteristic by its corresponding BLEGATT# parameter. The second numerical index is optional- if not specified, the most recent subscription detail will be retrieved.

Returns:
13.2.9.1   OK{EOL}

No notification detail record was found.

13.2.9.2   OK {BLEGATT#} [N|I] {detail}{EOL}

A notification detail record was found. Where “N” stands for Notification and “I” for Indication. When requesting a subscription to a characteristic that has both Notification and Indication, the module will subscribe only to Notification.

13.2.9.3   ERR7 OUT OF RANGE{EOL}

The first numerical suffix is out of bounds (0 or greater than MaxBLECentral).

13.2.9.4   ERR7 OUT OF RANGE{EOL}

The second numerical suffix is out of bounds (0 or greater than MaxBLEGatt).

13.2.9.5   ERR8 PARAMETER UNDEFINED{EOL}

A BLECentral# configuration was not set.

13.2.9.6   ERR25 NOT ALLOWED{EOL}

If the device is not initialized in the Central role.

Example 1:

    # Assuming the configuration: 
AT+CONF BLECentral1={"peer": "a4:c1:38:12:56:5d", "filterDups": 1}{EOL} 
OK{EOL} 
AT+CONF BLEGATT2={"service":"1809", "chr":"1F1F"}{EOL} 
OK{EOL} 

    # After initializing and connecting to a peripheral device: 
AT+BLE INIT CENTRAL{EOL} 
OK{EOL} 
AT+BLE1 CONNECT{EOL} 
OK{EOL} 

   # Subscribe to notifications/indication provided by characteristic 0x1F1F 
AT+BLE1 SUBSCRIBE2{EOL} 
OK{EOL} 

   ...EVENT 48 102 SUBSCRIPTION received... 

    # Request additional information: 
AT+BLE1 GET SUBSCRIBE2{EOL} 
OK 2 N 021A45{EOL}

13.2.10 BLE[#] UNSUBSCRIBE[#]   »Unsubscribe to characteristics«

Terminate a notify or indicate subscription to a peripheral device characteristic.

Returns:
13.2.10.1   OK{EOL}

On successfully terminating the subscription to the peripheral characteristic.

13.2.10.2   ERR8 PARAMETER UNDEFINED{EOL}

A BLECentral# configuration was not set.

13.2.10.3   ERR8 PARAMETER UNDEFINED{EOL}

A BLEGATT# configuration was not set.

13.2.10.4   ERR7 OUT OF RANGE{EOL}

The BLECentral numerical suffix is out of bounds (0 or greater than MaxBLECentral).

13.2.10.5   ERR7 OUT OF RANGE{EOL}

The BLEGATT numerical suffix is out of bounds (0 or greater than MaxBLEGATT).

13.2.10.6   ERR6 NO CONNECTION{EOL}

When not connected to a peripheral device.

13.2.10.7   ERR25 NOT ALLOWED{EOL}

The command can only be executed when initialized as a Central.

13.2.10.8   ERR27 BLE ERROR{EOL}

When the command fails to successfully unsubscribe from the selected characteristic.

Example:

    # Assuming the configuration: 
AT+CONF BLECentral1={"peer": "a4:c1:38:12:56:5d", "filterDups": 1}{EOL}
OK{EOL}
AT+CONF BLEGATT8={"service":"1809", "chr":"1F1F"}{EOL} 
OK{EOL}

    # After initializing and connecting to a peripheral device and subscribing to notifications: 
AT+BLE INIT CENTRAL{EOL}
OK{EOL}
AT+BLE1 CONNECT{EOL}
OK{EOL}
AT+BLE1 SUBSCRIBE8{EOL}
OK{EOL}

 ...EVENT 50 108 SUBSCRIPTION received...

AT+BLE1 UNSUBSCRIBE8{EOL}
OK{EOL}

    # No more subscription events will be generated for the selected characteristic.

13.3 BLE PERIPHERAL role commands

When initialized as a Peripheral device, an ExpressLink module waits for connections initiated by central devices. Only one Central device at a time can connect to a module initialized as Peripheral.

13.3.1 BLE CONNECT?   »Connection status query«

Request the current Peripheral device connection status.

Returns:
13.3.1.1   OK 0 NOT CONNECTED{EOL}

When not connected to a Central device.

13.3.1.2   OK 1 CONNECTED{EOL}

When connected to a Central device.

13.3.1.3   OK 2 ADVERTISING{EOL}

When advertising is in progress.

13.3.1.4   ERR25 NOT ALLOWED{EOL}

When the module role was not initialized as Peripheral.

Example:

AT+CONF BLEPeripheral={"appearance": "4142"}{EOL} 
OK{EOL} 
AT+CONF BLEGATT1=={"service":"1809", "chr":"1F1F"}{EOL} 
OK{EOL} 
AT+BLE INIT PERIPHERAL{EOL} 
OK{EOL} 
AT+BLE CONNECT?{EOL} 
OK 0 NOT CONNECTED{EOL} 

    # Currently initialized in peripheral role but not connected to a central device.

13.3.2 BLE DISCONNECT   »Connection termination request«

Terminate the current connection, if one was established by a central device.

Returns:
13.3.2.1   OK{EOL}

On successfully terminating the connection of if there was no connection to terminate.

13.3.2.2   ERR25 NOT ALLOWED{EOL}

When the module role was not initialized as Peripheral.

13.3.2.3   ERR27 BLE ERROR{EOL}

If the command fails to terminate the connection.

Example:

    # When initialized as a peripheral and wishes to disconnect from central device. 
AT+CONF BLEPeripheral={“appearance”: “4142”}{EOL} 
OK{EOL} 
AT+CONF BLEGATT1={“service”:”1809”, ”chr”:”1F1F”}{EOL} 
OK{EOL} 
AT+BLE INIT PERIPHERAL{EOL} 
OK{EOL} 

   ...A central device connects... 
   ...a BLE CONNECTED EVENT occurs...

    # The host wishes to terminate the connection with the central device: 
AT+BLE DISCONNECT{EOL} 
OK{EOL}

13.3.3 BLE ADVERTISE {CANCEL}   »Advertise to nearby devices«

Start the advertising process, making the module a connectable, scannable device. The process will continue until connected or cancelled by AT+BLE ADVERTISE CANCEL.

Returns:
13.3.3.1   OK{EOL}

When the ExpressLink module successfully starts the Advertising process.

13.3.3.2   OK{EOL}

On successfully canceling advertisements, or if not currently advertising.

13.3.3.3   ERR4 PARAMETER ERROR{EOL}

When initialized as a peripheral and the command is provided with an index #.

13.3.3.4   ERR27 BLE ERROR{EOL}

When the Advertising process fails to start.

13.3.3.5   ERR27 BLE ERROR{EOL}

When the Advertising process fails to terminate (with the CANCEL parameter).

13.3.3.6   ERR25 NOT ALLOWED{EOL}

If BLE INIT is not set to PERIPHERAL mode.

Example 1 - A successful startup of the advertising process:

AT+CONF BLEPeripheral={“appearance”: “4142”}{EOL} 
OK{EOL} 
AT+CONF BLEGATT1={ "service" : "72bdd8d118874a3fbedaf6c22d45cfa0", "chr": "72bdd8d218874a3fbedaf6c22d45cfa0"}{EOL} 
OK{EOL} 
AT+BLE INIT PERIPHERAL{EOL} 
OK{EOL} 
AT+BLE ADVERTISE{EOL} 
OK{EOL} 

    # Now other devices can discover the ExpressLink device

Example 2 - When the necessary configuration CONF BLEPeripheral and/or BLEGATT# are missing:

AT+CONF BLEGATT1={ "service" : "CFAO", "chr": "72BD"}{EOL} 
OK{EOL} 
AT+BLE INIT PERIPHERAL{EOL} 
ERR28 CONFIGURATION ERROR{EOL}

Example 3 - Cancelling an ongoing Advertisement:

AT+CONF BLEPeripheral={“appearance”: “4142”}{EOL} 
OK{EOL} 
AT+CONF BLEGATT1={"service" : "CFAO", "chr": "72BD"}{EOL} 
OK{EOL} 
AT+BLE INIT PERIPHERAL{EOL} 
OK{EOL} 
AT+BLE ADVERTISE{EOL} 
OK{EOL} 

    # Now other devices can discover the ExpressLink device 

AT+BLE ADVERTISE CANCEL{EOL} 
OK{EOL}

13.3.4 BLE GET[#]   »Synchronous read of a local characteristic«

The BLE GET command allows the host to perform a synchronous read of the value of a local peripheral characteristic. The maximum value that can be retrieved from a characteristic is MaxBLECharLen bytes, where MaxBLECharLen is a value (>=31) defined by the vendor and documented in the module datasheet.

Figure 12 - Reading from a local characteristic in BLE peripheral mode

Figure 12 - Reading from a local characteristic in BLE peripheral mode

 

Returns:
13.3.4.1   OK {value}{EOL}

The GET request was successful, the characteristic value is returned as a hex string.

13.3.4.2   OK {EOL}

On a successful get read, when the characteristic value is an empty string.

13.3.4.3   ERR8 PARAMETER UNDEFINED{EOL}

A BLEGATT# configuration is not set.

13.3.4.4   ERR7 OUT OF RANGE{EOL}

The BLEGATT# numerical suffix is out of bounds (0 or greater than MaxBLEGATT).

13.3.4.5   ERR25 NOT ALLOWED{EOL}

The characteristic can be only be read when the peripheral is initialized.

13.3.4.6   ERR27 BLE ERROR{EOL}

When the command fails to successfully read from a characteristic.

Example: Read value of local characteristics configured at BLEGATT1 index.

AT+BLE GET1{EOL} 
OK 014A{EOL}

13.3.5 BLE SET[#} [payload]   »Write to a local characteristic«

The BLE SET command allows the host to perform a synchronous write to the value of a local peripheral characteristic. TThe maximum value that can be retrieved from a characteristic is MaxBLECharLen bytes, where MaxBLECharLen is a value (>=31) defined by the vendor and documented in the module datasheet.

Figure 13 - Writing to a connected BLE device

Figure 13 - Writing to a connected BLE device

 

Returns:
13.3.5.1   OK{EOL}

On a successful write to the local characteristic.

13.3.5.2   ERR4 PARAMETER ERROR{EOL}

If the payload is not valid hex array.

13.3.5.3   ERR8 PARAMETER UNDEFINED{EOL}

If the BLEGATT# configuration is not set.

13.3.5.4   ERR7 OUT OF RANGE{EOL}

If the numerical suffix is out of bounds (0 or greater than MaxBLEGATT).

13.3.5.5   ERR25 NOT ALLOWED{EOL}

The command can only be executed when initialized as a Peripheral.

13.3.5.6   ERR27 BLE ERROR{EOL}

When the command fails to set the value of a local characteristic.

Example- Update the value of local characteristics configured at BLEGATT2 index to 014A:

AT+BLE SET2 014A{EOL} 
OK{EOL}

13.3.6 BLE AUTH[#] [0/1]   »Authorize access to a characteristic«

The BLE AUTH command allows the host to authorize or deny access to a peripheral characteristic. This is used when a characteristic is configured to require a read or write authorization from the host. When a central device attempts to perform an authorization protected operation, the module configured as peripheral generates a BLE_AUTHORIZE event to notify the host. The host can use this command to authorize or deny access as appropriate for application logic.

 

Returns:
13.3.6.1   OK{EOL}

Acknowledge authorization accepted/denied.

13.3.6.2   ERR4 PARAMETER ERROR{EOL}

If the auth code is not Boolean, only 0/1 are valid values.

13.3.6.3   ERR8 PARAMETER UNDEFINED{EOL}

BLEGATT# characteristic configuration is not found.

13.3.6.4   ERR7 OUT OF RANGE{EOL}

The numerical suffix is out of bounds (0 or greater than MaxBLEGATT).

13.3.6.5   ERR25 NOT ALLOWED{EOL}

The command can only be executed when initialized as a Peripheral.

13.3.6.6   ERR27 BLE ERROR{EOL}

The command cannot be executed (e.g., the BLE connection was lost).

13.4 Pairing, Bonding and Filtering

13.4.1 AT+BLE PAIR   »Initiate pairing as peripheral«

Pairing can be initiated from either end, peripheral and/or central. This command initiates the pairing from the ExpressLink device when configured in Peripheral mode. Successful connection with the central is a pre-requisite. This adds the device to the module's Bond list, i.e. bonding (saving the BLE pairing information) happens automatically after pairing. Setting the correct peripheral advertising configuration before issuing a BLE INIT PERIPHERAL command, is essential. (See BLEPeripheral configuration in Paragraph 13 introduction).

 

Returns:
13.4.1.1   OK{EOL}

Pairing was successful, the central device was added to the Bond list.

13.4.1.2   ERR6 NO CONNECTION{EOL}

Pairing not possible, device not connected or not initialized.

13.4.1.3   ERR27 BLE ERROR{EOL}

Pairing failed, device could not be paired.

13.4.2 AT+BLE[#] PAIR   »Initiate pairing as central«

Pairing can be initiated from either end, peripheral and/or central. This command initiates the pairing from the ExpressLink device when configured in Central mode. Successful connection with a peripheral device identified by the numerical parameter (#) is a pre-requisite. This adds the device to the module's Bond list, i.e. bonding (saving the BLE pairing information) happens automatically after pairing.

Pairing is a process that can require several steps optionally including user input over a long period of time. Once initiated using the AT+PAIR{#} commands, it continues asynchronously. The host is notified of progress via the BLE PAIR event (see Table 4 - ExpressLink event codes). The pairing process is aborted if no response is received within 30 seconds. A BLE PAIR event with a PAIR_FAIL code followed by a BLE DISCONNECT event will be generated.

 

Returns:
13.4.2.1   OK{EOL}

Pairing was successful, the peripheral device was added to the Allow list and Bond list.

13.4.2.2   ERR6 NO CONNECTION{EOL}

Pairing not possible, device not connected or not initialized.

13.4.2.3   ERR27 BLE ERROR{EOL}

Pairing failed, device could not be paired.

Figure 14 - Typical BLE Peripheral initialization and pairing flow

Figure 14 - Typical BLE Peripheral initialization and pairing flow

13.4.3 BLE PAIR?   »Query device pairing status«

Fetch the status of the pairing process. This can be polled at any time or in response to a specific BLE PAIR event. If successful, the host can then respond by issuing appropriate PAIR_ACTION(s).

Returns:
13.4.3.1   OK {code} [detail]{EOL}

See Table 11 – Pairing Codes to interpret the response.

13.4.3.2   ERR6 NO CONNECTION{EOL}

Device not connected or not initialized.

Table 11 – Pairing Codes

Code

Mnemonic

Description

Detail

0

NONE

No pairing in progress

(empty)

1

PASSKEY_REQ

Request host to provide a 6-digit passkey

(empty)

2

PASSKEY_RECV

Received a 6-digit passkey for host to display

(empty)

3

NC_VALUE

Numeric-comparison value ready, host must display and accept/reject

(empty)

4

PAIR_OK

Pairing completed successfully

(empty)

5

PAIR_FAIL

Security Manager Error – see error code in detail

(error code, hex)

The detailed error codes (hex values) definitions are found at NimBLE Host Return Codes, and atNimBLE Host Return Codes (peer).

13.4.4 BLE PAIR_ACTION SET_PASSKEY {6-digit code} »Supply passkey to controller«

Use this action to supply the 6-digit passkey to the controller after you receive a BLE PAIRING event with pairing code: PASSKEY_REQ (2).

Returns:
13.4.4.1   OK{EOL}

The controller accepts the passkey and continues the pairing process.

13.4.4.2   ERR4 PARAMETER ERROR{EOL}

The parameter is missing or malformed (expects a 6-digit decimal code).

13.4.4.3   ERR17 MODE NOT AVAILABLE{EOL}

No passkey request is pending.

13.4.6 BLE PAIR_ACTION NC {ACCEPT | REJECT} »Accept or reject numerical code«

This command accepts or rejects the numerical code that you receive during the pairing process. Use this in response to pairing code: NC_VALUE(4).

Returns:
13.4.6.1   OK{EOL}

The controller accepts or rejects the numerical code confirmation.

13.4.6.2   ERR17 MODE NOT AVAILABLE{EOL}

No NC confirmation is pending.

End-to-end Example (Peripheral role)

  1. A smartphone initiates pairing and the IoT ExpressLink module raises an event:

    
> AT+EVENT?
< OK 48 0 BLE PAIR
    Note

    In Central role, the second parameter returned (0) is replaced by the BLEGATT index(#).

    Smartphone initiates pairing with ExpressLink module

  2. The host queries the sub-state:

    
> AT+BLE PAIR?
< OK 3 NC_VALUE
    Host queries pairing sub-state and receives NC_VALUE

  3. Fetch the six-digit number and display it:

    
> AT+BLE PAIR_ACTION GET_PASSKEY
< OK 123456
    Retrieve and display six-digit pairing code

  4. The user taps "Yes" on the device to accept pairing:

    
> AT+BLE PAIR_ACTION NC ACCEPT
< OK
    User accepts pairing by tapping Yes on device

  5. Pairing completes and you receive a final notification event:

    
> AT+EVENT?
< OK 48 0 BLE PAIR

    It's a pairing event!

    
> AT+BLE PAIR?
< OK 4 PAIR_OK

    Pairing was successful!

    Pairing completion notification and success confirmation

13.4.7 AT+BLE UNPAIR »Removes device from the Allow list and Bond list«

This command removes the currently connected and paired device from the Bond list and Allow list. The device must be paired and connected to the ExpressLink device before you can issue this command.

Returns:
13.4.7.1   OK{EOL}

Unpairing was successful. The device was removed from the Allow list and Bond list.

13.4.7.2   ERR6 NO CONNECTION{EOL}

Unpairing not possible. Device not connected or not initialized.

13.4.7.3   ERR27 BLE ERROR{EOL}

Unpairing failed. Device not paired.

13.4.8 AT+BLE FORGET »Clears the Allow list and Bond list«

This command clears all contents of the Bond list and Allow list.

Returns:
13.4.8.1   OK{EOL}

Clearing was successful. All devices were removed from the Allow list and Bond list.

13.4.8.2   ERR25 NOT_ALLOWED{EOL}

BLE not initialized.

13.4.8.3   ERR27 BLE ERROR{EOL}

Clearing failed.

13.4.9 AT+BLE ALLOW_ADD »Add a device to the Allow list«

Adds the connected device to the Allow list.

Returns:
13.4.9.1   OK{EOL}

The device was successfully added to the Allow list.

13.4.9.2   ERR6 NO CONNECTION{EOL}

No device connected or BLE not initialized.

13.4.9.3   ERR27 BLE ERROR{EOL}

Command failed. Could not add device to AllowList.

13.4.10 AT+BLE ALLOW_REMOVE »Remove a device from the Allow list«

Remove the connected device from the Allow list.

Returns:
13.4.10.1   OK{EOL}

The device was successfully removed from the Allow list.

13.4.10.2   ERR6 NO CONNECTION{EOL}

No device connected or BLE not initialized.

13.4.10.3   ERR27 BLE ERROR{EOL}

Command failed. Could not remove device from AllowList.

13.4.11 AT+BLE ALLOW_CLEAR »Remove all devices from the Allow list«

Remove all devices from the Allow list.

Returns:
13.4.11.1   OK{EOL}

All devices were successfully removed from the Allow list.

13.4.11.2   ERR6 NO CONNECTION{EOL}

No device connected or BLE not initialized.

13.4.11.3   ERR27 BLE ERROR{EOL}

Command failed. Could not clear the AllowList.

Note

The state of the BLE Allow and Bond lists can be queried at any time using the AT CONF? command, and respectively the >BLEBondList and BLEAllowList configuration parameters.

Querying BLE Lists

You can query the state of the BLE Allow and Bond lists at any time using the AT CONF? command and the BLEBondList and BLEAllowList configuration parameters.

Example 1 - Query Bond List:

AT+CONF? BLEBondList{EOL}

Returns:
OK [{"type":"Public","address":"CC:F9:F0:54:11:3F"}, {"type":"Public","address":"06:05:04:03:02:01"}]{EOL}
# The BLEBondList contains two Public items.

OK []{EOL}
# The BLEBondList is empty.

ERR25 NOT ALLOWED{EOL}
# The BLE functionality has not been initialized.

Example 2 - Query Allow List:

AT+CONF? BLEAllowList{EOL}

Returns:
OK [{"type":"Public","address":"CC:F9:F0:54:11:3F"}, {"type":"Public","address":"06:05:04:03:02:01"}]{EOL}
# The BLEAllowList contains two public items.

OK []{EOL}
# The BLEAllowList is empty.

ERR25 NOT ALLOWED{EOL}
# The BLE functionality has not been initialized.