Core IOTile Tools

• Core IOTile Tools
• Build Status
  • Core Packages
  • Built-in Device Transport Protocols
• Installation
  • from PyPI
  • for development
• Working with Encrypted Device Data
• Installing Support for IOTile Based Devices
• Continuous Deployment
• Manually Releasing
• Contributing
• Code of Conduct
• License

This repository contains the basic infrastructure needed build and interact with IOTile based devices. It is divided into a set of python packages that work together to create an extensible but easy to use framework that supports any IOTile device.

Read the latest Documentation!

Build Status

Core Packages

These are the building blocks that make up CoreTools. Depending on your particular use case, you may need just one of them or you may use them all.

Tool	Description	PyPI Version
iotile-core	The central package of CoreTools, includes the core plugin architecture and device communication system
iotile-build	A build system for creating IOTile device firmware that is controllable from CoreTools
iotile-gateway	A multi-user, multi-device transparent proxy for IOTile devices
iotile-sensorgraph	A simulator for the embedded sensorgraph engine included in some IOTile device firmware
iotile-emulate	A complete set of emulation tools for emulating physical iotile devices
iotile-ship	A manufacturing tool that lets you define repeatable recipes to bring up IOTile based hardware at a factory
iotile-test	Internal test harnesses and mocks to test the rest of CoreTools and applications built using CoreTools
iotile-ext-cloud	A CoreTools-like wrapper for interacting with IOTile.cloud, a cloud based device management system that works well with IOTile based devices

Built-in Device Transport Protocols

CoreTools is inherently agnostic in how it connects to an IOTile Device. Many physical IOTile devices use Bluetooth Low Energy to communicate with the external world but this is not an intrinsic assumption of how CoreTools works.

The currently included protocols are shown below.

Tranport Plugin	Description	PyPI Version
iotile-transport-nativeble	Connects to IOTile devices over BLE using the cross-platform baBLE project to use your computers native bluetooth stack
iotile-transport-websocket	Connects to IOTile devices over websockets
iotile-transport-bled112	Connects to IOTile devices over BLE using the BLED112 USB dongle by Silicon Labs
iotile-transport-jlink	Connects to an IOTile device using a physical SWD debug connection through a Segger JLink emulator

Installation

from PyPI

The core set of tools is divided into three pip installable packages

pip install iotile-core iotile-emulate iotile-transport-bled112

If you also wish to use the IOTile build system to build IOTile components, you should also install IOTile-Build

pip install iotile-build

If you want to use the IOTile testing tools (necessary for testing CoreTools among other uses,

pip install iotile-test

for development

You can install any given package if you have the repository cloned locally in the normal way. For example, to install a development (i.e. master / your branch tip) of iotile-core:

pip install -e coretools/iotilecore

Working with Encrypted Device Data

If your devices are configured to protect the report data that they produce, you need to install pycrypto in order to CoreTools to be able to decrypt report data. This is only necessary to view encrypted report data and, obviously, also requires that you have access to the device in question's signing key.

Pycrypto can be installed using:

pip install pycrypto

If you are running on Windows, you may not have a compiler installed that is able to compile the PyCrypto package. Microsoft provides a free compiler that is easily installed here.

Installing Support for IOTile Based Devices

CoreTools just gives you the framework to interact with IOTile based devices. In order to control any given IOTile device, you need to also install a support package that contains support for that device. Support packages extend CoreTools to provide support for specific tiles.

There are currently no publicly available support packages, so please contact Arch to get access to private support packages.

Continuous Deployment

Automatic release to pypi is handled by Travis CI every time a new tag is created on the master branch. The tags must have a specific naming format:

<distribution_name>-<version>

Where <distribution_name> is the name of a specific component of CoreTools. Currently, the known components are:

iotilecore
iotilebuild
iotilegateway
iotiletest
iotilesensorgraph
iotileemulate

iotile_transport_bled112
iotile_transport_awsiot
iotile_transport_nativeble
iotile_transport_jlink
iotile_transport_websocket

The version must match the version that is encoded in version.py in the corresponding python distribution to be released and is checked in the release.py script before attempting to release.

Manually Releasing

Releasing new builds to pypi is handled by the scripts/release.py script. The script should be called with one argument, which is the name and version of the distribution being released.

First, make sure all build requirements are satisfied:

> pip install -r build_requirements.txt

Then, release (for example iotilecore-X.Y.Z) using

> python scripts/release iotilecore-X.Y.Z

You need to have the following environment variables set correctly with pypi and slack secrets:

PYPI_USER
PYPI_PASS
SLACK_WEB_HOOK

Contributing

If you are interesting in contributing to CoreTools, please see the Contributing guide!

Code of Conduct

Please familiarize yourself with our Code of Conduct

License

This software is released under the terms of the LGPL v3 license. It includes pieces that are distributed under the terms of their own licenses. A list of included 3rd party software is described in the README files for each component of IOTile CoreTools.