Temper

Temper

A Python tool for discovering temperature and humidity sensor units on the local LAN, recording their readings to a SQLite database, and visualising the data through a web-based dashboard.

Overview

Temper consists of two programs that work together along with the ESP32 based hardware.

• temper_db — a background collector that listens for sensor broadcasts on the LAN and saves every reading to a local SQLite database.
• temper_gui — a browser-based dashboard (built with NiceGUI and Plotly) for plotting temperature and humidity data across any time range.

The two programs are independent. temper_db can run continuously as a background service while temper_gui is started on demand to view the data.

Hardware

Temper is designed to work with TEMPER-branded sensor units that broadcast JSON payloads over UDP on the local network. Each unit reports up to four independent temperature/humidity sensor channels, along with system telemetry (RAM, disk, uptime, RSSI, battery voltage, etc.).

Details of the hardware including kicad schematic, PCB and BOM can be found in the hardware folder.

This hardware runs a micropython program which can be found in software/mcu folder. It listens on UDP port 2934 and responds to Are You There broadcast messages with the status (temperature/humidity etc).

Requirements

• Python 3.10 or later

Installation

The python wheel installer file can be found in the linux folder.

Using the bundled installer

python3 install.py linux/temper-<version>-py3-none-any.whl

This creates a virtual environment, installs all dependencies, and adds the temper_db and temper_gui commands to your PATH. A temper_gui launch icon is also added to you desktop.

Usage

Collector — temper_db

Discovers TEMPER hardware units on the local LAN and writes every received reading to the database.

python -m temper.temper_db [options]

Example — record all units, broadcast every 30 seconds:

temper_db --seconds 30

Example — record only one unit:

temper_db --address 192.168.0.99

Example Running as a service

Use the built-in boot manager to have the tool start automatically (Linux only):

temper_db --seconds 30 --enable_auto_start

Press Ctrl-C to stop.

Dashboard — temper_gui

Starts a local web server and opens the dashboard in the default browser.

temper_gui [options]

Browser Example

Example — start on a non-default port:

temper_gui --port 9090

Example — headless server (access from another device):

temper_gui --no_web_launch

Then navigate to http://<host-ip>:8085 from any browser on the same network, including a mobile phone.

Example Running as a service

Use the built-in boot manager to have the tool start automatically (Linux only):

temper_gui -n --enable_auto_start

Dashboard features

The dashboard is responsive and works on both desktop and mobile browsers.

Sidebar controls

• Units — chips showing every known unit and its total reading count. Click to select a unit and load its data.
• Time Range — preset buttons (1h, 6h, 24h, 7 days, 30 days, All) plus a Custom option with date pickers.
• Plot — switch between Temperature and Humidity views.
• Sensor Names — rename each of the four sensor channels (e.g. Living Room, Loft, Outside). Names are saved to sensor_names.json and persist across restarts. The chart legend and stat tiles update immediately on save.

Main area

• Latest Reading — a tile grid showing the most recent temperature and humidity value for each active sensor on the selected unit.
• Chart — an interactive Plotly time-series plot. Hover over any point to see values for all sensors at that timestamp. Zoom and pan with standard Plotly controls.

Data storage

The database and sensor name configuration are stored in:

Files created:

Database schema

Two tables are used:

units — one row per discovered device.

sensor_readings — one row per received broadcast.

Maintenance

To delete readings older than 90 days from a Python session:

from temper.temper_db import TemperDB
from unittest.mock import MagicMock
db = TemperDB.__new__(TemperDB)
db._uio = MagicMock(); db._options = None
db._db_file = TemperDB.GetDBFile()
deleted = db.prune_readings_older_than(days=90)
print(f"Deleted {deleted} rows")

Running tests

Tests use pytest. From the client directory:

./run_tests.sh

The test suite covers all database operations (TemperDB) including table creation, unit upsert, reading insertion, time-range filtering, latest-reading queries, and data pruning. No network access or real hardware is required.

Project structure

temper/software/client/
├── src/
│   └── temper/
│       ├── temper_db.py        # Collector + database layer
│       └── temper_gui.py       # NiceGUI web dashboard
└── tests/
    └── test_temper_db.py       # pytest test suite

Licence

See LICENSE in the repository root.

Author

Paul Austen — pjaos@gmail.com

Acknowledgements

Development of this project was assisted by Claude (Anthropic's AI assistant), which contributed to code review, bug identification, test generation, and this documentation.