EPIC Add endpoints corresponding to jython commands

[stan-dot]

Available console commands in addition to Jython syntax:
* help                            -prints this message
* pos <scannable>                 -gets the current position of the object
* pos <scannable> new_position    -moves the object to the new position
* inc <scannable> increment       -incremental move by the given amount
* upos <scannable> new_position   -pos command without print out during the move
* uinc <scannable> increment      -inc command without print out during the move
* ls                              -list all the interfaces of existing objects
* ls interfaceName                -lists all the objects of the given type (interface)
* ls_names                        -lists the names of all findables
* list_defaults                   -lists all objects which would be used in a scan by default
* add_default <scannable>         -add an object to the defaults list
* remove_default <scannable>      -remove an object from the defaults list
* pause                           -during a script, checks to see if the pause/resume button has been pressed
* watch <scannable>               -adds the scannable to the watch sub-panel in the terminal panel.
* level <scannable> [value]       -if value is declared then sets move order (level) of the scannable, else returns the current level.
* alias functionName              -where functionName is a function in the global namespace.  This dynamically adds a function to the extended syntax.
* run "scriptName"                -runs the named script.
* record [on|off]                 -starts/stops recording all terminal output to a file placed in the scripts directory
* scan <scannable> start stop step [pseudoDevice2] [start] [[stop] step]        -automated movement of a group of pseudoDevices in concurrent steps, with data collected after each step
* testscan <scannable> start stop step [pseudoDevice2] [start] [[stop] step]    -as scan, except does not move anything and justs validates the parameters.
* cscan <scannable> [centroid] width step [pseudoDevice2] [centroid] [width]    -as scan, except uses different inputs
* pscan <scannable> start stop no_points [pseudoDevice2] start [stop]           -as scan, except uses different inputs
* gscan <scannable> start stop step [pseudoDevice2] [start] [stop] [step]       -grid scan in which each dimension is moved separately.  Data is collected after each step.
* timescan detector numberOfPoints pauseTime collectTime                        -Time scan in which the positions of a list of pseudoDevices are collected at regular intervals.
* tscan numberOfPoints pauseTime [collectTime] scannable...                     -Time scan in which the positions of a list of pseudoDevices are collected at regular intervals.
* cvscan [motor1] [start] [stop] time [motor2 start stop] [detectors]           -constant velocity scan (XPS motor only).
* robotscan sample startNumber stopNumber [step] [translator start stop step] cv-motor startAngle [stopAngle] totalTime -cvscan multiple sample at multiple sample position (Motoman & XPS only).

those can be grouped into:

• position changes
• list devices
• scan-running and pausing
• various scan types

Many of those are already available, some (like devices/{protocol} ) would be easy to make and correspond to the get devices by interface GDA method, finally some would be custom.

Achieving a console-like behaviour is readily achievable then with xterm.js, and SQUID could talk to blueapi that way.

The implementation details — whether the pos runs in the full blueapi RunEngine or through EPICS are a separate matter.

[DiamondJoseph]

• help
  Between /docs, documentation and a web interface being more accessible than a CLI, I think we should mostly be fine. The CLI client if it doesn't already have a --help should get one.

• pos, inc, upos, uinc
  These all fall under Mechanism to expose some ophyd device methods directly? #576 and will take a while to get right. A pos scan that takes a list of devices, (that defaults to the BASELINE devices where defined?) would be useful, but would still be a plan and not a new endpoint.

• ls [interface]
  /devices should be extended for a query parameter: /devices?q=Movable etc.

• ls_names
  No Findables.

• list_defaults, add_default, remove_default
  Defaults are already described in the scan parameter schema.

• pause
  Not relevant

• watch
  Mechanism to expose some ophyd device methods directly? #576

• level, alias, run
  Not relevant

• record
  Probably not relevant?

• scan, testscan, cscan, pscan, gscan, timescan, tscan, cvscan, robotscan
  This is just running a plan. The UI for a beamline can prioritise particular plans that will be run most often, but there will not be a specific endpoint for it.

[stan-dot]

this is very helpful @DiamondJoseph , thanks!

[callumforrester]

Following a meeting we had last week, I think it would be useful to document exactly how GDA's Scannable API differs from the bluesky Movable API and the expected differences in usage. We have discussed it at length informally but it should be written somewhere.