ST STM32WB Demo
This demo will walk you through the functionality of the SwaraLink BLE Platform running on an STMicroelectronics NUCLEO-WB55RG development kit (DK) featuring the STM32WBxx device.
NOTE: Support for the STM32WB is currently in a beta state. We are continually working to improve our demo and will have full, production-ready support available in the future. Please contact SwaraLink Technologies directly for more information.
Prequisites - Hardware
NUCLEO-WB55RG development kit - Required development kit (DK) to flash the Swaralink software onto and run the demo
Personal Computer (PC) - A Windows, Mac, or Linux machine to flash the DK
Smartphone - iOS 14.1 or later or Android version 8 or later
Prequisites - Software
On your PC, install the latest available version of the programmer application with default options:
Install the Swaralink Mobile App on your phone:
STM32WB DK setup
To configure the STM32WB DK and flash the SwaraLink demo embedded application onto your STM32WB DK, please follow the instructions listed below:
Download our STM32WB application hex code here.
Open the Cube Progammer application on your PC.
From the Programmer application, navigate to "Erasing & Programming" in the top-left corner menu.
If you do not see STM32WB DK under the "ST-LINK configuration", ensure that the DK is connected to your PC through USB and powered on by confirming with LED 6 turning solid red.
Press "Connect" to prepare your DK for flashing. Once connected, the "ST-LINK configuration" will be automatically populated.
Now, to flash the device, either:
- Drag and drop the hex file from your files onto the "Download" or "Erase flash memory" area.
- Press the "Browse" button and choose the subdirectory leading to your downloaded hex file.
Lastly, press the "Start Programming" button to program the DK with the SWL demo application hex file. If done properly, the Cube Programmer application log will read:
Swaralink Mobile App
Next, we will walk through the utility of our mobile app in communicating with the DK. This section is identically reproducible on Android and iOS.
Upon opening the SWL app, you will be prompted for location services if you are using Android, please allow this permission. Once the app is loaded, from top-to-bottom you will be presented with: an assortment of API functions, a button reading About, an expandable log panel/console with several button functionalities, and lastly the SWL Central Status at the bottom of the screen.
In this section we will discuss all of these mobile app features in-depth and guide you through using them side by side the STM32WB DK.
All functions in our API include a thorough description within the app. To view this, select any function (i.e. SWLCentral.discoverAndConnect) and find the description block at the top of the screen. These descriptions will help familiarize you with the API basics.
The about page displays the version number of the Swaralink app in use as well as the date of its release. Additionally, you can easily find & navigate to our website for more information or to contact us.
The log console is an immensely useful tool designed to help you follow the communication events as well as debug code from the central perspective. Any call to one of the API functions will be logged and timestamped as well as any subsequent events. Users can also choose whether transmissions send acknowldgement packets, in which case the log output holds this information.
We have included a few console functionalities to further facilitate debugging. The "Save Log" option will allow you to save the current log as a txt file to your local phone files; On iOS, you can also instantly share the log file. Alternatively, the log can be wiped using Clear Log and Auto Scroll can be toggled on or off for closer log observations.
At the bottom of the screen, the Central Status displays the current connection status of your smartphone. Initially, this state is set as Idle. Other common states are SWLCentralStateEstablishingConnection, SWLCentralStateDiscovered, and SWLCentralStateConnected.
Note that some API functions are only callable (usable) when the Central Status is in a certain state.
Now that you have completed setting up the STM32WB DK and installed our mobile app, walk through the following steps to see the platform in action.
Ensure that the DK is still powered on.
Once the hex has been flashed, its contents are stored in flash memory so powering on the DK will start the program.
Factory reset the DK by pressing Button 2. This puts the device into a fresh state and readies it for operation.
Enter the DK into pairing mode by pressing Button 1.
Now, on the mobile app, enter the SWLCentral.discoverAndConect page and select the "Connect to first discovered device" under mode. Then, press "Begin", and when prompted by your phone press "Pair".
After a few moments you can observe the Central Status transitions from SWLCentralStateIdle to SWLCentralStateConnected state. At this point you are securely paired and have an encrypted connection between your smartphone and the DK.
Now that the DK and mobile app are connected, let's send data from the mobile app to the DK, or from central-to-peripheral (C2P). Navigate to the SWLCentral.sendData API function, here we can enter the Major and Minor ID Headers and can set the payload.
The ID Header fields enable you to distininguish between data types when sending and receiving. When writing custom applications, you are free to use whatever values you want for the headers and can define them however you like. Note, the ID headers as well as the payload are all hexadecimal fields and must be input in this format.
For both major and minor ID headers, enter 42. In the data field let's send 2 bytes of data. Enter the 2-byte payload "AB12" and press "Send".
If "Acknowledged Transfer" is set to yes, you will see a C2PDataAcknowledged event with the corresponding major and minor header is logged with a successful acknoweledgement.
The embedded application is not designed to perform any specific action based on those major and minor headers, so you won't see any response from the peripheral. Next we will try some useful major and minor IDs for this demo.
Again, under SWLCentral.sendData, enter Major: 00, Minor: 00, and Payload: 01 in the data field and hit "Send".
When the embedded application receives the packet, it in turn sends one packet of pre-configured 4096 byte payload to the central. Within the log the SWLCentral.sendData call with our input parameters can be observed as well as an event in response to the call under the event "evtP2CDataReceived". In this case, the Major ID value was set to 01 and the Minor ID value was set to 00 by the embedded application on the peripheral side. Not to be confused with the central side call which used Major ID 00 and Minor ID 00.
Changing the payload specifies how many transmissions of the 4096 bytes to request from the peripheral. So for example, if you send another C2P packet with Major: 00, Minor: 00, and Payload: 32, the peripheral would send the same 4096 bytes of data 50 times (since 0x32 hexadecimal is equal to 50 decimal), for a total of 204,800 bytes of data. Feel free to try this out and see how fast the SwaraLink Platform is!
Once more, under SWLCentral.sendData, enter major: 00, minor: 02, and payload: 01, then hit "Send".
The functionality of the 02 minor ID is nearly identical to the previous minor ID, in that it sends the same set of bytes discussed above. However, now an Acknowledged Transfer from the peripheral to the central takes place and the central acknowledges that the bytes of data sent by the peripheral were received.
Navigate to SWLCentral.setPeripheralPriorities, this API function provides optimization for the peripheral from the listed priorities, ranked in importance from 1 to 3. However, the same option can be selected and prioritized on all three. Let's try this by setting "Reduce Power" in all three priorities, and if done successfully the following log will be observed:
Note that setting priorities involves tradeoffs among the other priorities. We can now visually observe one of these tradeoffs by using SWLCentral.sendData again to request the 4KB of data previously sent by the peripheral. Did you notice how much longer the data took to send and observe on the app? Both the C2P call requesting the data as well as the P2C response with the 4KB. This can be attributed to fully prioritizing power consumption, consequentially this comes at the expense of throughput.
Using SWLCentral.getPeripheralPriorities, we can confirm the set changes by pressing the button:
Priorites 1 through 3 are all set to "Increase Throughput" by default in our demo application, the log output also showed this earlier upon entering SWLCentralStateConnected. However, in the previous step we changed these priorities all to reduce power and we observe these modifications in the log.
Disconnect from the app using SWLCentral.terminateConnection and pressing "Terminate", after doing so you should see the SWL Central Status back in Idle.
That concludes the demo walkthrough, however other key features and uses of the demonstration code provided are listed in the next section.
Other Key Features
Using SWLCentral.directConnect at this point will show your device under "Known Devices", as the DK has already been paired previously through SWLCentral.discoverAndConnect and stored in the Known Device List (KDL).
Managing the KDL
To view peripheral devices formerly paired use SWLCentral.getKnownDeviceList. Similarly, to remove any peripheral from the KDL or to clear the KDL entirely use SWLCentral.removeFromKnownDeviceList or SWLCentral.clearKnownDeviceList respectively.
Over-the-Air (OTA) Firmware Updates
The Swaralink app provides OTA functionality to seamlessly update the peripheral firmware. To do so, navigate to SWLCentral.updatePeripheralFirmware and select the zip package and initiate the update.
Request Diagnostic Logs
Diagnostic logs are stored by the peripheral and contain data on stack events, such as on connection and more important information. These logs serve to assist in our debugging and help us keep track of key events.