Setting Up IoLT Devices

Setting Up IoLT Devices#

The AC Training Lab emphasizes not only repeatability, but also replicability. Solutions within the training lab should be chosen, designed, implemented, and documented with this in mind. In other words, if someone can take a look at something within the AC training lab and replicate it easily within their own lab with minimal frustration, the AC Training Lab is serving one of its most fundamental purposes. To achieve that, the following items are typically present when taking an Internet of Laboratory Things (IolT) device and demo from start to finish.

GitHub Issues#

Core tasks and sub-projects will be tracked using the AC Training Lab GitHub issues. See for example setting up the OT-2 liquid handler and RS232 control of digital scale. Many of these will also be surfaced to the corresponding GitHub Project (private) and any applicable training lab milestones.

Pull Requests#

When you start writing some code for a device, create a new branch and open a draft pull request (PR) pointing to the training lab repo main branch. AC Training staff will have write access to anything other than the main branch, so if this applies to you, you can simply clone the repo and create a new branch. Youā€™re welcome to fork the repo if thatā€™s more straightforward for you. These PRs make it easier to have tight feedback cycles. See for example mycobot 280 implementation.

MWE for functionality#

Typically, these go into a src/ac_training_lab/*/_scripts folder. This also makes it easier to iteratively develop (start with basic functionality of the device, gradually work towards the full implementation with MQTT). You can check out some examples of _scripts folders for the digital pipette, fan control, and magnetometer demos.

Accelerated discovery post#

This is used as a sort of ā€œtravel logā€ of work on the project. This one is more public facing, and easier for others to look at and contribute discussion to (easier than GitHub for those who are unfamiliar with GitHub). Check out the examples. Periodic updates should be provided.

MQTT orchestrator and device code#

This enables hardware/software communication over WiFi. Typically, this will follow closely to https://ac-microcourses.readthedocs.io/en/latest/courses/hello-world/1.4-hardware-software-communication.html and the companion notebook tutorial. See below for some examples (both orchestration and device code).

Orchestration

Device

Please upload the device code to an appropriate directory (you may need to create a new one) within AccelerationConsortium/ac-training-lab. For MicroPython implementations, please include a main.py that should be run by the user and any dependencies that are required in a lib subdirectory. For non-MicroPython implementations (e.g., Python), please include a device.py (meant to be run by user), __init__.py, and requirements.txt file. You can include other modules at the same level as device.py or in subdirectories of your choice (e.g., utils, donā€™t use lib so that we can avoid confusion). Special instructions can go in a README.md file.

Prefect workflow orchestration#

Prefect is a workflow orchestration platform that can be used as an alternative or complement to MQTT-based orchestration for laboratory automation.

Setup#

  • Account setup: Create a free account at app.prefect.cloud

  • Authentication: Use prefect cloud login with a non-personal worker account for interactive setup or see the official connection guide

  • Additional setup resources: See GitHub issues #109, #250, and #408 for lab-specific setup discussions

Repository examples#

Prefect integrates with MQTT, MongoDB, Hugging Face Spaces, and hardware devices. For detailed documentation, see docs.prefect.io.

MongoDB logging setup#

Typically, anything with data and timestamp-based actions will be logged to a database. These implementations will usually follow closely to https://ac-microcourses.readthedocs.io/en/latest/courses/hello-world/1.5-data-logging.html and the companion notebook.

Hugging Face Spaces#

Each demo will typically have a streamlit app hosted on Hugging Face Spaces within the Acceleration Consortium organization under a hardware control list.

Some additional context is available at https://ac-bo-hackathon.github.io/resources/ (scroll to bottom).

Watch the two-minute video about hugging face spaces [docs]:

Likewise, watch a follow-up video about contributing to a Hugging Face Spaces repository from within VS Code:

Next, explore the code (see ā€œfilesā€ tab) in the ACā€™s various hardware control apps: https://huggingface.co/collections/AccelerationConsortium/hardware-control-66a4506f9876e9781c8a0808. New web apps will live next to these in the same list.

In particular, the light-mixing app is an example of sending a command and receiving a single set of sensor data. The Digital Pipette app is an example of sending a command without feedback or a response. The fan control app is an example of sending a command and receiving a continuous flow of data back.

In general, you should cache the MQTT client to avoid creating a new connection every time a button is clicked.

# Singleton: https://docs.streamlit.io/develop/api-reference/caching-and-state/st.cache_resource
@st.cache_resource
def create_paho_client(tls=True):
    client = mqtt.Client(protocol=mqtt.MQTTv5)
    if tls:
        client.tls_set(tls_version=mqtt.ssl.PROTOCOL_TLS_CLIENT)
    return client

Paho MQTT is the preferred MQTT package. Generally, you wonā€™t need threading or asynchrony, and these donā€™t work well with the Streamlit package anyway, which is primarily designed for synchronous code.

The AC Training Lab apps typically have public test credentials given, but depending on the hardware and broker being used (e.g., the ACā€™s HiveMQ Starter Plan broker to allow for temporary access control), the credentials should be accessed via Hugging Face Spaces secrets.

Video demo#

Some examples:

Video setup tutorial#

Examples:

Docs page and tutorial (BoM, setup, etc.)#

To be added as a device page. More examples to follow.

Examples:

Embedding into Gather Town#

The AC Training Lab has recently become virtual šŸ˜Ž. After running the Bayesian optimization hackathon in March 2024 using https://www.gather.town/, I decided I would give it a try for the AC Training Lab. The devices have embedded Streamlit web apps hosted on Hugging Face Spaces (see below). The physical hardware shown here are typically set up in Toronto, ON, with plans to add interfaces to communicate with hardware in other locations.

../_images/gather-town.png

You can check the space out yourself by clicking on the invite link below. If you find something not working or have a suggestion, please feel free to open an issue.

Invite link: https://app.gather.town/invite?token=Ob0RdnDDQ2u0IbA1r674

Password: japanese-envelope-spoken (subject to change in case access needs to be refreshed for some reason)

You can add create sprites for new Gather Town ā€œdevicesā€ using the following steps:

  1. Snap a picture of or find an online image of the physical hardware and save to AccelerationConsortium/ac-training-lab

  2. Use the Adobe Express background remover on the image and save to AccelerationConsortium/ac-training-lab with -bg appended to the filename (e.g., mycobot-280.png ā€“> mycobot-280-bg.png).

  3. Use https://giventofly.github.io/pixelit/#tryit to create the pixelated image (may need to play around with the settings)

    • Each block is 32 pixels2, and you can set the max width and max height settings as needed (see below)

    • For larger devices or devices with more detail that you want to expose, you can take up multiple ā€œblocksā€ within Gather Town

    • Try not to take up more than a 2x2 grid

../_images/pixelit-interface.png

See the Gather Town instructions for adding custom objects.

Finally, enter a short name for the device in ā€œPrompt Messageā€ under advanced settings for the object. This is what users will see pop up when they go nearby the device.

image