Installation

You can install this package from pip:

pip install pzp-hardware

If you would like to develop your own Pieces and contribute changes to this library, you may choose to clone the repository instead, and install a local, editable copy:

git clone https://github.com/jdranczewski/pzp-hardware.git
cd pzp-hardware
pip install -e .

Once installed, you can use the Pieces provided like you would any other Piece in puzzlepiece:

import puzzlepiece as pzp
from puzzlepiece.extras import hardware_tools as pht
from pzp_hardware.thorlabs import camera, apt_stage

# Create a Qt app, the backend that will run our GUI
app = pzp.QApp()

# Create a Puzzle, the main window of the application.
# We prompt the user whether they want to launch in debug mode, which doesn't talk to hardware.
# We use the Puzzle as a context manager, so that if any of the Pieces raise exceptions while
# being added, the Puzzle can clean up other APIs and exit cleanly.
with pzp.Puzzle(name="Test", debug=pht.debug_prompt()) as puzzle:
    puzzle.add_piece("camera", camera.Piece, row=0, column=0)
    puzzle.add_piece("stage", apt_stage.Piece, row=0, column=1, param_defaults={
        "serial": 1234 # you can provide default values for the params during setup
    })

# Display the Puzzle and execute the Qt app
puzzle.show()
app.exec()

Check out Getting started for more details!

Structure

The library consists of a number of manufacturer folders, each containing Python files that each interface with a specific hardware/software provided by that manufacturer. The library contains all files on installation, but they need to be specifically imported, so that you never have to import the full library, just the parts you require:

from pzp_hardware.thorlabs import camera, apt_stage
from pzp_hardware.vialux import dmd

See Modules for all currently supported hardware.

Development and contributing

Puzzlepiece provides a unified API for all of your devices, so the best laboratory automation experience is if you have Pieces for all of your hardware. If your hardware is not supported by pzp-hardware, you can create a Piece yourself – puzzlepiece aims to make that as easy as possible! You can create a fork of the main repository, install it locally as shown above to allow development, and we welcome pull requests adding support for new hardware.

Your Piece should broadly follow the same conventions as the ones currently in the repository. For example, image-based Pieces like cameras, DMDs, or SLMs should have an image param, allowing you to use the standard preview layouts provided in pzp_hardware.generic.mixins.image_preview. Your Piece should work reliably in debug mode to allow testing. You can use puzzlepiece.extras.hardware_tools to make integration with manufacturer APIs and DLLs easier, and in particular you should indicate requirements specific to your Piece with puzzlepiece.extras.hardware_tools.requirements (these are automatically parsed to appear in this documentation).

Documentation is key to your users being able to find, install, and use the Piece. Pull requests that don’t include at least basic documentation for the new Piece will not be merged. Documentation should be included in your Piece’s Python file, mostly as a docstring at the top, with docstrings in the Pieces that you want exposed in the docs. It’s also recommended to include a screenshot of your Piece, but an explicit list of params is not required, as the user can inspect this in debug mode. Check out the Piece file template on GitHub .