155 lines
5.1 KiB
Markdown
155 lines
5.1 KiB
Markdown
# digitemp-rrdgraph
|
|
|
|
digitemp-rrdgraph is a command-line application for temperature monitoring with 1-Wire sensors. It collects measurements through `digitemp`, stores them in RRD files, generates graph images, and sends email notifications based on configured schedules and thresholds.
|
|
|
|
The repository is organized as a Cargo workspace with two crates:
|
|
|
|
- `digitemp-rrdgraph`: the CLI binary crate
|
|
- `digitemp_rrdgraph_core`: the internal library crate used by the CLI commands
|
|
|
|
## Features
|
|
|
|
- Read temperature data from 1-Wire sensors through `digitemp`
|
|
- Store time-series data in RRD files
|
|
- Generate graph images for hourly, daily, weekly, monthly, and yearly views
|
|
- Send periodic information emails and threshold-based alert emails
|
|
- Configure runtime behavior through JSON and template files
|
|
|
|
## Requirements
|
|
|
|
- Rust toolchain compatible with edition 2024
|
|
- [digitemp](https://www.digitemp.com/)
|
|
- [RRDTool](https://oss.oetiker.ch/rrdtool/)
|
|
- Access to an SMTP server for email delivery
|
|
|
|
## Project Layout
|
|
|
|
- `Cargo.toml`: workspace root and CLI package definition
|
|
- `src/`: CLI entrypoint and command modules
|
|
- `crates/core/`: internal library crate shared by the CLI commands
|
|
- `crates/core/src/`: shared modules for config loading, DigiTemp access, RRD operations, mail sending, and template rendering
|
|
- `etc/`: configuration files and cron examples
|
|
- `templates/`: Tera mail templates
|
|
- `db/`: RRD database files
|
|
- `html/images/`: generated graph images
|
|
|
|
## Setup
|
|
|
|
1. Build the release binary.
|
|
|
|
```sh
|
|
cargo build --release
|
|
```
|
|
|
|
2. Choose where to place the application configuration file.
|
|
|
|
You can always override the default search order with `--config /path/to/digitemp-rrdgraph.json`.
|
|
|
|
Recommended locations are checked in this order:
|
|
|
|
- `$HOME/.config/digitemp-rrdgraph.json`
|
|
- `/etc/digitemp-rrdgraph.json`
|
|
- `<parent directory of the executable>/etc/digitemp-rrdgraph.json`
|
|
- `$PWD/etc/digitemp-rrdgraph.json`
|
|
|
|
For an installed layout such as `/opt/digitemp-rrdgraph/bin/digitemp-rrdgraph`, place the file at `/opt/digitemp-rrdgraph/etc/digitemp-rrdgraph.json`.
|
|
|
|
For local development from the repository root, create `etc/digitemp-rrdgraph.json`.
|
|
|
|
```sh
|
|
cp etc/digitemp-rrdgraph.sample.json etc/digitemp-rrdgraph.json
|
|
```
|
|
|
|
3. Create a DigiTemp configuration file.
|
|
|
|
```sh
|
|
digitemp_DS9097U -i -s /dev/ttyUSB0 -c ./etc/digitemp.conf
|
|
```
|
|
|
|
4. Edit the selected `digitemp-rrdgraph.json` file for your environment.
|
|
|
|
Pass `--verbose` if you want the CLI to print the selected configuration file path to standard error.
|
|
|
|
Configure at least these values:
|
|
|
|
- `digitemp` and `digitemp_config`
|
|
- `database_dir`, `html_dir`, and `images_dir`
|
|
- `templates_dir` and `html_template`
|
|
- `room_name`
|
|
- SMTP server settings
|
|
- mail recipients, subjects, and alert thresholds
|
|
|
|
`room_name` is required. It is used in mail templates, graph titles, and the generated top page.
|
|
The `update` command renders `html_template` and writes it under `html_dir` using the same relative path with the `.tera` suffix removed. For example, `index.html.tera` becomes `html/index.html`.
|
|
|
|
SMTP settings support these combinations:
|
|
|
|
- `mail_smtp_security`: `smtp`, `starttls`, or `smtps`
|
|
- `mail_smtp_auth`: `true` to send SMTP AUTH credentials, `false` for unauthenticated servers
|
|
- `mail_smtp_username` and `mail_smtp_password`: required only when `mail_smtp_auth` is `true`
|
|
|
|
## Build
|
|
|
|
```sh
|
|
cargo build --release
|
|
```
|
|
|
|
This builds both workspace members, including the internal `digitemp_rrdgraph_core` crate.
|
|
|
|
The release binary is written to `target/release/digitemp-rrdgraph`.
|
|
|
|
To build only the CLI package explicitly:
|
|
|
|
```sh
|
|
cargo build --release -p digitemp-rrdgraph
|
|
```
|
|
|
|
To run tests across the workspace:
|
|
|
|
```sh
|
|
cargo test --workspace
|
|
```
|
|
|
|
## Commands
|
|
|
|
The application provides these subcommands:
|
|
|
|
- `update`: read sensors, update RRD files, and regenerate graph images
|
|
- `check-alert`: evaluate current data against configured alert thresholds and send an alert email when required
|
|
- `send-info`: send a periodic information email
|
|
|
|
Examples:
|
|
|
|
```sh
|
|
./target/release/digitemp-rrdgraph update
|
|
./target/release/digitemp-rrdgraph --verbose update
|
|
./target/release/digitemp-rrdgraph --config /opt/digitemp-rrdgraph/etc/digitemp-rrdgraph.json update
|
|
./target/release/digitemp-rrdgraph check-alert
|
|
./target/release/digitemp-rrdgraph send-info
|
|
```
|
|
|
|
## Scheduling
|
|
|
|
Use cron or another scheduler to run the subcommands at appropriate intervals.
|
|
|
|
- Run `update` on the data collection interval you want to keep in RRD.
|
|
- Run `send-info` on the reporting interval you want for periodic summaries.
|
|
- Run `check-alert` on the alert polling interval you want for threshold checks.
|
|
|
|
See `etc/crontab.sample` for a sample schedule.
|
|
|
|
## Templates
|
|
|
|
Templates are stored in `templates/` and rendered with [Tera](https://tera.netlify.app/).
|
|
The top page uses `html_template`, while the mail bodies use `mail_info_template` and `mail_alert_template`.
|
|
|
|
## Development Notes
|
|
|
|
- CLI subcommands live under `src/commands/`.
|
|
- Shared application logic lives under `crates/core/src/` and is exposed by the `digitemp_rrdgraph_core` crate.
|
|
- The root crate depends on the internal core crate through a local path dependency.
|
|
|
|
## License
|
|
|
|
MIT
|