Module description

About microspec

The microspec module is a wrapper to simplify using the API auto-generated by the microspeclib module. Applications should import microspec, not microspeclib.

About microspeclib

microspeclib provides an API for:

  • sending commands over USB to the Chromation Spectrometer dev-kit
  • receiving the responses to those commands

This API simplifies USB communication by hiding serial communication details from the application.

Internally, microspeclib auto-generates the API from a JSON file. This makes the API easy to modify at the expense of being user-friendly.

Changes introduced in the firmware are easily added to the API: just one JSON file to edit, one test suite to run, and one set of documentation to rebuild.

But this automation prevents customization. Rather than modify microspeclib and compromise automation, customization is added by building module microspec on top of microspeclib.

microspec – Make microspeclib user-friendly

Benefits of microspec to application developers

  • a more intuitive command interface:

    • commands have default parameter values

    • commands include helper functions

      • e.g., handle unit conversion internally
      • e.g., raise a Timeout exception if a command timeouts

  • a more intuitive response to commands:

    • responses use string names in place of integer codes

    • responses include additional attributes as conveniences

      • e.g., return exposure time with attributes ms and cycles to avoid doing the unit conversion in the application code

    • responses now have a __repr__()

      • eliminates the need to print() responses when working in a REPL

  • simple access to the names of the API global constants:

    • constants are top-level

      • e.g., microspec.MAX_CYCLES

  • a namespace that only goes one level-deep for:

    • a simpler/shorter/more-intuitive import statement: import microspec

    • reading documentation with pydoc

      • e.g., python -m pydoc microspec
      • e.g., python -m pydoc microspec.commands.Devkit.autoExposure

  • better documentation of the commands:

    • function signatures show type hints and default values

Benefits to API developers (contributors to microspec)

  • commands – wrap commands and responses, creating a seam to:

    • add custom code and docstrings to commands in microspec.commands
    • reformat the responses

  • replies – a place to add docstrings to responses

  • helpers – a place to add helper functions (reusable solutions to common application code problems)

  • constants – a place to:

    • add docstrings to constants
    • add new constants hard-coded in firmware (as opposed to directly editing the JSON config file)