Software architecture

Repository structure

The repository is structured as follows:

  • docs - documentation

  • examples - example of use

  • src - source code

  • tests - test files (pytest) We follow the “src-layout”, read this article for more details.

Moreover, the source code in the flowchem packages is organized in:

  • components - the abstract components representing specific device capabilities (e.g. pumping).

  • devices - containing the code to control the different devices, sorted by manufacturer

  • server - the modules related to configuration parsing and API server initializaiton.

  • utils - various helper functions

flowchem command

At its core, flowchem is a command line application that:

  1. parse a configuration file

  2. connects to the lab devices described and

  3. offer access to them via a RESTful API.

All of this can be achieved without installing anything via pipx run, e.g.

pipx run flowchem my_device_config.toml

Flowchem server startup

When the CLI command flochem is called, the following happens:

  1. The configuration file provided as argument is parsed, and the device objects are created in the order they appear in the file.

  2. Communication is established concurrently for all the devices via calls to each object’s initialize() method.

  3. The components of each hardware object are collected, their routes added to the API server and advertised via mDNS.

  4. Flowchem is ready to be used.

It follows that:

  • All the code in components (step 3) can assume that a valid connection to the hw device is already in place (step 2).

  • Components can use introspection on the relevant hardware device object, e.g. to determine if a pump has withdrawing capabilities or not.

  • The devices are validated during the initialization and are expected to raise exceptions only during the server startup.

  • For safety reasons, all exceptions thrown after the server startup, i.e. during the server lifetime, are caught. This ensures that potential errors on one device do not affect the operation of the other devices on the same server.

FAQ

Principles:

  • No-code shim: device settings via YAML file creates OpenAPI endpoints with predictable names based on serial numbers.

  • Implements existing interoperable standard for lab IoT to avoid standard proliferation.

Implementation design:

  • ideally all permanent device specific parameters (not changing during normal use) are received/set in a uniform way and advertised as such (to enabling dynamic graphs config via web interface, somehow similar to Magritek protocol options).

  • Don’t force code-reuse, but allow for easy extension and leave device modules as independent as possible.

  • Each device has a name, unique per server, tha will be the endpoint path.

To provide the best possible experience for users, flowchem took inspiration from different aspects of packages with similar aims, including (in alphabetical order):