From 590030683552c82aace4cc45343be2c03308afef Mon Sep 17 00:00:00 2001 From: Julian Stirling Date: Sat, 7 Mar 2026 21:12:07 +0000 Subject: [PATCH] Add developer documentation for the config file. --- README.md | 4 +- apidocs/dev/config-file.md | 101 +++++++++++++++++++++++++++++++++++++ 2 files changed, 104 insertions(+), 1 deletion(-) create mode 100644 apidocs/dev/config-file.md diff --git a/README.md b/README.md index ce80a5d0..00c3262d 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,9 @@ The microscope is initially configured by a LabThings config file. This specifie By default, this configuration file should be read from `/var/openflexure/settings/ofm_config.json` when the microscope is run as a service. If it is run at the command line you should specify the configuration using the `-c` command line flag. This configuration file does not change often, and usually only needs to be updated when you change the physical hardware. It may be that this file should be made read-only, particularly in microscopes deployed for e.g. medical applications. -The settings folder is, by default, `/var/openflexure/settings/` if running on a Raspberry Pi, or `./settings/` if run elsewhere. It can be changed in the configuration file. This holds every other persistent setting. Camera settings, calibration data, default capture settings, stream resolution and so on. There is one folder per `Thing`, each with their own file. The settings files can change very regularly, and if you need to reset your settings, it's usually these files that you should remove or reset. If you delete one settings file this should reset the corresponding `Thing`, you don't have to delete the whole folder. +In the future tool will be created for crating custom microscope configurations. Currently no custom configurations are recommended, except for development. More [information on the configuration file](https://openflexure.gitlab.io/openflexure-microscope-server/dev/index.html#config-file) can be found in the developer documentation. + +The settings folder holds the state of your microscope, including the calibrations. The settings folder is, by default, `/var/openflexure/settings/` if running on a Raspberry Pi, or `./settings/` if run elsewhere. It can be changed in the configuration file. This holds every other persistent setting. Camera settings, calibration data, default capture settings, stream resolution and so on. There is one folder per `Thing`, each with their own file. The settings files can change very regularly, and if you need to reset your settings, it's usually these files that you should remove or reset. If you delete one settings file this should reset the corresponding `Thing`, you don't have to delete the whole folder. ## Development diff --git a/apidocs/dev/config-file.md b/apidocs/dev/config-file.md new file mode 100644 index 00000000..bbda452c --- /dev/null +++ b/apidocs/dev/config-file.md @@ -0,0 +1,101 @@ +# The Configuration File + +By default, this configuration file is located at read from `/var/openflexure/settings/ofm_config.json` when the microscope is run as a service. If it is run at the command line, you should specify the configuration using the `-c` command line flag. + +The default configuration file links to the configuration file in the repository: + +``` +{ + "base_config_file": "/var/openflexure/application/openflexure-microscope-server/ofm_config_full.json" +} +``` + +## Understanding and modifying the base configuration file + +This section describes how to change the microscope configuration for development. For example, when making a Merge Request to add a new Thing to the standard microscope configuration. **Do not do this for customising a single microscope.** For customising the configuration of a single microscope see the next section. + +The specification for the configuration file is set by [LabThings FastAPI](https://labthings-fastapi.readthedocs.io/). The file is a JSON file. As such, it cannot contain comments. + +The configuration file has three keys: + +* `things` - A dictionary (Object) containing the [`Thing`s](https://labthings-fastapi.readthedocs.io/en/latest/using_things.html) that should be loaded. All instrument control and server interaction is via `Thing`s. +* `settings_folder` - The directory that LabThings will save settings for each `Thing`. +* `application_config` - A space for the OpenFlexure Microscope Server to list its custom configuration. The OpenFlexure Microscope Server has the following keys: + * `log_folder` - Where the log files are stored. + * `data_folder` - Where data is stored. + +The `things` dictionary can specify a `Thing` to be loaded into the server in two different ways. If there is no custom configuration for the `Thing` then: + +* The key is a **name** for the `Thing`, this defines the URL of its endpoints. +* The value is the Python object reference for the `Thing`. + +For example: + +``` +"autofocus": "openflexure_microscope_server.things.autofocus:AutofocusThing", +``` + +If further information needs to be supplied then the value should be a dictionary (Object) with the following keys: + +* `class` - *(Required)* The Python object reference for the `Thing`. +* `args` - *(Optional)* The positional arguments to be passed to the `Thing` when initialised. +* `kwargs` - *(Optional)* The keyword arguments to be passed to the `Thing` when initialised. +* `thing_slots` - *(Optional)* Information for how the [thing slots](https://labthings-fastapi.readthedocs.io/en/latest/thing_slots.html) of the `Thing` are populated. + +For example: + +``` +"camera": { + "class": "openflexure_microscope_server.things.camera.picamera:StreamingPiCamera2", + "kwargs": { + "camera_board": "picamera_v2" + } +} +``` + +## Customising the configuration + +To have a custom configuration for a specific microscope, we recommend editing `ofm_config.json` in the settings folder. **Avoid editing the base configuration in the repository.** This will keep your customisations that should not be pushed separate from changes to the base file. + +The customisations are performed using [**JSON merge patch** (IETF RFC 7396)](https://datatracker.ietf.org/doc/html/rfc7396) syntax. The patch should specify only the keys that are to change. The RFC documentation provides a number of examples. + +> **Note** +> If a key is set to `null` that key is deleted entirely. There is a [LabThings FastAPI issue](https://github.com/labthings/labthings-fastapi/issues/190) discussing how to handle the rare cases where a value may need to be patched to have the value `None` in Python. + +For our configuration file, an extra key `patch` is added that describes how to patch the base configuration file. + +### Configuration for the Raspberry Pi HQ Camera + +> **Note** +> HQ camera support is currently experimental in v3. While it can be used, it is not as thoroughly tested or supported as the standard v2 camera module. + +You can configure a microscope for the Raspberry Pi HQ Camera by specifying the `camera_board` keyword argument for the `camera` `Thing`. The value needs to change from `picamera_v2` to `picamera_hq`. This will load the HQ camera tuning file and configure the pipeline accordingly. + +As the only key that needs changing is `things.camera.kwargs.camera_board` the patch is: + +```json +{ + "base_config_file": "/var/openflexure/application/openflexure-microscope-server/ofm_config_full.json", + "patch": { + "things": { + "camera": { + "kwargs": { + "camera_board": "picamera_hq" + } + } + } + } +} +``` + +Note that even though the `camera` patch is specified as: + +```json +"camera": { + "kwargs": { + "camera_board": "picamera_hq" + } +} +``` + +This only affects the specified keys. So the camera class is unaffected.