Configuration¶

geiger2mqtt uses pydantic-settings for configuration, giving you several ways to set any value:

1. CLI flags — highest priority
2. Environment variables — GEIGER2MQTT_ prefix
3. .env file — loaded from the working directory
4. Defaults — built-in values

For most deployments, a .env file copied from .env.example is all you need.

Settings Reference¶

Geiger counter¶

GEIGER2MQTT_GPIO_GID (default 997) is read by compose.yml, not by the app. See Getting Started.

How the readings are computed (ADR-001):

• cpm is the number of pulses in the last 60 seconds. The first reading comes 60 seconds after the start.
• dose_rate is cpm × conversion_factor.
• dose_rate_avg counts the pulses in the last AVERAGE_WINDOW seconds and converts them to a rate per minute. Until that window has filled, it divides by the time counted so far, so the first readings are not biased low.

Conversion factors¶

The factor converts counts per minute to µSv/h. It depends on the tube and on the radiation it was calibrated against, so published values differ by tens of percent. Treat the table as a starting point and calibrate against a reference instrument if the absolute dose matters.

MQTT¶

TLS. cosalette defaults to TLS. The bundled Mosquitto broker listens in plaintext on the host's loopback interface, so compose.yml sets GEIGER2MQTT_MQTT__TLS=${GEIGER2MQTT_MQTT__TLS:-false} and .env.example keeps false. For a remote broker, set it to true together with GEIGER2MQTT_MQTT__TLS_CA_FILE (and TLS_CERT_FILE/TLS_KEY_FILE for mutual TLS). The decision is recorded in the monorepo's ADR-006.

MQTT 5 retained-message expiry¶

The shipped compose.yml connects geiger2mqtt with MQTT 5. Every retained message it publishes carries a Message Expiry Interval of MESSAGE_EXPIRY_INTERVAL seconds (default 86400, 24 hours): state, availability, Home Assistant discovery, _meta/* and the last will. While geiger2mqtt runs, it re-publishes each retained topic every third of that interval, so the topics stay alive. A topic that nothing refreshes any more disappears from the broker by itself. The decision is recorded in the monorepo's ADR-009.

Operator contract

• The broker must support MQTT 5. The bundled eclipse-mosquitto:2 does. To check another broker, publish a retained message that expires and confirm it disappears:

mosquitto_pub -V mqttv5 -r -t check/expiry -m hello -D publish message-expiry-interval 3
sleep 5 && mosquitto_sub -V mqttv5 -t check/expiry -W 2   # prints nothing

• There is no automatic fallback. If the broker refuses MQTT 5, geiger2mqtt logs does the broker support MQTT 5? and retries the connection. Set GEIGER2MQTT_MQTT__PROTOCOL_VERSION=3.1.1 to return to MQTT 3.1.1.
• Expiry applies to new messages only. Retained topics published before the switch never expire. Clear them by hand with an empty retained publish.
• A long outage lets topics expire. If geiger2mqtt is down or disconnected for longer than the expiry interval, the broker drops its retained topics until the next publish.
• Consumers may see a repeat on refresh. The repeat has the same payload as the last publish and arrives without the retain flag. The radiation state is published every PUBLISH_INTERVAL anyway, so a repeat looks like any other reading.

Logging¶

Health and recovery¶

MQTT is the primary health signal: the geiger2mqtt/status heartbeat and last will, and the geiger2mqtt/radiation/availability topic (see MQTT Topics). Recovery comes from process exits and the restart: unless-stopped policy in compose.yml.

No pulse is not stale. When no pulse arrives for NO_PULSE_TIMEOUT seconds, the radiation sensor goes offline and stays offline until the next pulse; the app keeps running. The channel therefore opts out of cosalette's freshness watchdog (stale_after=None). With the derived bound, every run without a pulse would count as a failed cycle, the channel would turn stale after about 90 seconds, and an exit_after_stale policy would restart the container every few minutes while the tube is quiet. The handler only reads memory, so freshness has nothing else to detect: a crashed task exits with code 4 and a blocked loop with code 6. geiger2mqtt therefore sets no exit_after_stale.

GPIO health check. Every 30 seconds the adapter checks that GPIO_CHIP exists. After five failed checks in a row, cosalette closes the input device and its owned lgpio factory, then creates a fresh factory to re-open the chip and pin, at most three times; then the app exits. Chip selection follows lgpio's Raspberry Pi auto-detection; GPIO_CHIP only selects the path checked for health.

Loop-stall watchdog. The GPIO callbacks run on lgpio's own thread, and the event loop does no blocking I/O. compose.yml still sets COSALETTE_LOOP_STALL_TIMEOUT=120 as a backstop: after 120 seconds without a loop turn, geiger2mqtt prints every thread's stack and exits with code 6. Set COSALETTE_LOOP_STALL_TIMEOUT in the shell or .env to change the value.

Docker health status. The image sets COSALETTE_HEALTH_FILE and probes it with cosalette-health every 60 seconds after a 90-second start period (60 seconds of counting plus margin), so docker ps shows healthy or unhealthy. An unhealthy status restarts nothing: the exit codes do. With a read-only root filesystem, mount a tmpfs on /tmp for the health file.