syncster-ioc 0.1.2

Description:

syncsterioc 0.1.2

Synchro-State Tracking IOC



This is a simple IOC that tracks the timing synchronization state on
specific laser repetition-control hardware. It was written with the
Menly Syncro RRE
in mind, but the structure is fairly clean and can likely be extended
to other devices easily.
About Repetion Control
Repetition control usually determines when a pulsed laser fires.
This is at the base of many scientific applications, e.g. pump-probe
experiments. It coordinates the firing rate, and point in time,
with an external signal -- typically a driving, gate or marker frequency
of another device.
The idea is to have a simple state variable exported as an
EPICS process variable
which indicates whether the system is in a "synchronized" state
with the external frequency, and to take limited action as to whether
to force or pause the synchronized state.
Quick Start
Either install locally with pip, then start directly from the
command line:
$ pip install syncster-ioc
$ syncster-ioc [args]

or start the pre-built image via Podman (or Docker)
$ podman run -ti --rm registry.gitlab.com:kmc3-xpp/syncster-ioc:latest [args]

The IOC State Diagram
The syncro hardware operation is tracked and reflected in the IOC through
the following state automaton:
stateDiagram-v2
[*] --> INIT
SYNCED --> OFF
INIT --> OFF
INIT --> SYNCED
STRAY --> SYNCED
OFF --> STRAY
ERROR --> OFF
SYNCED --> ERROR
STRAY --> ERROR
INIT --> ERROR
OFF --> ERROR

The state definition is as follows:


INIT: IOC initialization, determines the state of the synchronization
hardware (i.e. whether it's synchronized to the control frequency)


SYNCED: this is the actual state we're most interested in: it
indicates that the hardware is synchronized and any processes depending
on it can continue. Showing this is the main purpose of this IOC.


OFF: if the hardware indicates being non-synchronized, we enter this
state. This is a defined "do not rely on synchronization"-state, and,
as far as we can control, no synchronization is attempted. (Beware that
at this point, syncster-ioc may not have control over whether the
hardware actually attempts any synchronization, but in any case,
we're not expecting it and not tracking it; we're well-defined "turned
off" and stay that way.)


STRAY: if synchronization is required / requsted / expected (e.g. by
user request), we enter this state to wait for it. We only leave this
when synchronization is achieved.


ERROR: can be entered from any state if (defined) erronous behavior
is detected. Most commonly this happens if error flags of the hardware
are set, or if we've spent too long in STRAY without any synchronization
occuring and a timeout was set. We leave ERROR only on explicit user
action ("clearing"), and we enter in OFF, where we wait for yet
another request as to whether to attempt (to detect or perform)
a new synchronization.


FAIL: for clarity purposed, this state is not indicated in the diagram.
However, it exists, and is very similar to ERROR -- the only difference
being that there is no returning from FAIL. It indicates a fundamentally
broken situation that led to inconsistencies and cannot be solved within
the current state of the IOC. Severe manual intervention
with IOC restart is required.


State Exported via EPICS PVs
The following EPICS process variables (PVs) are exported:

{prefix}state: string, indicates one of the above states.
{prefix}error: string, shows a human-readable error description.
This is only valid if ...:state is "ERROR".
{prefix}clear: if 1 is written here, the error state is
cleared, which will trigger the IOC once to proceed away from the
"ERROR" state into "OFF".
{prefox}stray: if 1 is written here, the IOC is triggered to
to proceed from "OFF" into "STRAY".

Environment Variables
The IOC reacts to the following (shell) environment variables:

SYNCSTER_LOG_LEVEL: one of "debug", "info", "warning" or "error"
SYNCSTER_PREFIX: the IOC EPICS prefix to use (see above). You should
include the : character at the end of the prefix, if you intend to
use it.
SYNCSTER_RRE_PORT: USB device to use with the Menly Syncro RRE,
e.g. /dev/ttyUSB0.
SYNCSTER_AUTO_STRAY: if set to "yes", the state automaton will
always automatically advance from "OFF" to "STRAY"; this will
make it easier e.g. to recover from errors (requiring a single
write to a PV instead of two), but will essentially make it imposible
to purposely stay in "OFF". Default behavior is not to.
SYNCSTER_SYNC_TIMEOUT: the number of seconds to wait in "STRAY"
for the synchronization to occur in hardware. Defaults to 300, which
may be too short for manual synchronization. Setting this to -1 will
wait forever, which may not exactly be what you want if you have an
automatic synchronization routine and want fall into a defined error
state if it fails to produce intended results.

Bugs & Caveats
"Bugs? Where we're going, we don't have... 😎 ...bugs!"