Overview

py-IoticAgent is the Python language client for Iotic Space. It enables a suitably authorised and authenticated Python program to connect to the space to share data - and to "find and bind" to receive data from other things.

It's designed to work in parallel with the UI at the Iotic Labs Developer Portal, so you can instantly see results from your agent code.

It provides two styles of interface:

• Synchronous - where your code blocks until the system has done what you asked before returning.
• Asynchronous - a more advanced style where your code doesn't block, since it issues commands and does other work before finally waiting on events that show the commands are complete.

Getting started

Once the agent's installed, the Agent documentation should get you started.

You will need a free Iotic Space developer account to get credentials for the agent's .ini file.

Building the docs

The online Agent documentation can also be built locally if you prefer. (See also sphinx-doc/README.md)

1. pip install -r sphinx-doc/requirements.txt
2. Run the make_docs.sh script to generate the docs.

System requirements

This agent requires Python 3.2+ or 2.7.5+ (with ssl module capable of TLS v1.2).

Security

Our PyPI releases are signed with the Iotic Labs software release signing key

Installing

• All examples use Python 3 commands but these should also work using the Python 2 equivalents.

Quick install with pip

This works on most Linux and BSD systems (see below for macOS), installing from PyPI. You may be able to omit the sudo if you have a user-installed pip.

sudo pip3 install py-IoticAgent

For Python 2, use sudo pip or pip2.

Mac install

Whatever your preferred version of Python on macOS, you must install it with Homebrew so it can use a recent version of OpenSSL - no sudo should be needed:

brew install python3
pip3 install py-IoticAgent

• For Python 2, use brew install python and pip
• To install brew, see the Homebrew site

Trying the agent

Now you can head to our getting started doc, which provides a simple 3-line 'minimal script' to check everything's working.

Possible issues

• For pip-related issues, first make sure pip and setuptools are up-to-date:

sudo pip install -U pip
# Upgrade afterwards due to potential pip change
sudo pip install -U setuptools

• If you do not have Python development headers and a C toolchain installed, this might produce warnings which can be safely ignored.
• With certain versions of pip, the installation of the py-ubjson dependency can fail when using -t flag. (Symptom: py-IoticAgent is installed but py-ubjson is not.) See this pip issue. In this case, force non-extension installation: PYUBJSON_NO_EXTENSION=1 pip3 install py-IoticAgent
• On macOS, non-Homebrew Python setups may encounter this error from the agent: Exception: At least SSL v1.0.1 required for TLS v1.2

Advanced: install from Git (development mode)

This is an alternative, if there's a specific change you need that's not in the pip version:

git clone https://github.com/Iotic-Labs/py-IoticAgent.git
cd py-IoticAgent
pip install -e .

Dependencies

The agent has both mandatory and optional dependencies - this only matters for the from-Git install:

• Mandatory py-ubjson to enable universal binary JSON
• Mandatory RDFlib to provide an RDF metadata handling API
• Mandatory enum34 (only for Python versions < 3.4)
• Optional regex re module replacement (for more accurate unicode validation)
• Optional py-lz4framed for faster compression (use lz4 extra target)