This an example application that demonstrates Bluetooth Low Energy (BLE) peripheral connectivity using BGLib C function definitions. It resets the device, then reads the MAC address and executes one or more test commands. The functionality can be used for RF testing and manufacturing verification purposes.
This is targeted to run on a Posix/Linux/Cygwin host. The BLE NCP can be connected to any /dev/ttyx including hardware UARTs as well as USB virtual COM ports. This includes the Silicon Labs Wireless Starter Kit (WSTK) development board (or Silicon Labs Thunderboard) connected over USB (virtual COM) with an applicable NCP firmware image programmed into the EFR32.
These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.
- Blue Gecko SDK version v4.0 (Gecko SDK 4.1.0) or greater installed via Simplicity Studio v5 or from github. NOTE: This tool is no longer compatible with Blue Gecko SDK version 2.x. For 2.x compatibility, revert to previous 1.x versions of BLEtest.
- Linux/Posix build environment (OSX, Raspberry Pi, etc.) or Windows (Cygwin/MinGW).
- Blue Gecko / Mighty Gecko device running a serial UART NCP (Network Co-Processor) firmware image from Bluetooth SDK v4.0 (Gecko SDK 4.1.0) or greater. See the "To Run" section below for more details.
- To use the advertising feature in this version of BLEtest without an assert, some component selections need to be changed from the defaults in the NCP firmware image. The following components should be removed from the NCP firmware project slcp: "Legacy Advertising", "Extended Advertising", and "Periodic Advertising". Removing these also removes the "Advertising Base Feature" which is required, so this component needs to be added back.
- The advertising scan functionality requires the "Scanner for legacy advertisements" component to be present in the NCP firmware.
This project can be built as supplied within the Blue Gecko SDK frameworks.
Clone or copy the contents of this repository into the Gecko SDK, into a subfolder of app/bluetooth/example_host. Commands shown here are from OSX using Gecko SDK Suite v4.0.2, but will be similar in Linux/Cygwin.
$ cd ~/SimplicityStudio/SDKs/gecko_sdk/app/bluetooth/example_host/
$ git clone https://github.com/kryoung-silabs/BLEtest.git
$ cd BLEtest
$ make
- Clone Gecko SDK (4.1.0 or higher) to the Raspberry Pi.
$ git clone https://github.com/SiliconLabs/gecko_sdk.git
- Clone BLEtest to the Raspberry Pi:
$ git clone https://github.com/kryoung-silabs/BLEtest.git
- Cd to the BLEtest folder and invoke make, specifying the SDK root directory via the SDK_DIR parameter.
$ cd BLEtest
$ make SDK_DIR=../gecko_sdk
- Program your NCP firmware image (using either the "Bluetooth - NCP Empty" or "Bluetooth - NCP" example projects) into your target board. Instructions on how to implement this, both on custom hardware and on Silicon Labs wireless starter kit (WSTK) radio boards are provided in AN1259: Using the v3.x Silicon Labs Bluetooth(R) Stack in Network Co-Processor Mode.
- Connect your device running the Bluetooth NCP firmware to the host (via USB, uart, etc.).
- Run the host application, pointing it to the correct serial port. Note that the default serial port created when plugging a Silicon Labs WSTK or Silicon Labs Thunderboard into a Raspberry Pi is "/dev/ttyACM0". The command line usage is:
BLEtest -u <serial port>
Arguments:
-h Print help message
-u <UART port name>
-t <tcp address>
-b <baud_rate, default 115200>
-f Enable hardware flow control
--version Print version number defined in application.
--time <duration ms> Set time for test in milliseconds, 0 for infinite mode (exit with control-c)
--packet_type <payload/modulation type, 0:PBRS9 packet payload, 1:11110000 packet payload, 2:10101010 packet payload, 4:111111 packet payload, 5:00000000 packet payload, 6:00001111 packet payload, 7:01010101 packet payload, 253:PN9 continuously modulated, 254:unmodulated carrier>
--power <power level> Set power level for test in 0.1dBm steps
--channel <channel index> Set channel index for test, frequency=2402 MHz + 2*channel>
--len <test packet length> Set test packet length, ignored for unmodulated carrier>
--rx TM receive test. Prints number of received DTM packets.
--ctune_set <ctune val> Set 16-bit crystal tuning value, e.g. 0x0136
--addr_set <MAC> Set 48-bit MAC address, e.g. 01:02:03:04:05:06
--ctune_get Read 16-bit crystal tuning value
--fwver_get Read FW revision string from Device Information (GATT)
--adv Enter an advertisement mode with scan response for TIS/TRP chamber and connection testing (default period = 100ms)
--adv_period <period> Set advertising period for the advertisement mode, in units of 0.625ms
--cust <ASCII hex string> Allows verification/running custom BGAPI commands.
--phy <PHY selection for test packets/waveforms/RX mode, 1:1Mbps, 2:2Mbps, 3:125k LR coded, 4:500k LR coded.>
--advscan Return RSSI, channel, and MAC address for advertisement scan results
--advscan=<MAC> Set optional MAC address for advertising scan filtering, e.g. 01:02:03:04:05:06
--rssi_avg <number of packets to include in RSSI average reports for advscan>
--conn=<MAC> Connect as central to 48-bit MAC address, e.g. 01:02:03:04:05:06
--conn_int <conn interval> Set connection interval for central connection, in units of 1.25ms
--coex Enable coexistence on the target if available
--throughput <0 or 1> Push dummy throughput data when connected as central to another unit running BLEtest as an advertiser, with ack (1) or without ack (0)
--report <interval> Print the channel map and throughput (if applicable) at the specified interval in milliseconds
Refer to the Blue Gecko API documentation for more details about the various arguments.
When you run with only the serial port argument, you'll get some simple default behavior:
$ ./exe/BLEtest -u /dev/ttyACM0
------------------------
Waiting for boot pkt...
boot pkt rcvd: gecko_evt_system_boot(4, 1, 0, 273, 0x 0, 257)
MAC address: 90:FD:9F:7B:53:23
Outputting modulation type 0xFE for 0 ms at 2402 MHz at 5.0 dBm, phy=0x01
Infinite mode. Press control-c to exit...
^CCanceling DTM in progress...
DTM completed, number of packets transmitted: 0
Examples:
- Transmit an unmodulated carrier for 10 seconds on 2402 at 5.0 dBm output power level on the device connected to serial port /dev/ttyACM0:
$ ./exe/BLEtest --time 10000 --packet_type 254 --power 50 -u /dev/ttyACM0 --channel 0
------------------------
Waiting for boot pkt...
boot pkt rcvd: gecko_evt_system_boot(4, 1, 0, 273, 0x 0, 257)
MAC address: 00:0D:6F:20:B2:D6
Outputting modulation type 0xFE for 10000 ms at 2402 MHz at 5.0 dBm, phy=0x01
DTM completed, number of packets transmitted: 0
- Transmit DTM (direct test mode) packets containing a pseudorandom PRBS9 payload of length=25 for 10 seconds on 2404 MHz at 8dBm output power level on device connected to serial port /dev/ttyACM0
$ ./exe/BLEtest --time 10000 --packet_type 0 --power 80 -u /dev/ttyACM0 --channel 1 --len 25
------------------------
Waiting for boot pkt...
boot pkt rcvd: gecko_evt_system_boot(4, 1, 0, 273, 0x 0, 257)
MAC address: 00:0D:6F:08:62:3F
Outputting modulation type 0x00 for 10000 ms at 2404 MHz at 8.0 dBm, phy=0x01
DTM completed, number of packets transmitted: 16014
- Receive DTM (direct test mode) packets for 10 seconds on 2404 MHz on device connected to serial port /dev/ttyACM0. Note that the printout below shows an example of 100% packet reception rate when running example 2 (TX with PRBS9 DTM length=25) on a separate device.
$ ./exe/BLEtest --time 20000 --rx -u /dev/ttyACM0 --channel 1
------------------------
Waiting for boot pkt...
boot pkt rcvd: gecko_evt_system_boot(4, 1, 0, 273, 0x 0, 257)
MAC address: 00:0D:6F:20:B2:D6
DTM receive enabled, freq=2404 MHz
DTM receive completed. Number of packets received: 16214
- Program custom MAC address 01:02:03:04:05:06 on device connected to virtual COM port /dev/ttyACM0:
$ ./exe/BLEtest -u /dev/ttyACM1 --addr_set 01:02:03:04:05:06 --time 1
------------------------
Waiting for boot pkt...
boot pkt rcvd: gecko_evt_system_boot(4, 1, 0, 273, 0x 0, 257)
MAC address: 01:02:03:04:05:06
Writing MAC address: 01:02:03:04:05:06
Rebooting with new MAC address...
boot pkt rcvd: gecko_evt_system_boot(4, 1, 0, 273, 0x 0, 257)
MAC address: 01:02:03:04:05:06
Outputting modulation type 0xFE for 1 ms at 2402 MHz at 5.0 dBm, phy=0x01
DTM completed, number of packets transmitted: 0
- Write crystal tuning value of 0x0155 to device connected to virtual COM port /dev/ttyACM0 and output test tone of 2402 MHz at 5.0 dBm for 10 seconds to verify frequency using a spectrum analyzer (set the instrument to 500 kHz bandwidth).
$ ./exe/BLEtest -u /dev/ttyACM0 --ctune_set 0x0155 --packet_type 254 --time 10000 --channel 0 --power 50
------------------------
Waiting for boot pkt...
boot pkt rcvd: gecko_evt_system_boot(4, 1, 0, 273, 0x 0, 257)
MAC address: 00:0D:6F:20:B2:D6
Writing ctune value to 0x0155
Rebooting with new ctune value...
boot pkt rcvd: gecko_evt_system_boot(4, 1, 0, 273, 0x 0, 257)
MAC address: 00:0D:6F:20:B2:D6
Outputting modulation type 0xFE for 10000 ms at 2402 MHz at 5.0 dBm, phy=0x01
DTM completed, number of packets transmitted: 0
- Send custom BGAPI payload "0x01" and print response payload. In our NCP example projects, custom BGAPI handlers for commands "0x01" and "0x02" are implemented as an example with functionality implemented to echo back the command in the response payload.
$ ./exe/BLEtest -u /dev/ttyACM0 --cust 01
------------------------
Waiting for boot pkt...
boot pkt rcvd: gecko_evt_system_boot(4, 1, 0, 273, 0x 0, 257)
MAC address: 00:0D:6F:20:B2:D6
Sending custom user message to target...
BGAPI success! Returned payload (len=1): 01
- Transmit a PN9 continuously modulated output (100% duty cycle) on logical channel 19 (physical channel 21, 2444 MHz) at 10dBm for 5 seconds using the 2Mbps PHY.
$ ./exe/BLEtest -u /dev/ttyACM0 --packet_type 253 --channel 21 --power 100 --time 5000 --phy 2
------------------------
Waiting for boot pkt...
boot pkt rcvd: gecko_evt_system_boot(4, 1, 0, 273, 0x 0, 257)
MAC address: 00:0D:6F:20:B2:D6
Outputting modulation type 253 for 5000 ms at 2402 MHz at 10.0 dBm, phy=0x02
Test completed!
- Run in advertisement mode with 50ms period as a background process for TIS/TRP chamber testing.
$ ./exe/BLEtest -u /dev/ttyACM0 --adv --adv_period 80 > /dev/null 2>&1 &
[1] 25670
$
- Scan for advertising packets (no filtering) for 500 ms.
$ ./exe/BLEtest -u /dev/ttyACM1 --advscan --time 500
------------------------
Waiting for boot pkt...
boot pkt rcvd: gecko_evt_system_boot(4, 1, 0, 273, 0x 0, 257)
MAC address: 90:FD:9F:7B:53:23
Enabling advertising scan.
No RSSI averaging - info from every packet will be printed
Scanning for 500 milliseconds
ADV RCVD from MAC 41:B8:FA:26:10:75, Channel: 38, RSSI: -40
ADV RCVD from MAC F4:5C:89:CA:51:80, Channel: 38, RSSI: -40
ADV RCVD from MAC 63:61:A9:EC:76:81, Channel: 38, RSSI: -54
ADV RCVD from MAC 01:95:DE:A0:D9:9E, Channel: 37, RSSI: -53
ADV RCVD from MAC 41:B8:FA:26:10:75, Channel: 38, RSSI: -40
ADV RCVD from MAC F4:5C:89:CA:51:80, Channel: 39, RSSI: -46
ADV RCVD from MAC 63:61:A9:EC:76:81, Channel: 38, RSSI: -54
ADV RCVD from MAC F4:5C:89:CA:51:80, Channel: 39, RSSI: -45
ADV RCVD from MAC 01:95:DE:A0:D9:9E, Channel: 38, RSSI: -54
ADV RCVD from MAC 63:61:A9:EC:76:81, Channel: 39, RSSI: -56
Exiting scan mode, total scan packets received = 10
- Scan for advertising packets filtering on a MAC address for 500 ms.
$ ./exe/BLEtest -u /dev/ttyACM1 --advscan=63:61:A9:EC:76:81 --time 500
------------------------
Waiting for boot pkt...
boot pkt rcvd: gecko_evt_system_boot(4, 1, 0, 273, 0x 0, 257)
MAC address: 90:FD:9F:7B:53:23
Enabling advertising scan with MAC address filter 63:61:A9:EC:76:81.
No RSSI averaging - info from every packet will be printed
Scanning for 500 milliseconds
ADV RCVD from MAC 63:61:A9:EC:76:81, Channel: 37, RSSI: -55
ADV RCVD from MAC 63:61:A9:EC:76:81, Channel: 38, RSSI: -62
Exiting scan mode, total scan packets received = 2
- Scan for advertising packets, filtering on a MAC address, averaging RSSI over every 10 packets, infinite mode.
$ ./exe/BLEtest -u /dev/ttyACM1 --advscan=63:61:A9:EC:76:81 --rssi_avg 10
------------------------
Waiting for boot pkt...
boot pkt rcvd: gecko_evt_system_boot(4, 1, 0, 273, 0x 0, 257)
MAC address: 90:FD:9F:7B:53:23
Enabling advertising scan with MAC address filter 63:61:A9:EC:76:81.
RSSI averaging over 10 packets
Infinite mode. Press control-c to exit.
AVG RSSI REPORT: -53.30
AVG RSSI REPORT: -52.80
AVG RSSI REPORT: -54.00
AVG RSSI REPORT: -53.10
^CExiting scan mode, total scan packets received = 49
For a commercially deployed system (i.e. embedded gateway, etc.), use the supplied makefile and source files from the Blue Gecko SDK to cross-compile for the desired platform.
I am a Field Applications Engineer for Silicon Labs, not a full time software developer, so I've created this application in my "spare time" to provide an example for Silicon Labs customers to use to bring up their hardware, do some testing, and perhaps form as the basis to extend with additional functionality. If needed, I can provide limited support for this specific software via email <[email protected]>. For support on building NCP firmware images, bringing up NCP firmware, and building target firmware images using examples under Simplicity Studio, please obtain support through the official Silicon Labs support portal.
I plan to use SemVer for versioning. For the versions available, see the tags on this repository. All notable changes to this project will be documented in CHANGELOG.md.
- Kris Young - Initial work - Kris Young <[email protected]>
This AS-IS example project is licensed under Zlib by Silicon Laboratories Inc. See the LICENSE.md file for details
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent