AMASC01 Thermal Control

The thermal control daemon keeps the AMASC01 camera dry and cool during long-term outdoor operation:

• it heats the optical dome so that dew and frost do not form on it,
• it ventilates the camera body when the electronics get warm,
• it switches the CPU fan when the Raspberry Pi gets hot,
• it monitors temperature, humidity, pressure and dew point at three places in and around the camera.

It runs as the thermal-control systemd service and is controlled with the thermal-control-cli command. The hardware it drives is described in AMRPI4HAT01 carrier board; the source code is open and available in the AMASC01 repository.

All thermal control settings are pre-configured from the factory with defaults suitable for most environmental conditions. Advanced users can adjust them for specific deployment scenarios.

Quick start

Log in to the camera over SSH and run:

thermal-control-cli --help           # list of all commands
thermal-control-cli test --help      # options of a command
python3 /opt/amasc01/current/camera_supervisor/thermal_control.py --help   # daemon configuration options
thermal-control-cli status           # current readings and outputs
thermal-control-cli test             # interactive hardware test (fans, sensors, heater)
journalctl -u thermal-control -f     # live log

The daemon --help shows the built-in defaults; the running service uses the values from the systemd unit and /amasc01.env, see Configuration.

Thermal control status view in the terminal.

After a new installation set the board variant in /amasc01.env (see Configuration) and restart the service.

How it works

Sensors

For DOME, BODY and ENVI the daemon also computes the dew point (Magnus formula). Readings outside −20 °C … 70 °C are treated as failed reads.

Note: The ENVI sensor does not replace a weather station. It measures the temperature and humidity of the air at the camera’s air intake, and the reading is influenced by the camera casing (sunlight, heat from the camera body).

Outputs

Which PWM channel drives the heater and which the fan depends on the board variant, see AMRPI4HAT01 – thermal outputs.

Control loop

The daemon runs a loop once per second:

1. Heater – a PID controller (Kp = 10, Ki = 0.5, Kd = 2) drives the heater so that the DOME temperature reaches TARGET_TEMP. The output is limited to 0–100 %; with only the P term the heater runs at 10 % per 1 °C below the target.
2. Body fan – the fan speed follows the BODY temperature linearly: 0 % at COOLING_MIN and below, 100 % at COOLING_MAX and above. With the default 30–70 °C the fan runs at 25 % at 40 °C.
3. CPU fan – switches on when the CPU temperature reaches CPU_FAN_THRESHOLD + 10 % and off when it drops below CPU_FAN_THRESHOLD − 10 %. With the default 45 °C it switches on at 49.5 °C and off at 40.5 °C.
4. Status – the current state is written to /var/run/thermal-control-status.json.

The dome target is a fixed temperature; the daemon does not adjust it according to the dew point. See Choosing the target temperature.

Sensor failures and failsafe

The daemon starts even when some sensors are missing and keeps the outputs in a safe state:

A sensor that has failed (or was not found at startup) is marked unavailable and is not retried until the service is restarted. In failsafe mode manual overrides are ignored. When the service stops, the heater, the body fan and the CPU fan are switched off; systemd restarts the service after 10 s.

Configuration

/amasc01.env (persistent)

Machine-specific settings live in /amasc01.env. The installer creates it from amasc01.env.example and never overwrites it. Values in this file take precedence over the defaults in the systemd unit.

sudo nano /amasc01.env
sudo systemctl restart thermal-control

Example:

BOARD_VARIANT=AMRPI4HAT01D
TARGET_TEMP=15

The board revision is printed on the PCB (AMRPI4HAT01D). The variant in use is shown on the first line of thermal-control-cli status together with the PWM channels.

Other parameters (sensor buses and addresses, sensor types, PID gains, failsafe values, valid temperature range) are constants in thermal/config.py.

Runtime changes (not persistent)

Target temperature, cooling range, PID gains and manual overrides can be changed while the service is running with the CLI. These changes are lost when the service restarts; put permanent values into /amasc01.env.

Choosing the target temperature

Dew forms on the dome when its temperature drops to the dew point of the surrounding air. Compare the DOME temperature with the ENVI dew point in the status output: keeping the dome a few degrees above the ambient dew point keeps it clear. A higher target costs more heater power and warms up the air around the lens.

CLI reference

thermal-control-cli talks to the running daemon over the Unix socket /var/run/thermal-control.sock; any user can use it.

Manual overrides stay active until the matching *-auto command or a service restart. Manual body fan and CPU fan control only works while the BODY sensor is available.

Status output

N/A means the sensor has not delivered a valid value.

Hardware test

The interactive test checks the complete thermal hardware, e.g. after assembly or installation:

thermal-control-cli test

1. Fans – stops all fans, switches the CPU fan on, then ramps the body fan 20 → 100 %; after each step it asks whether the fan really behaves as expected (y/n).
2. Sensors – checks that DOME, BODY, ENVI and CPU are available, deliver fresh readings and that temperature, humidity and pressure are within plausible ranges.
3. Heater – sets the heater to 100 % and waits until the DOME temperature rises by 5 °C, printing temperature and heating rate; reports the time to +1 °C (response) and to +5 °C. It is not started when DOME is already above 50 °C and aborts at 60 °C or after 20 minutes.

All outputs are returned to automatic control at the end, also after Ctrl+C. The test prints a PASS/FAIL summary and exits with code 0 only when everything passed.

The daemon must be running. The fan test needs a working BODY sensor, the heater test a working DOME sensor.

If a fan or the heater reacts to the wrong command (the heater warms up during the fan test, or the fan spins during the heater test), BOARD_VARIANT in /amasc01.env does not match the board.

Service and logs

sudo systemctl status thermal-control
sudo systemctl restart thermal-control
journalctl -u thermal-control -f

• journal – INFO and higher, one line per second with temperatures and outputs.
• /var/log/thermal_control.log – only warnings and errors (start, sensor failures, failsafe), to spare the SD card.

Integration

Other software (e.g. the AllSky overlay module allsky_amasc01_thermalstatus) can read the status without talking to the daemon: /var/run/thermal-control-status.json is rewritten every second.

Missing values are null. The socket protocol for sending commands is described in the developer documentation.

Installing and updating

The camera is shipped with the thermal control installed. To install or update to the latest release:

curl -fsSL https://github.com/roman-dvorak/AMASC01/releases/latest/download/install.sh | sudo bash

/amasc01.env is kept during updates. Installer options and rollback are described in the release documentation.

Troubleshooting

Expected I²C devices: bus 1 – 0x44 (ENVI), 0x51 (RTC, shown as UU when the kernel driver is loaded), 0x76 (BODY); bus 10 – 0x44 (DOME).