Nordic nRF52 Demo
This demo will walk you through the functionality of the SwaraLink BLE Platform running on a Nordic Semiconductors nRF52 family device.
Prequisites - Hardware
Nordic nRF52 DK - 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:
nRF52 DK setup
To configure the nRF52 DK and flash the SwaraLink demo embedded application onto your nRF52 DK, please follow the instructions listed below:
Download our nRF52 application hex code here.
Open the nRF Conncect for Desktop Application on your PC.
The main program includes multiple apps embedded within. Find the "Programmer" app in the list, and click the "Install" button.
Once it is installed, click the "Open" button to start the app. You should see a window that looks like this:
From the Programmer application, hit "Select Device" at the top-left corner and select your nRF52 DK.
If you do not see nRF52 DK in the device list, ensure that the nRF52 DK is connected to your PC through USB and powered on via switch.
Now, to flash the device, either:
- Drag and drop the hex file from your files onto the "File memory layout" area.
- Press the "Add File" button and browse to and select your hex file.
Lastly, press the "Erase & Write" button on the left-hand Device menu to program the DK with the SWL demo application hex file. If done properly, the nRF Connect 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 nRF52 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 nRF52 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 using nRF Connect, 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, and observe this by checking LED 2 toggling on.
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. The DK will also turn on LED 1 once successfully paired and connected.
Now that we are connected, let's send some data from the device to the phone, or from peripheral-to-central (P2C). Press Button 4 on the DK.
When button 4 was pressed, the embedded application transmitted a pre-configured 4096 byte payload using the swl_periph embedded API. After pressing the button, on the SWL mobile app log you can observe the raw 4096 bytes of data that were sent from the DK to the smartphone under the event "evtP2CDataReceived".
If you scroll to the top of the event, you'll see fields for "Major ID Header" and "Minor ID Header" before the payload is displayed. The ID Header fields enable you to distininguish between data types when sending and receiving. In this case, the Major ID value was set to 01 and the Minor ID value was set to 00 by the embedded application (note: these values, as well as the payload, are displayed in hexadecimal format). When writing custom applications, you are free to use whatever values you want for the headers and can define them however you like.
Now let's send data from the mobile app to the device, 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 (again, all input fields are in a hexadecimal 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 will send one 4096 byte packet to the central (identical to the functionality of pressing Button 4). 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 pressing button 4 again to send the 4KB of data previously sent. 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:
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.