microspec 0.1.1a5

Python API for the Chromation spectrometer dev-kit

MicroSpec Overview

Package microspeclib is a Python API for the Chromation spectrometer dev-kit.

The microspec project also includes:

• command line utility microspec_cmdline for running basic measurements without developing a Python application
• an emulator (Mac and Linux only) for faking the dev-kit hardware in unit tests

Spectrometer Hardware

The Chromation spectrometer is a surface-mount PCB package consisting of a linear photodiode array and optical components.

The Python API communicates with firmware on the two microcontrollers in the dev-kit, one on each of the stacked PCBs.

• The microcontroller on the bottom of the stack provides a SPI interface to the Chromation spectrometer.
• The microcontroller on the PCB stacked above provides a USB bridge that turns the SPI interface into a USB interface.

microspeclib accesses this USB interface using pyserial.

Install the Python API

Install the microspec project with pip:

$ pip install microspec

To extend/customize/repurpose the API, clone the repository from the project homepage: https://github.com/microspectrometer/microspec and install in --editable mode.

Windows Load VCP

On Windows, when connecting the dev-kit for the first time:

• Open Device Manager:
  • right-click on USB Serial Converter
  • select Properties
  • go to tab "Advanced"
  • check "Load VCP"
  • cycle power to the dev-kit (unplug/plug the USB cable)

Now "Load VCP" is enabled every time the dev-kit is connected to this Windows computer.

If "Load VCP" is not enabled, pyserial cannot communicate with the dev-kit and microspec will report that it does not see a connected USB device.

Install extra requirements for testing and documentation

Developers may want to install additional packages required for running unit tests and rebuilding documentation.

1. Unit tests require pytest and tabulate. Install these by adding [test] to the install command:

$ pip install microspec[test]

2. Many unit tests use the emulator. The emulator requires psutil. Install this by adding [emulator] to the install command:

$ pip install microspec[emulator]

The emulator also requires the utility socat, which is only available for Mac and Linux.

3. The documentation is built with Sphinx. Developers extending the API will need to rebuild the documentation. Install the Sphinx-related requirements by adding [dev] to the install command:

$ pip install microspec[dev]

Use the Python API

Import the API in a Python script or at a Python REPL:

>>> from microspeclib.simple import MicroSpecSimpleInterface

The API is a set of commands for configuring the spectrometer and acquiring data.

There is one method for each command. Commands are camelCaseFormatted. Commands return the received reply object. If there is an error or a timeout, the reply is None.

The following will connect to the dev-kit USB hardware, capture a single frame, then print the status, number of pixels, and the value of the 3rd pixel.

from microspeclib.simple    import MicroSpecSimpleInterface
si = MicroSpecSimpleInterface(timeout=2)
reply = si.captureFrame()
print(reply.status)
print(reply.num_pixels)
print(reply.pixels[2])

Command Line API

The microspec_cmdline.py executable will run a single command and print the reply to stdout, optionally in CSV format. The default is to look for hardware, but -f FILE can be used to point it to either a device file or the name of a port, as in "COM3", if necessary. The command itself is case-insensitive, and after the command are key=value pairs of options for the command, if necessary, such as led_num=0 or cycles=100.

The -t timeout is how long it will wait for the command each time, and if it fails it will print None and move on. If a -r repeat is specified, it will run the command that many times. And if it is repeating, a -w wait will wait that long in between commands. All times are in fractional seconds.

For example, to set the exposure and cycles and then get 3 capture frames spaced 1.5 seconds apart, with a timeout of 0.2 seconds on each, and print it in CSV format:

microspec_cmdline.py setsensorconfig binning=true gain=gain1x row_bitmap=0x1f
microspec_cmdline.py setexposure cycles=100
microspec_cmdline.py captureframe -t 0.2 -r 3 -w 1.5 --csv

The command line utility is a .exe on Windows

On Windows, replace microspec_cmdline.py in the above lines with microspec_cmdline.exe.

For example:

> microspec-cmdline.exe captureframe -t 0.2 -r 3 -w 1.5 --csv

Emulate hardware with -e

Note that if you have no hardware connected, you can (on Linux and MacOSX) add a "-e" flag to use the emulator. It won't return very interesting capture frame data, but it will give an opportunity to test the interface.

Emulator

For now, this is only supported on Linux and MacOSX, and requires the socat executable to be installed and available on your PATH.

Use the emulator with the command-line utility by adding a "-e" flag.

Use the emulator with the microspeclib.simple or microspeclib.expert API with keyword argument emulation=True.

More information

Please see the project homepage for more information:

https://github.com/microspectrometer/microspec

Authors

• Sean Cusack - Initial version - GitHub Blog