FastCS Odin

FastCS support for the Odin detector software framework

Source	https://github.com/DiamondLightSource/fastcs-odin
PyPI	pip install fastcs-odin
Docker	docker run ghcr.io/diamondlightsource/fastcs-odin:latest
Documentation	https://diamondlightsource.github.io/fastcs-odin
Releases	https://github.com/DiamondLightSource/fastcs-odin/releases

Development

In most cases it should be sufficient to work within the fastcs-odin devcontainer (or a virtualenv) and run the unit tests to develop new features and bug fixes.

In order to develop and test fastcs-odin alongside local dev versions of odin-control and odin-data applications, a development environment can be run up from the odin-data devcontainer.

Full Development Environment

The following instructions assume use of vscode, as it makes it very convenient to set up an environment that "just works". However, it is possible to run the same environment up manually using the odin-data-developer container and the following steps should still provide a good overview.

Note, commands starting with > are vscode commands and can be run with Ctrl+Shift+P, while commands starting with $ are bash commands to be run in a terminal (inside the vscode devcontainer).

1. Clone odin-data (next to fastcs-odin), checkout the fastcs-dev branch and re-open in devcontainer

2. Add fastcs-odin to the workspace > Workspaces: Add Folder to Workspace...

   i. If it asks to reload window, then do so

3. Install the recommended extensions with > Extensions: Show Recommended Extensions

4. Build odin-data into /odin

   i. > CMake: Delete Cache and Reconfigure and select a compiler, e.g. /usr/bin/gcc

   ii. > CMake: Install

5. Install fastcs-odin and its odin dev environment

   i. > Python: Select Interpreter, Select at workspace level and select /venv/bin/python

   ii. Run $ pip install -e .[dev,odin] at the root of fastcs-odin

6. Prepare the dev environment (in the root of fastcs-odin)

   i. $ dev/configure.sh one_node_fp /workspaces/odin-data/vscode_prefix /venv

   ii. $ zellij, wait for it to finish installing and close with Ctrl+Q

7. Run the dev environment (in the root of fastcs-odin)

   i. $ dev/start.sh

8. > Debug: Select and Start Debugging and select Odin IOC to run the IOC

UIs will be generated in the root of fastcs-odin that can be opened in Phoebus. This is the clearest way to see the PVs that have been generated for the Odin server. It is also possible to run dbl() in the EPICS shell to print a flat list of PVs.

To run a dev version of any of the applications, stop that process in the deployment (by clicking the pane and pressing Ctrl+C) then run/debug it manually. There is a vscode launch config for an odin server using the same config as the dev deployment for this purpose.

To run local versions of odin-data / odin-control python applications install it into the virtual environment with $ pip install -e ... to override the versions installed from GitHub.

Isolated Development Environment

While it is necessary to work on odin-control / odin-data alongside fastcs-odin in some cases, once these additions have been made they should be backed by tests that can be run without the full development environment. This means in most case it is possible to develop fastcs-odin in isolation and trust the unit tests to give a good indication that things are working as expected, and so that the same checks can be made in CI and reduce manual testing during code review.

It is possible to test some functionality in isolation by dumping server responses and creating tests that parse those responses. Responses can be dumped from various Odin systems and tests written against them that can run in CI to ensure support for those systems is not broken (or get early warning that an adapter needs to be updated to work with the latest fastcs-odin). The tests/dump_server_response.py helper script will generate json files for each adapter in an Odin server to write tests against.

See https://diamondlightsource.github.io/fastcs-odin for more detailed documentation.