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	nrf52840dk_nrf52840	nrf52840dk_nrf52840
nRF5340 DK	PCA10095	nrf5340dk_nrf5340	nrf5340dk_nrf5340_cpuapp

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
SX1262	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:

nRF52840nRF5340

• 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 toggled on and immediately off when the packet has been received.

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:

1. Connect your Nordic device to the PC through USB. Set the power switch on the device to ON.

2. 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!
   

3. 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.

4. 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.

5. Perform a button action.

   1. 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.

   2. For a LoRa and FSK device, no action is needed.

6. 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:

1. Enter # and click Subscribe to topic. You are now subscribed to the republished device messages.

2. 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

1. To be able to use AWS CLI, ensure you completed steps in the Installing or updating the latest version of the AWS CLI documentation.

2. 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 the Nordic_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)

1. 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.

2. 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.

3. 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:

1. 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
   

2. 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
   

3. 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
   

4. 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)

1. To enable CLI, add the CONFIG_SIDEWALK_CLI=y option to one of the following places:

   • Menuconfig

   • Build command

   • prj.conf file

2. To verify Sidewalk CLI, open the UART shell of the device on the default speed 115200.

3. Once you see a prompt uart:~$, type the sidewalk 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.