BOOSTXL-CC1125

CC112x TI-SIGFOX SDK Demo Getting Started Guide Literature Number: SWRU487 June 2016 Chapter 1 SWRU487 – June 2016 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. 1.1 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. 1.2 Get the Hardware 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 LaunchPad, BoosterPack, MSP430 are trademarks of Texas Instruments. Linux is a registered trademark of Linus Torvalds. 2 Introduction SWRU487 – June 2016 Submit Documentation Feedback Copyright © 2016, Texas Instruments Incorporated Setup the Hardware www.ti.com 1.3 Setup the Hardware To assemble the kits for either FCC or ETSI/ARIB, simply connect the BoosterPack to the LaunchPad as shown in Figure 1-1 and Figure 1-2. Figure 1-1. LaunchPad and BoosterPack Assemble for FCC SIGFOX Applications SWRU487 – June 2016 Submit Documentation Feedback Introduction Copyright © 2016, Texas Instruments Incorporated 3 Extract Activation ID from LaunchPad www.ti.com Figure 1-2. LaunchPad and BoosterPack Board Settings for ETSI/ARIB SIGFOX Applications 1.4 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 in Figure 1-3. 4 Introduction SWRU487 – June 2016 Submit Documentation Feedback Copyright © 2016, Texas Instruments Incorporated Extract Activation ID from LaunchPad www.ti.com Figure 1-3. 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.themeiers.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. Figure 1-4. Identifying Applications UART Port Number 7. Set up the serial port that is identified by MSP Application UART1 (see Figure 1-5). SWRU487 – June 2016 Submit Documentation Feedback Introduction Copyright © 2016, Texas Instruments Incorporated 5 Extract Activation ID from LaunchPad www.ti.com Figure 1-5. UART Serial Port Setup 8. Enable local echo on the terminal to see the characters that are typed on the terminal (see Figure 1-6). Figure 1-6. 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 going to this link. 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. 6 Introduction SWRU487 – June 2016 Submit Documentation Feedback Copyright © 2016, Texas Instruments Incorporated CCS Project www.ti.com 1.5 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. Figure 1-7 shows the Code Composer build and download buttons. Figure 1-7. Code Composer Build and Download Buttons SWRU487 – June 2016 Submit Documentation Feedback Introduction Copyright © 2016, Texas Instruments Incorporated 7 Chapter 2 SWRU487 – June 2016 SIGFOX Backend 2.1 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/. 2.2 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. Figure 2-1 shows how to add a new device to the SIGFOX backend. Figure 2-1. Add New Device to SIGFOX Backend 8 SIGFOX Backend SWRU487 – June 2016 Submit Documentation Feedback Copyright © 2016, Texas Instruments Incorporated Communicating With the SIGFOX Base Station www.ti.com 2.3 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 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. Figure 2-2 shows the spectrum at the base station. Figure 2-2. Spectrum at the Base Station 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. 2.4 Retrieving Messages From the Base Station To 1. 2. 3. check the message received at the base station from your device, perform the following steps. Click on the Device tab. Select your Device ID. Select the Messages button. Figure 2-3 shows examples of messages on the base station. SWRU487 – June 2016 Submit Documentation Feedback SIGFOX Backend Copyright © 2016, Texas Instruments Incorporated 9 Sending Bidirectional Messages www.ti.com Figure 2-3. Messages on the Base Station 2.5 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. Figure 2-4 shows the bidirectional message. Figure 2-4. Bidirectional Message 2.6 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 (see Figure 2-5). 10 SIGFOX Backend SWRU487 – June 2016 Submit Documentation Feedback Copyright © 2016, Texas Instruments Incorporated Associate a Device to a Device Type www.ti.com Figure 2-5. New Device Type Setup 2.7 Associate a Device to a Device Type To 1. 2. 3. associate the device to a device type, perform the following steps. Click on the Device tab. Click on the ID of the device. Click the Edit button, and select the device type from the drop-down list, then click OK (see Figure 26). SWRU487 – June 2016 Submit Documentation Feedback SIGFOX Backend Copyright © 2016, Texas Instruments Incorporated 11 Changing the Downlink Message www.ti.com Figure 2-6. Add a Device to a Device Type 2.8 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=,1. Figure 2-7 shows the field where downlink data can be modified. Figure 2-7. Downlink Data Figure 2-8 shows the modified downlink received data. 12 SIGFOX Backend SWRU487 – June 2016 Submit Documentation Feedback Copyright © 2016, Texas Instruments Incorporated Adding Custom Callbacks www.ti.com Figure 2-8. Downlink Received Data 2.9 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 1. 2. 3. 4. 5. add a new callback, perform the following steps. Click the Device Type tab. Select the Device type. Click the Callbacks button. Click the New button. Click the Custom Callbacks button. Figure 2-9 shows adding a callback that sends out an email when an uplink message is received from a device. Figure 2-9. Add a Callback for a Device Type SWRU487 – June 2016 Submit Documentation Feedback SIGFOX Backend Copyright © 2016, Texas Instruments Incorporated 13 Chapter 3 SWRU487 – June 2016 AT Commands ATtention (AT) commands are instructions used to control a modem. Every command starts with AT, and is case sensitive. Figure 3-1 lists the structure of the AT commands. Figure 3-1. AT Command Structure Table 3-1 lists the available AT commands and their usage. Table 3-1. List of AT Commands Task Command and Response Parameter Description Send bit status CMD: AT$SB= : status value 1/0 : 8 bytes of downlink message RESP: OK Send bit status with downlink request (1) CMD: AT$SB=,1 RESP: OK +RX= +RX END Send payload (in bytes) CMD: AT$SF= RESP: OK Send payload with downlink request CMD: AT$SF=,1 : 0 to 12 bytes of uplink message (1) : 8 bytes of downlink message (1) RESP: OK +RX= +RX END Get device id CMD: AT$ID? : device ID RESP: (1) 14 ASCII coded HEX value AT Commands SWRU487 – June 2016 Submit Documentation Feedback Copyright © 2016, Texas Instruments Incorporated www.ti.com Table 3-1. List of AT Commands (continued) Task Command and Response Parameter Description Get uplink frequency CMD: AT$IF? : central uplink frequency (Hz) RESP: Set uplink frequency (2) CMD: AT$IF= RESP: OK Get downlink frequency CMD: AT$DR? : central downlink frequency (Hz) RESP: Set downlink frequency (2) CMD: AT$DR= RESP: OK TX test mode (3) RX test mode (3) CMD: AT$ST=, : number of random 12-byte messages to send in test mode. 0 to 32767, or –1 for infinite packet TX. : channel for uplink. 0 to 480 or –1 for channel hopping RESP: OK , (4) CMD: AT$SR=,, RESP: RX= RSSI= … RX= RSSI= TX continuous wave mode (2) (3) (4) (3) : downlink message sequence number. : channel for downlink message. 0 to 480. : number seconds for RX time window. Automatically time out RX after this. for X count, : 8 bytes of downlink data. (1) : rssi value CMD: AT$CW=, : frequency for CW mode (Hz) RESP: OK : 1 to start CW mode and 0 to stop CW mode If the uplink or downlink frequency value is not set to the correct value, use this function to set the correct frequency value. Test mode function. A special tool is required to emulate a downlink message from a base station. Each AT command and response is terminated with a carriage return . All the commands are case sensitive. There are no spaces between the characters or fields of these commands. SWRU487 – June 2016 Submit Documentation Feedback AT Commands Copyright © 2016, Texas Instruments Incorporated 15 Chapter 4 SWRU487 – June 2016 Acronyms • • • • • • • • • • • • • 16 ADMIN - Administrator CCS - Code Composer Studio CMD - Command CR - Carriage Return (0x0D) HEX - Hexadecimal Value LNA - Low-Noise Amplifier OOB - Out of Band PA - Power Amplifier RESP - Response RX - Receive TCXO - Temperature Controlled crystal (XTAL) Oscillator TX - Transmit XTAL - Crystal Oscillator Acronyms SWRU487 – June 2016 Submit Documentation Feedback Copyright © 2016, Texas Instruments Incorporated IMPORTANT NOTICE Texas Instruments Incorporated and its subsidiaries (TI) reserve the right to make corrections, enhancements, improvements and other changes to its semiconductor products and services per JESD46, latest issue, and to discontinue any product or service per JESD48, latest issue. Buyers should obtain the latest relevant information before placing orders and should verify that such information is current and complete. All semiconductor products (also referred to herein as “components”) are sold subject to TI’s terms and conditions of sale supplied at the time of order acknowledgment. TI warrants performance of its components to the specifications applicable at the time of sale, in accordance with the warranty in TI’s terms and conditions of sale of semiconductor products. Testing and other quality control techniques are used to the extent TI deems necessary to support this warranty. Except where mandated by applicable law, testing of all parameters of each component is not necessarily performed. TI assumes no liability for applications assistance or the design of Buyers’ products. Buyers are responsible for their products and applications using TI components. To minimize the risks associated with Buyers’ products and applications, Buyers should provide adequate design and operating safeguards. TI does not warrant or represent that any license, either express or implied, is granted under any patent right, copyright, mask work right, or other intellectual property right relating to any combination, machine, or process in which TI components or services are used. Information published by TI regarding third-party products or services does not constitute a license to use such products or services or a warranty or endorsement thereof. Use of such information may require a license from a third party under the patents or other intellectual property of the third party, or a license from TI under the patents or other intellectual property of TI. Reproduction of significant portions of TI information in TI data books or data sheets is permissible only if reproduction is without alteration and is accompanied by all associated warranties, conditions, limitations, and notices. TI is not responsible or liable for such altered documentation. Information of third parties may be subject to additional restrictions. Resale of TI components or services with statements different from or beyond the parameters stated by TI for that component or service voids all express and any implied warranties for the associated TI component or service and is an unfair and deceptive business practice. TI is not responsible or liable for any such statements. Buyer acknowledges and agrees that it is solely responsible for compliance with all legal, regulatory and safety-related requirements concerning its products, and any use of TI components in its applications, notwithstanding any applications-related information or support that may be provided by TI. Buyer represents and agrees that it has all the necessary expertise to create and implement safeguards which anticipate dangerous consequences of failures, monitor failures and their consequences, lessen the likelihood of failures that might cause harm and take appropriate remedial actions. Buyer will fully indemnify TI and its representatives against any damages arising out of the use of any TI components in safety-critical applications. In some cases, TI components may be promoted specifically to facilitate safety-related applications. With such components, TI’s goal is to help enable customers to design and create their own end-product solutions that meet applicable functional safety standards and requirements. Nonetheless, such components are subject to these terms. No TI components are authorized for use in FDA Class III (or similar life-critical medical equipment) unless authorized officers of the parties have executed a special agreement specifically governing such use. Only those TI components which TI has specifically designated as military grade or “enhanced plastic” are designed and intended for use in military/aerospace applications or environments. Buyer acknowledges and agrees that any military or aerospace use of TI components which have not been so designated is solely at the Buyer's risk, and that Buyer is solely responsible for compliance with all legal and regulatory requirements in connection with such use. TI has specifically designated certain components as meeting ISO/TS16949 requirements, mainly for automotive use. In any case of use of non-designated products, TI will not be responsible for any failure to meet ISO/TS16949. Products Applications Audio www.ti.com/audio Automotive and Transportation www.ti.com/automotive Amplifiers amplifier.ti.com Communications and Telecom www.ti.com/communications Data Converters dataconverter.ti.com Computers and Peripherals www.ti.com/computers DLP® Products www.dlp.com Consumer Electronics www.ti.com/consumer-apps DSP dsp.ti.com Energy and Lighting www.ti.com/energy Clocks and Timers www.ti.com/clocks Industrial www.ti.com/industrial Interface interface.ti.com Medical www.ti.com/medical Logic logic.ti.com Security www.ti.com/security Power Mgmt power.ti.com Space, Avionics and Defense www.ti.com/space-avionics-defense Microcontrollers microcontroller.ti.com Video and Imaging www.ti.com/video RFID www.ti-rfid.com OMAP Applications Processors www.ti.com/omap TI E2E Community e2e.ti.com Wireless Connectivity www.ti.com/wirelessconnectivity Mailing Address: Texas Instruments, Post Office Box 655303, Dallas, Texas 75265 Copyright © 2016, Texas Instruments Incorporated