Skip to content

Resources¤

Resources are custom classes for interfacing with specific equipment. In previous releases of msl-equipment (versions < 1.0), the resources were automatically bundled with msl-equipment. As of v1.0, the resources are maintained in another package, msl-equipment-resources, that must be installed separately.

Some of the resources might not work in your application because the resource might depend on an external dependency, e.g., the Software Development Kit (SDK) provided by a manufacturer, and this external dependency might not be available for your operating system.

Examples

There are examples on how to use the resources in the repository.

Attention

Companies that sell equipment that are used for scientific research are identified in this guide in order to illustrate how to adequately use msl-equipment-resources in your application. Such identification is not intended to imply recommendation or endorsement by the Measurement Standards Laboratory of New Zealand, nor is it intended to imply that the companies identified are necessarily the best for the purpose.

Install¤

msl-equipment-resources is currently only available for installation from source. It can be installed using a variety of package managers.

pip install msl-equipment-resources@git+https://github.com/MSLNZ/msl-equipment#subdirectory=packages/resources

uv add msl-equipment-resources@git+https://github.com/MSLNZ/msl-equipment#subdirectory=packages/resources

poetry add msl-equipment-resources@git+https://github.com/MSLNZ/msl-equipment#subdirectory=packages/resources

pdm add msl-equipment-resources@git+https://github.com/MSLNZ/msl-equipment#subdirectory=packages/resources

Create a resource¤

To create a new resource you must create a class that inherits from Interface and specify the manufacturer and model number (product series) that the resource can be used for. This inheritance may also be acquired by sub-classing from one of the interface protocols (see also Multiple interfaces).

The following example shows how to create a new resource for equipment that use the RS-232 protocol for communication. The values specified for the manufacturer and model support a regular-expression pattern.

# my_resource.py
from __future__ import annotations

from msl.equipment import Equipment, Serial

class MyResource(Serial, manufacturer=r"Company Name", model=r"ABC"):

    def __init__(self, equipment: Equipment) -> None:
        """My custom resource.

        Args:
            equipment: An `Equipment` instance.
        """
        super().__init__(equipment)

    def do_something(self) -> None:
        self.write("The command to write to the equipment")

When my_resource is imported, the MyResource class is automatically registered as a resource that will be used when connecting to the equipment if the values of manufacturer and model match the specified regular-expression pattern.

Contribute a resource¤

Important

As an ISO/IEC 17025 accredited laboratory, the resources in the repository are part of the Quality Management System of MSL. As such, contributions from people outside of MSL may be considered but the equipment must be available to MSL staff for the code to be checked and validated.

When adding a new resource to the repository the following steps should be performed.

uv is used as the package and project manager for msl-equipment development, it is recommended to install it. mypy and basedpyright are used as type checkers, ruff is used as the formatter/linter and the documentation is built with MkDocs using the Material theme and the mkdocstrings-python plugin. Installation of these packages is automatically managed for you by uv. CSpell provides spell checking and can be installed by running npm install -g cspell@latest (which requires Node.js and npm to be installed).

  1. Create a fork of the msl-equipment repository.

  2. Resources are located in the packages/resources/src/msl/equipment_resources directory. A sub-directory is the name of the manufacturer of the equipment. If the manufacturer directory does not exists for the new resource, create it (also create an __init__.py file in the manufacturer directory).

  3. Create a new Python file within the manufacturer directory with a filename that represents the model number or product series of the equipment that the resource is used for. Follow the example in Create a resource to implement the resource class in this file.

  4. Import your resource class in the packages/resources/src/msl/equipment_resources/MANUFACTURER/__init__.py and the packages/resources/src/msl/equipment_resources/__init__.py modules and alphabetically add the class to the __all__ variable.

  5. Add at least one example on how to use the resource to the packages/resources/examples directory. Create a new manufacturer sub-directory if it does not already exist.

  6. From the packages/resources directory, lint uv run ruff check, format uv run ruff format and type check uv run basedpyright, uv run mypy . the code. These checks are also performed once you do Step 12. Type checking with mypy requires the MYPYPATH=src environment variable to be defined to fix the Source file found twice under different module names issue.

  7. If you are able to create a test for the new resource, that does not depend on the equipment being attached to a computer, add a test to the packages/resources/tests directory. Run uv run pytest to verify the tests pass.

  8. To add the resource to the documentation, create a new Markdown file in the docs/resources directory. The format follows the docs/resources/MANUFACTURER/MODEL.md structure. Also, add the new resource, alphabetically, to the nav: → Resources: → MANUFACTURER: section in the mkdocs.yml file. Follow what is done for the other resources.

  9. Update CHANGELOG.md stating that you added this new resource.

  10. From the root directory of the repository, build the documentation uv run mkdocs serve and check that your resource renders correctly.

  11. Run the spell checker cspell .. Since this step requires Node.js and npm to be installed, you may skip it. This check is also performed once you do Step 12.

  12. If running the tests pass and linting, formatting, type/spell checking and building the documentation do not show errors/warnings then create a pull request.

Multiple interfaces¤

If the equipment supports multiple interfaces for message-based protocols (e.g., Socket, Serial, GPIB, ...) you can create a resource that inherits from the MultiMessageBased class. Upon calling super in the subclass, the connection is established with the appropriate protocol class.