Writing a Custom Fridge Backend#

This guide walks you through writing a custom fridge backend for OrangeQS Juice.

Overview#

Juice supports pluggable fridge backends, allowing you to integrate any fridge hardware by writing:

Your own device driver classes (thermometers, heaters, compressors, etc.)
A minimal application class that wires your drivers together

Prerequisites

You should first read Tutorial 3. Fridge Monitor to understand how to configure and launch the system monitor service.

1. Implement your device drivers#

Your driver classes need to implement the same interface as the corresponding protocol in orangeqs.juice.fridge.protocols: HeaterProtocol, ThermometryProtocol, CompressorProtocol, and GHSProtocol. See that module for the full, up-to-date interface each driver must satisfy.

For example, a thermometry driver must expose a temperatures property and an update method:

# my_fridge/thermometry.py
from collections.abc import Sequence

from orangeqs.juice.fridge.data_structures import TemperaturePoint


class MyThermometry:
    def __init__(self, address: str, component_id: str) -> None:
        self._component_id = component_id
        ### Custom code to connect to your hardware

    async def update(self) -> bool:
        """Update the temperature readings from the device."""
        ### Custom code

    @property
    def temperatures(self) -> Sequence[TemperaturePoint]:
        """Return data in Juice-compatible format."""
        return [
            TemperaturePoint(
                component_id=self._component_id,
                sensor_id="thermometer_1",
                temperature=0.0,  ### Custom code
            ),
        ]

Component and sensor IDs

component_id identifies the thermometry unit itself, and sensor_id identifies an individual sensor on it. Both are used to build the pubsub/InfluxDB topic for each reading, and must match the thermometry_component_id and thermometers keys you configure for fridge-monitor-dashboard.toml::thermometry_component_id and fridge-monitor-dashboard.toml::thermometers — otherwise the dashboard will show no data for that thermometer.

You only need to implement drivers for the subsystems your fridge actually has — any of heaters, thermometry, compressors, or ghs can be omitted.

2. Write your application class#

Subclass FridgeApplication and pass in your drivers.

# my_fridge/app.py
from orangeqs.juice.fridge import FridgeApplication

from my_fridge.config import MyFridgeConfig  # extends FridgeBaseConfig
from my_fridge.heater import MyHeater
from my_fridge.thermometry import MyThermometry


class MyFridgeApp(FridgeApplication):
    def __init__(self) -> None:
        config = MyFridgeConfig.load()
        super().__init__(
            config=config,
            heaters={"sample_stage": MyHeater(config.heater_address)},
            thermometry=MyThermometry(
                config.thermometry_address, component_id="thermometry_unit_1"
            ),
        )

Your configuration class should extend FridgeBaseConfig to get the report_interval and bucket_name fields required by the base application class, plus any backend-specific settings you need:

# my_fridge/config.py
from typing import ClassVar

from orangeqs.juice.fridge import FridgeBaseConfig


class MyFridgeConfig(FridgeBaseConfig):
    filename: ClassVar[str] = "my-fridge"

    heater_address: str
    thermometry_address: str

3. Start the service and the dashboard#

Create a new service and point it to your application class. You can do this by adding the following snippet to your orchestration.toml, then running:

juice install --restart --rebuild

 [services.fridge]
 entrypoint = "orangeqs.juice.fridge._service:FridgeService"
 install_proxy = true

 [services.fridge.init_kwargs]
 application_class = "my_fridge.app:MyFridgeApp"

 [influxdb2.buckets.service-fridge]
 name = "service-fridge"

Double‑check that your task manager shows a running fridge service.
With the service running, you can now configure its dashboard. Create a configuration file my-fridge.toml. Once saved, click the restart button on your dashboard to apply the changes.