How a session runs and talks to services¶

A service is a server your devices talk to, such as an EPICS IOC, a camera server or a motion controller's gateway. Your ophyd-async devices talk to it over Channel Access or PVAccess without redsun taking part. redsun does the rest: it starts a launched service, notices when it exits, stops it cleanly, and hands its prefix and transport to the devices.

Devices and services¶

A session splits your setup into devices and services, which know as little as possible about each other. Point at a shape to read what it does:

The devices model your setup the way its users think of it, as an ophyd-async tree: a microscope has a stage, the stage an X and a Y axis, each axis a position. A service describes no setup; it only makes hardware reachable, so the same model can sit on real hardware or on a simulation.

A session can declare the whole setup as one device at the root of such a tree. MyMicroscope holds its stage and its camera, so the session declares only the microscope:

class MyMicroscope(StandardReadable):
    def __init__(
        self,
        stage_prefix: str,
        camera_prefix: str | None = None,
        name: str = "",
    ) -> None:
        self.xy = MyStage(stage_prefix)
        if camera_prefix is not None:
            self.camera = MyCamera(camera_prefix)
        super().__init__(name=name)


class MyApp(QtSession):
    microscope: Annotated[
        AsDevice[MyMicroscope],
        Declare(
            services={"stage_prefix": "stage_ioc", "camera_prefix": "camera_ioc"}
        ),
    ]

The session then holds every device of the tree, under the name ophyd-async gives it, such as microscope-xy, so the positioner finds the stage's axes and a plan can be offered the camera. Asking about devices says how components see them. A device can also declare its children with annotations, in the ophyd-async style. An EpicsDevice creates them when it is made, or while it connects when it asks the IOC for its structure (with_pvi=True). The session reads the tree after connecting, so it finds them either way.

The pieces of a setup often sit behind different services, as the stage and the camera do in the picture above. So services maps each of the root's prefix arguments to the service that gives it: here stage_prefix gets the prefix of stage_ioc, and camera_prefix that of camera_ioc. A session file says the same under the device's entry:

devices:
  microscope:
    services:
      stage_prefix: stage_ioc
      camera_prefix: camera_ioc

An argument whose default is None makes its piece optional. When camera_ioc does not start, the session leaves camera_prefix out, builds the microscope with its stage alone, and says so in the build summary:

Built without: microscope (camera_prefix: camera_ioc not started)
Services not started: camera_ioc (exited with code 3 before it was ready)

An argument with any other default, or none, is required, so the session skips the whole device instead. A strict session stops in either case, because a service did not start. You can still declare each piece as a device of its own, and one session can mix both styles.

A device declared with service="stage_ioc" gets that service's prefix as its prefix argument, the same as services={"prefix": "stage_ioc"}, and the prefix is all it knows of the service. So you can change one side and keep the other:

• The same components run against the lab's services or simulated ones; only the services change:

  # common.yaml: what the setup is
  devices:
    stage:
      plugin_name: mylab
      plugin_id: stage
      service: stage_ioc
  

  # lab.yaml: how it is reached in the lab
  services:
    stage_ioc:
      plugin_name: mylab
      plugin_id: stage-ioc
      prefix: "ST:"
  

  # simulation.yaml: how it is reached without hardware
  services:
    stage_ioc:
      plugin_name: mylab
      plugin_id: stage-sim
      prefix: "ST:"
  

  The session lists common.yaml and one of the other two in its config.

• A crashing vendor library takes down its service, not the session; the service's devices time out until it is back.

• An attached service can run on another machine, since the devices need only its prefix.

A device that needs no hardware, such as the soft stage in the tutorial, needs no service.

Two connection levels¶

A device reaches its hardware in two steps, and each step connects on its own:

A mocked session connects each device to a simulated backend and launches no service, so it reaches neither level. The two levels are kept apart on purpose: a session can stay connected to a service that holds no hardware yet, and a service can release its hardware while every connection stays up.

Launched and attached services¶

A service is either launched by the session or attached to it. You declare a launched one with Launch, naming the module the session runs, and an attached one with Attach, naming only its prefix:

class MyApp(QtSession):
    camera_ioc: Annotated[
        AsService, Launch("mylab.iocs.camera", ready="Server startup complete.")
    ]
    beamline: Annotated[AsService, Attach("BL01:", address="10.0.0.5")]

An attached service already runs, in a container or on another host; the session only passes its prefix on, and address says where to look when the network search wouldn't find it. Either kind can also be declared in a session file's services section, which fills any keyword the class leaves out; see Write a service.

A launched service starts in the first build step, before any device:

All launched services start at once, each waited for up to startup_timeout seconds, STARTUP_TIMEOUT (15) unless the declaration gives another; one declared without ready text counts as ready when its process starts. A service that doesn't start is logged, and every device naming it is skipped. Services stop at shutdown, after every component and before the log files close, so the files record how each ended; a build that raises stops the ones it started.

Stopping a process¶

The session asks a service to stop more and more firmly. After each step it waits up to stop_timeout seconds, 10 unless the declaration gives another, for the service to exit:

Closing standard input comes first because it is the only request that runs a service's cleanup on every platform: Popen.terminate() skips cleanup on Windows and Linux, and a console control event never reaches a process started without a console window, as a Qt application starts its services. It also stops a service when the session crashes, since the operating system closes the pipe. A service that needs longer to close takes a longer stop_timeout.

One transport per session¶

All the services of a session are reached over the same protocol, which you name once in the services section of the configuration:

services:
  transport: pv-access
  camera_ioc:
    plugin_name: mylab
    plugin_id: camera-ioc

A session speaks channel-access unless it says otherwise, and a file layered over another can't change it. Pick a scenario to compare how each transport sets up the launched services:

The port numbers are examples: the session takes free ones. Environment variables lists what it sets.

There is one transport because both protocols read variables that hold one setting for the whole process. Channel Access services get a port each because of Windows, where a second IOC on the default port is never found: libca reads its list of server addresses once per process, so each service keeps its port for as long as the session process runs. PVAccess servers share the search port, and the client is told to look at 127.0.0.1 because it doesn't search the loopback address otherwise.

Under sharedbox the session sets up nothing, because a device finds its service's boxes by name, under the service's prefix, with no port or address involved. The service and the session then have to run on the same computer. How to serve a FastCS controller over sharedbox shows both sides.

redsun itself depends on ophyd-async and on nothing that either network protocol needs. Each component brings what its own service speaks, such as caproto, p4p or fastcs, plus ophyd-async[ca] or ophyd-async[pva] for the device side; see Write a service. The sharedbox transport comes with the sharedbox extra of redsun.

What a launched service receives¶

A launched service is told its name and prefix, its ready text and the session's log level, on top of the transport's variables. A Python service reads them with identity, ready and configure_logging, so one module can serve several sessions and name its channels from its identity. Environment variables lists how they are passed.

Unexpected exits¶

Nothing restarts a launched service that stops on its own. Step through what happens instead:

sig_exited is emitted only when the service exits after it was ready and without being asked to stop, from the thread reading its output, service-<name>. A presenter slot that touches what only the main thread may use, such as a Qt widget, needs @slot(thread="main"). An attached service has no process to watch, so an outage shows up only as timeouts on its devices.

Service output¶

Everything a launched service prints ends up in the logs, under the logger redsun.service.<name> and in the service's own log file, next to the application's:

Log from a service shows how a service writes records the session can read.

Not supported yet¶

• Restarting a crashed service.
• Standby, a service releasing its hardware while it stays connected. For now the presenter that owns the devices does it, see Letting go of hardware; the session will take it over once ophyd-async can disconnect a device.
• Launching a service in a container. An attached service covers one you start beside the session with docker compose.

ADR 12 records the decisions behind this design.