Dev-kit API Guide¶
Two Most Important Docs¶
These are the two most important pages in the documentation. Keep them handy when developing applications.
documents the input arguments for each API command
example: the command
setExposure
takes input argumentcycles
documents the reply attributes for each API command
example: the reply to
autoExposure
has three attributes:
status
success
iterations
API Commands¶
The API commands are documented here: microspeclib.simple module (dev-kit API commands)
Command names¶
API command names and automated documentation command names look a little different but they refer to the same function definitions.
For example, API command
autoExposure
shows up in the automated documentation as
CommandAutoExposure
.
The automated documentation uses the low-level command names.
These are defined in the dict
microspeclib.datatypes.command.CHROMASPEC_COMMAND_NAME
. The
command names all start with Command
, and the next letter is
capitalized.
For the curious: the rename to the familiar API name happens in
microspeclib.simple._generateFunction()
.
Command arguments¶
The automated documentation of the arguments is not great.
Please ignore =None
:
setAutoExposeConfig(max_tries=None, start_pixel=None, stop_pixel=None, target=None, target_tolerance=None, max_exposure=None, **kwargs)
When keyword arguments are listed they need values and it is
never OK to set an argument to None
. Showing =None
is
the best we could automate to convey the idea that the dev-kit
expects values for these arguments.
The expected type and valid range are described in the Parameters section for each commmand.
Please ignore **kwargs
:
autoExposure(**kwargs)
The **kwargs
shows up in every signature in the
documentation. If an API command only shows **kwargs
(like
this one) it take no arguments.
API Replies¶
The replies to API commands are documented here: microspeclib.datatypes.sensor module (dev-kit API responses).
Return values¶
Every API command gets a reply. This is documented in the
Returns
section for each command in dev-kit API
commands; click the Sensor...
datatype
link.
Every reply has a status
attribute, indicating the status of
the serial communication. Applications do not need to check
status
in an attempt to handle communication errors. This
low-level work is handled automatically by microspeclib
.
Typical return values¶
If serial communication is successful, the reply is a
Sensor...
datatype.
When sending Bridge
commands, the reply is a Bridge...
datatype. There are only three Bridge
commands:
getBridgeLED
,
setBridgeLED
, and
null
.
Value returned when communication fails¶
If the serial communication fails, the reply is None
.
In practice, a serial communication failure always results from a timeout. See How to handle timeouts.
View API replies at the REPL¶
Another way to find out what a command returns is by printing its reply:
open a Python REPL
send the command
print its reply
Example:
from microspeclib.simple import MicroSpecSimpleInterface
kit = MicroSpecSimpleInterface()
reply = kit.autoExposure()
print(reply)
Reply:
SensorAutoExposure(status=0, success=0, iterations=1)
The values are accessed as reply.success
, reply.iterations
, etc.
Every command reply includes status
.
status
is part of the low-level serial communication data and is safe to
ignore as an API user. For example, Chromation’s microspecgui
application
never checks the reply status.
Other Useful Docs¶
Two more useful API references:
constants defined by the API
example:
StatusOK
this is
microspec.cfg
, the JSON file that defines the protocol agreed upon by the Python API and the dev-kit C firmwareit is the file that creates it all:
the
microspeclib.simple
API functions are auto-generated frommicrospec.cfg
and the function factorymicrospeclib.simple._generateFunction()
the API function docstrings are auto-generated by
microspeclib.simple._generateFunction()
and human-written documentation added via modulemicrospeclib.interal.docstrings
the
microspec
unit tests are similarly auto-generated from unit test factories