Speedway Revolution Embedded Development Tools and Sample Application (ETK)

The Octane ETK is a bundle of libraries, tools, and examples for creating an embedded application on Impinj Speedway Revolution readers and gateways.  Development is supported with Ubuntu Operating System version 14.04 and 16.04 *.  The documentation and training videos we provide explain how to setup this environment, cross compile libraries for the ARM processor **, and use VSCode to perform remote debugging **.

* - Ubuntu 16.04 will require you to downgrade gnu tools to version 4.8
** - Training Videos Only

Documentation:

Sample Application

• The Octane Embedded Development Tools provided in the “Downloads” section above contains a sample application that will show how to read tags. The following output is what should be seen when tags are in the Field of View:

Tag report
 -----------------------------------
 Antenna ID : 1
 EPC : 3008-33B2-DDD9-0140-0000-0006
 Timestamp : 1419097603747553
 Peak RSSI : -41
 FastID : E28011052000205CDEAF0000
 TID : 1020E280
 User memory (Word 0) : ABCD

Recommended Development

• We recommend you do most of your development and debug on the host PC, rather than cross-compiling your application and transferring it to the reader every time. This will allow you to develop applications much quicker using a debugger of your choosing. You can periodically transfer your application to the reader for performance testing or final deployment via FTP or CAP installation.

Setting Up ETK Development Environment

• Run these commands to set up your Linux development environment.  NOTE: We test with Ubuntu 14.04.

sudo apt-get update
sudo apt-get install g++-multilib g++-4.8-multilib
sudo apt-get install lib32z1
sudo apt-get install libc6:i386
sudo apt-get install libc6-dev-i386
sudo apt-get install libssl-dev:i386
sudo apt-get install build-essential
ln -s /usr/bin/g++-4.8 /usr/bin/g++

Installing an FTP client

• Most Linux distributions include a command line FTP client by default.
• If you would rather use a graphical FTP client, you can install gFTP using your package manager.
• The following is the command for Debian and Ubuntu distributions:

sudo apt-get update
sudo apt-get install gftp

GNU Toolchain Installation Instructions

• If your Linux machine doesn’t have the GNU toolchain (gcc compiler) installed, you should do so using your distribution’s package manager.
• The following is the command for Debian and Ubuntu:

sudo apt-get update
sudo apt-get install build-essential

Installing the ARM cross-compiler toolchain

• To start installing the Octane Embedded Toolkit, unzip the download and ensure the following two files are in your HOME directory
• octane_etk-5.12.0.240.tar.gz (file names will change with version)
• octane_etk_sample-5.12.0.240.tar.gz (file names will change with version)
• Extract the Speedway Revolution Embedded Development Tools (octane_etk-5.12.0.240.tar.gz) to a directory (~/) on your computer.

cd ~
tar xvfz ~/octane_etk-5.12.0.240.tar.gz

• The above commands will extract the contents of the file into directory “octane_etk-5.12.0.240”.
• For the purposes of this tutorial, we will assume the directory is beneath your home directory (~/octane_etk-5.12.0.240).

Note: If using an ETK version prior to 6.0, then you will need to unpack the arm-toolchain using the steps below. If using version 6.0 or later, you should be okay to skip to the PATH change in the next section, as the arm-toolchain is already unpacked.

cd octane_etk-5.12.0.240 
tar xvf arm-2013.11-33-arm-none-linux-gnueabi-i686-pc-linux-gnu.tar.bz2
ln -s arm-2013.11 arm-toolchain

• The above commands will extract the arm toolchain into the directory "octane_etk-5.12.0.240".

• It is now time to update your system PATH either in ~/.bash_profile (or .profile on Ubuntu or .bashrc on other flavors of unix) or on the command line prior to compilation to include the following folders:
• ~/octane_etk-5.12.0.240
• ~/octane_etk-5.12.0.240/arm-toolchain/bin
• ~/octane_etk_sample-5.12.0.240

PATH=$PATH:$HOME/octane_etk-5.12.0.240:$HOME/octane_etk-5.12.0.240/arm-toolchain/bin:$HOME/octane_etk_sample-5.12.0.240

• You may need to re-login for this change to take effect.
• Verify the PATH is updated properly with the following command:

echo $PATH
-or-
which arm-none-linux-gnueabi-gcc 

Installing the Sample Application and LTK Libraries

• Extract the Speedway Revolution Embedded Development Tools sample (octane_etk_sample-5.12.0.240.tar.gz) to a directory (~/) on your computer.

cd ~
tar xvfz ~/octane_etk_sample-5.12.0.240.tar.gz

• This will extract the contents of the file into directory “octane_etk_sample-5.12.0.240”.
• For the purposes of this tutorial, we will assume the directory is beneath your home directory (~/octane_etk_sample-5.12.0.240).
• The sample application is configured for a four port reader (R420, xPortal).
• Note: If you are using a reader with a different number of antenna ports (R220, Antenna Hub) please change the NUM_ANTENNAS constant in the example source code file (speedway_embedded_example.cpp).
• The Sample Application has a version of the C++ LTK libraries stored in directories ~/octane_etk_sample-5.12.0.240/lib (.a object files) and ~/octane_etk_sample-5.12.0.240/include (.h headers).
• The “~/octane_etk_sample-5.12.0.240/lib” folder should contain the following files:
  1. libcrypto_atmel.a
  2. libdl_atmel.a
  3. libltkcpp_atmel.a
  4. libltkcppimpinj_atmel.a
  5. libltkcppimpinj_x86_64.a
  6. libltkcppimpinj_x86.a
  7. libltkcpp_x86_64.a
  8. libltkcpp_x86.a
  9. libssl_atmel.a
  10. libxml2_atmel.a
  11. libxml2_x86_64.a
  12. libxml2_x86.a

• The “~/octane_etk_sample-5.12.0.240/include” folder should contain the following files:
  1. impinj_ltkcpp.h
  2. ltkcpp_base.h
  3. ltkcpp_connection.h
  4. ltkcpp_frame.h
  5. ltkcpp.h
  6. ltkcpp_platform.h
  7. ltkcpp_xmltext.h
  8. out_impinj_ltkcpp.h
  9. out_ltkcpp.h
  10. version.inc

• The version.inc file has the version of the ltk installed.  It should indicate "10.26.1".

Building the Sample Application

• Switch to the ~octane_etk_sample-5.12.0.240 directory:

cd ~/octane_etk_sample-5.12.0.240

• The included makefile can build three different targets:
• x86 (host PC)
• ARM (Speedway Revolution)
• CAP (loader for Speedway Revolution)
• To clean your folder you can type:

make clean

• To build both the x86 and arm executable, type:

make

• To build just the x86 version, type:

make x86

• To build an ARM executable that can run directly on Speedway Revolution, type:

make arm

• Building these two targets will create the following files
• ~/octane_etk_sample-5.12.0.240/bin/speedwayr_arm
• ~/octane_etk_sample-5.12.0.240/bin/speedwayr_x86
• To have your program start automatically after reboot on a reader, rename the application (e.g. speedwayr_arm) to a file named “start”.

• Note: The reader will execute file '/cust/start' from the root folder '/'. Please create a script that changes to the appropriate folder and then calls your application referring to relative files.
• Note: Please disregard the following warning messages:
  
  lib/libcrypto_atmel.a(dso_dlfcn.o): In function `dlfcn_globallookup':
  (.text+0x10): warning: Using 'dlopen' in statically linked applications requires at runtime the shared libraries from the glibc version used for linking
  lib/libcrypto_atmel.a(b_sock.o): In function `BIO_get_host_ip':
  (.text+0x10c): warning: Using 'gethostbyname' in statically linked applications requires at runtime the shared libraries from the glibc version used for linking
  lib/libcrypto_atmel.a(b_sock.o): In function `BIO_get_port':
  (.text+0x290): warning: Using 'getservbyname' in statically linked applications requires at runtime the shared libraries from the glibc version used for linking

• To build the CAP, copy the binary over to the CAP folder:

cp ~/octane_etk_sample-5.12.0.240/bin/speedwayr_arm ~/octane_etk_sample-5.12.0.240/cap/ 

• To create the CAP with the arm version of the app (~/octane_etk_sample-5.12.0.240/speedwayr_cap.upg), type:

cd ~/octane_etk_sample-5.12.0.240
make cap

Executing the Host PC Sample Application

• Switch to the ~/octane_etk_sample-5.12.0.240 directory (if not already there)

cd ~/octane_etk_sample-5.12.0.240

• Execute the Host PC Sample Application against a target reader (<reader_address>):

bin/speedwayr_x86  <reader_address>

• Replace <reader_address> with either the ip address or hostname of the reader you want to read from.
• The output should look similar to the following if tags are in the Field of View:

Tag report
 -----------------------------------
 Antenna ID : 1
 EPC : 3008-33B2-DDD9-0140-0000-0006
 Timestamp : 1419097603747553
 Peak RSSI : -41
 FastID : E28011052000205CDEAF0000
 TID : 1020E280
 User memory (Word 0) : ABCD


 Tag report
 -----------------------------------
 Antenna ID : 1
 EPC : 3008-33B2-DDD9-0140-0000-696E
 Timestamp : 1419097603775686
 Peak RSSI : -38
 FastID : E280110520002556DE920000
 TID : 1020E280
 User memory (Word 0) : ABCD

• Press Ctrl + C to stop running the sample application.

Reader Deployment Options

• When you are ready to deploy the sample solution to the reader, there are several files that should be copied over at a minimum:
• bin/speedway_arm
• cap/sys/reader.conf
• The files must be placed beneath the /cust folder on the reader:
• /cust/speedway_arm
• /cust/sys/reader.conf
• Refer to the Impinj Reader and Gateway Embedded Developers Guide to learn more about the contents of the reader.conf file.
• The sample application sets the Linux shell (named OSShell) password to "developer" and starts the FTP server.
• Please disable these features for a production application if your application does not require them.
• There are two ways the application can be deployed to one or more readers.

1. FTP the application to the reader once the reader FTP and OSShell are enabled.
2. Create a CAP file for multiple reader deployment.

Enabling FTP and OSShell on the Reader

• OSShell and FTP access are disabled by default on Speedway Revolution.
• To enable these features, you can do one of the following:
• Create a Custom Application Partition (CAP) image.
• Use the pre-built CAP file (see below for accessing "~/octane_etk_sample-5.12.0.240/cap") that is included with the Speedway Revolution embedded development tools.
• (FTP only) Connect to RShell by SSH'ing to the reader and issuing the command:

config network ftp enable

Installing a CAP File On the Reader via Web UI

• You can load the pre-built (or any other) CAP file on to the reader by opening up a web browser and navigating to the following URL:

http://<reader_address>/

(<reader_address> should be replaced with the actual reader hostname or ip address. E.g. http://speedwayr-10-25-32)

• You will be prompted to login. The default login information is:
• Username: root
• Password: impinj
• Click the Browse button (next to the "Select Upgrade File") and select the pre-built CAP file (or any other one you just created).
• Click the Upgrade button.
• Wait until the 'Reboot Status' indicator on the Web UI reads “Ready to Reboot”.
• Click the reboot button to restart the reader.
• Once the reader reboots, system shell and FTP access will be enabled.

FTP the Application to the Reader

• To have your program start automatically rename it to a file named “start” so that it will reside as file "/cust/start" on the reader.
• Using an FTP client, connect to the reader using its IP address or hostname.

ftp <reader_address>

(<reader_address> should be replaced with the actual reader hostname or ip address. E.g. http://speedwayr-10-25-32)

• You will be prompted to login (Default username is “root” and password “impinj”)
• Once connected, navigate to folder /cust and binary transfer the executables there.

cd /cust
bin
put bin/speedwayr_arm
mkdir sys
cd sys
put cap/sys/reader.conf

Building a CAP (Installation) File

• If you would like to deploy your application across multiple readers, you can create an installation file, also known as a CAP file.
• Creating a CAP file will take care of creating directories and copying all the files for your application over to the reader.
• First, create a working directory to build the CAP file in.
• The sample application already has a cap folder (~/octane_etk_sample-5.12.0.240/cap).
• You can put the CAP files wherever you like.
• Update the ~/octane_etk_sample-5.12.0.240/cap_description.in file with the following contents:

# CAP Description File
 # This file contains the settings used by the CAP generation tool
 # when a CAP partition upgrade file is produced.
 [Description]
 
 # Version is a 4 part number in decimal with each part limited to
 # 0-255. It is the version of the CAP to be generated.
 Version = 1.0.0.0
 # Valid Reader Hardware is a 3 part number in decimal representing
 # the reader model and major/minor revisions on which the CAP may be
 # loaded. Each field may be replaced by a '*' to mean 'all'.
 # Format = aaa.bbb.ccc
 # aaa - Model number
 # bbb - Major revision
 # ccc - Minor revision
 Valid Reader Hardware = 240-*-*
 Valid Reader Hardware = 250-*-*
 Valid Reader Hardware = 260-*-*
 Valid Reader Hardware = 270-*-*
 # File System Layout is a value used by the reader to determine how
 # the CAP partition should be loaded to flash. Currently the only
 # supported layout version is 10.
 File System Layout = 10
 # All the files in this directory will be loaded on the reader under /cust.
 # Specify this directory using an absolute path.
 Input Directory = /home/notroot/cap/input

• Modify the entries above to suit your needs.
• E.g. Change the version number that shows up on the reader's web UI.
• Now copy all of your application files to the cap directory (~/octane_etk_sample-5.12.0.240/cap)

cd ~/octane_etk_sample-5.12.0.240/cap
chmod a+rx ~/octane_etk_sample-5.12.0.240/bin/speedwayr_arm
cp ~/octane_etk_sample-5.12.0.240/bin/speedwayr_arm .

• Change the "." to "start" in the line above if you want this program to start immediately after a reader reboot.
  • Note: If the application assumes it is run in the '/cust' folder, then this approach will not work because the reader executes '/cust/start' from folder '/'.
    • Create a bash script that changes to the /cust folder and then executes speedwayr_arm instead.
• Execute the following to generate the "speedwayr_cap.upg" CAP file:

cd ~/octane_etk_sample-5.12.0.240/
make cap

• Now that you have created the CAP file (~/octane_etk_sample-5.12.0.240/speedwayr_cap.upg), you can load it on to the reader.
• Follow the instructions in section “Installing a CAP File On the Reader” above for installing this CAP file on the reader.
• Please refer to the “Firmware_Upgrade_Reference_Manual.pdf” file in the Octane Documentation article for how to upgrade multiple readers simultaneously using a single CAP file.
• Your application should start once the reader has finished rebooting if you named it “start”, otherwise follow the instructions below for running the application manually.

Running the Application Manually

• Open up RShell by connecting to the reader via ssh.
• The default user name is "root" and the default password is 'impinj".
• At the RShell prompt, enter the following command to open a system shell:

osshell developer

• From the Linux shell prompt, you can navigate to /cust and execute your application.

cd /cust
chmod a+rx speedwayr_arm
./speedwayr_arm

• The output should look something like:

Tag report
 -----------------------------------
 Antenna ID : 1
 EPC : 3008-33B2-DDD9-0140-0000-0006
 Timestamp : 1419097603747553
 Peak RSSI : -41
 FastID : E28011052000205CDEAF0000
 TID : 1020E280
 User memory (Word 0) : ABCD


 Tag report
 -----------------------------------
 Antenna ID : 1
 EPC : 3008-33B2-DDD9-0140-0000-696E
 Timestamp : 1419097603775686
 Peak RSSI : -38
 FastID : E280110520002556DE920000
 TID : 1020E280
 User memory (Word 0) : ABCD