openflexure-microscope-server/apidocs/dev/config-file.md

The Configuration File

By default, this configuration file is 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 file path 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 customiston please refeer to the section on customising the configuration.

The specification for the configuration file is set by LabThings FastAPI. The file is a JSON file. As such, it cannot contain comments.

The configuration file has three keys:

• things - A dictionary (Object) containing the Things that should be loaded. All instrument control and server interaction is via Things.
• 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, which 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",

will add an autofocus Thing to the server. The Thing is located at openflexure_microscope_server.things.autofocus:AutofocusThing, (allowing multiple Things per Python file), and any endpoints (such as actions and properties) in that Thing will have the URL base_url:port/autofocus/endpoint_name

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 of the Thing are populated.

For example:

"camera": {
    "class": "openflexure_microscope_server.things.camera.picamera:StreamingPiCamera2",
    "kwargs": {
        "camera_board": "picamera_v2"
    }
}

Customising the configuration :id=section-customise-config

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) 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 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:

{
    "base_config_file": "/var/openflexure/application/openflexure-microscope-server/ofm_config_full.json",
    "patch": {
        "things": {
            "camera": {
                "kwargs": {
                    "camera_board": "picamera_hq"
                }
            }
        }
    }
}

This will change the camera section to:

"camera": {
    "class": "openflexure_microscope_server.things.camera.picamera:StreamingPiCamera2",
    "kwargs": {
        "camera_board": "picamera_hq"
    }
}