# 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