Getting Started

CoreTools is distributed using normal pip installable packages on PYPI. It is recommended that you install everything in a virtual environment since CoreTools is highly extensible and the IOTile devices you interact with may require plugins or extensions that should not pollute your global site-packages.

Note

On Windows you may need to install Python 3.6+ since it does not come preinstalled. Any distribution should work but CoreTools is tested using the official Python for Windows distribution running under PowerShell.

Installation Requirements

CoreTools is cross-platform and is tested on Mac OS, Linux and Windows. It currently requires Python 3.6+.

Note

It is recommended to always install coretools into a virtual environment. This allows you to separate any plugins that you may install on top of CoreTools on a project by project basis:

pip install virtualenv
virtualenv --python=python3.8 iotile

#On Mac/Linux
source iotile/bin/activate

#On Windows Powershell
iotile/Scripts/activate.ps1

#On Windows CMD
iotile\Scripts\activate.bat

Note that virtualenv only needs to be installed once; iotile must be activated in a every new virtual enviroment.

Installing CoreTools is just a normal pip install:

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

See also

If you plan on building your own IOTile device, you should also install iotile-build but there are additional requirements to use iotile-build that must be installed separately, see Build Requirements.

First Steps

The easiest way to try out your new CoreTools installation is by using the iotile tool that is installed as a console script by iotile-core.

The iotile tool provides command line access to key parts of the IOTile API. It allows many tasks to be performed without writing python scripts.

Note

Everything that you can do with the iotile tool, you can also do from a python script. This makes the iotile tool an ideal way to perform quick tasks that you could then wrap up into a script later if you find yourself doing the same thing repeatedly.

Let’s get started by trying to talk to an IOTile device. Let’s say you have a simple piece of IOTile based hardware and you want to connect to it and send it commands. In this example we’re going to be using a virtual IOTile device that doesn’t require any physical hardware but the process to talk to a real device is exactly the same:

iotile hw --port=virtual:simple
(HardwareManager) quit

By using the iotile hw command, we’re attempting to connect to an IOTile Device. In this case we’re telling the tool that we want to connect to a virtual device using the virtual port. The remaining argument tells the tool which installed virtual device we would like to load. The quit command always quits the shell.

Like a normal shell, we can use <TAB> to see a list of supported commands:

iotile hw --port=virtual:simple
(HardwareManager)
app                  controller           enable_broadcasting  help                 watch_reports
back                 count_reports        enable_streaming     quit                 watch_scan
close                debug                enable_tracing       reset
connect              disconnect           get                  scan
connect_direct       dump_trace           heartbeat            watch_broadcasts

At this point, we have not connected to the simple device yet, so let’s connect directly to it:

(HardwareManager) connect_direct 1

Since this is an example device, it has a hard-coded unique identifier of 1. In real life, devices would have their unique identifiers set at the factory and printed on the device.

Now that we have connected to the device, we can send it commands. Every IOTile Device has one component that acts as a Controller and handles communication with the external world. We can get access to this device’s controller using the controller command:

(HardwareManager) controller
(SimpleProxy) <TAB>
back              config_manager    help              reset             tile_name         tile_version
check_hardware    hardware_version  quit              status            tile_status

Notice how the prompt changes to indicate what context we’re in. When we typed controller we moved from the HardwareManager context to the SimpleProxy context that is a python representation (or Proxy object) for the physical controller hardware that we are talking to.

Note

When you are talking to an IOTile device, commands that you enter are sent to the IOTile Device as Remote Procedure Calls (RPCs) and the response from the device is routed back to you and displayed. This means that the iotile tool effectively becomes a REPL for your IOTile Device.

The only commands that are supported by the simple device are RPCs to query its name, version and status, so lets try those:

(SimpleProxy) tile_name
Simple
(SimpleProxy) tile_version
[1, 0, 0]
(SimpleProxy) tile_status
configured: True
debug_mode: False
app_running: True
trapped: False
(SimpleProxy)

The results of each command are printed in the console for you. We can see that this device is named ‘Simple’ and has version 1.0.0. It’s reporting its status as configured and running with no errors and not currently in debug mode.

Writing Scripts

Every action you take in the iotile tool maps 1:1 to exactly one python function or method. So it’s easy to take something that’s done in the iotile tool and turn it into a python script. For example, lets create a script that connects to the same device we just used in First Steps and gets its version:

from iotile.core.hw.hwmanager import HardwareManager

with HardwareManager(port='virtual:simple') as hw:
    hw.connect_direct('1')
    con = hw.controller()
    version = con.tile_version()

    print("Tile Version: {}".format(version))

Save this script as example.py and let’s run it:

python example.py
Tile Version: (1, 0, 0)

Clearly, this code creates a hardware manager and finds the version number. The manager is instantiated in the with-as statement. The following 3 lines connect, gain control, and find the version respectively.

Note how every command in the script mapped to a single line in iotile and how the arguments you passed were the same. There is always a 1:1 mapping like this between the iotile tool and python scripts.

That’s it, you now know the basics of using CoreTools to interact with IOTile Devices and transform iotile shell commands into python scripts.