Skip to main content

ophyd-service

Prototype for REST API Server for Ophyd devices. The server loads the startup code (profile collection) that creates Ophyd and ophyd-async devices and provides the REST API and websockets for reading, monitoring and setting the devices.

Installation

Clone the repository:

git clone https://github.com/<organization>/ophyd-service.git
cd ophyd-service

The recommended way to set up the development environment is pixi. Pixi creates the environment and installs the package in editable mode with development dependencies:

pixi install

Environments with specific versions of Python are also available (py311, py312, py313 and py314):

pixi install -e py313

Run commands in the environment using pixi run (e.g. pixi run uvicorn ...) or activate the environment using pixi shell.

Alternatively, the package may be installed in an existing Python (>=3.11) environment using pip:

pip install -e .           # Basic installation
pip install -e .[dev]      # Installation with development dependencies

Starting the server

The server is started using uvicorn. By default the server loads the simulated profile collection distributed with the package (ophyd_service/profile_collection_sim), which contains simulated Ophyd and ophyd-async devices:

uvicorn --host localhost --port 60620 ophyd_service.server:app

Single user API key. The simplest way to access the API is to use a single user API key. The key is set using the environment variable OPHYD_SERVICE_SINGLE_USER_API_KEY. If the variable is not set, a random key is generated at startup:

OPHYD_SERVICE_SINGLE_USER_API_KEY=a uvicorn --host localhost --port 60620 ophyd_service.server:app

The key is passed with each request in the Authorization header:

http GET http://localhost:60620/api/v1/ping 'Authorization: ApiKey a'

Config file. The server configuration may be loaded from a YAML file. The path to the file is passed using the environment variable OPHYD_SERVICE_CONFIG:

OPHYD_SERVICE_CONFIG=config.yml uvicorn --host localhost --port 60620 ophyd_service.server:app

Minimum config file:

authentication:
    single_user_api_key: a

Startup code. If the location of the startup code is not specified, the server starts in demo mode and loads the demo startup scripts with simulated devices distributed with the package (ophyd_service/profile_collection_sim). For practical deployments, the location of the startup code (profile collection) must be specified in the ophyd_service_configuration section of the config file. Only one of the options startup_dir, startup_module_name, startup_script_path or startup_profile may be specified:

authentication:
    single_user_api_key: a
ophyd_service_configuration:
    startup_dir: ~/.ipython/profile_collection/startup
    # startup_module_name: my_beamline.startup
    # startup_script_path: ~/my_beamline/startup.py
    # startup_profile: collection        # IPython profile name
    # ipython_dir: ~/.ipython            # Used with 'startup_profile'
    user_group_permissions_path: ~/my_beamline/user_group_permissions_ophyd.yaml

The user group permissions (the devices that are readable or writable by each user group) are loaded from the file user_group_permissions_ophyd.yaml. By default, the file is expected to be in the startup directory. See ophyd_service/profile_collection_sim/user_group_permissions_ophyd.yaml for an example.

Read-only mode. The server may be started in read-only mode, which disables write operations on device values regardless of the user permissions. Read-only mode is enabled in the ophyd_service_configuration section of the config file (default: false):

ophyd_service_configuration:
    read_only_mode: true

In read-only mode, write_idle and write_always permissions are reported as false for all devices and the websocket /api/v1/device-socket behaves the same way as /api/v1/device-socket/read (the set action is not allowed).

Examples of API calls

The examples use HTTPie (http) and assume that the server is started with the single user API key a and the simulated profile collection (ophyd_service/profile_collection_sim). The same requests can be sent with curl:

curl -H 'Authorization: ApiKey a' http://localhost:60620/api/v1/ping

Check that the server is running:

http GET http://localhost:60620/api/v1/ping 'Authorization: ApiKey a'

Ophyd devices. The simulated profile collection contains the devices from ophyd.sim (det1, motor1, rand, …) and the devices sim_periodic_device1 and sim_periodic_device2 with the components noise and sine updated periodically in background threads. Read the device (read()), its description (describe()) or its value (get()):

http GET http://localhost:60620/api/v1/device/read/det1 'Authorization: ApiKey a'
http GET http://localhost:60620/api/v1/device/describe/det1 'Authorization: ApiKey a'

http GET http://localhost:60620/api/v1/device/read/motor1 'Authorization: ApiKey a'
http GET http://localhost:60620/api/v1/device/get/motor1/readback 'Authorization: ApiKey a'

http GET http://localhost:60620/api/v1/device/read/sim_periodic_device1 'Authorization: ApiKey a'
http GET http://localhost:60620/api/v1/device/get/sim_periodic_device1 'Authorization: ApiKey a'

Components of the device are addressed by appending their names to the URL, separated by slashes. For example, read or get the component sim_periodic_device1.sine:

http GET http://localhost:60620/api/v1/device/read/sim_periodic_device1/sine 'Authorization: ApiKey a'
http GET http://localhost:60620/api/v1/device/get/sim_periodic_device1/sine 'Authorization: ApiKey a'

Ophyd-async devices. The simulated profile collection contains the ophyd-async devices rand_async_device1 … rand_async_device4 (the signal value is updated with a new random number every second), sim_stage_async (motors x and y) and sim_det_async. The methods read and describe work the same way as for Ophyd devices. The method get is supported for signals and returns the result of get_value():

http GET http://localhost:60620/api/v1/device/read/rand_async_device1 'Authorization: ApiKey a'
http GET http://localhost:60620/api/v1/device/describe/rand_async_device1 'Authorization: ApiKey a'

http GET http://localhost:60620/api/v1/device/read/rand_async_device1/value 'Authorization: ApiKey a'
http GET http://localhost:60620/api/v1/device/get/rand_async_device1/value 'Authorization: ApiKey a'

http GET http://localhost:60620/api/v1/device/read/sim_stage_async/x 'Authorization: ApiKey a'
http GET http://localhost:60620/api/v1/device/get/sim_stage_async/x/user_readback 'Authorization: ApiKey a'

Device information. Get the properties of the device stored in the device registry and the permissions of the user group for the device. These methods are supported for both Ophyd and ophyd-async devices:

http GET http://localhost:60620/api/v1/device/properties/motor1 'Authorization: ApiKey a'
http GET http://localhost:60620/api/v1/device/permissions/motor1 'Authorization: ApiKey a'
http GET http://localhost:60620/api/v1/device/properties/rand_async_device1 'Authorization: ApiKey a'

If the request fails (e.g. the device does not exist or the user group has no access to the device), the response contains "success": false and the error message in err_msg.

The examples of using the Finch compatible websocket are included in the description of the websocket below.

Supported API

All API endpoints have the prefix /api/v1.

Device names

Devices and their components are addressed by full names, e.g. det1, motor1 or sim_periodic_device1.sine. In the REST API URLs the components are separated by slashes (sim_periodic_device1/sine), in websocket messages by dots (sim_periodic_device1.sine). Access to devices is controlled per user group: each device may allow read, write_idle and write_always access.

Core API

GET /api/v1/ping (scope read:status)

Returns the server version:

{"success": true, "msg": "Ophyd-Service: v.<version>"}
GET /api/v1/device/{method}/{device_name} (scope read:devices)

Read the device or the information on the device. Supported methods:

  • read – result of device.read() (readable devices only);

  • describe – result of device.describe() (readable devices only);

  • get – result of device.get() (get_value() for ophyd-async signals);

  • properties – device properties stored in the device registry;

  • permissions – permissions of the user group for the device ({"read": ..., "write_idle": ..., "write_always": ...}).

Response:

{"success": true, "err_msg": "", "method": "read", "device_name": "det1", "value": {...}}

Example:

http GET http://localhost:60620/api/v1/device/permissions/motor1 'Authorization: ApiKey a'
/api/v1/monitor/ws (websocket, scope read:devices)

Experimental. The server sends heartbeat messages once per second:

{"heartbeat": {"timestamp": "2026-10-19T12:00:00.000000"}}

The client may send the list of devices to monitor:

{"monitor_devices": ["det1", "motor1"]}

Device monitoring is not implemented yet: the server replies with {"requested_devices": [], "accepted_devices": []}.

Finch compatible websocket

/api/v1/device-socket (scope write:devices)

Subscribe to devices, receive streamed value updates and set device values. If the server is running in read-only mode, the set action is not allowed.

/api/v1/device-socket/read (scope read:devices)

Same as /api/v1/device-socket, but the set action is not allowed.

The client sends requests as JSON messages with the action key. Requests on a connection are processed one at a time in the order they are received.

subscribe

Subscribe to the device and its components:

{"action": "subscribe", "device": "sim_periodic_device1", "recursive": true}

If recursive is true (default), the components of the device are subscribed as well. Only the components with read access are subscribed. Subscribing to the device that is already subscribed (including the components of a recursively subscribed device) is not allowed.

subscribeSafely

Same as subscribe, but the request fails if the device is not connected.

subscribeReadOnly

Same as subscribe, but set requests are rejected for the subscribed devices.

unsubscribe

Unsubscribe from the device:

{"action": "unsubscribe", "device": "sim_periodic_device1"}

If the device was subscribed recursively, its components are unsubscribed as well. All subscriptions are removed when the connection is closed.

refresh

Call get() for all subscribed devices (e.g. to reconnect EPICS devices):

{"action": "refresh", "timeout": 5}

timeout (optional) is the maximum time in seconds to wait for each device. Devices that fail or time out are skipped. If timeout is not specified, the default timeouts of the devices are used.

set

Set the value of the subscribed device:

{"action": "set", "device": "motor1", "value": 2.5, "timeout": 5}

The device must be subscribed (not with subscribeReadOnly) and the user group must have write_idle or write_always access to the device. Numbers (or numeric strings) are set using device.set() and the request completes once the operation is finished (e.g. the motor stopped moving). Other strings are written using device.put() with put completion. Numeric values are checked against the device limits (if defined). timeout is the maximum time to wait for completion in seconds (default: 1).

Messages sent by the server:

  • value updates:

    {"device": "det1", "signal": "det1", "value": 0.85, "timestamp": 1760870000.0,
     "connected": true, "read_access": true, "write_access": true}
  • connection state updates:

    {"device": "motor1", "signal": "motor1_user_readback", "connected": false, ...}
  • replies to requests:

    {"message": "Subscribed to device det1"}
  • errors:

    {"error": "Device 'abc' is not available: ...", "available_devices": ["det1", "motor1", ...]}

The script scripts/stream_monitor_finch.py may be used to test the websocket:

pixi run python scripts/stream_monitor_finch.py --api-key a --devices det1 motor1
pixi run python scripts/stream_monitor_finch.py --api-key a --devices sim_periodic_device1 --recursive false
pixi run python scripts/stream_monitor_finch.py --api-key a --devices det1 --action refresh
pixi run python scripts/stream_monitor_finch.py --api-key a --devices motor1 --action set --value 2.5 --timeout 5

Metadata

Release files for ophyd-service 0.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ophyd-service 0.0.2
File Size Uploaded Provenance Actions
ophyd_service-0.0.2.tar.gz 146.9 kB Without provenance Details for ophyd_service-0.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ophyd-service 0.0.2
File Interpreter ABI Platform Actions
ophyd_service-0.0.2-py3-none-any.whl Python 3 none any Details for ophyd_service-0.0.2-py3-none-any.whl

Total release size: 292.7 kB

Release files / ophyd_service-0.0.2.tar.gz

Download URL ophyd_service-0.0.2.tar.gz
Size 146.9 kB
Tags Source
SHA-256 checksum
How to use checksums
8eb7f080585fe2025d7d70cfd5da5a43f12a422bd958bbb1e3c6e57ac7b6aff4
BLAKE2b-256 checksum
How to use checksums
1f7a9f9880f54229969c7663c5adf83b9e7a848308ef6a85ef7cccfd7af71478
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / ophyd_service-0.0.2-py3-none-any.whl

Download URL ophyd_service-0.0.2-py3-none-any.whl
Size 145.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
280b10450d860f67850a289634eeece0f176480328a91cd03f695d3634bcfbeb
BLAKE2b-256 checksum
How to use checksums
72c5bf2ee0d65b2a667b79cd3f0c456cc03ae2b69a4f0e92b63125414f8c033a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Security for ophyd-service 0.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page