The TI 15.4-Stack Linux SDK example applications helps developers create ultra-low power, very long-range, star-topology network solutions. The TI 15.4-Stack Linux SDK includes the Collector and Gateway Example Applications (in addition to others; See the TI 15.4-Stack Embedded Developer’s Guide for more details). The Linux Collector Example Application interfaces over UART with a CC13x0 LaunchPad™, which acts as a MAC CoProcessor (CoP). The Collector Example Application implements a full-function device which performs the functions of a network PAN coordinator (starting a network and permitting devices to join this network) and also provides an interface for monitoring and collecting sensor data from one or more sensor devices. In addition, the Collector Gateway Example Application provides a socket server interface to the Linux Gateway Application.
The Linux Gateway Application, implemented using the NodeJs framework, connects as a client to the socket server created by the Linux Collector. It then establishes a local web server, to which the user can connect through a web browser, to monitor and control the network devices. The Collector and Gateway Example Applications, constitute together a complete **IEEE 802.15.4** to **IP** Bridge, and is a great starting point to create Internet of Things (IoT) applications based on TI 15.4-Stack.
This lab makes use of pre-built binary files, so no coding or building is required. It provides detailed instructions to assist developers set up and understand the principles behind this working demo of a Linux-Collector-based star network of sensors.
**Task 1**: Prepare the sensor
**Task 2**: Prepare the MAC CoProcessor
**Task 3**: Install the TI 15.4-Stack Linux Gateway SDK
**Task 4**: Prepare the host
**Task 5**: Run and use the solution
[[b! Technical support
For any questions you may have, please have a look at the relevant E2E forum - [TI Sub-1 GHz E2E Forum](http://e2e.ti.com/support/wireless_connectivity/proprietary_sub_1_ghz_simpliciti/)
Some basic Linux knowledge is required for performing this lab.
* [SmartRF Flash Programmer 2](http://www.ti.com/tool/FLASH-PROGRAMMER) (Note the 2 in the program name when downloading)
* [SimpleLink CC13x0 SDK](http://www.ti.com/tool/simplelink-cc13x0-sdk) 1.40 or later
* [TI 15.4-Stack Linux Gateway SDK](http://www.ti.com/tool/ti-15.4-stack-gateway-linux-sdk) 2.2.0 or later (Will be set up in Task 3 below)
* [PROCESSOR-SDK-LINUX-AM335X SD Card Image v. 03.02.00.05 for BeagleBone Black](http://software-dl.ti.com/processor-sdk-linux/esd/AM335X/latest/index_FDS.html) (Only if using Embedded host - see Task 4 below)
* [Tera term](https://ttssh2.osdn.jp/index.html.en) or any other equivalent terminal program
* 2 x CC13x0 LaunchPads ([CC1350](http://www.ti.com/tool/LAUNCHXL-CC1350) or [CC1310](http://www.ti.com/tool/LAUNCHXL-CC1310))
* 2 x USB Cables
* Wired network access (e.g. Wi-Fi router with an available Ethernet connection)
* Host platform - either one of:
* Embedded host platform
* [BeagleBone Black](http://www.ti.com/tool/BEAGLEBK) rev. C (other revisions of the BBB may be compatible, but were not tested)
* Compatible 5v Power adapter
* Ethernet cable
* [TTL-232R-3V3](http://www.ftdichip.com/Products/Cables/USBTTLSerial.htm) USB to TTL Serial cable by FTDI, AKA simply as FTDI cable (optional)
* PC host platform
* A PC or a virtual machine connected to the local network and running ubuntu
* A PC or a virtual machine running ubuntu 14.04 64bit (required, even if using an embedded host), for extracting the pre-compiled gateway binaries from the Linux SDK installer (other Linux versions may also be compatible but were not tested)
* A Windows PC for running SmartRF Flash Programmer 2 and for installing the SimpleLink CC13x0 SDK
[[b! Two host platform options
The TI 15.4-Stack Linux Gateway is compatible out-of-the-box with both embedded host (the BeagleBone Black) and PC host (see Hardware Prerequisites above).
Using a PC host may provide easier development and debugging capabilities. If you already have an available ubuntu PC or virtual machine, it will also provide a faster bring-up time, as you will not need to re-install the host environment. On the other hand, while using the BeagleBone as a host may involve some extra steps for setting it up, it provides a more realistic environment, closer to the embedded target product.
This lab can be performed using either CC1310 or CC1350 LaunchPads. The training material is based on CC1350, so if using CC1310, all references to CC1350 in text and screenshots should be refered to as CC1310.
Task 0: Label your LaunchPads
1. Label each of your LaunchPads with its XDS Device ID, as described [here](../util_identify_lp/util_identify_lp.html).
* Additionally, label one LaunchPad as "Sensor" and the other as "MAC-CoP". These labels will be referred to throughout this lab. It is recommended to use a non-permanent marking for this (e.g. sticky notes), as these labels may only be relevant for this specific lab.
Task 1: Program the "Sensor" LaunchPad
1. It is assumed that [SimpleLink CC13x0 SDK](http://www.ti.com/tool/simplelink-cc13x0-sdk) is already installed on your windows PC. If not, please install it now.
* Connect the "Sensor" LaunchPad to the Windows PC.
* Run SmartRF Flash Programmer 2, and perform the following steps:
* In the left pane, titled **Connected device**, select the "Sensor" LaunchPad as the target device, by clicking on it.
[[y! If more than one LaunchPad is connected to the pc:
Make sure to select the correct LaunchPad when programming the firmware: Compare the XDS Device ID that you written on the LaunchPad in Task 0 to the device ID shown in the left pane of SmartRF Flash Programmer 2 - see the red arrow in the image below
* In the Main tab, under **Flash image(s)**, select **Single**, and brows to the pre-built sensor hex file, located at:
In the path above, x..xx represent the SDK revision. The base folder may differ, depending on your SDK installation destination folder.
[[y! Using CC1310?
If using CC1310 instead of CC1350 LaunchPad, please modify the path above accordingly. While it is possible that the actual hex image for both platforms is the same, this may change in a future release so please use the correct path.
* Make sure **Erase**, **Program** and **Verify** are all selected, and then prfrom these actions by pressing the "**Play**" button:
[[g! Did it work?
Make sure that the programming procedure completed successfully: it should take a few seconds, after which SmartRF Flash Programmer 2 should say **Success!** on a green bar at the bottom of the window.
Task 2: Program the "MAC-CoP" LaunchPad
1. Follow the steps above to program the "MAC-CoP"" LaunchPad using the respective hex image located at:
Task 3: Install the TI 15.4-Stack Linux Gateway SDK
1. Download [TI 15.4-Stack Linux Gateway SDK](http://www.ti.com/tool/ti-15.4-stack-gateway-linux-sdk) to your ubuntu 14.04 machine. The SDK package comes in the form of a Linux executable, named **ti15.4stack_linux_x64_x_xx_xx_xx.run** (the x_xx… will show the actual version number).
* Assign execute permissions to the installer, and then execute it:
chmod +x ti15.4stack_linux_x64_x_xx_xx_xx.run
```Run the Gateway SDK installer
* Follow the installer instructions, accept the license agreement and select a destination path, to extract the SDK content to the Linux filesystem. Wait for the installer to finish.
Task 4a: Prepare the embedded host
This tasks walks through setting up the BeagleBone Black as an embedded host for the TI 15.4-Stack Linux Gateway. If you are using a ubuntu linux PC (or virtual machine) _as a host_, rather than a BBB, please skip this task and go straight to the next task.
[[b! Doing stuff differently
Some of the tasks below can be done on either a Windows or a Linux PC (don't get confused with the host platform discussed above - here we talk about _the PC used for performing the lab_). For simplicity, for such tasks, only Windows instructions are provided in detail. If you feel you do know how to perform certain tasks on a Linux PC and prefer to do so, please go ahead and try it!
1. Program the SD card with the processor SDK image using the following steps, which can be done on either a windows or a linux machine:
1. Download the prebuilt TI processor SDK SD card image file, **am335x-evm-linux-03.02.00.05.img.zip** from [here]( http://software-dl.ti.com/processor-sdk-linux/esd/AM335X/latest/index_FDS.html)
* Follow these instructions to program the microSD memory card with the above image:
For Windows instructions, follow [this wiki](http://processors.wiki.ti.com/index.php/Processor_SDK_Linux_Creating_a_SD_Card_with_Windows)
For Linux instructions, follow [this wiki](http://processors.wiki.ti.com/index.php/Processor_SDK_Linux_create_SD_card_script)
* Connect the FTDI cable to header J1 on the BeagleBone - the black wire should be connected to the pin marked with a dot.
* Connect the USB connector of the FTDI cable to the Windows PC.
* The FTDI cable should be automatically enumerated as a serial device. If not, please install the required drivers.
* Run a terminal program on that PC (e.g. Tera Term), and connect it to the FTDI cable's serial port. Configure it to use 115,200 kbps, 8 data bits, No parity, 1 stop bit, No flow control.
* Boot the BBB using the newly prepared SD card:
1. Make sure no cable is connected to the BBB (e.g. power, USB) other than the FTDI cable.
* Connect the BBB to your network using the Ethernet cable
* Insert the SD card into the BBB
* Press and hold the Boot Select button, which is located near the SD card slot. Note that the boot button is detected only at initial power on, and not on other types of reset:
* While holding the Boot button, provide power to the BBB by connecting the 5v power supply
* Wait a few seconds, then release the Boot button. In about 5 to 15 seconds the LEDs should begin to blink.
[[b! Be patient :-)
The first boot from a freshly formatted SD card takes about 1 to 2 minutes longer, during this extended time the BBB Linux distribution performs some one-time-only steps.
* Once the BBB is up and running, you should see the Arago Project wellcome message, and a prompt to enter enter the user name. Type in the user name **root** and press ENTER:
* Use the ifconfig command to get the ip address assigned to the BBB for the Ethernet connection (You will need this address in order to transfer files to the BBB and to open additional terminal windows):
* Open another terminal window, and connect to the BBB using SSH to the ip address you found above. Use user name **root** and no password. Close the older terminal window (that is connected via the FTDI cable).
The console connection over the FTDI cable provides some extra level of debug traces that may be useful during development, but may make user interaction less comfortable.
* Locate the file **bbb_prebuilt.tar.gz** in the Linux Gateway SDK that you installed in Task 3. This file is under the **prebuilt** directory in the main SDK folder (by default, the SDK is extracted to **~/ti/simplelink/ti-15.4stack-x.xx.xx.xx**).
Copy this file from the ubuntu machine to the BBB file system - you may use a USB thumb-drive to do so. Alternatively, if the BBB and the ubuntu machine (where the gateway SDK is installed) are on the same network, you can use scp for transferring the file, by executing the following commands in the ubuntu machine:
First, change your working directory to the directory where the file is located, then call scp (replace <bbb-ip-address> with the actual ip address of the bbb):
scp bbb_prebuilt.tar.gz root@:/home/root/
```Copy the pre-built files onto the BBB
* On the BBB, extract the **bbb_prebuilt.tar.gz** file by executing the following commands
tar -xvf bbb_prebuilt.tar.gz
```Extract the pre-built content
Task 4b: Prepare the PC host
If you are using a BeagleBone Black as a host, please skip this task and go straight to the next task.
1. Assuming you log in to the ubuntu PC as a standard user and not as root, you will need to execute the following command to gain access to the serial port used for communicating with the LaunchPad:
sudo adduser $USER dialout
```Allow access to the LaunchPad's serial port
* For the command above to take full effect, please reset your ubuntu PC after executing that command.
Task 5: Run and use the gateway
In this chapter, the term _host_ is used in reference to either the BBB or the PC host. In places where a distinction should be made, it will be clearly noted.
Connecting the MAC CoProcessor to the host
1. Plug-in the "MAC-CoP" LaunchPad to the host using a USB cable. If you are using the embedded host option, it should look like this:
* Wait a few seconds, and then check to see if the LaunchPad enumerated successfully as 2 serial ports, by entering the following command in the host terminal window:
ls –l /dev/ttyACM*
```Verify correct enumeration of "MAC-CoP"
[[g! Did it work
When the "MAC-CoP" LaunchPad has enumerated successfully, you should see the following output. If you don't, keep on reading for a possible solution.
```Successful enumeration output
[[y!What if it does not work?
If you do not see any new serial port enumerated after plugging in the "MAC-CoP" LaunchPad, wait a few more seconds and try entering the command above again.
It is also possible that the LaunchPad had enumerated using different serial device names (e.g. /dev/ttyACM3). If this is the case, you will need to update the gateway configuration file, which assumes /dev/ttyACM0 by default. To do this, open the file prebuilt/bin/collector.cfg, look for **ttyACM0** and update this value accordingly. Note that the LaunchPad enumerates as two separate serial devices - please choose the one with the lower number suffix. If the next steps fail, you may return to this step and try the other serial device name instead.
Starting the Application – Starting the Network
The PREBUILT directory contains a simple shell script called run_demo.sh, which is all you need to get everithing up and running.
1. Change the working directory on the host according to the host platform. If using a PC host, replace the x.xx... with the actual SDK version number:
```If using BBB host
```If using PC host
* Execute the following commands on the host. The rm command is for getting rid of any pre-existing network configuration, and is only needed if you have already ran the gateway on this BBB before. The sh script starts the TI 15.4-Stack Gateway and Collector Application.
``` Start the TI 15.4-Stack Linux Gateway
[[g! What to expect
The gateway will start up and show some informational messages, then it will brings back the command prompt while continue running in the background. If using BBB host, the terminal window will look similar to this to the image below. If using a PC host, in addition to similar traces in the console, a web browser will automatically be opened and connected to the collector application (as discussed later on).
Note that the message **Connected to App Server** may appear a few seconds after the command prompt is dispalyed.
* The integrated web server is now accessible via the links provided in the console traces. If using a PC host, a web browser will automatically be opened and connected to this web server. If using BBB host, select the link accessible from your PC (depending on your PC's IP address), open a web browser on the PC, enter this link in the address line and press ENTER. The link you should use will have the same IP address as you discovered earlier with ifconfig, with an addition of a specific port number - 1310. When copying the link to your web browser, make sure to include the complete link, including the port number. If you omit the port number, the browser will default to port 80, which may lead to a different web page which is outside the scope of this lab.
[[g!How it should look
Your web browser should now be displaying a page similar to this:
[[b!Modifying the network parameters
Notice the PanID value in web page you just opened. This value, as well as the RF channel, the Beacon Order and other RF-related parameters can be easily changed by editing the file **prebuilt/bin/collector.cfg**, then rebooting the BBB and rerunning the gateway as explained above.
Adding sensor device(s) to the network
When the gateway example application starts for the first time, no devices are present in the Sensor Nodes list and the network is closed for joining meaning it will not accept new device connections.
1. Connect the "Sensor" LaunchPad to an available powered USB port, or USB power adapter.
2. Reset the sensor node to factory defaults, by pressing and holding **Button 2**, then pressing and releasing the **Reset** button while **Button 2** is still being pressed and then releasing **Button 2**. Following reset, the sensor device will automatically try to connect to an available network.
3. Click the **Open** button on the web page, to open the network for new devices. The sensor devices will connect to the gateway/collector after a few seconds
[[g!What to expect
Once the "Sensor" LaunchPad is connected to the network, its red LED (DIO6) will light up, and the **Sensor Nodes** list will show this newly added device.
[[y!If it does not connect...
...simply press the "Sensor" LaunchPad's reset button again - no need to press Buttons 1 and 2 this time.
Monitoring sensor data and sending control commands
1. Watch the web interface you opened in the web browser.
[[g! Sensor data reports
After the new device is added to the network, its short and extended addresses should appear in the device list. At the beginning, the data fields are displayed as — (hyphens), indicating no data. 1-2 minutes later, sensor reading values will also be displayed (the exact interval is configured in the Collector application using a #define value - see the TI 15.4-Stack Embedded Developer’s Guide or the Linux Example Collector source code for more details). From that point on, the sensor nodes periodically report their sensor data to the collector, and the display is updated accordingly.
2. Click the Toggle LED button in the web interface
[[g! Interacting with the sensor from the gateway
Clicking the Toggle LED button sends a message to the sensor module to toggle the LED. A slight delay (up to a few seconds) my be observed before the LED is actually toggled. This delay is because the sensor nodes are normally in sleep mode, and only wake up periodically to receive commands buffered on the collector.
Network information and state is saved in non-volatile memory by both the Collector (using the host file system) and the Sensor (using the internal Flash memory). This ensures that both devices can re-establish the connection following a power-cycle.
If you want to repeat task 5 from scratch, you will need to reset both the Collector and the Sensor to their factory defaults, as explained in the lab material above (button-press combination for the Sensor, and deleting the file nv-simulation.bin for the Collector)
[[b!Want to get deeper?
This lab is based on pre-built binaries. To build run the example from the source, please refer to Linux Development Host chapter in the TI 15.4-Stack Linux Developer’s Guide.
**TI 15.4-Stack wiki pages** are at [http://www.ti.com/ti154stack-wiki](http://www.ti.com/ti154stack-wiki)
**CC13xx Software Overview** – Available at [http://www.ti.com/tool/cc13xx-sw](http://www.ti.com/tool/cc13xx-sw).
**CC13xx Technical Reference Manual** – Available [here][Technical Reference Manual]
[Technical Reference Manual]: http://www.ti.com/lit/swcu117