دیدبان — "the lookout". A small Go daemon that watches the house through a Raspberry Pi sensor HAT and reports to Prometheus.
didban reads the sensors on a Waveshare Pioneer600 HAT over I²C and shows them on a small status page and as Prometheus metrics: room temperature, air pressure, the real-time clock, and four analog inputs. It also draws a status screen on the HAT's OLED, shows a sing-box tunnel's state on LED1, sounds the buzzer, keeps the RTC set, and can drive an HD44780 character LCD when one is connected.
It is one static binary with no CGO and no external assets, so a GOARCH=arm64 build copies straight onto the Pi. A dead or missing chip is logged and skipped; the other sensors keep reporting.
| Address | Chip | What didban does with it |
|---|---|---|
0x77 |
BMP180 | temperature (°C) and barometric pressure (Pa), with the datasheet's fixed-point compensation |
0x68 |
DS3231 | the RTC's own die temperature, and the time it holds |
0x48 |
PCF8591 | 4 × 8-bit ADC channels, raw and scaled to volts |
0x20 |
PCF8574 | the active-low buzzer on bit 7, LED2 on bit 4, and the joystick's four directions on bits 0–3 (all active-low) |
| BCM 20 | GPIO | the joystick's centre press, with a pull-up |
| SPI0 CE0, BCM 16 (DC), BCM 19 (RST) | SSD1306 | the 128×64 OLED: clock, temperature, and the tunnel (exit, delay, throughput, flows) |
| BCM 26 | LED1 | the tunnel light (see LED1) |
| 1-Wire | DS18B20 | temperature probes, through the kernel's w1-gpio driver (optional; the board ships one loose) |
The PCF8574 and joystick wiring comes from Waveshare's own demo code (PCF8574/python/pcf8574.py, KEY/python/key.py in the Pioneer600 code archive). Versions before the joystick support used bit 0 for the buzzer, which is the joystick's "left" line, so the buzzer stayed silent.
Warning
On the Pioneer600, 0x20 is the buzzer, not an LCD backpack. Writing LCD frames to it makes the buzzer chatter, so the LCD is off by default. If it ever beeps without stopping: i2cset -y 1 0x20 0xff.
The OLED pins come from the pi4j project's Pioneer600 board config (Waveshare's wiki was unreachable). The OLED is on SPI, not I²C, so i2cdetect never shows it, and it needs dtparam=spi=on (or sudo dtparam spi=on until the next boot). SPI is write-only: didban cannot tell whether a panel is there, so it draws either way.
Enable I²C first (dtparam=i2c_arm=on in config.txt), and check the bus with i2cdetect -y 1. For the DS18B20 add dtoverlay=w1-gpio-pullup, and for the joystick centre gpio=20=pu; both take effect after a reboot. Probes then appear as /sys/bus/w1/devices/28-*.
The BMP180 sits right above the Pi's CPU, so it reads the board's heat (around 36 °C), not the room's. When a DS18B20 probe is attached, the status page shows the probe as the temperature.
Download a binary from Releases (linux_arm64 for a Pi 4/5, linux_armv7/armv6 for older boards), or build it:
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -trimpath -o didban ./cmd/didban
scp didban pi:/usr/local/bin/$ didban read
rtc time : 2026-11-09 04:12:51 +0330
temperature : 24.80 °C (bmp180)
rtc temp : 25.25 °C (ds3231)
pressure : 880.4 hPa
adc[0] ain0 : raw=212 2.744 V
...
$ didban read --json # the same reading as JSON
$ didban beep --count 3 # three short beeps
$ didban serve # poll every 15 s; status page, API and /metrics on :9465
$ didban rtc # the RTC's time next to the system clock
$ sudo didban rtc sync # set the RTC from the system clock (only when NTP has set it)
$ didban lcd -s 120 dinner is ready # show a message on the LCD for 2 min (needs an LCD; see below)didban lcd talks to the running daemon: serve accepts POST /lcd with a JSON body {"text": "...", "seconds": 60} (or "lines": [...], one per row), so any other service can put a message on the display. Between messages the LCD shows the latest reading.
serve answers on / with a status page in the Naz palette. It shows the current readings, the pressure trend over three hours, the RTC's drift from the system clock, 24-hour temperature and pressure charts, the joystick (each key lights while held, with its press count and the latest presses), the DS18B20 probes, the ADC channels, which chips were found, and buttons that sound the buzzer.
The joystick is polled every 50 ms. Each press is counted once however long it is held, logged, exported as a metric, and answered with a short chirp ([joystick] beep = false turns that off). The page is embedded in the binary and loads nothing from the internet. It refreshes itself at the poll interval.
The charts are kept in memory, one point a minute, and start empty after a restart. Prometheus keeps the long history.
The OLED is redrawn every second. Its four rows are the clock and temperature, the tunnel's exit and probe delay, the download rate, and the upload rate with the number of open flows. When the tunnel fails open or its API does not answer, the second row is a lit bar with dark text, so it shows from across the room. Without a tunnel, it shows the pressure instead. A message sent to POST /lcd replaces the screen while it lasts. The whole screen moves by one pixel each minute, so that no pixel stays lit for days: OLEDs burn in.
LED1 shows the tunnel's state at a glance:
| LED | Means |
|---|---|
| steady on | the tunnel is up and idle |
| on, with short dark flickers | the tunnel is up and data moves; the more data, the faster it flickers |
| slow blink (1 s on, 1 s off) | fail-open: the selector is on direct, so traffic leaves without the tunnel |
| double flash | the tunnel's API does not answer (sing-box is down) |
| off | no tunnel configured, or didban is stopped |
When the same host runs a sing-box tunnel with the Clash API on, [tunnel] enabled = true adds a Tunnel section at the top of the page. didban reads the API every 2 s and shows the exit the selector uses now (groups followed down to the outbound), the last probe delay of every exit it can reach, the download and upload rate, the totals since sing-box started, a 24-hour download chart, and the flows open now: host, address, exit, age, the rate of each flow over the last poll, and its bytes. The busiest flows come first. When the selector is on a direct outbound, the page marks it as fail-open. Give the API secret in DIDBAN_TUNNEL__SECRET, not in a file you commit.
The page reads a small JSON API, which other tools can use too:
| Route | |
|---|---|
GET /api/status |
host, version, uptime, the chips found, the latest reading, rtc_drift_seconds, and led, the LED's pattern (up, busy, fail-open, api-down, off) |
GET /api/history |
the last 24 h, one sample a minute: temperature, pressure, RTC temperature |
GET /api/joystick |
the keys held now, presses per key, and the last ten presses |
GET /api/tunnel |
the tunnel now: selector, exit, exits with their delays, rates, totals and the open flows (404 without [tunnel]) |
GET /api/tunnel/history |
the tunnel's download and upload rate over the last 24 h, one point a minute |
POST /api/beep |
{"count": 1} (1–5) sounds the buzzer. It needs Content-Type: application/json, so a page on another site cannot trigger it, and answers 409 while a beep is still sounding |
POST /lcd |
a message for the LCD (see above) |
GET /metrics |
Prometheus |
didban has no login. Keep the port inside the house, or put a reverse proxy with an allow-list in front of it.
| Metric | Labels | Meaning |
|---|---|---|
didban_up |
1 when the last poll read at least one sensor | |
didban_temperature_celsius |
sensor (bmp180, ds3231) |
temperature |
didban_pressure_pascals |
barometric pressure | |
didban_rtc_temperature_celsius |
DS3231 die temperature | |
didban_adc_raw |
channel, label |
ADC conversion, 0–255 |
didban_adc_volts |
channel, label |
ADC value scaled to vref |
didban_ds18b20_temperature_celsius |
id |
each DS18B20 probe |
didban_joystick_presses_total |
key |
joystick presses since start (up, down, left, right, center) |
Scrape it like any exporter:
scrape_configs:
- job_name: didban
static_configs:
- targets: ["chopper.lan:9465"]A few useful queries: didban_temperature_celsius{sensor="bmp180"} for the room, didban_pressure_pascals / 100 for hPa, deriv(didban_pressure_pascals[3h]) for a falling barometer.
Every setting has a default that matches the Pioneer600, so no file is needed. To change something, pass --config (or DIDBAN_CONFIG) with a TOML file; configs/config.example.toml lists every key. Environment variables win over the file, with __ for nesting:
DIDBAN_POLL__INTERVAL=5s DIDBAN_BUZZER__ENABLED=false didban serveTo use a real HD44780 LCD on a PCF8574 backpack, set [lcd] enabled = true and its own address (usually 0x27 or 0x3f), never the buzzer's.
[Unit]
Description=didban
After=network-online.target
[Service]
ExecStart=/usr/local/bin/didban serve
Restart=always
DynamicUser=yes
SupplementaryGroups=i2c gpio
[Install]
WantedBy=multi-user.targetThe gpio group is for the joystick centre key (/dev/gpiochip*). The i2c group must own /dev/i2c-* (SUBSYSTEM=="i2c-dev", GROUP="i2c", MODE="0660" in a udev rule).
just test # go test -race
just lint # golangci-lint (default: all)
just build-piThe layout follows cmd/ + internal/{cmd,infra,sensor}: one package per chip under internal/infra, internal/infra/station composes them, internal/infra/web embeds the status page, and internal/sensor holds the plain reading types and the chart history. The BMP180 compensation is tested against the worked example in the datasheet, and the DS3231 register encoding by a round trip.
Apache-2.0