ZWO EFW filter wheel library

This is a Python library for interacting with a ZWO EFW filter wheel over USB. The EFW family of filter wheels can only be communicated to via USB, and so this library wraps the official ZWO EFW dynamic library (.dll on Windows and .so on macOS and Linux) with Python's foreign-function interface, using the built-in ctypes library. From there, it exposes a clean interface for interacting with the filter wheel in Python that requires no underlying knowledge of the EFW's dynamic library wrapping and USB communication. For an example of how to use the library, see the Example use section.

The library is configured as a Poetry library and can be pulled in directly from the GitHub repository by running the following command:

poetry add git+https://github.com/mit-kavli-institute/python-zwo-efw-filter-wheel.git#main

This pulls in the latest revision from the main branch. See the Poetry docs for adding a library for more information. The library is not currently published to a Python package server.

Example use

The following is a shortened example, in order to highlight just the main library interface, from the more complete example.py script.

import time
from zwo_efw import EFW, EFWInformation

efw = EFW()

try:
    # Initialize communication to any EFW filter wheels that are connected
    efw.initialize()

    # Get the information for all the filter wheels that were identified
    filter_wheel_information: list[EFWInformation] = efw.filter_wheel_information

    # Get the first available filter wheel
    filter_wheel: EFWInformation = filter_wheel_information[0]

    # Cycle through all the slots in the filter wheel once
    for current_slot in range(1, filter_wheel.NumberOfSlots + 1):
        efw.move(filter_wheel.ID, current_slot)

        # Wait until the filter wheel has finished moving to the commanded slot
        while efw.is_moving(filter_wheel.ID):
            time.sleep(0.5)

        # Wait 1 second before the next move
        time.sleep(1)

finally:
    efw.close()

You can also run a poetry script via poetry run move --id <id> --slot <slot> to test out and use the library.

Dependencies

Windows

There are no additional dependencies needed on Windows.

Linux

1. On Linux, the libudev library must be installed.

   • For Ubuntu, this can be installed via:

     sudo apt-get install libudev-dev -y

   • On a RaspberryPi, this can be installed via:

     sudo apt-get install libudev-dev -y

   For other distributions, you will need to find the package that needs to be installed to make the libudev.so library be available in the $PATH.

2. Run sudo install efw.rules /lib/udev/rules.d

   • From the root of this repository, the efw.rules file is found at zwo_efw/efw_sdk/EFW_SDK/EFW_linux_mac_SDK_V1.7/lib/efw.rules. See the README at zwo_efw/efw_sdk/EFW_SDK/EFW_linux_mac_SDK_V1.7/lib/README.txt.

   • If this step is not taken, then you will get the EFW_ERROR_REMOVED error code when trying to open the filter wheel during the EFW.initialize method.

macOS

There are no additional dependencies for macOS (but note that Apple silicon is not supported due to limitations of the ZWO EFW SDK).

Supported operating systems and platforms

In general, this library is intended to support every operating system and platform that the ZWO EFW SDK supports. However, there are limitations in the amount of platforms that can be easily tested since virtual machines and Docker containers are not enough since we need to be able to test the OS and platform against a real filter wheel. Also, some platforms, namely Linux, are incredibly difficult to test across the various permutations. So, the table below lists off the platforms that this library has been tested against. The table does not exhaustively list all platforms that are intended to be supported.

OS	Platform	Intention to support	Tested
Windows 11	64-bit x86	✔️	✔️
macOS	Apple silicon	❌	❌
macOS	x86	✔️	✔️
Ubuntu	64-bit x86	✔️	✔️
RaspberryPi	armv7	✔️	✔️

If you are encountering issues with a platform that is supported by the ZWO EFW SDK, then please file a GitHub issue. In that issue, please provide what the function debug_efw_sdk_library_loading in the zwo_efw.debug module prints out to the console. This will help more quickly narrow down the source of the issue. If you have the repository cloned locally, then the function can be ran by executing poetry run python zwo_efw/scripts/debug.py. With the information printed out by that script, it should be fairly straightforward to add in support for the target OS and platform.