User Tutorial

This tutorial is an introduction to using the RPi-DeviceAdapters Docker-based application. The application is built around the Micro-Manager Python wrapper and will show you how to run a simple script that communicates with the Micro-Manager core.

The steps in this tutorial should be executed either in a terminal running directly on a Raspberry Pi or through ssh. It is assumed that the Raspberry Pi is running a recent version of the Raspbian operating system, though the steps listed here may work on other Linux-based operating systems as well.

Prerequisites

Begin by opening a terminal window (also known as a shell).

If you do not already have Docker installed on your Raspberry Pi, you may install it by running the command:

$ curl -sSL https://get.docker.com | sh

Follow the steps described in the installation script. After the installation has finished, you may optionally add your user to the Docker group so that you do not need to enter sudo before running Docker commands.

$ sudo groupadd docker
$ sudo usermod -aG docker $USER

Log out and log back in for the changes to take effect.

You will also likely want to grab the venv package for Python from the Raspbian package manager.

$ sudo apt-get install python3-venv

Create a new virtual environment for the application to isolate it from the rest of your system:

$ python3 -m venv ~/venvs/mm

~ corresponds to your home folder; you may instead replace ~/venvs/mm with any directory that you wish. Next, activate the virtual environment:

$ source ~/venvs/mm/bin/activate

You should see the name of the venv (in this case, mm) at the start of the command line. Whenever you want to stop working on the project, type deactivate. To reactivate the venv, simply rerun the command above.

Installation

To install RPi-DeviceAdapters into the venv, run the following command:

$ pip install tacpho.adapters

It will be assumed throughout the rest of this tutorial that you have added your user to the Docker group. (See the previous section for details.)

Next, download the latest Docker image of the application:

$ mm.py pull

This command may take several minutes before it completes as it downloads the application from DockerHub. mm.py is a convenience script for interacting with RPi-DeviceAdapters’ Docker resources. To see its help message, type

$ mm.py --help

Execute a script

Open your text editor and enter the following code:

import MMCorePy

mmc = MMCorePy.CMMCore()
mmc.loadDevice('tutorial', 'RPiTutorial', 'RPiTutorial')
mmc.initializeAllDevices()

print(mmc.getProperty('tutorial', 'Switch On/Off'))

mmc.setProperty('tutorial', 'Switch On/Off', 'Off')
print(mmc.getProperty('tutorial', 'Switch On/Off'))

Save the text to a file named tutorial.py. This is just a short Python script that uses the Micro-Manager Python API to load the tutorial device adapter. It will report the value of a “switch”, flip its value, and then print the new value.

To run the tutorial, enter the following command from the same folder that contains the script you just saved (be sure that the virtual environment in which you installed tacpho.adapters is active).

$ mm.py run tutorial.py

You should see the output from the script appear in your console.

Next steps

Example scripts for other device adapters may be found in the examples folder of the RPi-DeviceAdapters root directory. Check out the Micro-Manager documentation on its Python interface for more information about interacting with the Micro-Manager core.

Do not forget to update the RPi-DeviceAdapters application when new versions and device adapters become available by running mm.py pull.