Template sub-GHz¶
The sample demonstrates a template for the Sidewalk End Node application. It supports LoRa and FSK link modes. The external QSPI Flash is used for firmware updates.
Requirements¶
The sample supports the following development kits:
Hardware platforms |
PCA |
Board name |
Build target |
---|---|---|---|
nRF52840 DK |
PCA10056 |
|
|
nRF5340 DK |
PCA10095 |
|
Besides the development kit, a LoRa radio module is also needed for this sample if you build it with the LoRa or FSK configuration. The supported modules are as follows:
Radio chip |
Board name |
Interface |
---|---|---|
SX126xMB2xAS |
SPI @ 8Mhz |
Note
The LoRa radio module shield must be connected to the development kit header, and the antenna has to be connected to the radio module. For the exact pin assignment, refer to the Pinout section.
Overview¶
You can use this sample as a starting point to implement a Sidewalk device. The sample shows implementation of the Sidewalk API for the following transport protocols:
LoRa - Bluetooth LE for registration and LoRa for communication
FSK - FSK for registration and communication
The Template sample supports all available configurations but because the size and location of the bootloader partitions must be consistent, the sample uses external memory to store the secondary partition for the application. This solution is required only for the Device Firmware Update (DFU).
User interface¶
A button action is triggered when you release the button. To use a long press action, hold a button for 2 seconds or longer, and release it.
The button assignment is as follows:
- Button 1 (long press):
Factory reset - The application informs the Sidewalk stack about the factory reset event. The Sidewalk library clears its configuration from the non-volatile storage. After a successful reset, the device needs to be registered with the cloud services again.
- Button 2 (short press):
Get current Device Profiles - The divice profile paramters are printed in logs.
- Button 2 (long press):
Switch between Device Profiles - The application sets the device profile fields like link, profile ID, window count, sync and async intervals for communication.
- Button 3:
Send Hello - This action will queue a message to the cloud. If Sidewalk is not ready, it will simply show an error without sending the message. The queue will be processed eventually, and all the queued messages will be sent.
- Button 4 (short press):
Send Hello.
- Button 4 (long press):
Enter DFU state - This action disables the Sidewalk stack and starts the Bluetooth LE SMP Server. You can update the firmware image using nRF Connect for mobile application. To exit DFU state, perform a power cycle on your device.
LEDs represent the current state of the application:
- LED 1:
Application
Connected
successfully.
- LED 2:
Application
Registered
successfully.
- LED 3:
Application
time sync
is successful.
- LED 4:
Application
link
is up.
Other states are routed to generic GPIO pins. When the voltage drops to 0, entering low logic state, it means that one of the following states is active:
- P1.1:
DFU
state.
- P1.2:
ERROR
has occured.
- P1.3:
Sending
pin is active when the packet is being transmitted.
- P1.4:
The
Received
pin is toggledon
and immediatelyoff
when the packet has been received.
- P1.2:
DFU
state.
- P1.3:
The
Received
pin is toggledon
and immediatelyoff
when the packet has been received.
- P1.4:
Sending
pin is active when the packet is being transmitted.
- P1.8:
ERROR
has occured.
Configuration¶
When running the sample, you can use different configurations files depending on the supported features.
Build types¶
Configuration files are provided for different build types and are located in the application root directory.
The prj.conf
file represents a debug
build type.
Other build types are covered by dedicated files with the respective build type added to the file name.
For example, the release
build type file is named prj_release.conf
.
The same naming convention is followed if a board has other configuration files that are, for example, associated with the partition layout or child image configuration.
Before you start testing the application, you can select one of the build types supported by the sample. Depending on the selected board, a sample supports the following build types:
debug
– Debug version of the application - can be used to enable additional features, such as logs or command-line shell, to verify the application behavior.release
– Release version of the application - can be used to enable only the necessary application functionalities to optimize its performance.
You can build the release
firmware for build_target
by running the following command in the project directory:
$ west build -b build_target -- -DCONF_FILE=prj_release.conf
For example:
$ west build -b nrf52840dk_nrf52840 -- -DCONF_FILE=prj_release.conf
Note
Selecting a build type is optional.
However, if the build type is not selected, the debug
build type is used by default.
Configuration files¶
For this sample, you can use the following overlays:
fsk.conf
- This configuration enables the FSK transport in the Sidewalk application. To enable this overlay, you have to connect the Semtech SX1262MB2CAS Arduino Shield.cli
- This configuration adds an nRF Connect Shell with Sidewalk Command Line Interface.
Bootloader and Device Firmware Update (DFU)¶
MCUboot is configured to have two banks of memory for an application.
For more information on bootloaders and delivery options for the updated images, see Bootloader and DFU solutions for NCS.
Memory layout¶
The following table presents how the memory is allocated for the Template sub-GHz sample:
external_flash (0x00000000 - 0x007fffff): +-------------------------------------------------------+ | 0x00000000 - 0x000eefff: mcuboot_secondary (956kB) | | 0x000ef000 - 0x007fffff: external_flash (7.07MB) | +-------------------------------------------------------+ flash_primary (0x00000000 - 0x000fffff): +-------------------------------------------------------+ | 0x00000000 - 0x00006fff: mcuboot (28kB) | +---mcuboot_primary (480kB)-----------------------------+ | 0x00007000 - 0x000071ff: mcuboot_pad (512B) | | 0x00072000 - 0x000f5fff: mcuboot_primary_app (955.5kB)| +-------------------------------------------------------+ | 0x000f6000 - 0x000f7fff: settings_storage (8kB) | | 0x000f8000 - 0x000fefff: sidewalk_storage (28kB) | | 0x000ff000 - 0x000fffff: mfg_storage (4kB) | +-------------------------------------------------------+ sram_primary (0x20000000 - 0x2003ffff): +-------------------------------------------------------+ | 0x20000000 - 0x2003ffff: sram_primary (256kB) | +-------------------------------------------------------+
DFU services¶
To test the Device Firmware Update, follow the Testing Device Firmware Update (DFU) subsection in Testing.
If a new, correct image is found, the bootloader can only start the application that is placed in the first partition and exchange the application from the second partition. It may take a few seconds.
Building and running¶
This sample can be found under samples/template_subghz
.
Note
Before you flash you Sidewalk sample, make sure you completed the following:
You downloaded the Sidewalk repository and updated west according to the Downloading the Sidewalk repository section.
You provisioned your device during the Setting up your Sidewalk product.
This step needs to be completed only once. You do not have to repeat it on every sample rebuild.
To build the sample, follow the steps in the Building and programming an application documentation. If you want to select a specific build type instead of a default one, see Selecting a build type
Selecting a build type¶
Before you start testing the application, you can select one of the available build types.
To select the build type when building the application from command line, specify it by adding one of the following parameters to the west build
command:
Build with the default configuration (LoRa link mode):
$ west build -b build_target
Build with the FSK link mode:
$ west build -b build_target -- -DOVERLAY_CONFIG="fsk.conf"
Build with the release configuration:
$ west build -b build_target -- -DCONF_FILE=prj_release.conf
Build with the debug configuration with application CLI:
$ west build -b build_target -DCONFIG_SIDEWALK_CLI=y
Testing¶
See Testing and debugging an application for information on testing and debugging in the nRF Connect SDK.
After successfully building the sample and flashing manufacturing data, the sample is ready to use. To refresh the logs, restart the program by pressing the RESET button on your development kit. You should see the following output:
*** Booting Zephyr OS build v3.2.99-ncs2 *** ---------------------------------------------------------------- sidewalk v1.14.3-1-g1232aabb nrf v2.3.0 zephyr v3.2.99-ncs2 ---------------------------------------------------------------- sidewalk_fork_point = af5d608303eb03465f35e369ef22ad6c02564ac6 build time = 2023-03-14 15:00:00.000000+00:00 ---------------------------------------------------------------- [00:00:00.006,225] <inf> sid_template: Sidewalk example started!
Wait for the device to complete the Automatic Touchless Registration using Sidewalk FFN.
Note
If you have multiple Echo devices registered under a single Amazon account, only one of those devices will be able to operate as an FSK gateway even if other devices have the same capability. If you need to operate multiple FSK gateways, we recommend setting them up under separate Amazon accounts.
Starting Sidewalk¶
To start Sidewalk, do the following:
Connect your Nordic device to the PC through USB. Set the power switch on the device to ON.
Flash the sample application with the manufacturing data as described in the Building and running section of the respective sample.
You should see the following logs:
*** Booting Zephyr OS build v3.2.99-ncs2 *** ---------------------------------------------------------------- sidewalk v1.14.3-1-g1232aabb nrf v2.3.0 zephyr v3.2.99-ncs2 ---------------------------------------------------------------- sidewalk_fork_point = af5d608303eb03465f35e369ef22ad6c02564ac6 build time = 2023-03-14 15:00:00.000000+00:00 ---------------------------------------------------------------- [00:00:00.006,225] <inf> sid_template: Sidewalk example started!
Wait for the device to register, or perform registration manually as described in the Registering Sidewalk Endpoint documentation.
You should see the following logs:
[00:00:31.045,471] <inf> sid_thread: Device Is registered, Time Sync Fail, Link status Up
When Sidewalk registration status changes, LED 2 turns on.
Wait for the device to complete time sync with the Sidewalk network.
You should see the following logs:
[00:00:35.827,789] <inf> sid_thread: status changed: ready [00:00:35.827,850] <inf> sid_thread: Device Is registered, Time Sync Success, Link status Up
When Sidewalk gets Time Sync, LED 3 turns on.
Perform a button action.
For a Bluetooth LE device, you need to send a connection request before sending a message. Press Button 2 to set the request.
[00:44:42.347,747] <inf> sid_thread: Set connection request
Sidewalk automatically disconnects Bluetooth LE after some inactivity period. You have to repeat the button action.
For a LoRa and FSK device, no action is needed.
Wait for status change. The following messages appear in the log:
[00:45:31.597,564] <inf> sid_thread: status changed: init [00:45:31.597,564] <dbg> sid_thread: on_sidewalk_status_changed: Device Is registered, Time Sync Success, Link status Up
When Sidewalk Link Status is Up, LED 4 turns on.
Sending message to AWS MQTT¶
You can use AWS IoT MQTT client to view the received and republished messages from the device. Follow the outlined steps:
Enter
#
and click Subscribe to topic. You are now subscribed to the republished device messages.To see the data republished into the subscribed MQTT topic, press Button 3 on your development kit.
# Logs from DK after pressing "Button 3" [00:04:57.461,029] <inf> sid_template: Pressed button 3 [00:04:57.461,120] <inf> sid_thread: sending counter update: 0 [00:04:57.461,456] <inf> sid_thread: queued data message id:3 # Logs from MQTT test client { "MessageId": "4c5dadb3-2762-40fa-9763-8a432c023eb5", "WirelessDeviceId": "5153dd3a-c78f-4e9e-9d8c-3d84fabb8911", "PayloadData": "MDA=", "WirelessMetadata": { "Sidewalk": { "CmdExStatus": "COMMAND_EXEC_STATUS_UNSPECIFIED", "MessageType": "CUSTOM_COMMAND_ID_NOTIFY", "NackExStatus": [], "Seq": 2, "SidewalkId": "BFFFFFFFFF" } }
Payload data is presented in base64 format. You can decode it using Python:
python -c "import sys,base64;print(base64.b64decode(sys.argv[1].encode('utf-8')).decode('utf-8'))" MDA= 00
Data is republished into the subscribed MQTT topic.
Receiving message from AWS MQTT¶
To be able to use AWS CLI, ensure you completed steps in the Installing or updating the latest version of the AWS CLI documentation.
Run the following command to send a message to your Sidewalk Endpoint:
aws iotwireless send-data-to-wireless-device --id=<wireless-device-id> --transmit-mode 0 --payload-data="<payload-data>" --wireless-metadata "Sidewalk={Seq=<sequence-number>}"
<wireless-device-id>
is the Wireless Device ID of your Sidewalk Device.You can find it in the
WirelessDevice.json
file, generated with theNordic_MFG.hex
file during Setting up your Sidewalk product.You can also find your Wireless Device ID in the message sent form the device to AWS, it you have sent it before.
<payload-data>
is base64 encoded.To prepare a message payload in the base64 format, run:
python -c "import sys,base64;print(base64.b64encode(sys.argv[1].encode('utf-8')).decode('utf-8'))" "Hello Sidewalk!" SGVsbG8gICBTaWRld2FsayE=
<sequence-number>
is an integer and should be different for each subsequent request.Note
Ensure to increase ‘Seq’ number on every message. The device will not receive a message with lower or equal sequence number.
Once you have populated the command with data, it should look similar to the following:
aws iotwireless send-data-to-wireless-device --id=5153dd3a-c78f-4e9e-9d8c-3d84fabb8911 --transmit-mode 0 --payload-data="SGVsbG8gICBTaWRld2FsayE=" --wireless-metadata "Sidewalk={Seq=1}"
Successfully sent response should look as follows:
{ "MessageId": "eabea2c7-a818-4680-8421-7a5fa322460e" }
In case you run into the following error, ensure your IAM user or role has permissions to send data to your wireless device:
{ "Message": "User: arn:aws:iam::[AWS Account ID]:user/console_user is not authorized to perform: iotwireless:SendDataToWirelessDevice on resource: arn:aws:iotwireless:us-east-1:[AWS Account ID]: WirelessDevice/[Wireless Device ID]" }
Data will be received in Sidewalk logs:
[00:06:56.338,134] <inf> sid_thread: Message data: 48 65 6c 6c 6f 20 20 20 53 69 64 65 77 61 6c 6b |Hello Sidewalk 21 |!
Testing Device Firmware Update (DFU)¶
To enter the DFU mode, long press Button 4 on your development kit. This action restarts the device in the DFU mode, in which only the Zephyr SMP Server is running and Sidewalk is not operational. When the application is in the DFU mode, all LEDs flash every 500 ms to signal that the application is waiting for a new image.
To perform a firmware update, follow the Bluetooth testing steps from the DevZone DFU guide. When the update starts, the LEDs change the pattern to indicate upload in progress.
To exit the DFU mode, reset your device. The device will restart in the Sidewalk mode. If the update completes successfully, the device will start a new image. After using the DFU mode, the first bootup might take up to 60 seconds. During the image swap the application is silent, meaning that LEDs are not blinking and the console does not output any logs. The application, however, is running, so do not reset the device. In case the update fails, the old image is started instead.
Testing Power Profiles¶
Power profiles are available for sub-GHz radio communication, such as LoRa or FSK. For more information about Sidewalk Power Profiles, refer to the Sidewalk Protocol Specification.
The following profiles are available in the template application:
Name |
Power consumption |
Messages may be lost |
LoRa profile |
FSK profile |
---|---|---|---|---|
Light |
Lower |
Yes |
A |
1 |
Fast |
Higher |
No |
B |
2 |
To test the power profiles, complete the following steps:
Build and flash the template application with the LoRa or FSK link mask.
*** Booting Zephyr OS build v3.2.99-ncs2 *** ---------------------------------------------------------------- sidewalk v1.14.3-1-g1232aabb nrf v2.3.0 zephyr v3.2.99-ncs2 ---------------------------------------------------------------- sidewalk_fork_point = af5d608303eb03465f35e369ef22ad6c02564ac6 build time = 2023-03-14 15:00:00.000000+00:00 ---------------------------------------------------------------- [00:00:00.063,476] <inf> sid_thread: Initializing sidewalk, built-in LoRa link mask
Wait a few seconds until device establishes the connection with Gateway. You should see the following output:
[00:00:15.017,425] <inf> sid_thread: Device Is registered, Time Sync Success, Link status Up [00:00:15.017,486] <inf> sid_thread: Link mode cloud, on lora
Get the current profile by short pressing Button 2.
[00:00:35.433,441] <inf> button: button pressed 2 long [00:00:35.433,654] <inf> sid_thread: Profile id 0x81 [00:00:35.433,654] <inf> sid_thread: Profile dl count 0 [00:00:35.433,685] <inf> sid_thread: Profile dl interval 5000 [00:00:35.433,685] <inf> sid_thread: Profile wakeup 0
Switch between the light and fast profile by long pressing Button 2.
[00:00:29.375,732] <inf> button: button pressed 2 short [00:00:29.375,854] <inf> sid_thread: Profile set fast [00:00:29.375,976] <inf> sid_thread: Profile set success.
Application CLI¶
The Sidewalk application can be build with the CLI support to help with testing and debugging.
Enabling and verifying Sidewalk command-line interface (CLI)¶
To enable CLI, add the
CONFIG_SIDEWALK_CLI=y
option to one of the following places:Menuconfig
Build command
prj.conf
file
To verify Sidewalk CLI, open the UART shell of the device on the default speed 115200.
Once you see a prompt
uart:~$
, type thesidewalk help
command to see the avaliable commands.Currently there are 6 commands avaliable:
sidewalk press_button {1,2,3,4}
- Simulates button press.sidewalk set_response_id <id>
- Set ID of a next send message with type response. It can be used for remote development or for test automation.sidewalk send <hex payload> <type [0-3]>
- Sends message to AWS. Type id: 0 - get, 1 - set, 2 - notify, 3 - response. The payload has to be a hex string without any prefix and the number of characters has to be even.sidewalk report [--oneline] get state of the application
- Presents a report in JSON format with the internal state of the application.sidewalk version [--oneline] print version of sidewalk and its components
- Presents a report in JSON format with versions of components that build the Sidewalk application.sidewalk factory_reset perform factory reset of Sidewalk application
- Performs factory reset.
See the example report output:
uart:~sidewalk report
"SIDEWALK_CLI": {
"state": "invalid",
"registered": 1,
"time_synced": 1,
"link_up": 0,
"link_modes": {
"ble": 0,
"fsk": 0,
"lora": 0
},
"tx_successfull": 4,
"tx_failed": 0,
"rx_successfull": 0
}
See the example version output:
uart:~sidewalk version
"COMPONENTS_VERSION": {
"sidewalk_fork_point": "ab13e49adea9edd4456fa7d8271c8840949fde70",
"modules": {
"sidewalk": "v1.12.1-57-gab13e49-dirty",
"nrf": "v2.0.0-734-g3904875f6",
"zephyr": "v3.0.99-ncs1-4913-gf7b0616202"
}
}
Note
By default, only core components are printed.
To show versions of all components, set CONFIG_SIDEWALK_GENERATE_VERSION_MINIMAL
to n
in prj.conf
file or in the menuconfig.