Treehopper Python API
|
Treehopper requires Python 3.6 or later. This is not a particularly new version of Python (it has already been superseded by 3.7), but some regular Python users are still using Python 3.5.
While Linux and macOS often come with Python installed, these can sometimes be quite ancient. To check which version you have, invoke:
If you don't already have a Python setup, we recommend installing the Anaconda distribution.
On Windows and macOS, it's a standard installer you can click through to install. By the way, you can choose to install Anaconda during the Visual Studio 2017 installation process, so you may already have an installation.
On Linux, it's a text-mode shell script. To invoke it, give it executable permission before running it:
In Linux and Windows, you can optionally add Anaconda to your PATH when prompted. This will make it easier to execute, but will shadow a potentially existing Python distribution. On Mac, Anaconda is automatically added to your PATH.
This Getting Started guide will assume you're using Anaconda (with the base
environment), but you can loosely follow along if you have another 3.6 distribution.
We need a terminal prompt with Python and pip on its path. Assuming you're using Anaconda, we'll need to launch on Anaconda environment.
source /anaconda3/bin/activate base
. If you prefer, you can also launch Anaconda Navigator, go to Environments, click on the arrow next to base (root), and choose Open Terminal.source anaconda3/bin/activate base
if Anaconda is not already in your path.You can verify your installation in Windows:
or on macOS or Linux:
The Treehopper Python package is hosted on PyPI, so we'll use pip
to install it:
If you don't have write permission, this will fail with a PermissionError
. On macOS or Linux, run the command with sudo
. On Windows, make sure you started the Anaconda Prompt with Run as administrator.
By default, most Linux-based operating systems restrict normal users from interacting with USB devices. To enable non-root users to interact with Treehopper boards, you must add a udev rule.
Paste and run this quick snippet into a terminal window:
Verify the rule was created:
Note that, for some distributions, sudo
may not be configured to allow this. You can launch a root shell and repeat the command.
Let's start an interactive Python shell and manually connect to a board and turn on its LED.
Launch python
on Windows, or python3
on macOS or Linux (python
will also alias to python3
if you're in an Anaconda prompt).
Type (or copy and paste) each of these commands, one by one (you don't need to include the comments, of course):
All of Treehopper's capabilities can be used from an interactive Python shell like this, which makes the Python package an invaluable tool for diagnosing and debugging.
Open a text editor and paste these contents in:
Save the file as blinky.py in your home directory, return to your command prompt, and execute it:
Notice that the script exits immediately once you unplug the board. While Treehopper's Python API doesn't support hotplug detection, it does support hotplug removal notification via the board.connected property.