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
)
pip install -r sphinx-doc/requirements.txt
- 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
andpip
- 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)