KBA_BT_0917: Implementing wireless direct test mode (DTM)
09/247/2018 | 01:29 PM
Introduction
To design an embedded system is a complex task. An even more complex task is to design it right. As a result, radio testing is one of the critical step that any design cycle shall implement.
Because it is wireless, a Bluetooth based design might need to support some kind of wireless based testing method as well. This is because some devices can be fully enclosed, preventing any physical access via wired protocols such as UART.
The dtm (direct test mode) routines are part of the bgapi, they consist in two commands that can be used to test transmition/reception of your design. The most common way to use them is having a device programmed with NCP firmware (Network Co-Processor) and launching the commands from a host using BGAPI over UART. For more details on dtm and radio testing please refer to AN1046: Bluetooth® Radio Frequency Physical Layer Evaluation
The purpose of this article is to enable the use of these routines in a completely wireless approach (no physical access to the device required) and provide an understanding on how to implement such testing wirelessly. This article also indicates how to integrate that feature into you design using the WSTK + radio board as an example.
Prerequisites
To test the wireless testing solution in this article you will need two WSTKs, one as the radio sender and another as the radio receiver.
Note : "direct test mode" is part of the Bluetooth standard
Functional operation
The DUTs (device under test) are slave devices which can be used either as transmitter or as receiver. You can use a single master device to control both DUTs, a smartphone for example.
The receiver part of the test is stimulated by a call to the following routine (see bluetooth api reference guide) :
gecko_cmd_test_dtm_rx(uint8 channel, uint8 phy);
On the other hand, the transmitter side is triggered using the following routine (see bluetooth api reference guide) :
This example allows passing the arguments to the DUT over the air, through a custom GATT service for each of the commands, and trigger the test commands on both the receiver and the transmitter. Furthermore, it allows reading the number of packets received/sent once the test is completed on both tx/rx DUTs.
The following charts indicate the sequence of steps allowing the master to control the two devices. Typically, one would be the transmitter and the other one would be the receiver. The GATT client will give the arguments of the "gecko_cmd_test_dtm_rx" and "gecko_cmd_test_dtm_tx" routines respectively to the receiver and the transmitter. In addition it will also pass a "time" argument which is the duration of the test. To make sure that no packets are lost by the receiver it needs to be ensured that the receiver is started first and stays in RX test mode for a longer period that the transmitting device so that all packets are captured.
Receiver :
Transmitter :
Transactions flow :
In order to be able to do that, the tester would need the corresponding bluetooth services and characteristics in the GATT editor.
Services and Characteristics
The GATT database consist in two services, one for the RX routine and one for the TX routine. Additionally, in order to pass the arguments, the choice has been made here to use one characteristic each. The reason for that choice is that it is easier to use and understand. Each of the argument are 1 byte long.
Here is the layout of the GATT database in Simplicity :
Additionaly, as shown in the previous figure, a service is needed in order to be able to read back the result of the test and set the duration of the test.
The reason for that is once the test has started, we do not have any control over it because the connection will drop. Once the timer has elapsed, the routine that ends the test is called and triggers the tester to readvertise so the user can reconnect and read the result.
As a result, this needs to be supported in the GATT data base. A control service is then defined that implement the following characteristics :
- two bytes write characteristic that implement the timer (in second)
- two bytes read characteristic that allows the user to read the result from the previous test
So that's it for the user side. But how does that work on the tester side ? That is what we will focus on in the next section.
How does it work ?
Since the code is available, anybody can go and have a look. As a result, we won't go too much in written details here. Nevertheless, here is a high level state machine that gives a good idea on how the tester side works.
Now that the reader has a good overview on both the user and the tester side, time has come for integration.
Integration steps
First of all, you will need to start from and soc_empty.
Under the app directory, add the sources attached to this article app.c and app.h :
app/app.c
app/app.h
Import gatt.xml to your project and generate gatt_db.h and .c.
Modify the main.c as following :
Remove the code corresponding to the body of the infinite loop in the main routine
Include app.h
Add a call dtm_intfc_init(void) before the infinite loop.
Add the call to the application background task in the infinite loop.
-> Once these modifications are done, your main.c should look like this :
At this stage the project should be compiling. Update both the receiver kit and the transmitter kit with the newly compiled image. Now it is demo time.
Demonstration steps
Power up the receiver kit.
Connect to device called "dtm_test" via bluetooth using whatever phone application or programme you prefer.
Enter in the timer characteristic the timer value on the receiver
First service, UUID starts with 0D8991EE and then the first characteristic UUID starts with 5ED6DC96 (see reference chapter for valid timer values).
Enter the two arguments for "gecko_cmd_test_dtm_rx" (see reference for more details on the arguments)
Second service, UUID starts with BACE30ED and then the first characteristic UUID starts with 7170EA45
Second service, UUID starts with BACE30ED and then the second characteristic UUID starts with 7170EA45
Power up the transmitter kit.
Connect to the second device that advertise using the same name "dtm_test" via bluetooth (using a second phone for example if needed).
Enter in the timer characteristic the timer value transmitter (see reference section for more detail)
First service, UUID starts with 0D8991EE and then the first characteristic UUID starts with 5ED6DC96 (see reference chapter for valid timer values).
Enter the four arguments for "gecko_cmd_test_dtm_tx" (see reference for more details on the arguments)
Third service, UUID starts with EF0EF18F and then the first characteristic UUID starts with 31D511A9 for the packet type.
Third service, UUID starts with EF0EF18F and then the second characteristic UUID starts with E4A01204 for the length.
Third service, UUID starts with EF0EF18F and then the third characteristic UUID starts with 1928CD35
Third service, UUID starts with EF0EF18F and then the forth characteristic UUID starts with D559D164
Disconnect the user device from the receiver first (that will trigger the receiver to start listening)
Only after, disconnect the user from the transmitter (that will trigger the transmitter to start sending)
Test is running ....
Once the test have finished on both testers (transmitter and receiver) are re-advertising
Reconnect and read out the result. The result correspond to the number of packets received (if the result is read on the receiver) and the number of packets transmitted (if the result is read on the transmitter).
First service, UUID starts with 0D8991EE and then the first characteristic UUID starts with 84D0E28A
Reference
For more information, please refere to the bluetooth api reference manual available with Simplicity Sudio (bluetooth_api_reference.pdf)
I added the source code in a zip archive and that seem to work better. Sorry for the inconvenience.
Concerning the DTM sample app you mentioned earlier, that is using USART(NCP mode). DTM commands are sent to the devices under test via the serial link which is different from what this KBA is aiming at.
In this article we tackle the case where there is no USART. you can definitely use the code delivered with that article using soc-empty as a base.
KBA_BT_0917: Implementing wireless direct test mode (DTM)
Introduction
To design an embedded system is a complex task. An even more complex task is to design it right. As a result, radio testing is one of the critical step that any design cycle shall implement.
Because it is wireless, a Bluetooth based design might need to support some kind of wireless based testing method as well. This is because some devices can be fully enclosed, preventing any physical access via wired protocols such as UART.
The dtm (direct test mode) routines are part of the bgapi, they consist in two commands that can be used to test transmition/reception of your design. The most common way to use them is having a device programmed with NCP firmware (Network Co-Processor) and launching the commands from a host using BGAPI over UART. For more details on dtm and radio testing please refer to AN1046: Bluetooth® Radio Frequency Physical Layer Evaluation
The purpose of this article is to enable the use of these routines in a completely wireless approach (no physical access to the device required) and provide an understanding on how to implement such testing wirelessly. This article also indicates how to integrate that feature into you design using the WSTK + radio board as an example.
Prerequisites
To test the wireless testing solution in this article you will need two WSTKs, one as the radio sender and another as the radio receiver.
Note : "direct test mode" is part of the Bluetooth standard
Functional operation
The DUTs (device under test) are slave devices which can be used either as transmitter or as receiver. You can use a single master device to control both DUTs, a smartphone for example.
The receiver part of the test is stimulated by a call to the following routine (see bluetooth api reference guide) :
On the other hand, the transmitter side is triggered using the following routine (see bluetooth api reference guide) :
This example allows passing the arguments to the DUT over the air, through a custom GATT service for each of the commands, and trigger the test commands on both the receiver and the transmitter. Furthermore, it allows reading the number of packets received/sent once the test is completed on both tx/rx DUTs.
The following charts indicate the sequence of steps allowing the master to control the two devices. Typically, one would be the transmitter and the other one would be the receiver. The GATT client will give the arguments of the "gecko_cmd_test_dtm_rx" and "gecko_cmd_test_dtm_tx" routines respectively to the receiver and the transmitter. In addition it will also pass a "time" argument which is the duration of the test. To make sure that no packets are lost by the receiver it needs to be ensured that the receiver is started first and stays in RX test mode for a longer period that the transmitting device so that all packets are captured.
Receiver :
Transmitter :
Transactions flow :
In order to be able to do that, the tester would need the corresponding bluetooth services and characteristics in the GATT editor.
Services and Characteristics
The GATT database consist in two services, one for the RX routine and one for the TX routine. Additionally, in order to pass the arguments, the choice has been made here to use one characteristic each. The reason for that choice is that it is easier to use and understand. Each of the argument are 1 byte long.
Here is the layout of the GATT database in Simplicity :
Additionaly, as shown in the previous figure, a service is needed in order to be able to read back the result of the test and set the duration of the test.
The reason for that is once the test has started, we do not have any control over it because the connection will drop. Once the timer has elapsed, the routine that ends the test is called and triggers the tester to readvertise so the user can reconnect and read the result.
As a result, this needs to be supported in the GATT data base. A control service is then defined that implement the following characteristics :
So that's it for the user side. But how does that work on the tester side ? That is what we will focus on in the next section.
How does it work ?
Since the code is available, anybody can go and have a look. As a result, we won't go too much in written details here. Nevertheless, here is a high level state machine that gives a good idea on how the tester side works.
Now that the reader has a good overview on both the user and the tester side, time has come for integration.
Integration steps
First of all, you will need to start from and soc_empty.
Under the app directory, add the sources attached to this article app.c and app.h :
Import gatt.xml to your project and generate gatt_db.h and .c.
Modify the main.c as following :
-> Once these modifications are done, your main.c should look like this :
At this stage the project should be compiling. Update both the receiver kit and the transmitter kit with the newly compiled image. Now it is demo time.
Demonstration steps
Power up the receiver kit.
Connect to device called "dtm_test" via bluetooth using whatever phone application or programme you prefer.
Enter in the timer characteristic the timer value on the receiver
Enter the two arguments for "gecko_cmd_test_dtm_rx" (see reference for more details on the arguments)
Power up the transmitter kit.
Connect to the second device that advertise using the same name "dtm_test" via bluetooth (using a second phone for example if needed).
Enter in the timer characteristic the timer value transmitter (see reference section for more detail)
Enter the four arguments for "gecko_cmd_test_dtm_tx" (see reference for more details on the arguments)
Disconnect the user device from the receiver first (that will trigger the receiver to start listening)
Only after, disconnect the user from the transmitter (that will trigger the transmitter to start sending)
Test is running ....
Once the test have finished on both testers (transmitter and receiver) are re-advertising
Reconnect and read out the result. The result correspond to the number of packets received (if the result is read on the receiver) and the number of packets transmitted (if the result is read on the transmitter).
Reference
For more information, please refere to the bluetooth api reference manual available with Simplicity Sudio (bluetooth_api_reference.pdf)
PHY settings :
Packet type settings:
Timer : The timer unit is the the second.
Hi Badiss
There is no gattd_db.xml available for download on the article. Can you put gattd_db.xml on article? This is convenient for DTM testing
Thanks
Richard
Hello Richard,
The gatt.xml data base file has been added. Shall you need further help, just come back to me and I will be happy to help.
Regards.
Badiss.
Is this guide suitable for applications using EFR32BG?
On the Bluetooth Gecko SDK 2.7.0.0 there is a DTM project template. Can we use that instead of starting from the Empy-SOC project?
The main structure is as follows:
How does this differ from the routines describes in your article?
Thanks.
Hi Badiss,
The link to app.h seems to be broken. Can you please upload the file again?
Thank you.
Hello matifineschi,
I added the source code in a zip archive and that seem to work better. Sorry for the inconvenience.
Concerning the DTM sample app you mentioned earlier, that is using USART(NCP mode). DTM commands are sent to the devices under test via the serial link which is different from what this KBA is aiming at.
In this article we tackle the case where there is no USART. you can definitely use the code delivered with that article using soc-empty as a base.
Let me know if you encounter any problem.
Badiss.