Get a Microchip ATSAMR34 Xplained Pro evaluation kit

The ATSAMR34 Xplained Pro evaluation kit is a hardware platform used to evaluate the ATSAMR34 Low Power LoRa® Sub-GHz SiP. It is supported by Atmel Studio 7.0 IDE and a collection of sample codes are available from Advanced Software Framework (ASFv3) since the 3.44.0 release.

The Xplained Pro MCU series evaluation kit includes an on-board Embedded Debugger (EDBG), and no external tools are necessary to program or debug the ATSAMR34.

The kit offers a set of features that enable you to get started with the ATSAMR34 Low Power LoRa® Sub-GHz SiP peripherals right away, and to understand how to integrate the device in your own design.

Details of the kit are available here: https://www.microchip.com/DevelopmentTools/ProductDetails/dm320111

The ATSAMR34 Xplained Pro kit contains the following items:

• One ATSAMR34 Xplained Pro
• One external antenna
  

Collect the Device EUI unique identifier

A LoRaWAN device has a 64-bit unique identifier (DevEUI) that is assigned to the device by the chip manufacturer. This DevEUI key is required for processing an Over The Air Activation (OTAA) to a LoRaWAN Network.

The Microchip ATSAMR34 Xplained Pro evaluation kit comes with DevEUI onboard. This unique key is stored in the EDBG chip and printed on a sticker putted on the back of the board.

Flip the board and collect the MAC value, which will be used later when provisioning the ATSAMR34 Xplained Pro kit in TTN Console.

Note: On Software side, the Microchip LoRaWAN Stack gives you the flexibility to use the DevEUI key flashed by Microchip or either to use your own DevEUI key.

Setting up a TTN account and Application

Here, you will get familiar to The Things Network interface. First, you will create your own account. Then you will create a unique Application and Add your new device that will allow you to connect the ATSAMR34 Xplained Pro evaluation kit.

Step 1. Create a TTN account

1. Go to https://account.thethingsnetwork.org/users/login
2. Click on "Create an account"
3. Enter a unique "USERNAME". You will not be able to change it after and it must be unique within TTN.
4. Enter your email address and a password.
5. Click "Create account".
6. You will receive an email to validate your account. You do NOT need to activate your account immediately. It is available for 1 week without activation.
7. Verify/Update Account information. While logged in, click on “account” on the top right corner and edit your information if desired.

Step 2. Create a LoRaWAN Application

1. Click on the "Console" link.
2. Click on the "APPLICATIONS" icon.
3. Click on the "Get started by adding one!" link.
   A form will appear to add application.
4. Fill the Application ID and Description boxes.
   Note: For Application ID, the identifier must be unique with The Things network. If you choose a name like "myfirstapp", most certainly someone else would have chosen the same name and it will fail.
5. For "Handle registration", select the appropriate handle according to your location.
   (e.g.: ttn-handler-eu if your are in Europe).
6. Then, click "Add Application".
7. You should now be presented with a summary page of your application.
   

Note the following:
Application ID, unique identifier to be used by apps that access your data via the MQTT data API.
Application EUI (AppEUI), needs to be embedded into your ATSAMR34 node before joining the network.
Access Keys: also required by apps that access your data via the MQTT data API.

Step 3. Register a LoRaWAN Device

1. Add your ATSAMR34 Xplained Pro device by clicking the "register device" link on the summary page.
   A "Register Device" form should appear.
2. Enter information for the Device ID and Device EUI boxes.
   For Device ID, enter a unique readable name. This name must be unique within your application.
   For Device EUI, enter the 8-byte DevEUI recorded from the ATSAMR34 Xplained Pro evaluation kit's sticker.
   For App Key, let TTN generates this key.
   
3. Click "Register".
   You should see an information box with status "never seen". Later you will activate the device.

Step 4. Collect the OTAA Credentials

From the EDBG chip integrated in the ATSAMR34 Xplained Pro Evaluation Kit, you've got the DevEUI.

From the TTN account, you've got the AppEUI and AppKey.

Note: in addition, you are in possession of credentials, Application ID and Access Key, you can embed into application (like Node-RED) to access the device data via the TTN MQTT data interface.

Record the AppEUI and AppKey in C-style/msb format. Later on, you will need to paste those data to the ATSAMR34 end-device demo application.

<o:p></o:p>

Register a Gateway on TTN

These instructions will help you to register your own gateway onto TTN.
For this purpose, we focus on The Things Gateway (https://www.thethingsnetwork.org/docs/gateways/gateway/).
You can also refer to the video instructions “How to: Activate The Things network Gateway within 5 min” (https://youtu.be/cJNK4y1is2Q?t=45s).

1. To activate your gateway, go to https://activate.thethingsnetwork.org/login.
2. Make sure you are already logged-in, then click on "Let's Get Started!".
   A form will appear to register your gateway.
3. Start by entering a unique identifier of your gateway in the "Gateway ID" field.
4. Select the appropriate Frequency Plan from the drop-down menu. This is based on the region in which the gateway is operating.
5. Leave the "Auto update gateway" box checked to enable further update.
6. Click "Register Gateway".
7. Then to move further, you will be connecting to the WiFi access point of the gateway.
   From your PC, select the WiFi access point named "Things Gateway - xxx" and connect to it.
8. Once you are connected to the gateway's WiFi, the "Continue" button will turn blue and you can click on it to move to the next step.
9. Then you must select how you want your gateway to be connected to the Internet.
   In case you select WiFi, enter the SSID of the network in the field followed by the security mode, the password and click on "Configure Gateway".
10. This will send the settings to the gateway and in the next few moments you will see the page with the status of the gateway. It takes from 30 seconds to 2 mins to get the configuration settings in place.
    The activation page will indicate what the LED's lights on the gateway indicate.
11. Your browser will refresh the page to switch back to your WiFi configuration and if everything done correctly you will see the first message being sent through your gateway.
12. Once the gateway is configured you can manage the rest of the settings through the console and add other details such as location, altitude, placement, etc. It is recommended to remove the SSID of the gateway from your PC by going to Manage Wireless Network as it will ensure your PC does not try to connect again to the Gateway.
13. You should see your gateway in the "Gateway Overview" page.
    
    
    

Note: Go to https://www.thethingsnetwork.org/map to view your registered gateway on a map.

Software Installation

Here the list of software used in this tutorial.

Atmel Studio 7.0

1. Download and install Atmel Studio 7.0 IDE.
   https://www.microchip.com/mplab/avr-support/atmel-studio-7
2. Open Atmel Studio 7.0 IDE.
3. Then, you need Advanced Software Framework (ASFv3) installed as an extension to Atmel Studio.
   From the menu, go to Tools -> Extensions and Updates ... and install Advanced Software Framework (>= 3.45.0 release).
4. Once the installation is complete, you must restart Atmel Studio.

Note: ASFv3 is an MCU software library providing a large collection of embedded software for AVR® and SAM flash MCUs and Wireless devices. ASFv3 is configured by the ASF Wizard in Atmel Studio 7.0 (installed as an extension to Studio). ASFv3 is also available as a standalone (.zip) with the same content as Studio extension (https://www.microchip.com/mplab/avr-support/advanced-software-framework). 

Important:
Until the next Atmel Studio IDE release, you have to manually install the Device Part Pack for developing with SAMR34/R35 on Atmel Studio 7.0 IDE.
(all products released in between IDE releases of Atmel Studio should be manually added by user to develop applications).

• Go to Tools -> Device Pack Manager
• Check for Updates
• Search for SAMR34 and click install
• Repeat the same for SAMR35
• Restart Atmel Studio 7.0 IDE
  
  

Tera Term

Download and install the serial terminal program from: https://osdn.net/projects/ttssh2/releases/

Node-RED

1. Download and install Node.js v8.11.1 using the Windows Installer from the following URL:
   https://nodejs.org/dist/v8.11.1/node-v8.11.1-x64.msi
   Node.js is required to run Node-RED
   
   
2. Install Git Client for Windows v2.18.0
   A Windows Git client is required for the nodejs “npm” package manager to install Node-RED nodes which use Git repositories. These instructions will have you install a Windows Git client and ensure its executable is in the System “Path” variable.
    Download and run the 64-bit Git for Windows installer from:
   https://git-scm.com/download/win
   Ensure that Git is installed in your computers PATH variable.
   Go to Start->Control Panel->System
   Select “Advanced system settings”
   Select “Environment Variables”
   Under System Variables, select “Path” then “Edit”:
   Verify the Git client path is appended to the Path variable (“C:\Program Files\Git\cmd”)
   
   
3. Install Node-RED using Node’s Package Manager, npm
   Open a Windows Administrator Command Prompt (Start Menu -> All Programs -> Accessories -> Command Prompt (Right-click) -> Run as Administrator).
   In the CMD prompt, go to the nodejs installation directory (“C:\Program Files\nodejs”)
   Run the following command: npm install -g --unsafe-perm node-red
   Reboot Windows.
   
   
4. Install Node-RED Dashboard Module
   This module provides a set of nodes in Node-RED to quickly create a live data dashboard:
   https://flows.nodered.org/node/node-red-dashboard
   After rebooting Windows, open an Administrator CMD prompt again.
   In the CMD prompt, we want to run Node-RED once to have it create the “.node-red” sub-directory needed for the following steps.
   Run the following command: node-red
   In the CMD prompt, press Ctrl-C to end the Node-RED process. You may need to type “Y” to confirm that you want to end the process.
   In the CMD prompt, go to your Node-RED directory (“C:\Users\<UserName>\.node-red”)
   Install the Node-RED Dashboard with the following command: npm install node-red-dashboard
   For further information on this package, visit: https://flows.nodered.org/node/node-red-dashboard
   
   
5. Install Node-RED TTN Module
   The Things Network (TTN) Nodes Module for Node-RED is used to receive device events and messages as well as send messages to devices: https://flows.nodered.org/node/node-red-contrib-ttn
   Still using the Administrator CMD prompt, navigate to the user Node-RED directory ( “C:\Users\<UserName>\.node-red”)
   Install the Node-RED TTN modules with the following command: npm install node-red-contrib-ttn
   For further information on this package, visit:
   
   https://flows.nodered.org/node/node-red-contrib-ttn
   https://github.com/TheThingsNetwork/nodered-app-node
   https://www.thethingsnetwork.org/docs/applications/nodered/quick-start.html
   
   

Hardware Installation

In order to connect, you will need to be in range of your gateway. If you don't have a gateway, check the world map (https://www.thethingsnetwork.org/map) to see if your local community has gateway deployed around your location.

To prepare the interaction with the ATSAMR34 Xplained Pro board, follow the steps below:

1. Plug the antenna and always make sure you have the antenna plugged to your board before powering it up.
2. Connect your board to the PC through the micro-USB cable.
   USB cable must be connected to the EDBG USB connector of the ATSAMR34 kit.
3. Wait for USB driver installation and COM port mounting.
   The USB port powers the board and enables the user to communicate with the kit.
4. Launch Tera Term program and configure the serial port mounted with: 115200 bps 8N1.

LoRaWAN Mote Application

The ASFv3 installer for the Microchip LoRaWAN stack is an extension to Atmel Studio which provides a solution for the LoRaWAN end-device in ATSAMR34 devices. This extension allows a user to plug and play the ATSAMR34 drivers or sensor modules from ASF into Microchip LoRaWAN stack and create easily demonstrable solutions.

Step 1. Generate the Application

Perform the following steps in Atmel Studio 7.0 to generate the LoRaWAN Mote Application.

1. Open Atmel Studio IDE.
2. Select from the top menu: File -> New -> Example Project
3. In the "New Example Project from ASF or the Extensions" window:
   => Select SAMR34 as Device Family.
   => From the project list, select the LoRaWAN Mote Application.
   => Give a name to the project or let the default name (avoid long file name).
   => Select a location of the project. The path of the project should be short as possible.
   => Click "Ok".
   
   
   
   
4. Select the "Accept the License Agreement" check box and then click Finish.
5. Atmel Studio generates the project files for the selected application example that can be used with the ATSAMR34 Xplained Pro board.
   
   
   
6. You can build the firmware with the default settings from the menu: Build -> Build Solution.
7. After the successful compilation and linking, firmware is displayed in the Output Files section of Solution Explorer.
   
   

Now, you are ready to modify the settings of the application to connect your end-device to TTN.

Set your regional band

Microchip LoRaWAN Stack supports multiple regional bands according to the LoRaWAN regional parameters defined by the LoRa® Alliance for different regulatory regions worldwide. By default, all the regions are enabled in the project. To disable certain regions, perform the following steps.

1. Select the project from the "Solution Explorer" panel.
   
   
2. From the top bar menu, go to: Project -> Properties (Alt+F7).
3. From the left-hand pane, select Toolchain.
4. In the right-hand pane, go to: "ARM/GNU C Compiler -> Symbols".
   The regional band macros are listed in the "Defined Symbols" pane.
   * AS_BAND=1 (Asia)
   * AU_BAND=1 (Australia)
   * EU_BAND=1 (Europe)
   * IND_BAND=1 (India)
   * JPN_BAND=1 (Japan)
   * KR_BAND (Korea)
   * NA_BAND=1 (North America)
   
   
5. Runtime support for the regional bands is enabled when the macro for the corresponding regional band is set to 1. And runtime support for the regional band is disabled when the macro is set to 0. 
   
   For example, the following are the macro values to enable only European region:
   * AS_BAND=0 (Asia: Brunei, Cambodia, Indonesia, Laos, New Zealand, Singapore, Taiwan, Thailand, Vietnam)
   * AU_BAND=0 (Australia)
   * EU_BAND=1 (Europe 868 MHz)
   * IND_BAND=0 (India)
   * JPN_BAND=0 (Japan)
   * KR_BAND=0 (Korea)
   * NA_BAND=0 (North America)

Note: The release notes of the Microchip LoRaWAN Stack contain the list of supported regional bands.

More details are available on the SAMR34/35 MLS Getting Starting Guide document:
https://www.microchip.com/design-centers/wireless-connectivity/low-power-wide-area-networks/lora-technology/sam-r34-r35

Gateways usually support only 8+1 channels and a set of 8+1 channels is called as SUBBAND. The NA/AU Regional band has 64+8 channels. Therefore there are eight SUBBAND's in the case of NA/AU region. The application by default is configured to work in SUBBAND 1.

Change the SUBBAND value according to the gateway/Nertwork Server configuration. If the gateway supports 64+8 channels then the SUBBAND definition must be commented. For example, TTN recommends SUBBAND 2 to be used within their network.

In case you need to change the SUBBAND setting, perform the following steps:

1. From the "Solution Explorer" pane, expand the /src/config folders.
   
2. Open the conf_app.h file.
   
   
   The file contains the possible configuration related to the LoRaWAN Mote Application.
   
   
3. By default, the macro is defined as: #define SUBBAND 1
4. As TTN recommends SUBBAND 2 to be used within their network, above macro should be changed to: #define SUBBAND 2

Configure LoRaWAN Activation Parameters

To activate your ATSAMR34 Xplained Pro board on TTN, you will be using the OTAA activation procedure. The OTAA method requires the following parameters to be embedded into the LoRaWAN Mote Application:

• AppEUI : Copy/Paste from your TTN Account
• AppKey: Copy/Paste from your TTN Account
• DevEUI: Serialized (Embedded) in the EDBG chip of the ATMSAMR34 Xplained Pro evaluation kit

Notes: from the TTN Console, copy to clipboard the AppEUI and AppKey in C-style and msb format.

The LoRaWAN Mote Application you have generated from ASFv3, provides configurable parameters such as OTAA credentials in conf_app.h file. This file is available at <your project folder>/src/config.

To provision your device, perform the following steps:

1. From the "Solution Explorer" pane, expand the /src/config folders.
   
2. Open the conf_app.h file.
   
   
   The file contains the possible configuration related to the LoRaWAN Mote Application.
   
   
3. Modify the values of the DEMO_APPLICATION_EUI and DEMO_APPLICATION_KEY macros with the AppEUI and AppKey you've collected from the TTN account.
   
   

Note: By default, the LoRaWAN Mote Application uses the embedded DevEUI from the EDBG chip. You can use your own DevEUI by changing the value of the EDBG_EUI_READ macro located in the symbols definition and in conf_board.h file. Make sure the DevEUI is the same on both side: end-device and network server.

conf_board.h file:

/* TODO: If Board is having EDBG with DEV_EUI flashed in
Userpage Enable this Macro otherwise make it as 0 */
#define EDBG_EUI_READ      1

Symbols definition window:

Building the Firmware

Perform the following steps in Atmel Studio 7.0 to build the firmware for the LoRaMote Demo Application.

1. From the menu, go to: Build -> Build Solution
2. After the successful compilation and linking, firmware is displayed in the Output Files section of Solution Explorer.
   
   
   

Flashing the Firmware

Perform the following steps to Flash the firmware on ATSAMR34 Xplained Pro.

1. After successfully building the firmware, connect the ATSAMR34 Xplained Pro kit to the PC through the USB cable. Atmel Studio detects the board after completing the driver installation.
2. Go to Debug -> Start without Debugging (Ctrl+Alt+F5)
   
   
   

Running the Demo application

The LoRaWAN Mote Application you have generated from ASFv3 is used to send the temperature sensor data through the LoRaWAN protocol to the network server. It uses UART serial interface with 115200 bps 8N1 configuration and the UART is used to display the menu options. The user input is provided through keyboard.

1. Open Tera Term program with 115200 bps 8N1 configuration.
2. On the ATSAMR34 Xplained Pro board, press the RESET button (near the EDBG USB connector).
   The application will start and on Tera Term the menu is displayed. From here, you can interact with the LoRaWAN Mote Application demo.
3. From the first menu, select the Demo application.
   
   
   
4. From the second menu and according to your regional band configuration, select the appropriate band.
   
   
   
5. Then, the end-device will automatically try to join the network using the OTAA parameters you have modified previously in the code. You should observe a successful join message otherwise double check the OTAA keys on both side (end-device and TTN) and send a Join Request from the menu.
   
   
   
6. From the third menu displayed, select "Send Data".
   
   
   The end-device will transmit uplink message which contains the temperature in Celsius and in Fahrenheit formats.
   
   Now it is time to verify the activation of your end device in the TTN Server to confirm the status of your device and to interact with the device via TTN Console.
   
   
7. In the TTN Console, navigate to the "Device Overview" page by clicking on Applications then select the application you have created, followed by clicking on the Devices sub-menu and selecting the Device you have created previously.
   
   
   
8. Scroll-down and observe the status of your device. You should see an "active" (GREEN) status along with a frame counter:
   
   
9. Click on the "Data" tab to see your board's uplink payload data being received on TTN.
   
   
   
   
   
   The payload is displayed in HEX format and corresponds to the temperature values in Celsius and in Fahrenheit formats.
   
   32 39 2E 32 43    =>    29.2C
   2F                                =>    /
   38 34 2E 36 46    => 84.6F
   
   

b.     

Deploy Payload Decoder function in TTN

You can deploy a small JavaScript code snippet in your TTN application that will decode the byte array payload received by TTN into a more usable format.

1. In TTN Console, navigate to Application -> <Your Application> -> Payload Formats
   
   
   
   
2. Type or Copy/Paste the JavaScript code below into the "decoder" editor window shown below:
   
   

function Decoder(bytes, port) {
    var result = {tempC: "", tempF: ""};
    result.tempC = String.fromCharCode(bytes[0], bytes[1], bytes[2], bytes[3]);
    result.tempF = String.fromCharCode(bytes[6], bytes[7], bytes[8], bytes[9]);
    return result; 
}

You can test the function by entering the (hex) test bytes 32 39 2E 32 43 2F 38 34 2E 36 46 into the "Payload" window and pressing "Test" button.

A successful result is indicated by the correct JSON being generated.

When finished, save/apply the function by pressing "save payload functions" button.

And now, when you go back to the Data view of your device, you should see decoded JavaScript objects being generated for each new uplink message. These are accessible by external applications.

Generate Downlink Packets from TTN

The TTN Console allows you to schedule/send downlink packets to your device. For the current tutorial, the ATSAMR34 Xplained Pro has been configured as a Class -A device. In this case, the device open up two listening windows after sending an uplink message in order to check for downlink messages from the network server.

1. In TTN Console, navigate to the Device Overview page.
2. Scroll-down to the Downlink fields. This is where you may enter/schedule a downlink payload.
   
   
   Notes:
   Payload is a hex byte-array field that will be sent.
   FPort is the Application Port Number.
   Downlink transmissions can also be Confirmed.
   
   
3. Complete the field as show below to send an unconfirmed downlink message (to FPort 1):
   
   
   
4. Press “Send” to schedule the downlink.
5. Go back to Tera Term program and from the menu, send the temperature data. The downlink message is received and processed after sending the uplink packet. You should observe the message received in hex format.
   
   Message received at device level:
   
   
   Message flow at Network Server:
   
   
   
   
   
   
   

Simple Node-RED Application

To go further, you may create a Node-RED application that displays temperature data coming from your ATSAMR34 Xplained Pro board through the TTN server.

To start, let’s wire up a simple flow that get uplink message from TTN, extract the Celsius and Fahrenheit temperature values with the help of a function node and plots the data on a simple chart.

 <o:p></o:p>