Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

Sigfox SDK Demo User's 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 CC112x SIGFOX Demo application. 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.

Getting Started

Get a SIGFOX Device ID with Temporary Access

Send an email to: tech-p1-team@sigfox.com to request the activation-code extraction firmware. 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 binary file called TI_SIGFOX_activation_code_application.txt. Follow the instructions in Section 1.2.

Hardware Options

The hardware is slightly different for the Americas and Europe.


To make a development kit for the Americas, order one of each of the following:

MSP430F5529 LaunchPad™ – http://www.ti.com/tool/msp-exp430f5529lp

CC1120 CC1190 BoosterPack™ – http://www.ti.com/tool/TIDC-SIGFOX-CC1120-CC1190-BP


To make a development kit for Europe, order one of each of the following:

MSP430F5529 LaunchPad – http://www.ti.com/tool/msp-exp430f5529lp

CC1125 BoosterPack– http://www.ti.com/tool/boostxl-cc1125


To make a development kit for Japan, order one of each of the following:

MSP430F5529 LaunchPad – http://www.ti.com/tool/msp-exp430f5529lp

CC1125 BoosterPack– http://www.ti.com/tool/boostxl-cc1125

Setup

Hardware

  • LaunchPad + BoosterPack for FCC
LaunchPad + BoosterPack
   - The USB port on the MSP430F5529 LaunchPad must be used to download and debug the code. This port can also be used for AT command interface over UART.
   - The jumper P7 on the BoosterPack must be connected between pin 2 and 3 to power up the BoosterPack from LaunchPad's power source.
   - PA/LNA control jumpers must be connected as shown above.


  • LaunchPad + BoosterPack for ETSI/ARIB
LaunchPad + BoosterPack


Extract Activation ID from LaunchPad

Download the image that reads the activation code from the LaunchPad and BoosterPack combo. The file is called TI_SIGFOX_activation_code_application.txt and is provided by SIGFOX as described in Section 1.1. Then, flash the file to the LaunchPad. Each activation code is specific for a specific region of the world, which is why it is important to provide the location information to SIGFOX in the initial request.

The two ways to flash the LaunchPad follow. Flashing can be done using the SmartRF Flash programmer (http://www.ti.com/tool/flash-programmer, version 1 only). Rename the .txt file to a .hex file, and flash it using the SmartRF Flash programmer, as shown below.


SmartRF Flash Programmer Configuration Page Settings

The alternative way to flash is by using the MSP430™ Flasher application.

1. Download and install the application from http://www.ti.com/tool/msp430-flasher.

2. Using the command prompt, execute the following commands from the correct folder.

> MSP430Flasher -w “.\TI_SIGFOX_activation_code_FCC.txt” -v -g -z [VCC]

3. If using a Linux® computer, set the path for the executable before executing the flash command.

> export LD_LIBRARY_PATH=~/MSP430Flasher_1.3.7/

4. Connect to the LaunchPad using a terminal program.

5. Download and install your favorite terminal program. We have tested Coolterm (http://freeware.the- meiers.org/) and TeraTerm (http://logmett.com/tera-term-the-latest-version).

6. Identify the UART port number using the device manager, as shown in Figure 1-4.

UART Port Number


7. Set up the serial port that is identified by MSP Application UART1

UART Serial Port Setup.jpg



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

UART Terminal Setup

9. Once the terminal set up is complete, connect the LaunchPad to the PC using the USB connector. The BoosterPack remains unconnected to PC.

10. Once the connection with the device is established, press ENTER. Then, the following message should appear: !!! Launchpad and Boosterpack boards must be fit together!!! Press Enter to get your device's numbers:

11. Press ENTER again to retrieve the 20-digit activation code in this format: 6BAE144709AA12004823.

12. If the HEX identifies that you are trying to extract an ID from an incorrect combination of devices it returns: “Not a VALID Board for TI-SIGFOX project”. In this case, check the hardware setup and try again.

13. Send a second email to: tech-p1-team@sigfox.com to request access to the full project by supplying the activation code that was extracted from the hardware. SIGFOX responds to the request by creating a unique development project that has been targeted for the unique MSP430 and CC112x device combination. This process can take up to 24 hours.

14. If not already installed, then install Code Composer 6, by visiting :http://processors.wiki.ti.com/index.php/Category:Code_Composer_Studio_v6. The installation must be Version 6.1.0.00104 or later, and ensure to select the MSP Ultra Low Power MCUs option for processor support.


CCS Project

Open the TI_SIGFOX_project into the CCS application; this is a MSP430 application using the radio on the BoosterPack. Compile the project, load it onto the LaunchPad, and run it. Once the project is running, the device is ready to send and receive packets to the SIGFOX network. The device is expected to be within range of a SIGFOX base station. The device accepts instructions from the user using AT commands. Below figure shows the Code Composer build and download buttons.

Code Composer Build and Download Buttons.png

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                -    9600 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 "MSP430 Application UART".

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$SF=<ul_data>,1<CR> OK<CR>
+RX=<dl_data><CR>
+RX END<CR>
This command sends a 12 byte frame in uplink and requests a downlink message.
<ul_data> is 0 to 12 byte long uplink message in HEX.
<dl_data> is 8 byte long downlink message in HEX.
CMD :
AT$SF=5464737420fD657373616765,1

RE :
OK
+RX=559319880000FF92
+RX END
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$SB=<status_val>,1<CR> OK<CR>
+RX=<dl_data><CR>
+RX END<CR>
This command sends a 1-bit status in uplink and requests a downlink message.
<status_val> is the bit status (0 or 1).
<dl_data> is 8 byte long downlink message in HEX.
CMD :
AT$SB=0,1

RE :
OK
+RX=559319880000FF9C
+RX END
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$SR=<seq_num>,<ch>,<rxtout><CR> RX=<msgN><CR>
RSSI=<rssi_valN><CR>
This command is used for RX test mode.
<seq_num>: downlink message sequence number.
<ch>: channel for downlink message. 0 to 480.
<rxtout>: number seconds for RX time window. Automatically time out RX after this. for X count
<msgX>: 8 bytes of downlink data. (1)
<rssi_valX>: rssi value
CMD :
AT$SR=1,1,60

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.