Sigfox CC1310 SDK Demo Users Guide

From Texas Instruments Wiki
Jump to: navigation, search

Introduction

This user's guide is intended to help users set up and get started with the CC1310 SIGFOX Demo application. This is a Sigfox Tx only solution. Rx is not supported for CC1310. This document explains how to acquire the hardware and software for the development kit. It also contains instructions on how to get the kit to communicate with the SIGFOX network. Currently only ARIB and ETSI are supported. Support for other regions is currently under development.


Getting Started

Hardware

A CC1310 LaunchPad can be ordered here

http://www.ti.com/tool/launchxl-cc1310

  • CC1310 LaunchPad
LaunchPad

NOTE : Please note to use Launchpads with CC1310 part PG 2.1 and later. We have noticed that performance on PG 2.0 part is not compliant with Sigfox specification.

To check the PG version, one can use the SmartRF Flash Programmer 2 by clicking on the connected device.


Software

The procedure to obtain working software for a board is a twostep process

1. Obtaining the Code composer studio project from Sigox

2. Obtaining an encrypted “sigfox_data.h” file from Texas Instruments that is merged into this project

Obtaining the Project from Sigfox

Send an email to: tech-p1-team@sigfox.com requesting for a CC1310 launch-pad solution. For this initial request, SIGFOX requires the following information:

  • Full legal company name
  • First and last name of employee being granted access to the SIGFOX network
  • Country and state, or region where development work will occur
  • Country or countries of target product deployment

SIGFOX responds with a Code Composer Studio project.

Users can install Code Composer Studio from here http://processors.wiki.ti.com/index.php/Download_CCS

During installation make sure to select “Simple Link Wireless MCUs” when prompted for Processor support selection.

Users will also need TI-RTOS that can be downloaded from here http://www.ti.com/tool/ti-rtos-mcu A version of 2.20.0.06 or later is required.

Once installed launch Code Composer Studio and Open the project by choosing Project, import CCS project.

Sigfox CCS Project



Obtaining the sigfox_data.h file from Texas Instruments

To be able to communicate with a Sigfox base station “sigfox_data.h” file is required that is unique to each launchPad. The MAC address on the launchPad is used by Texas Instruments to generate this file.

Below is the procedure to obtain the MAC address of the CC1310 LaunchPad and receive a “sigfox_data.h” file.

1. Install SmartRF Flash Programmer-2 from http://www.ti.com/tool/flash-programmer
2. Connect the CC1310 LaunchPad to the PC using USB.
3. Launch the SmartRF Flash Programmer-2
4. Select the CC1310 under the “Connected devices” list as shown in Figure 1.3
5. Click on “MAC Address” tab
6. Click “Read” button. This will read a unique 8 byte hex MAC address.
7. Email the MAC address to sigfox@list.ti.com along with the below information

  • Full legal company name
  • First and last name of employee being granted access

8. Once the MAC address is sent to TI, user should receive an email with sigfox_data.h file that can be integrated into the CCS project as shown in below Figure

CC1310 MAC Address


Building and running the CCS project

Integrate the sigfox_data.h file into the CCS project. Now you can build, download and run the project using the CCS buttons listed in above figure showing the CCS project.

Below describes how to interface with the device using the serial port.


CC1310 MAC Address


  • Set up the serial port identified by XDX110 Class Application/User UART with baudrate of 115200 as shown below.


SerialPortSetup1


  • Enable local echo on the terminal to see the characters that are typed on the terminal.


SerialPortSetup2


  • Once the serial port is configured, select “Connect” to connect to the LaunchPad.

Now you are ready to issue “AT” Commands to interfacing with the CC1310 Launchpad. Please refer to the AT commands described in chapter 3. Before that user needs to create an account on the Sigfox backend and register the device that is ready to communicate with the basestation.


Please note that the CC1310 currently only supports TX. RX is still under development. This means that any references to the RX in this document are not functional yet


SIGFOX Backend

What is Backend?

SIGFOX backend is a web portal that gives users access to manage devices and data on the SIGFOX Network. Users can log in to the backend to add and access their devices. https://backend.sigfox.com/


Adding a User Device to Backend

The device ID and PAC number are required to add a device to the backend. This information can be obtained using AT commands through the terminal. Press ENTER after every command.

To obtain the device ID, type command: AT$ID?

To obtain the device PAC, type command: AT$PAC?


To add a device to the backend, login to the SIGFOX backend, click on Device, and then click New, in the top right corner of the browser. Now add the new device by filling out the form. Below figure shows how to add a new device to the SIGFOX backend.

Add New Device to SIGFOX Backend.jpg

Communicating With the SIGFOX Base Station

Data can be sent and received from the closest SIGFOX base station using AT commands. To send one bit of data, use command AT$SB=0/1. To send a frame of data, use command AT$SF=<payload data>. Payload data is a hexadecimal number with even bytes. Example: 123abc.


Once the command is issued, a packet is transmitted three times at three different frequencies, to increase the chances of reception. Below figure shows the spectrum at the base station.

Spectrum at the Base Station.jpg


NOTE: After flashing or resetting any device connected to the SIGFOX network, users must press Disengage Sequence Number button, on the Device or Device Type page, in the SIGFOX backend. The sequence number is a security measure, which prevents device spoofing by verifying that an incremental sequence number is generated by the device each time it transmits to the network. This number is reset each time the device is flashed. Without disengaging the sequence number on the backend, no messages can be received.


Retrieving Messages from the Base Station

1. Click on the Device tab.

2. Select your Device ID.

3. Select the Messages button.


Below figure shows examples of messages on the base station.

Messages on the Base Station.jpg


Sending Bidirectional Messages

Using AT$SB or AT$SF with a second argument set to 1 initiates a bidirectional message. The response from the base station is printed on the terminal. Below image shows the bidirectional message.

Bidirectional Message.jpg


Creating Device Type

Creating a device type in the backend lets users to group a set of devices, and manage the base station as desired. To add a new device type, perform the following steps.

1. Click the Device Type tab.

2. Click the New button in the top right corner.

3. Choose the group, and fill out the form that appears

New Device Type Setup.jpg

Associate a Device to a Device Type

To associate the device to a device type, perform the following steps.

1. Click on the Device tab.

2. Click on the ID of the device.

3. Click the Edit button, and select the device type from the drop-down list, then click the OK button.

Add a Device to a Device Type.jpg


Changing the Downlink Message

Once the device is associated with a device type, users can modify the downlink message for a device type. Perform the following steps.

1. Click on the Device Type tab.

2. Select the device type.

3. Click the Edit button in the top right corner.

4. Modify the downlink data in hexa to change the downlink message.

5. Send a bidirectional message using the command AT$SF=<payload data>,1. Below image shows the field where downlink data can be modified.

Downlink Data.jpg

Below images shows the modified downlink received data.

Downlink Received Data.jpg

Adding Custom Callbacks

Users can create a callback for a device type. A callback defines how the base station should respond to devices from a device type. Callbacks are triggered when a new device message is received, or device communication loss is detected. A set of available variables are replaced by their value when a callback is called. More information can be found here: https://backend.sigfox.com/apidocs/callback.


To add a new callback, perform the following steps.

1. Click the Device Type tab.

2. Select the Device type.

3. Click the Callbacks button.

4. Click the New button.

5. Click the Custom Callbacks button.


Below image shows adding a callback that sends out an email when an uplink message is received from a device.

Add a Callback for a Device Type.jpg



AT Commands

ATtention (AT) commands are instructions used to control a modem. Every command starts with AT, and is case sensitive. Below image lists the structure of the AT commands.

AT Command Structure.png



AT$ commands

Use the following serial link parameters in CoolTerm or similar terminal program to configure the COM port.

  Baud Rate                -    115200 bps
  Parity                   -    None
  Data Bits                -    8
  Stop Bits                -    1
  Flow Control             -    None
  Local Echo (Optional)    -    Yes

Make sure the hardware is connected to the PC via a USB port. Connect to the COM port listed as "XDS110 Class Application/User UART(COM??)".

After successfully establishing the serial link with the MSP430, you can use various AT commands to interface with the Demo module. Following table has some of the most frequently used AT commands.
User can type in the AT command in the COM port. After executing the task related to that command, the demo module will send a response to the COM port. Each command and its response are terminated with carriage return <CR>(0x0D).

AT command
"CMD"
Response
"RE"
Description Example
AT$ID?<CR> <dev_id><CR> This command prints the device's ID in response.
<dev_id> is devices ID number in HEX.
CMD :
AT$ID?

RE :
AABBCCDD
AT$PAC?<CR> <pac><CR> This command prints the device's PAC number in response.
<pac> is devices PAC number in HEX.
CMD :
AT$PAC?

RE :
1234567890ABCDEF
AT$IF?<CR> <ul_freq><CR> This command prints the up-link frequency in response.
<ul_freq> is up-link frequency in Hz.
CMD :
AT$IF?

RE :
902000000
AT$IF=<ul_freq><CR> OK<CR> This command sets the up-link frequency.
<ul_freq> is up-link frequency in Hz.
CMD :
AT$IF=<ul_freq>

RE :
OK
AT$DR?<CR> <dl_freq><CR> This command prints the down-link frequency in response.
<dl_freq> is down-link frequency in Hz.
CMD :
AT$DR?

RE :
902000000
AT$DR=<dl_freq><CR> OK<CR> This command sets the down-link frequency.
<dl_freq> is down-link frequency in Hz.
CMD :
AT$DR=<dl_freq>

RE :
OK
AT$SF=<ul_data><CR> OK<CR> This command sends a 12 byte frame in uplink only mode.
<ul_data> is 0 to 12 byte long uplink message in HEX.
CMD :
AT$SF=313233343536373839404142

RE :
OK
AT$SB=<status_val><CR> OK<CR> This command sends a 1-bit status in uplink only mode.
<status_val> is the bit status (0 or 1).
CMD :
AT$SB=1

RE :
OK
AT$ST=<count>,<ch><CR> OK<CR> This command is used for TX test mode.
<count> number of random 12-byte messages to send in test mode. 0 to 32767, or –1 for infinite packet TX.
<ch>: channel for uplink. 0 to 480 or –1 for channel hopping.
CMD :
AT$ST=1,1

RE :
OK
AT$CW=<freq>,<mode><CR>> OK<CR> This command sets the device in CW mode.
<freq> is frequency for CW in Hz.
<mode>: 1 to start CW mode and 0 to stop CW mode
CMD :
AT$CW=902000000,1

RE :
OK

A full list of the AT commands supported in the SDK can be found in the documentation of the demo software.