XRT Installation Guide Version 1.1.1 Table of Contents
Copyright and Trademarks iii Disclaimer iii About This Manual iv Audience iv Copy and Paste from PDF iv Conventions used in this Manual iv IOTech Support v XRT Installation 1 Apache Paho MQTT Client Library Installation 2 Thrift C RPC Library Installation 2 XRT-dependent Libraries Installation 3 XRT Builds 3 Install on Debian-based Systems 4 Install on RPM-based Systems 5 Install on Alpine Linux-based Systems 10 Install on ClearLinux-based Systems 11 Install for Zephyr RTOS 12 Install for Azure Sphere 13 XRT License 14 Test an Installation 15
TABLE of CONTENTS ii Copyright and Trademarks
Copyright and Trademarks
This document contains proprietary information belonging to IOTech Systems.
All trademarks acknowledged.
Disclaimer
This manual applies to Version 1.1.1 of the XRT package and to all subsequent versions and modifications of documentation unless otherwise indicated in new editions.
It is the policy of IOTech Systems to improve products as technology, components, software and firmware become available. IOTech therefore reserves the right to change specifications without prior notice.
Note that although this publication contains the latest information available, it may be subject to modification and may contain technical inaccuracies or typographical errors.
This document contains examples of data, screens and reports used in normal operations. To illustrate them as completely as possible, the examples may include the names of individuals or companies. Apart from some genuine names, used only with permission, these names are fictitious and any similarity to the names and addresses of any individuals or companies is coincidental.
To provide improved information in later editions of this manual, IOTech welcomes your views. Please address your comments to the address given below.
© 2021
IOTech Systems The Catalyst, Science Square, Newcastle Helix, Newcastle upon Tyne, United Kingdom NE4 5TG Email: [email protected]
All Rights Reserved
Disclaimer iii About This Manual
About This Manual
This manual describes the following:
l Installing XRT on the following systems: o Debian-based systems o RPM-based systems o Alpine Linux systems o ClearLinux systems o Zephyr RTOS development hosts o Azure Sphere development hosts
l Obtaining and applying a license
l Testing an installation
Audience
This manual is designed for individuals who want to install XRT on a variety of native and cross- development systems.
Copy and Paste from PDF
You can copy and paste the commands from this PDF for use in your project.
There is a known issue in some PDF readers, such as the Document Viewer in Ubuntu, where extra spaces are added on pasting content. This particularly occurs following a forward slash (/) character.
If you have issues after copying and pasting commands or examples from this document, please check for extra spaces that may have been added.
Conventions used in this Manual
Throughout this manual, the following conventions are used:
Convention Used for Example
Monospace font Command examples xrtd & Code examples
Code extracts
Audience iv About This Manual
Convention Used for Example
Italic monospace font Variables
Italics File names /opt/iotech/xrt
Paths
Bold Menu options Select the Add button
Button text
Field name
Notes Emphasize important Note: You must have a information, or providing license file. extra information or tips
Cautions Warn of possible Caution: Ensure the damage to yourself or hardware is disconnected your system before starting to avoid electric shocks.
Blue font with heading and Internal cross-reference "XRT Installation" on page 1 page reference
Blue bold underlined font Internal links IOTech Support
Indigo bold italic External links, which Contact Form underlined font open in a new browser window
IOTech Support
If you require further support from IOTech, visit the IOTech Support and Knowledge Base, or use the Contact Form.
IOTech Support v XRT Installation
XRT Installation
The method used to install XRT differs depending on the system that you are using. Where possible, XRT is delivered using the standard packaging system for a distribution; if this is not possible, standard compressed TAR or ZIP files are used.
Note: IOTech recommends that all installations are done as root. The installation instructions in this document, with the exception of the Debian-based installation instructions, provide the commands for installations done as root.
The following table shows which systems and architectures support XRT, and provides a direct link to the appropriate installation instructions:
64 Bit 32 Bit 64 Bit System Installation Instructions Intel X86 ARM ARM
Debian 10 Y Y Y "Install on Debian-based Systems" on page 4
Debian 9 Y Y Y "Install on Debian-based Systems" on page 4
Ubuntu 20.04 Y Y Y "Install on Debian-based Systems" on page 4
Ubuntu 18.04 Y Y Y "Install on Debian-based Systems" on page 4
CentOS 8 Y N Y "Install on CentOS 8" on page 5
Fedora 33 Y N Y "Install on Fedora 33" on page 5
openSUSE Y Y Y "Install on OpenSUSE Leap 15.2" 15.2 on page 6
Photon 3.0 Y N Y "Install on Photon 3.0" on page 7
Clear Linux Y N N "Install on ClearLinux-based Systems" on page 11
1 XRT Installation
64 Bit 32 Bit 64 Bit System Installation Instructions Intel X86 ARM ARM
Alpine Linux Y Y Y "Install on Alpine Linux-based 3.12 Systems" on page 10
Alpine Linux Y Y Y "Install on Alpine Linux-based 3.13 Systems" on page 10
Zephyr 2.3 Y Y Y "Install for Zephyr RTOS" on page 12
Zephyr 1.14 Y Y Y "Install for Zephyr RTOS" on page 12
Azure Sphere N Y N "Install for Azure Sphere" on page 13
The core XRT framework requires support for the standard C library and Portable Operating System Interface (POSIX) API. This means that it can be ported to any real-time operating system (RTOS) that supports these features.
Note: Some individual XRT components may have more restrictive API requirements and, therefore, not all XRT component modules are supported on all platforms.
Apache Paho MQTT Client Library Installation
The XRT MQTT plug-ins use the Apache Paho MQTT client library.
Where possible, IOTech includes binary packages in the package repositories; however, not all systems support a binary package. When this is the case, the Paho MQTT library must be built and installed manually. The relevant installation instructions include the steps for manual installation.
Thrift C RPC Library Installation
Some XRT plug-ins use the Thrift C RPC library, which requires the mdedtls package for secure communication.
Where possible, IOTech includes binary packages in the package repositories; however, not all systems support a binary package. When this is the case, the mdedtls package must be built and installed manually. The relevant installation instructions include the steps for the manual installation.
Apache Paho MQTT Client Library Installation 2 XRT Installation
XRT-dependent Libraries Installation
IOTech provides dependent libraries as packages on all supported platforms.
The dependencies are managed by the package manager, when possible. If this behavior is not supported, instructions for installing the dependencies manually are included in the relevant section of this document.
XRT Builds
The following XRT builds are available:
Build Package Description
Release iotech-xrt Use when developing connected IoT edge applications with XRT deployment-ready components
Contains the following:
l Component libraries
l XRT and XRT CLI application
l Examples
Development iotech-xrt- Use when developing XRT-based components dev Contains the following:
l Component libraries
l XRT and XRT CLI application
l Examples
l Headers required for development using XRT components
Cross iotech-xrt- Use when installing Azure Sphere on development Development azsphere7 hosts
XRT-dependent Libraries Installation 3 XRT Installation
Install on Debian-based Systems
This method uses .deb packages to install XRT. It is used for all systems that are based on the Debian packaging mechanism, such as Debian and Ubuntu.
To install XRT using .deb packages, complete the following steps:
1. Install the packages, using the following command:
sudo apt-get install lsb-release apt-transport-https curl gnupg2
2. Add the key for the IOTech repository, using the following command:
curl -fsSL https://iotech.jfrog.io/artifactory/api/gpg/key/public | sudo apt-key add -
3. Register the IOTech repository, using the following command:
echo "deb https://iotech.jfrog.io/iotech/debian-release $(lsb_release -cs) main" | sudo tee -a /etc/apt/sources.list.d/iotech.list
4. Update the repositories, using the following command:
sudo apt-get update
5. Install XRT using the following command:
sudo apt-get install iotech-xrt
Install on Debian-based Systems 4 XRT Installation
Install on RPM-based Systems
RPM-based systems, such as Fedora, SUSE and CentOS, do not all use the same package management system or support the same packages. This means that the installation instructions for RPM-based systems are specific to the system.
You can install XRT on the following RPM-based systems:
l CentOS 8. For installation instructions, see "Install on CentOS 8" below
l Fedora 33. For installation instructions, see "Install on Fedora 33" below
l OpenSUSE Leap 15. For installation instructions, see "Install on OpenSUSE Leap 15.2" on the next page
l Photon 3.0. For installation instructions, see "Install on Photon 3.0" on page 7
Install on CentOS 8
To install XRT on CentOS 8 as root, complete the following steps:
1. Download and install the iotech.repo repository access file from the IOTech support portal, using the following command:
cp iotech.repo /etc/yum.repos.d/
2. Add EPEL and PowerTools repository support, if not already enabled, using the following commands:
dnf install -y 'dnf-command(config-manager)' dnf config-manager --set-enabled PowerTools dnf install -y epel-release
3. Install the build packages, using the following command:
dnf -y install git cmake make gcc openssl-devel libcurl-devel mbedtls-devel lua-devel
4. Install XRT, using the following command:
dnf install iotech-xrt
Install on Fedora 33
To install XRT on Fedora 33 as root, complete the following steps:
1. Download and install the iotech.repo repository access file from the IOTech support portal, using the following command:
cp iotech.repo /etc/yum.repos.d/
Install on RPM-based Systems 5 XRT Installation
2. Install the build packages, using the following command:
yum -y install git cmake3 make gcc openssl-devel libcurl-devel mbedtls-devel lua-de vel
3. Install XRT, using the following command:
yum install -y iotech-xrt
Install on OpenSUSE Leap 15.2
The XRT packages can be installed on OpenSUSE 15.2 beta release.
To install XRT on OpenSUSE Leap 15.2 as root, complete the following steps:
1. Install the build packages, using the following command:
zypper install git gcc cmake make curl libressl-devel mbedtls-devel libcurl-devel lua- devel
2. Obtain an account name and password from the IOTech support portal
Note: In the following commands, replace
3. Download the IoT C Utilities .rpm package from the IOTech repository, using the following command:
curl -L -u "
4. Download the IOTech Thrift .rpm package from the IOTech repository, using the following command:
curl -L -u "
5. Download the XRT .rpm package from the IOTech repository, using the following command:
curl -L -u "
6. Download the Paho MQTT RPM package from the IOTech repository. For OpenSUSE, this must be done manually, as follows:
curl -L -u "
7. Download the libmodbus RPM package from the IOTech repository. For OpenSUSE, this must be done manually, as follows:
Install on RPM-based Systems 6 XRT Installation
curl -L -u "
8. Download the ethernet-ip RPM package from the IOTech repository. For OpenSUSE, this must be done manually, as follows:
curl -L -u "
9. Download the soem RPM package from the IOTech repository. For OpenSUSE, this must be done manually, as follows:
curl -L -u "
10. Install Paho MQTT, libmodbus, ethernet-ip, soem and XRT, using the following command:
rpm -i paho-c*.rpm modbus*.rpm ethernet-ip*.rpm soem*.rpm iotech*.rpm
Install on Photon 3.0
To install XRT on Photon 3.0 as root, complete the following steps:
1. Install the build packages, using the following commands:
tdnf remove -y toybox
tdnf install -y rpm gcc glibc-devel linux-api-headers binutils make git cmake go rpm- build openssl-devel curl-devel findutils sed lua-devel
2. Obtain an account name and password from the IOTech support portal
Note: In the following commands, replace
3. Download the IoT C Utilities .rpm package from the IOTech repository, using the following command:
curl -L -u "
4. Download the IOTech Thrift .rpm package from the IOTech repository, using the following command:
Install on RPM-based Systems 7 XRT Installation
curl -L -u "
5. Download the XRT .rpm package from the IOTech repository, using the following command:
curl -L -u "
6. Download the Paho MQTT RPM package from the IOTech repository. For Photon, this must be done manually, as follows:
curl -L -u "
7. Download the libmodbus RPM package from the IOTech repository. For Photon, this must be done manually, as follows:
curl -L -u "
8. Download the ethernet-ip RPM package from the IOTech repository. For Photon, this must be done manually, as follows:
curl -L -u "
9. Download the soem RPM package from the IOTech repository. For Photon, this must be done manually, as follows:
curl -L -u "
10. Install the mbedtls library. For Photon, this must be done manually, as follows: a. Clone the mbedtls package, using the following command:
git clone --recursive https://github.com/ARMmbed/mbedtls
b. Navigate to the directory containing the mbedtls package, using the following command:
cd mbedtls
c. Checkout the required version, using the following command:
git checkout tags/mbedtls-2.16.6
Install on RPM-based Systems 8 XRT Installation
d. Build and install the mbedtls package, ensuring that you include the relevant shared libraries, using the following command:
make install && make clean && export SHARED=true && make lib && make install
11. Install the Paho MQTT, libmodbus, ethernet-ip, soem and IOTech RPM packages, using the following command:
rpm -i --nodeps /paho-c*.rpm /modbus*.rpm /ethernet-ip*.rpm /soem*.rpm /iotech*.rpm
Install on RPM-based Systems 9 XRT Installation
Install on Alpine Linux-based Systems
To install XRT on Alpine Linux Systems as root, complete the following steps:
1. Install the IOTech repository key, using the following command:
wget https://iotech.jfrog.io/artifactory/api/security/keypair/public/repositories/alpine- release -O /etc/apk/keys/alpine.dev.rsa.pub
2. Add the IOTech repository, using the following commands:
echo "https://iotech.jfrog.io/artifactory/alpine-release/v3.13/main" >> /etc/apk/repositories apk update
Note: If using Alpine 3.12, replace v3.13 in this command with v3.12.
3. Install XRT, using the following command:
apk add iotech-xrt
Install on Alpine Linux-based Systems 10 XRT Installation
Install on ClearLinux-based Systems
To install XRT on ClearLinux as root, complete the following steps:
1. Install the build packages, using the following command:
swupd bundle-add dev-utils devpkg-openssl devpkg-curl devpkg-lua devpkg-paho- mqtt-c wget doxygen graphviz devpkg-sqlite-autoconf
2. Obtain an account name and password from the IOTech support portal
Note: In the following commands, replace
3. Download the IoT C Utilities tar ball from the IOTech repository, using the following command:
curl -L -u "
4. Download the IOTech Thrift tar ball from the IOTech repository, using the following command:
curl -L -u "
5. Download the XRT tar ball from the IOTech repository, using the following command:
curl -L -u "
6. Download the libmodbus tar ball from the IOTech repository. For ClearLinux, this must be done manually, as follows:
curl -L -u "
7. Download the ethernet-ip tar ball from the IOTech repository. For ClearLinux, this must be done manually, as follows:
curl -L -u "
8. Download the soem tar ball from the IOTech repository. For ClearLinux, this must be done manually, as follows:
curl -L -u "
Install on ClearLinux-based Systems 11 XRT Installation
"https://iotech.jfrog.io/artifactory/generic-release/clearlinux/soem-1.8.0_x86_ 64.tar.gz"
9. Install the mdedtls library. For ClearLinux, this must be done manually, as follows: a. Clone the mbedtls package, using the following command:
git clone --recursive https://github.com/ARMmbed/mbedtls
b. Navigate to the directory containing the mbedtls package, using the following command:
cd mbedtls
c. Checkout the required version, using the following command:
git checkout tags/mbedtls-2.16.6
d. Build and install the mbedtls packages, ensuring that you include the relevant shared libraries, using the following command:
make install && make clean && export SHARED=true && make lib && make install
10. Install the libmodbus, ethernet-ip and soem tar balls, using the following commands:
tar -xz -C / -f /modbus*.tar.gz tar -xz -C / -f /ethernet-ip*.tar.gz tar -xz -C / -f /soem*.tar.gz mv /*modbus* /usr/lib mv /*soem* /usr/lib mv /*ethernet-ip* /usr/lib
11. Install the IOTech tar balls, using the following commands:
mkdir -p /opt/iotech tar -xz -C /opt/iotech -f /iotech-iot-*.tar.gz tar -xz -C /opt/iotech -f /iotech-thrift-*.tar.gz tar -xz -C /opt/iotech -f /iotech-xrt-*.tar.gz mv /opt/iotech/iotech-iot* /opt/iotech/iot mv /opt/iotech/iotech-thrift* /opt/iotech/thrift mv /opt/iotech/iotech-xrt* /opt/iotech/xrt
Install for Zephyr RTOS
Zephyr projects are built for a specific target platform, architecture and set of features. This means that each project requires a custom build.
IOTech can support evaluation builds for QEMU, ACRN, and the ARM NXP FRDM-K64F board.
For further information contact IOTech Support, as described in the IOTech Support section of "About This Manual" on page iv.
Install for Zephyr RTOS 12 XRT Installation
Install for Azure Sphere
XRT is supported on micro-controllers running Microsoft Azure Sphere.
Azure Sphere applications are cross-compiled on either Ubuntu or Windows hosts, so XRT for Azure Sphere must also be installed on the development host.
Note: As all XRT Azure Sphere applications must be compiled on the development host, there is not a separate development package. The currently supported development hosts are Ubuntu 20.04 and Windows 10. For further information on building, deploying and integrating XRT with the Azure Cloud, refer to the XRT for Azure Sphere Guide.
Install on Ubuntu Development Host
To install XRT Azure Sphere, complete the following steps:
1. Install the Azure Sphere SDK. For further information on installing the Azure SDK on Ubuntu, refer to the Linux installation quickstart section of the Azure Sphere documentation 2. Install the packages, using the following command:
apt-get install lsb-release apt-transport-https curl gnupg2
3. Add the key for the IOTech repository, using the following command:
curl -fsSL https://iotech.jfrog.io/artifactory/api/gpg/key/public | apt-key add -
4. Register the IOTech repository, using the following command:
echo "deb https://iotech.jfrog.io/iotech/debian-release $(lsb_release -cs) main" | tee -a /etc/apt/sources.list.d/iotech.list
5. Update the repositories, using the following command:
apt update
6. Install XRT using the following command:
apt-get install iotech-xrt-azsphere7
Install on Windows 10 Development Host
To install XRT Azure Sphere, as root, complete the following steps:
1. Install the Azure Sphere SDK. For further information on installing the Azure SDK on Windows 10, refer to the Windows installation quickstart section of the Azure Sphere documentation
2. Download the XRT .zip package from the IOTech repository, using the following command:
Install for Azure Sphere 13 XRT License
curl -L -O https://iotech.jfrog.io/artifactory/windows-release/iotech-xrt-1.1.0.zip
3. Open Windows File Explorer
4. Select the downloaded .zip package and extract the files to the following location:
C:\Program Files (x86)\Microsoft Azure Sphere SDK\Sysroots\7
XRT License
You must obtain a license for XRT before you can use or test any XRT component, as XRT checks for licensing permission before instantiating any component.
To obtain an XRT license, which is a file called Xrt_license.lic, contact IoT Support.
When you have obtained the XRT license file you must ensure that XRT can locate the license in one of the following ways:
l Set the XRT_LICENSE_FILE environment variable to the absolute path to the license file, using the following command, where
export XRT_LICENSE_FILE=
l Copy the license file to the config directory used in your test
l Place the license file in the default installation location; that is, the /opt/iotech/xrt directory
Install for Azure Sphere 14 Test an Installation
Test an Installation
Before testing an installation, do the following:
l Copy the examples from the distribution
l If using the iotech-xrt-dev package and you have modified the example, build the example
l Obtain and install the license, as described in "XRT License" on page 14
As different systems install packages in different locations, you might need to update the env.sh file, which sets environment variables including PATH and LD_LIBRARY_PATH. If using the iotech-xrt-dev package, you might also need to update the Makefile.defs file to deal with variant library names or header inclusion paths.
You can then test an installation.
For example, you could test an installation as follows:
1. Load the env.sh file, using the following command:
source /opt/iotech/xrt/bin/env.sh
2. Copy the examples to a temporary directory, using the following command:
cp -R /opt/iotech/xrt/examples .
3. Navigate to the temporary directory, using the following command:
cd examples
4. If using the iotech-xrt-dev package, build the examples using the following command:
make
5. Navigate to the example you want to run, for example, to run the Container example enter the following command:
cd container
6. Run the XRT application, using the following command, where
xrt
Note: The [
For example, to use the container component configuration and run the test for five seconds, the commands are as follows:
15 Test an Installation
cd container xrt config 5
Note: The provided configuration data expects the test to be run from the location in which the config directory is available.
16
All products and company names listed are trademarks or trade names of their respective companies. All specifications are subject to change without further notice.