Custom drivers

A custom driver controls an instrument that Lager does not include, such as an in-house test fixture. You write it once as a small bundle and install it on a box with lager drivers install. Then every user can drive its nets with the standard CLI. The driver code is stored on the box only.

Bundle layout

stepper/
  lager_driver.json   # the manifest
  driver.py           # class Driver(CustomDriver)
  helpers.py          # optional; driver.py can import it by name
  requirements.txt    # optional; Python packages, see below
  wheels/             # optional; wheel files for a box without internet

A driver can import the Python standard library, the packages that come with the box (such as pyserial, pyusb and hidapi) and the lager package. For other packages, see Python packages.

The manifest

The manifest gives the driver’s type, its net settings and its actions. The CLI builds the lager <type> command from it, and the box checks every call against it.

{
  "type": "stepper",
  "version": "1.0.0",
  "lager_api": 1,
  "description": "Stepper rig controlled over a UART net",
  "timeout_s": 30,
  "params": {
    "uart_net": {"type": "net", "role": "uart", "required": true,
                 "help": "UART net wired to the controller"},
    "baudrate": {"type": "int", "default": 115200, "help": "Serial baud rate"}
  },
  "actions": {
    "position": {"help": "Query the current position"},
    "home": {"help": "Return to the home position"},
    "jog": {
      "help": "Move forward for N seconds, then return home",
      "args": {
        "seconds": {"type": "float", "min": 0.1, "max": 30, "required": true}
      }
    }
  }
}

Key	Description
`type`	2 to 32 lower case letters, digits, `-` or `_`, starting with a letter. It becomes the net role and the `lager <type>` command. It cannot be a built-in role or command name
`version`	Your version string, shown by `lager drivers list`
`lager_api`	The driver interface version. Use `1`
`description`	One line, shown in help
`timeout_s`	Default timeout for each action, 1 to 600 seconds (default 60). An action can set its own
`requirements`	Optional. The name of a requirements file at the top of the bundle, such as `requirements.txt`. See Python packages
`params`	Settings stored with each net, given to `lager nets add-custom --param`
`actions`	The actions the driver provides, with their `args`

Each param and arg has a type: str, int, float, bool or choice. A param can also be net, which names another saved net of the given role; the driver then uses that net to reach the hardware. Fields can also have required, default, min and max (numbers only), choices (for choice) and help. Action, param and arg names are 1 to 32 lower case letters, digits and _, starting with a letter. No - is allowed; the CLI shows hold_time as --hold-time. These arg names are reserved, because the CLI uses them already: box, json, as_json, help, netname, action, role, quiet, http_timeout, ctx, box_addr, params.

The driver

from lager.drivers import CustomDriver, action


class Driver(CustomDriver):
    def setup(self):
        # base_net() returns the built-in net that a "net" param names
        self.port = self.base_net("uart_net").connect(
            baudrate=self.params["baudrate"], timeout=2)

    @action
    def position(self):
        self.port.write(b"?\r")
        return {"message": "position read", "position": int(self.port.readline())}

    @action
    def jog(self, seconds):
        self.port.write(b"1\r")
        ...
        return {"message": "jogged %s s and returned home" % seconds}

    def teardown(self):
        self.port.close()

Only methods marked with @action can be called, and each must be named in the manifest. The method gets the action’s args as keyword arguments, with the types the manifest gives.
setup() runs before the action and teardown() runs after it, also when the action raises an exception.
Return a dict, a value or None. A dict’s message is printed by the CLI; the other keys are shown below it, and --json prints the whole result.
An exception becomes an error for the user, with its type and message.
print() output and self.log go to the box log, not to the user.

Attribute	Description
`self.name`	The net’s name
`self.params`	The net’s settings, checked against the manifest
`self.net`	The saved net record
`self.log`	A logger
`self.base_net(param)`	The built-in net that a `net` param names, as a `Net` object

Python packages

A driver can use packages that are not on the box. List them in a requirements file and name it in the manifest:

"requirements": "requirements.txt"

The box installs the packages when you run lager drivers install, so a call never waits for them. They are stored with the driver in /etc/lager/drivers/, so they stay installed after lager update. If a package cannot be installed, the driver is not installed, and the version that was installed before keeps working. The file must pin every package to one version with a hash, including the packages that your packages need. pip-compile writes such a file:

pip install pip-tools
echo "crcmod" > requirements.in
pip-compile --generate-hashes --output-file requirements.txt requirements.in

Rules:

Exact versions with hashes only. Each line is name==version with at least one --hash. Options such as -r, -e and --index-url are not allowed.
Wheels only. The box does not build packages from source. A package must have a wheel for the box’s Python (3.12) and CPU. Boxes can be x86_64 or aarch64 (ARM), so pick packages that have wheels for both, or pure-Python wheels. pip-compile --generate-hashes lists the hashes for every platform.
The box’s own packages come first. A driver cannot replace a package that the box already has. If you pin a package the box has, the version must be the same as the box’s, or the install is refused. Leave such packages out.
Each driver has its own packages. Two drivers can use different versions of the same package.
Limits. The box gives the install 5 minutes, and the installed packages can use at most 200 MB.

A box without internet

Put the wheel files in a wheels/ folder in the bundle. The box uses them before it looks on the internet. They count toward the 5 MB bundle limit. To download them for the box’s CPU:

pip download --only-binary=:all: --python-version 3.12 \
  --platform manylinux_2_36_aarch64 --dest wheels -r requirements.txt

Use manylinux_2_36_x86_64 for an x86_64 box. Running uname -m on the box shows which one it is. Pure-Python wheels work on both.

After an update

If a lager update changes the box’s Python version, lager drivers list shows the driver as error and its Deps as stale. Install the packages again with:

lager drivers reinstall-deps stepper --box my-lager-box

A package’s code runs on the box, with full access to the box’s hardware and network, when the driver imports it. The box only installs wheels, so no package code runs during the install. But treat every package in the file as code that runs on the box, and install only packages you trust.

How a call runs

Each call runs the driver in a new process on the box. A driver that crashes or hangs cannot stop the box. The box loads Lager before the call, so the process starts quickly. It loads driver.py again for each call, so an installed update takes effect on the next call. Two calls on the same net run one after the other. If a lager uart session holds the UART net that the driver uses, the call is refused until that session closes.

Using a driver from a script

A lager python script can use a custom net directly:

from lager.drivers import open_driver

with open_driver("RIG_1") as rig:
    rig.home()
    rig.jog(seconds=3)

open_driver() loads the driver in the script’s own process. It runs setup() on entry and teardown() on exit. It raises ManifestError when the net is not a custom net. It also raises it when a net param names a missing net or a net of the wrong role. It raises DriverFailed when the driver does not import or has no such action. lager.drivers also exports DriverBusy, DriverTimeout and DriverUnavailable. The box’s HTTP API uses them for a busy net, a timeout and a driver that is not installed.

Install and use it

lager drivers install ./stepper --box my-lager-box
lager nets add-custom RIG_1 stepper --param uart_net=UART_1 --box my-lager-box
lager stepper RIG_1 jog --seconds 3 --box my-lager-box

A driver runs on the box with the same access as a lager python script. It is kept out of the public Lager code, but a person who can connect to the box can read it.

Getting Started

Development

Power & Simulation

Measurement

I/O & Communication

Utilities

Custom drivers

Bundle layout

The manifest

The driver

Python packages

A box without internet

After an update

How a call runs

Using a driver from a script

Install and use it

​Bundle layout

​The manifest

​The driver

​Python packages

​A box without internet

​After an update

​How a call runs

​Using a driver from a script

​Install and use it

Bundle layout

The manifest

The driver

Python packages

A box without internet

After an update

How a call runs

Using a driver from a script

Install and use it