Testing with Zephyr’s BLE Stack

Zephyr’s BLE stack recently got a big boost by virtue of Nordic’s involvement towards a certified BLE 5.0 stack. In this article, we’ll look at some of the test functionality provided in the Zephyr BLE stack.

The most flexible way of integrating Zephyr’s BLE stack with the test host controller is through HCI/UART, building a HCI variant of the BLE stack.

This HCI interface can be used for testing, hooked up to the test host controller’s high-level BLE stack (such BlueZ on Linux), for both functional and low-level RF testing, during development, production or debugging.

Building

Out of the box, Zephyr provides build configurations for most nRF5x-based development boards. To build the HCI-UART Zephyr BLE sample, use:

west build -b nrf52_pca10040 samples/bluetooth/hci_uart
sudo west flash

Note: by default, the hci_uart firmware assumes a 1000000Mbps bitrate for UART communication. If your tooling has trouble with this, specify a more conservative bitrate, like 115200.

Using with BlueZ

To test the Zephyr BLE stack with BlueZ, use the btattach command to register the UART-connected Zephyr BLE device with the BlueZ host stack.

# btattach -B /dev/ttyACM0 -S 1000000 -P h4 &
Attaching Primary controller to /dev/ttyACM0
Switched line discipline from 0 to 15
Device index 1 attached
#

Vendor-Specific HCI

The Zephyr BLE stack only provides a limited set of Vendor-specific HCI commands. However, since source is available, specific test commands can be easily added.

Always available:

HCI Command OGF OCF
READ_VERSION_INFO 0x3F 0x0001
READ_SUPPORTED_COMMANDS 0x3F 0x0002
READ_SUPPORTED_FEATURES 0x3F 0x0003

Extra VS HCI commands (CONFIG_BT_HCI_VS_EXT):

HCI Command OGF OCF
WRITE_BR_ADDR 0x3F 0x0006
READ_BUILD_INFO 0x3F 0x0008
READ_STATIC_ADDRS 0x3F 0x0009
READ_KEY_HIERARCHY_ROOTS 0x3F 0x000a

Mesh VS HCI commands (CONFIG_BT_HCI_MESH_EXT)

ASAS OGF OCF
MESH 0x3F 0x0042

Write BR Address

The WRITE_BD_ADDR Vendor-specific HCI command can be used to set the Bluetooth address (until power cycle).

HCI Command OGF OCF
WRITE_BR_ADDR 0x3F 0x0006

Command Parameters:

Offset Size Parameter
0 6 Bluetooth Address

Return Parameters:

Offset Size Parameter
0 1 Status 
hcitool cmd 0x3f 0x006 0x1 0x2 0x42 0x0 0x21 0xAD
< HCI Command: Vendor (0x3f|0x0006) plen 6
        01 02 42 00 21 ad
> HCI Event: Command Complete (0x0e) plen 4
      Vendor (0x3f|0x0006) ncmd 1
        Status: Success (0x00)

Read Build Info

The READ_BUILD_INFO Vendor-specific HCI command can be to extract the Zephyr OS version from the device.

HCI Command OGF OCF
READ_BUILD_INFO 0x3F 0x0008

Command Parameters: none.

Return Parameters:

Offset Size Parameter
0 1 Status
1 … Zephyr OS v...

Example:

# hcitool cmd 0x3f 0x008
< HCI Command: Vendor (0x3f|0x0008) plen 0
> HCI Event: Command Complete (0x0e) plen 22
    Vendor (0x3f|0x0008) ncmd 1
      Status: Success (0x00)
      5a 65 70 68 79 72 20 4f 53 20 76 32 2e 30 2e 39  Zephyr OS v2.0.9
      39 00                                            9.
#

Read Static Address

The READ_STATIC_ADDRS Vendor-specific HCI command can be to retrieve addresses from persistent memory.

HCI Command OGF OCF
READ_STATIC_ADDRS 0x3F 0x0009

Command Parameters: none.

Return Parameters:

Offset Size Parameter
0 1 Status
1 1 Number of addresses
2 6 Address
8 6 …

Example:

# hcitool cmd 0x3f 0x009
< HCI Command: Vendor (0x3f|0x0009) plen 0
> HCI Event: Command Complete (0x0e) plen 27
      Vendor (0x3f|0x0009) ncmd 1
        Status: Success (0x00)
        01 75 c7 29 6b f4 c5 00 00 00 00 00 00 00 00 00  .u.)k...........
        00 00 00 00 00 00 00                             .......
#

Read Key Hierarchy Roots

The READ_STATIC_ADDRS Vendor-specific HCI command can be to retrieve the cryptographic IR and ER initialization vectors.

HCI Command OGF OCF
READ_KEY_HIERARCHY_ROOTS 0x3F 0x000a

Command Parameters: none.

Return Parameters:

Offset Size Parameter
0 1 Status
1 16 IR vector
17 16 ER vector

Example:

# hcitool cmd 0x3f 0x00a
< HCI Command: Vendor (0x3f|0x000a) plen 0
> HCI Event: Command Complete (0x0e) plen 36
      Vendor (0x3f|0x000a) ncmd 1
        Status: Success (0x00)
        1e b9 23 59 3a fd 7a a7 79 af 9d 94 fd f9 d5 66  ..#Y:.z.y......f
        0c bb 56 71 39 83 79 7a 07 fe 9a d2 57 7a 31 eb  ..Vq9.yz....Wz1.
#

Direct Test Mode (DTM) HCI

While primarily meant for certification and qualification tests, you can also use DTM during development, validation or production testing.

Without the specialized hardware used in certification labs, DTM can still be useful for:

  • measuring power consumption during TX,
  • packet loss detection
  • range testing

To ensure Zephyr’s BLE stack is built with DTM support, make sure the following is set:

CONFIG_BT_CTLR_DTM_HCI=y

Several HCI commands are defined in the Bluetooth Spec to support Direct Test Mode (DTM) control over HCI. Bluetooth devices are required to either support DTM over HCI, or provide a 2-wire UART interface for DTM. Zephyr does not provide the 2-wire DTM interface, but does

HCI Command OGF OCF
HCI_LE_Receiver_Test [v1] 0x08 0x001d
HCI_LE_Transmitter_Test [v1] 0x08 0x001e
HCI_LE_Test_End 0x08 0x001f
HCI_LE_Receiver_Test [v2] 0x08 0x0033
HCI_LE_Transmitter_Test [v2] 0x08 0x0034

Note that Zephyr’s BLE stack doesn’t yet support the newer HCI_LE_Receiver_Test [v3] (OCF: 0x004f) and HCI_LE_Transmitter_Test [v3] (OCF: 0x0050) HCI commands defined in Bluetooth Core v5.1.

LE Receiver Test

The HCI_LE_Receiver_Test HCI command can be used to start a test where the Device Under Test (DUT) receives test packets at a fixed interval.

HCI Command OGF OCF
HCI_LE_Receiver_Test [v1] 0x08 0x001d

Command Parameters:

Offset Size Parameter
0 1 RX_Channel

Return Parameters:

Offset Size Parameter
0 1 Status

Example:

# hcitool -i hci0 cmd 0x08 0x1d 0x02
< HCI Command: ogf 0x08, ocf 0x001d, plen 1
  02
  LE Receiver Test (0x08|0x001d) ncmd 1
> HCI Event: 0x0e plen 4
  01 1D 20 00
  Status: Success (0x00)

# hcitool -i hci0 cmd 0x08 0x1f
< HCI Command: ogf 0x08, ocf 0x001f, plen 0
  LE Test End (0x08|0x001f) plen 0
> HCI Event: 0x0e plen 6
  01 1F 20 00 02 84
  LE Test End (0x08|0x001f) ncmd 1
  Status: Success (0x00)
  Number of packets: 33794

LE Transmitter Test

The HCI_LE_Transmitter_Test HCI command can be used to start a test where the Device Under Test (DUT) generates test packets at a fixed interval.

HCI Command OGF OCF
HCI_LE_Transmitter_Test [v1] 0x08 0x001e

Command Parameters:

Offset Size Parameter
0 1 TX_Channel
1 1 Length_Of_Test_Data
2 1 Packet_Payload

Packet_Payload

Value Description
0 PRBS9 sequence (11111111100000111101…)
1 11110000
2 10101010
3 PRB15 sequence
4 11111111
5 00000000
6 00001111
7 01010101

Return Parameters:

Offset Size Parameter
0 1 Status

Example:

# hcitool -i hci1 cmd 0x08 0x1e 0x02 0x03 0x07
< HCI Command: ogf 0x08, ocf 0x001e, plen 3
  02 03 07
  LE Transmitter Test (0x08|0x001e) plen 3
      TX frequency: 2406 MHz (0x02)
      Test data length: 3 bytes
      Packet payload: 0x07
> HCI Event: 0x0e plen 4
  01 1E 20 00
  Status: Success (0x00)

# hcitool -i hci1 cmd 0x08 0x1f
< HCI Command: ogf 0x08, ocf 0x001f, plen 0
> HCI Event: 0x0e plen 6
  01 1F 20 00 00 00
  LE Test End (0x08|0x001f) ncmd 1
  Status: Success (0x00)
  Number of packets: 0

LE Test End

The HCI_LE_Test_End HCI command can be used to stop any ongoing Receive or Transmit test, and receive a count of received test packets.

HCI Command OGF OCF
HCI_LE_Test_End 0x08 0x001f

Command Parameters: none.

Return Parameters:

Offset Size Parameter
0 1 Status
1 2 Number of packets (0 for transmit test)

Example:

# hcitool -i hci0 cmd 0x08 0x1f
< HCI Command: ogf 0x08, ocf 0x001f, plen 0
  LE Test End (0x08|0x001f) plen 0
> HCI Event: 0x0e plen 6
  01 1F 20 00 02 84
  LE Test End (0x08|0x001f) ncmd 1
  Status: Success (0x00)
  Number of packets: 33794

Bluetooth Testing Protocol (BTP)

Zephyr also includes a standalone tester firmware for testing the internals of the Bluetooth stack. It can be used in conjunction with a Microsoft Windows-based test suite controller provided by the Bluetooth SIG.

This tester firmware does not provide an HCI interface, but instead implements the UART-based “Bluetooth Testing Protocol (BTP)”, allowing the internals of the Bluetooth stack to be tested with the Bluetooth Profile Tuning Suite (PTS) provided by Bluetooth SIG.

Conclusion

While the Direct Test Mode (DTM) functionality offered in Zephyr’s BLE stack might not be sufficient to test all the testing needed during prototype testing, it can be useful for more targeted testing such as in a production test.

References