GW16122 - Mini-PCIe Radio for Internet of Things - IoT

Software Disclaimer: This hardware was designed from a Texas Instruments Reference design. Thus, all All software support is community supported through Texas Instruments.

Getting Started

Gateworks recommends the following setup for getting started and development:

• Gateworks ​Ventana or Newport Single Board Computer
  • Gateworks SBC loaded with Ubuntu operating system
• Gateworks GW16122 IoT Card
• Gateworks GW10124 900Mhz Antenna
• Gateworks GW10074 MMCX to SMA Female Adapter Cable
• ​Ti Sensor Tag - Gateworks SBC and GW16122 are the 'collector'. This Sensor tag becomes the 'sensor' for development.

• The firmware pre-installed on the GW16122 is built from the source code here:

/usr/src/ti/simplelink_cc13x0_sdk_1_40_00_10/examples/rtos/CC1350_LAUNCHXL/ti154stack/coprocessor

Steps to Getting Started:

1. Connect GW16122 to Gateworks SBC
2. Connect antenna to GW16122
3. Install Ubuntu for Gateworks SBC
4. Install Ti 15.4 Stack on Gateworks board

General Information

Features Include:

• Texas Instruments ​CC1350 MCU
• Open Source 802.15.4g
• Lowest Power
• Sub 1GHz
  • 5.4 mA Radio RX current
  • 13.4 mA Radio TX @ +10 dBm
  • 24.4 mA Radio TX @ +14 dBm
• Longest Range
  • Excellent Receiver Sensitivity –124 dBm Using Long-Range Mode, –110 dBm at 50 kbps (Sub-1 GHz), –87 dBm at Bluetooth low energy
  • Programmable Output Power up to +14 dBm (Sub-1 GHz) and +9 dBm at 2.4 GHz (Bluetooth low energy)
• Small form factor (7x7mm chip size)
• Low Bandwidth applications - Sensor Data, etc
• Minimal interference - Narrow Bandwidth
• Can perform Sigfox TX if required, no RX

This features two RF Channels:

• Sub 1GHz (USA 915MHz) - Used for long distance communication
• Bluetooth 4.2 Low Energy (2.4GHz) - Used for programming sensor nodes

Texas Instruments Reference Design

For more information see the ​TI ​CC1350 Product Page.

RF Network / Infrastructure

The GW16122 / CC1350 operates on its own network. It does not rely on towers/networks installed by 3rd party companies (LoRa, Sigfox, Verizon, AT&T, etc). The entire network infrastructure is under control by the user. This includes sensors/nodes, collector(s), antennas and more.

Network Architecture

The default is a star-based topology system where there is one central collector (The GW16122 on a Gateworks SBC) that listens to all the sensors / nodes that are around it.

Sensor Limits

Number of connected users:

• Support for 50 nodes in network is for the MAC-CoProcessor configuration, where the network employs full MAC level security (AES-128).

The Security table can take up all available RAM considering 500 bytes packets so some trade off are possible if the max packet size that must be supported by the application is smaller and the network size can go bigger (probably not reach 1K nodes). The network can scale up to much more nodes if for instance the security is removed at MAC level and deployed at application level (the code is hosted on Linux). The actual network size would be in that case more limited by the traffic profile (ie how frequently data is exchanged).

Glossary

• BLE - Bluetooth Low Engery
• BLE-ADV - Bluetooth Low Energy Advertising
• OAD - Over the Air Download
• 802.15.4 - IEEE standard defining the operation of low-rate wireless personal area networks (LR-WPANs). Definition includes the physical layer and media access control. Can be used with 6LoWPAN. The IEEE 802.15.4 standard is used as a data-link layer of many popular networking standards deployed in the market (6LoWPAN, Wi-SUN, ZigBee®, Thread and WHART). It guarantees a solid wireless foundation thanks to features like air arbitration (through CSMA-CA), acknowledgments and retransmissions and built-in AES security.
  • Frequency: North America: 902–928 MHz, up to 30 channels
• RTOS - Real Time Operating System
• 6LoWPAN - Low Power Personal Area Network, allowing for IPv6 packets.
• LRM - Long Range Mode
• PA/LNA - Power amplifier (PA) for increased output power, and a low-noise amplifier (LNA) with low noise figure for improved receiver sensitivity. This can be used with the ​Ti CC1190 RF Booster / Front End
• BLE Modes - advertising, scanning, master, slave. Read more ​here
• TI-RTOS - TI-RTOS kernel is a tailored version of the legacy SYS/BIOS kernel and operates as a real-time, preemptive, multi-threaded operating system with drivers, tools for synchronization and scheduling.
• TI-15.4 Stack - The TI 15.4-Stack is a software development kit (SDK) running on the SimpleLink™ Sub-1 GHz CC1310 wireless microcontroller (MCU). Based on the proven IEEE 802.15.4 standard, it implements the 'g' amendment of the specification for operations in North America and Europe in the Sub-1 GHz band (regulated respectively by FCC and ETSI).
• LPWAN - Low‑Power Wide‑Area
• Contiki - Open Source Operating System

GW16122 Development

Much of the following information is taken from TI documentation which is licensed under ​​CC BY NC ND 4.0. This wiki page aims to get users up and runnning with the GW16122 by collating relevant information contained by aforementioned TI sources along with our own annotations.

The subsequent sections detail the information collected by Gateworks related to development with the GW16122. The GW16122 constitutes the following embedded systems:

• TiVa TM4C1294NCPDT MCU - Primarily used to program the CC1350; converts USB signals to UART
• CC1350 MCU - The main MCU responsible for taking sensor readings

A pre-made sensor node is provided by Texas Instruments:

​* ​Simplelink CC1350 SensorTag Bluetooth and Sub-1GHz Long Range Wireless Further information on the TI MCU's and tools utilized in GW16122 development can by found on the ​TI Wiki.

Set Up

The following sections detail the steps necessary to set up a development environment for the GW16122. It is assumed that you already have a general understanding of Gateworks products and linux based OS operations.

Host Tools

Development can be done on either a Windows or Linux x86 based machine. Various references to Mac OS exist for some tools but were untested by Gateworks. You will need to create a TI account through their ​registration page before downloading some of the software listed here. After creating an account you will still need to sign an agreement on each download indicating its intended use.

1. JTAG USB dongle firmware for serial access and programming of Gateworks SBC (​Direct download link)
2. Remote terminal program, e.g. ​PuTTY for serial connection to Gateworks SBC
3. ​Code Composer Studio which is an IDE maintained by TI with preinstalled tools and libraries for software development on TI MCU's (​Direct download link)
   • Don't forget to run the post install script ccsv7/install_scripts/install_drivers.sh
   • The executable for the IDE is located at ccsv7/eclipse/ccstudio
4. ​Simple Link CC13X0 SDK from TI's site is available on multiple platforms and contains prebuilt firmware images, example software, and documentation for working with the CC1350
5. ​SmartRF Flash Programmer for quickly installing prebuilt firmware without code composer studio and especially useful for quickly programming sensor nodes using a GUI (Windows only)

OR

​Uniflash Programmer which is a linux compatible alternative that includes both a GUI and command line interfaces

Some quick commands for installing Uniflash properly on an Ubuntu system:

# Get the installer (software version subject to change)
wget --no-check-certificate http://software-dl.ti.com/ccs/esd/uniflash/uniflash_sl.4.2.1490.run
# Link udev library for installer error
sudo ln -sf /lib/x86_64-linux-gnu/libudev.so.1 /lib/x86_64-linux-gnu/libudev.so.0
# Run gui installer
chmod +x uniflash_*.run
./uniflash_*.run

Gateworks SBC Tools

The mechanism controlling the GW16122 will be a Gateworks SBC (testing was done with a GW5404-E.2). The Gateworks Ubuntu image is recommended and the instructions will use Ubuntu specific commands.

Some of the TI example projects make use of the Node.js framework in order to create a web interface to control what is referred to as the "collector" which in our case is the GW16122.

Once Ubuntu has been installed and a network connection has been established, complete the following steps to finish initial target configuration:

1. Install necessary packages

   # Always update your package manager information
   apt-get update
   apt-get upgrade
   # Install packages for GW16122 development
   apt-get install -y build-essential nodejs
   

2. Acquire and install TI's 15.4 BLE stack source files from the ​SDK available online
   1. Since TI apparently only offers the SDK installer in the form of an x86 binary (ventana CPU is arm architecture), you will need to download the installer on a compatible linux machine, run it, and repackage the files for transfer

      # ON SEPARATE x86 CPU LINUX MACHINE:
      # enable execute permissions on binary downloaded from above link, your file name may be different
      chmod +x ti15.4stack_linux_x64_2_02_00_03.run
      # run the installer
      ./ti15.4stack_linux_x64_2_02_00_03.run
      # package the install files from target directory
      tar -czvf ti15-4.tar.gz ti/
      

   2. Transfer and extract the sdk files to your Gateworks SBC filesystem using your method of choice

      # pull installation file from host pc (networked method)
      wget http://remotehost/path/to/ti15-4.tar.gz
      # extract the files
      tar xzvf ./ti15-4.tar.gz
      

Software

A quick breakdown of the software running on each piece of hardware in an example network utilizing the GW16122:

• Gateworks SBC
  • Ubuntu Xenial Gateworks Image
  • node-js (if using web interface)
  • serial program (if using serial api)
• GW16122 Mini-PCIe Card
  • TiVa TM4C1294NCPDT MCU
    • boot_loader.bin - TI boot loader firmware
    • firmware.bin - XDS110 emulation firmware binary
  • CC1350 MCU
    • Co-Processor firmware (.out/.hex) - Either a prebuilt TI example or custom firmware designed with CCS

The following subsections detail the various software layers developed by TI for use with the CC1350 which is the main MCU in the GW16122 as well as Code Composer Studio and other general notes.

TI-RTOS RF driver

The RF core has a dedicated driver called the TI-RTOS RF driver, which is used for all interaction with the RF core. If you do not wish to use the EasyLink abstraction layer, there is also the option to do simple packet RX/TX using the TI-RTOS RF driver directly.

A reference for the example lab located in the TI resource center, see ​SimpleLink Academy lab Proprietary RF - Basic RX and TX.

For more information, see the ​CC13X0 Proprietary RF User's Guide.

EasyLink API

EasyLink is a simple abstraction layer on top of the RF Driver and is intended as a starting point for customers creating a proprietary Sub1-GHz protocol or application.

For more information see the ​EasyLink wiki page.

TI 15.4-Stack

On the other hand, if you wish to create a full stack-based network solution, consider using the TI 15.4-Stack, available as part of the CC13x0 SDK.

The example lab documentation to get started can be found at the ​TI 15.4-Stack Project Zero page.

Further documentation can be found in the ​TI 15.4 User's Guide.

Texas Instruments Code Composer Studio

Code Composer Studio (CCS) is an IDE based on Eclipse and includes various libraries and software packages required to develop on many TI MCU's, including the CC1350 which is the primary component of the GW16122.

Below are some various notes on using CCS. See the ​Getting Started wiki and the ​Main CCS wiki for more information.

Resource Center

Click Menu item View -> Resource Explorer Expand software and view SimpleLink CC13x0 SDK as well as Ti-RTOS for CC2650 Drill down to the area you would like to explore Find an example, then click the download button to download to desktop Then click the import to IDE to import the project

Building a Project

Once the project is imported, right click on the project title in the explorer window and click 'Build Project' and let it compile. You can also click the debug button to build the project and run it on the connected target. Once it is complete, a binaries folder will be created under the project. Most TI tools will use the .out file that is produced there to program with.

Alternatively you can build projects via command line and avoid the entire IDE if you so desire. See the official TI wiki on ​Command Line Build/Create for more information.

A couple of additional notes when building via command line:

Note that the executable for Linux CCS installations is named "eclipse" and not "eclipsec" Run with "-ccs.help" to see full list of options Use full path names for all command line arguments (environment variables useful here)

Serial Command API

The serial command API for the CC1350 is implemented in the form of standard AT+ commands that correlate to EasyLink API functions. This serial control method there has an example project provided by the TI resource center. The web page can be found ​here.

You can easily test the AT to Easylink api commands by using two GW16122/SensorTag devices running the rfEasyLinkNp and the rfEasyLinkRx examples.

Serial Format

Parameters offer set and get functionality.

• The format of a parameter read command to get the TxPower parameter is:

   “ATP00?”
  

• The response to a read will be of the format shown below, depending on the parameter it will be hex or decimal:

   “-10”
  

• The format of an AT command to set the Frequency Parameter to 868MHz is:

   “ATPFR=868000000”
  

• The response of a write will be of the format:

  OK<CR>
  

The response to the "rx" "RX" (receive) command is of the format:

• For ASCII Data Mode:

  RX: Hello World<CR>
  OK<CR>
  For Binary Data Mode:
  RX: 2fbb1aa8ec84045fb0c3e5236cb8cc5b3c<CR>
  OK<CR>
  

• The response to the "rs" "RX" (reset) command is of the format:

  For ASCII Data Mode:
  RESET:vxx.xx.xx<CR>
  Where vxx.xx.xx is the version number of the !EasyLink API
  

Command List

The registers exposed for the EasyLink API are:

Param	R/W	Description	Parameter(s)
ST	R	Read The last EasyLink status returned	EasyLink status in 0x4B: hex<br> Success = 0000 Config_Error = 0001 Param_Error = 0002 Mem_Error = 0003 Cmd_Error = 0004 Tx_Error = 0005 Rx_Error = 0006 Rx_Timeout = 0007 Rx_Buffer_Error = 0008 Busy_Error = 0009 Aborted = 000a
AE	R/W	UART Echo Enable	0 or 1 to enable/disable echo
FR	R/W	Read/Write frequency in kHz	Frequency in 0x1B
PW	R/W	Read/Write tx power in dBm	Power in decimal between -10 to 14dBm. Note cfg changes are required for 14dBm output power
BM	R/W	Read/Write data mode for Tx/Rx data	Mode in 0x1B 0:ASCII 1:Binary
IE	R	Read IEEE address	None
AS	R	Read address size in Bytes	None
TS	R/W	Read/Write Tx address	address 0x01-0x8B
RT	R	Read current radio time	None
TY	R/W	Read/Write Time Type	Time in 0x1B 0:Absolute 1:Relative Time
TT	R/W	Absolute or relative (based on Time Type) radio time to Tx a packet	Absolute/relative time in units of 4MHz ticks in decimal OR 0 for immediate
TR	R/W	Absolute or relative (based on Time Type) radio time to Rx a packet	Absolute/relative time in units of 4MHz ticks in decimal OR 0 for immediate
RO	R/W	Relative time for Rx timeout	Relative time in units of 4MHz ticks in decimal OR 0 for never
LA	R	Destination address of last Rx'ed message	None
LT	R	Read absolute radio time of last Rx'ed message	None
LR	R	Read RSSI of last Rx'ed message	None
F0	R/W	Read/Write address filter 0	address 0x01-0x8B
F1	R/W	Read/Write address filter 1	address 0x01-0x8B
F2	R/W	Read/Write address filter 2	address 0x01-0x8B
TM	R/W	Read/Write test mode	Test mode in 0x1B: 0:None/Cancel 1:Tone/Carrier Wave 2:Modulated Signal 3:PER Tx 4:PER Rx
PI	R/W	Read/Write PER Tx bursts interval	0x1B time between PER bursts in units of ms
PB	R/W	Read/Write PER Tx burst size	0x1B Tx Burst Size in hex
PP	R/W	Read/Write number of PER Tx/Rx packets	0x1B Tx/Rx Packets in hex
PL	R/W	Read/Write PER Tx/Rx packet length	0x1B Tx/Rx Packet Length in hex
GM00-03	R/W	Read/Write GPIO Mode	0:1 GPIO Value input/output
GV00-03	R/W	Read/Write GPIO Value	0:1 GPIO Value

Command Responses Response for Register Write and Control Commands are formatted as:

Response	Description
OK<CR>	Command or Register write successful
Error 0001<CR>	Command or register read/write failed due to bad formatting
Error 0002<CR>	Command or register read/write failed due to bad length
Error 0003<CR>	Command or register write failed due to a parameter Error
Error 0004<CR>	Command or register write failed due to a Memory Error
Error 0005<CR>	Command or register write failed due to Error From EasyLink API (EasyLink error is stored in Parameter "ST")

Sample app to interface with 16122 running this software (link to it under software example section)

For further documentation on this serial implementation see the official ​TI wiki page.

General Notes

• The XDS110 USB debugger referenced by material related to the CC1350 or in CCS is equivalent to the TiVa chip that's on the GW16122
• Make sure the GW16122 is properly into the miniPcie->USB adapter board otherwise it will come up as a usb device but fail to be recognized by the code composer software. You can check if its connected properly by opening the .ccxml file under the projects targetConfigs folder and hitting the "test connection" button. If multiple boards are connected at once you will * need to specify them by serial number.
• The US frequency allows for a total of 129 channels to choose from, defined in CONFIG_CHANNEL_MASK

You can prevent conflicts of sensor networks by either limiting the channels enabled on each collector/sensor, or by setting the PAN-ID to match on the devices belonging to each * network.

• Beware of adding too many channels to your channel mask, for example, adding all of them took well over 20 minutes to complete the channel selection cycle and bring up the network.
• Line of sight is extremely significant. Depending on the material, a few obstacles can drastically reduce your maximum range.
• General RF information and specific information regarding antenna choice and performance can be found in this ​app note.

Programming the CC1350

The CC1350 of the GW16122 can be programmed a number of ways depending on your host machine. Gateworks has tested both Windows (SmartRF Flash Programmer) and Linux (Uniflash) tools but specific instructions will be provided from the Linux perspective.

You will need to have installed the software detailed in the Set Up section in order to continue.

The Uniflash tool is linux compatible and has both a gui and command line interface. The gui program has an autodetect feature and is somewhat easier to use but the command line tool has the same functionality and is better suited for repeated tasks with constant configurations.

• Note that there doesn't appear to be a way to update the firmware on a running ARM based target. All of the methods we used to program the TiVa and CC1350 MCU's from a x86 host are not compatible with an ARM based system. This means that users will not be able to update firmware on running boards.

GUI Approach

1. Connect a single GW16122 to the host machine via mini-PCIe to USB adapter.
2. Open the "Uniflash" application through a gui file manager from the uniflash_4.2 install directory, or via command line:

   ./uniflash_4.2/node-webkit/nw
   

3. Select target device of CC1350F128
4. Select connection of Texas Instruments XDS110 USB Debug Probe
5. Click the "Start" button

In the Program tab, select the firmware file you wish to load. This is typically a .out file created via a Code Composer Studio Project and can be found in your workspace directory (default ~/workspace_v7/)

1. Click the "Load Image" and "Verify Image" buttons and see the text console output on the bottom of the window for a green success message

It should also be mentioned that you can program your GW16122 directly from the Code Composer Studio IDE by creating a proper target configuration and then selecting "Debug". Most of the TI example projects will detail this procedure.

At this point you may want to power cycle your device.

Command Line Approach

1. Navigate to your uniflash install directory

   cd uniflash_4.2
   

1. Run the installer providing a configuration and .out file as arguments, for example:

   ./dslite.sh --config=CC1350F128.ccxml ~/workspace_v7/collector_cc1350lp/collector_cc1350lp/collector_cc1350lp.out
   

The CC1350F128.ccxml file can be created via the uniflash gui or Code Composer Studio IDE. The contents of the file are provided in the collapsible text below for convenience.

CollapsibleStart(CC1350F128.ccxml)

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<configurations XML_version="1.2" id="configurations_0">
<configuration XML_version="1.2" id="configuration_0">
        <instance XML_version="1.2" desc="Texas Instruments XDS110 USB Debug Probe" href="connections/TIXDS110_Connection.xml" id="Texas Instruments XDS110 USB Debug Probe" xml="TIXDS110_Connection.xml" xmlpath="connections"/>
        <connection XML_version="1.2" id="Texas Instruments XDS110 USB Debug Probe">

                           <instance XML_version="1.2" href="drivers/tixds510icepick_c.xml" id="drivers" xml="tixds510icepick_c.xml" xmlpath="drivers"/>

                           <instance XML_version="1.2" href="drivers/tixds510cs_dap.xml" id="drivers" xml="tixds510cs_dap.xml" xmlpath="drivers"/>

                           <instance XML_version="1.2" href="drivers/tixds510cortexM.xml" id="drivers" xml="tixds510cortexM.xml" xmlpath="drivers"/>


                  <property Type="choicelist" Value="4" id="SWD Mode Settings">
            <choice Name="cJTAG (1149.7) 2-pin advanced modes" value="enable">
                <property Type="choicelist" Value="1" id="XDS110 Aux Port"/>
            </choice>
        </property>

                  <property Type="choicelist" Value="1" id="Power Selection">
            <choice Name="Probe supplied power" value="1">
                <property Type="stringfield" Value="3.3" id="Voltage Level"/>
            </choice>
            <choice Name="Target supplied power" value="0">
                <property Type="choicelist" Value="1" id="Voltage Selection">
                    <choice Name="User specified value" value="1">
                        <property Type="stringfield" Value="3.3" id="Voltage Level"/>
                    </choice>
                </property>
            </choice>
        </property>

                  <property Type="choicelist" Value="0" id="JTAG Signal Isolation"/>

            <platform XML_version="1.2" id="platform_0">
                <instance XML_version="1.2" desc="CC1350F128" href="devices/cc1350f128.xml" id="CC1350F128" xml="cc1350f128.xml" xmlpath="devices"/>
            </platform>
        </connection>
    </configuration>
</configurations>

CollapsibleEnd

References

• ​CC1350 Wiki
• ​CC1350 Bluetooth Software for use with iPhone App
• ​Launch Pad Landing Page on Ti
• ​Ti Information regarding Contiki
• ​XDS110 User Guide
• ​TI 15.4-Stack - Linux Gateway Project Zero App Note
• ​TI Sub-1GHz E2E Forum