------------------
Inbound Control and Query API
=============================
An inbound API has been provided using a REST-like interface over HTTP.
The API should be reasonably complete in its payload and method
definitions and comments are welcomed on its sufficiency and
completeness.
Both the inbound and outbound APIs run in separate *processes* to reduce
the load on the controller itself.
GET should be available for the registered resources. See, in
``src/pyDE1/dispatcher``
- ``resource.py`` for the registered resources, and
- ``mapping.py`` for the elements they contain, the expected value
types, and how they nest.
``None`` or ``null`` are often used to me "no value", such as for
stop-at limits. As a result, though similar, this is not an `RFC7368
JSON Merge Patch <https://datatracker.ietf.org/doc/html/rfc7386>`__.
In Python notation, ``Optional[int]`` means an ``int`` or ``None``.
Where ``float`` is specified, a JSON value such as ``20`` is permitted.
GET presently returns "unreadable" values to be able to better show the
structure of the JSON. When a value is unreadable, ``math.nan`` is used
internally, which is output as the JSON ``NaN`` token.
GET also returns empty nodes to illustrate the structure of the
document. This can be controlled with the ``PRUNE_EMPTY_NODES`` variable
in ``implementation.py``
Although PATCH has been implemented for most payloads, PUT is not yet
enabled. PUT will be the appropriate verb for\ ``DE1_PROFILE`` and
``DE1_FIRMWARE`` as, at this time, in-place modification of these is not
supported. The API mechanism for starting a firmware upload as not been
determined, as it should be able to abort as it runs in the background,
as well as notify when complete. Profile upload is likely to be similar,
though it occurs on a much faster timescale.
If you'd like the convenience of a GET of the same resource after a
PATCH, you can set ``READ_BACK_ON_PATCH`` to ``True`` in
``dispacher.py``
The Python ``http.server`` module is used. It is not appropriate for
exposed use. There is no security to the control and query API at
this time. See further
https://docs.python.org/3/library/http.server.html
It is likely that the server, itself, will be moved to a uWSGI (or
similar) process.
With either the present HTTP implementation or a future uWSGI one, use
of a webserver, such as ``nginx``, will be able to provide TLS,
authentication, and authorization, as well as a more "production-ready"
exposure.
Other Significant Changes
=========================
- ``ShotSampleWithVolumeUpdates`` (v1.1.0) adds ``de1_time``.
``de1_time`` and ``scale_time`` are preferred over ``arrival_time``
as, in a future version, these will be estimates that remove some of
the jitter relative to packet-arrival time.
- To be able to keep cached values of DE1 variables current, a
read-back is requested on each write.
- ``NoneSet`` and ``NONE_SET`` added to some ``enum.IntFlag`` to
provide clearer representations
- Although ``is_read_once`` and ``is_stable`` have been roughed in,
optimizations using them have not been done
- Disabled reads of ``CUUID.ReadFromMMR`` as it returns the request
itself, which is not easily distinguishable from the data read. These
two interpret their ``Length`` field differently, making it difficult
to determine if ``5`` is an unexpected value or if it was just that 6
words were requested to be read.
- Scaling on ``MMR0x80LowAddr.TANK_WATER_THRESHOLD`` was corrected.
------------------