Running Bluetooth Low Energy tests - FreeRTOS
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Running Bluetooth Low Energy tests

This section describes how to set up and run the Bluetooth tests using Amazon IoT Device Tester for FreeRTOS. Bluetooth tests are not required for core qualification. If you do not want to test your device with FreeRTOS Bluetooth support you may skip this setup, be sure to leave the BLE feature in device.json set to No.



Raspberry Pi setup

To test the BLE capabilities of the device under test (DUT), you must have a Raspberry Pi Model 4B or 3B+.

To set up your Raspberry Pi to run BLE tests
  1. Download one of the custom Yocto images that contains the software required to perform the tests.


    The Yocto image should only be used for testing with Amazon IoT Device Tester for FreeRTOS and not for any other purpose.

  2. Flash the yocto image onto the SD card for Raspberry Pi.

    1. Using an SD card-writing tool such as Etcher, flash the downloaded image-name.rpi-sd.img file onto the SD card. Because the operating system image is large, this step might take some time. Then eject your SD card from your computer and insert the microSD card into your Raspberry Pi.

  3. Configure your Raspberry Pi.

    1. For the first boot, we recommend that you connect the Raspberry Pi to a monitor, keyboard, and mouse.

    2. Connect your Raspberry Pi to a micro USB power source.

    3. Sign in using the default credentials. For user ID, enter root. For password, enter idtafr.

    4. Using an Ethernet or Wi-Fi connection, connect the Raspberry Pi to your network.

      1. To connect your Raspberry Pi over Wi-Fi, open /etc/wpa_supplicant.conf on the Raspberry Pi and add your Wi-Fi credentials to the Network configuration.

        ctrl_interface=/var/run/wpa_supplicant ctrl_interface_group=0 update_config=1 network={ scan_ssid=1 ssid="your-wifi-ssid" psk="your-wifi-password" }
      2. Run ifup wlan0 to start the Wi-Fi connection. It might take a minute to connect to your Wi-Fi network.

    5. For an Ethernet connection, run ifconfig eth0. For a Wi-Fi connection, run ifconfig wlan0. Make a note of the IP address, which appears as inet addr in the command output. You need the IP address later in this procedure.

    6. (Optional) The tests execute commands on the Raspberry Pi over SSH using the default credentials for the yocto image. For additional security, we recommend that you set up public key authentication for SSH and disable password-based SSH.

      1. Create an SSH key using the OpenSSL ssh-keygen command. If you already have an SSK key pair on your host computer, it is a best practice to create a new one to allow Amazon IoT Device Tester for FreeRTOS to sign in to your Raspberry Pi.


        Windows does not come with an installed SSH client. For information about how to install an SSH client on Windows, see Download SSH Software.

      2. The ssh-keygen command prompts you for a name and path to store the key pair. By default, the key pair files are named id_rsa (private key) and (public key). On macOS and Linux, the default location of these files is ~/.ssh/. On Windows, the default location is C:\Users\user-name.

      3. When you are prompted for a key phrase, just press ENTER to continue.

      4. To add your SSH key onto your Raspberry Pi so Amazon IoT Device Tester for FreeRTOS can sign into the device, use the ssh-copy-id command from your host computer. This command adds your public key into the ~/.ssh/authorized_keys file on your Raspberry Pi.

        ssh-copy-id root@raspberry-pi-ip-address

      5. When prompted for a password, enter idtafr. This is the default password for the yocto image.


        The ssh-copy-id command assumes the public key is named On macOS and Linux, the default location is ~/.ssh/. On Windows, the default location is C:\Users\user-name\.ssh. If you gave the public key a different name or stored it in a different location, you must specify the fully qualified path to your SSH public key using the -i option to ssh-copy-id (for example, ssh-copy-id -i ~/my/path/ For more information about creating SSH keys and copying public keys, see SSH-COPY-ID.

      6. To test that the public key authentication is working, run ssh -i /my/path/myKey root@raspberry-pi-device-ip.

        If you are not prompted for a password, your public key authentication is working.

      7. Verify that you can sign in to your Raspberry Pi using a public key, and then disable password-based SSH.

        1. On the Raspberry Pi, edit the /etc/ssh/sshd_config file.

        2. Set the PasswordAuthentication attribute to no.

        3. Save and close the sshd_config file.

        4. Reload the SSH server by running /etc/init.d/sshd reload.

    7. Create a resource.json file.

      1. In the directory in which you extracted Amazon IoT Device Tester, create a file named resource.json.

      2. Add the following information about your Raspberry Pi to the file, replacing rasp-pi-ip-address with the IP address of your Raspberry Pi.

        [ { "id": "ble-test-raspberry-pi", "features": [ {"name":"ble", "version":"4.2"} ], "devices": [ { "id": "ble-test-raspberry-pi-1", "connectivity": { "protocol": "ssh", "ip": "rasp-pi-ip-address" } } ] } ]
      3. If you didn't choose to use public key authentication for SSH, add the following to the connectivity section of the resource.json file.

        "connectivity": { "protocol": "ssh", "ip": "rasp-pi-ip-address", "auth": { "method": "password", "credentials": { "user": "root", "password": "idtafr" } } }
      4. (Optional) If you chose to use public key authentication for SSH, add the following to the connectivity section of the resource.json file.

        "connectivity": { "protocol": "ssh", "ip": "rasp-pi-ip-address", "auth": { "method": "pki", "credentials": { "user": "root", "privKeyPath": "location-of-private-key" } } }

FreeRTOS device setup

In your device.json file, set the BLE feature to Yes. If you are starting with a device.json file from before Bluetooth tests were available, you need to add the feature for BLE to the features array:

{ ... "features": [ { "name": "BLE", "value": "Yes" }, ... }

Running the BLE tests

After you have enabled the BLE feature in device.json, the BLE tests run when you run devicetester_[linux | mac | win_x86-64] run-suite without specifying a group-id.

If you want to run the BLE tests separately, you can specify the group ID for BLE: devicetester_[linux | mac | win_x86-64] run-suite --userdata path-to-userdata/userdata.json --group-id FullBLE.

For the most reliable performance, place your Raspberry Pi close to the device under test (DUT).

Troubleshooting BLE tests

Make sure you have followed the steps in Preparing to test your microcontroller board for the first time. If tests other than BLE are failing, then the problem is most likely not due to the Bluetooth configuration.