BLE Connectivity on Portenta H7

This tutorial explains how to use Bluetooth® Low Energy connectivity on the Portenta H7 to control the built-in LED using an external Bluetooth® application.

Overview

In this tutorial we will enable low energy Bluetooth® on the Portenta H7 to allow an external Bluetooth® device to control the built-in LED either by turning it on or off.

Goals

  • Enabling Bluetooth® Low Energy connectivity on the Portenta H7.
  • Connecting the Portenta to an external Bluetooth® Low Energy Mobile Application (In this case nRF Connect by Nordic Semiconductor).

Required Hardware and Software

Portenta and Low Energy Bluetooth®

The onboard Wi-Fi/Bluetooth® module of the Portenta H7 offers low energy Bluetooth® functionality, in order to provide the board with the flexibility to be easily connected to devices which also support Bluetooth® Low Energy, such as the Arduino Nano 33 IoT or most modern smartphones. Compared to classic Bluetooth®, Low Energy Bluetooth® is intended to provide considerably reduced power consumption and cost while maintaining a similar communication range.

Instructions

Configuring the Development Environment

To communicate with the Portenta H7 via Bluetooth®, you need to upload a pre-built sketch that starts a Bluetooth® network and allows your mobile device, which will be used to control the LEDs, to connect to it. The sketch uses the ArduinoBLE Library that enables the Bluetooth® Low Energy module and handles important functions, such as scanning, connecting and interacting with services provided by other devices. You will also be using a third party application (e.g. nRF Connect), running on your mobile device in order to connect your device to the board and help you control the built-in LED.

BLE Configuration Scheme

1. The Basic Setup

Begin by plugging in your Portenta board to the computer using a USB-C® cable and open the Arduino IDE. If this is your first time running Arduino sketch files on the board, we suggest you check out how to set up the Portenta H7 for Arduino before you proceed.

The Portenta H7 can be connected to the computer using an appropriate USB-C® cable

2. Install the ArduinoBLE Library

You will need to install the ArduinoBLE library in the Arduino IDE you are using. To install the library go to : Tools > Manage Libraries... type ArduinoBLE and click Install. Make sure you install ArduinoBLE version 1.1.3 or higher.

Download the Bluetooth® Low Energy library in the Library Manager.
Download the Bluetooth® Low Energy library in the Library Manager.

3. Create the Bluetooth® Low Energy Sketch

Let's program the Portenta with the following example sketch. If the Bluetooth® Low Energy module has been initialized correctly, you will see the blue LED lighting up for one second after uploading the sketch. If it fails, you will see the red LED lighting up instead. Copy and paste the following code into a new sketch in your IDE or download it from Arduino_Pro_Tutorials in the Arduino IDE and open it from: Examples > Arduino_Pro_Tutorials > BLE Connectivity on Portenta H7 > PortentaBLE

1#include <ArduinoBLE.h>
2
3BLEService ledService("19b10000-e8f2-537e-4f6c-d104768a1214");
4
5// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, read and writable by central
6BLEByteCharacteristic switchCharacteristic("19b10000-e8f2-537e-4f6c-d104768a1214", BLERead | BLEWrite);
7
8const int ledPin = LED_BUILTIN; // Pin to use for the LED
9
10void setup() {
11 Serial.begin(9600);
12 //while (!Serial); // Uncomment to wait for serial port to connect.
13
14 // Set LED pin to output mode
15 pinMode(ledPin, OUTPUT);
16 digitalWrite(ledPin, HIGH);
17
18 // Begin initialization
19 if (!BLE.begin()) {
20 Serial.println("Starting Bluetooth® Low Energy failed!");
21 digitalWrite(LEDR, LOW);
22 delay(1000);
23 digitalWrite(LEDR, HIGH);
24
25 // Stop if Bluetooth® Low Energy couldn't be initialized.
26 while (1);
27 }
28
29 // Set advertised local name and service UUID:
30 BLE.setLocalName("LED-Portenta-01");
31 BLE.setAdvertisedService(ledService);
32
33 // Add the characteristic to the service
34 ledService.addCharacteristic(switchCharacteristic);
35
36 // Add service
37 BLE.addService(ledService);
38
39 // Set the initial value for the characeristic:
40 switchCharacteristic.writeValue(0);
41
42 // start advertising
43 BLE.advertise();
44 digitalWrite(LEDB, LOW);
45 delay(1000);
46 digitalWrite(LEDB, HIGH);
47 Serial.println("BLE LED Control ready");
48}
49
50void loop() {
51 // Listen for Bluetooth® Low Energy peripherals to connect:
52 BLEDevice central = BLE.central();
53
54 // If a central is connected to peripheral:
55 if (central) {
56 Serial.print("Connected to central: ");
57 // Print the central's MAC address:
58 Serial.println(central.address());
59 digitalWrite(LEDB, HIGH);
60 delay(100);
61 digitalWrite(LEDB, LOW);
62 delay(100);
63 digitalWrite(LEDB, HIGH);
64
65 // While the central is still connected to peripheral:
66 while (central.connected()) {
67 // If the remote device wrote to the characteristic,
68 // Use the value to control the LED:
69 if (switchCharacteristic.written()) {
70 if (switchCharacteristic.value()) { // Any value other than 0
71 Serial.println("LED on");
72 digitalWrite(ledPin, LOW); // Will turn the Portenta LED on
73 } else {
74 Serial.println("LED off");
75 digitalWrite(ledPin, HIGH); // Will turn the Portenta LED off
76 }
77 }
78 }
79
80 // When the central disconnects, print it out:
81 Serial.print("Disconnected from central: ");
82 Serial.println(central.address());
83 digitalWrite(LEDB, HIGH);
84 delay(100);
85 digitalWrite(LEDB, LOW);
86 delay(100);
87 digitalWrite(LEDB, HIGH);
88 }
89}

In this example, you use a pre-defined Bluetooth® number code pre-setup for controlling a device's LED. This code can also be referred to as GATT codes, which define how two Bluetooth® low energy devices transfer data. Once a connection is established with a device, its respective GATT code, which is a 16 bit identifier, is stored in a lookup table for future reference.

These GATT codes are very long, but, in this example, it is always the same code:

BLEService ledService("19b10000-e8f2-537e-4f6c-d104768a1214"); // BLE LED Service

Remember that on the Portenta the built-in LED is turned on by setting it to LOW and turned off by setting it to HIGH, the opposite of most other Arduino boards.

4. Upload the Sketch

Double press the reset button so the built-in LED is slowly pulsing green. Then, select your board in the menu: Tools > Board > Arduino Portenta H7 (M7 core)

Select the Arduino Portenta H7 (M7 core) in the board selector.
Select the Arduino Portenta H7 (M7 core) in the board selector.

Choose the Port where your Portenta is connected to and Upload the sketch. Open the Serial Monitor once you have uploaded the code to the board to see debugging messages. If the Bluetooth® Low Energy setup was successful, you should see the message

BLE LED Control ready
. If something went wrong, you will see the message
Starting Bluetooth® Low Energy failed!
. In that case update the Arduino BLE library (in the Library Manager) and the board (in the Board Manager) to the latest version and try again.

Select the Port to which the Portenta is connected to.
Select the Port to which the Portenta is connected to.

5. Connect an External Device

On your mobile device install nRF Connect or an equivalent app that allows for Bluetooth® Low Energy connections. We will refer to nRF Connect for the rest of this tutorial.

Download the nRF Connect app from the Apple App Store or Google Play Store.
Download the nRF Connect app from the Apple App Store or Google Play Store.

Once you have downloaded the nRF application on your mobile device, look for your Portenta in the device list. You may filter the list by "Portenta" to easierly find your board in case you are using nRF Connect.

  • When you find your board in the list tap "Connect".
  • Navigate to the "Services" screen and tap the arrow up button.
  • Switch to "Bool" type and move the toggle to "True". Confirm the dialog with a tap on "Write" and you should see the built-in LED turned on. If you do the same procedure again but setting the toggle switch to "False", it will turn off the LED.

In the nRF Connect app use a Bool toggle switch to toggle the built-in LED.
In the nRF Connect app use a Bool toggle switch to toggle the built-in LED.

Conclusion

This tutorial shows how to connect and control the built-in LED using a Bluetooth® Low Energy connection. You have learned how a simple Bluetooth® Low Energy connection between your Portenta and your cell phone, which has basic communication abilities between the two devices, works.

Next Steps

Now that you learned how to configure the Portenta as a Bluetooth® Low Energy endpoint, you can try with two Portentas (or other Bluetooth® Low Energy capable Arduino devices), to facilitate bidirectional communication. More information on how to achieve that can be found on the BLE library reference page.

Troubleshooting

Sketch Upload Troubleshooting

If you try to upload a sketch and receive an error message, saying that the upload has failed, you can try to upload the sketch while the Portenta H7 is in bootloader mode. To do so, you need to double click the reset button. The green LED will start fading in and out. Try to upload the sketch again. The green LED will stop fading when the upload completes.

Suggest changes

The content on docs.arduino.cc is facilitated through a public GitHub repository. If you see anything wrong, you can edit this page here.

License

The Arduino documentation is licensed under the Creative Commons Attribution-Share Alike 4.0 license.