# alarm_widg

Minimal alarm scheduler, part of CandyWidgets.

Reads alarms from a TOML configuration file and triggers them at the configured times.

> **Work in progress:** The project is still under active development and may change.

## Install

Build the release binary:

```bash
cargo build --release
````

Install it somewhere in your `$PATH`, for example:

```bash
install -Dm755 target/release/alarm_widg ~/.local/bin/alarm_widg
```

Install the systemd user service:

```bash
mkdir -p ~/.config/systemd/user
cp extra/alarm-widg.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now alarm-widg.service
```

Check the service:

```bash
systemctl --user status alarm-widg.service
```

## Configure

Create or edit:

```text
~/.config/candywidgets/alarm-app/config.toml
```

Example:

```toml
# Daily task
[[alarm]]
title = "Take medication"
time = "08:00"
days = [1, 2, 3, 4, 5, 6, 0]

# Daily task, disabled
[[alarm]]
title = "Check personal email"
time = "18:00"
days = [1, 2, 3, 4, 5, 6, 0]
enabled = false

# Weekly task
[[alarm]]
title = "Water plants"
time = "10:00"
days = [0]

# A few days each week
[[alarm]]
title = "Exercise"
time = "17:30"
days = [1, 3, 5]

# Specific date
[[alarm]]
title = "Submit monthly report"
time = "16:00"
dates = ["2026-08-31"]

# Multiple specific dates
[[alarm]]
title = "Project deadlines"
time = "17:00"
dates = [
    "2026-08-15",
    "2026-08-22",
    "2026-08-29",
]
color = "FFFFCC00"
```

### Options

| Option    | Description                                         |
| --------- | --------------------------------------------------- |
| `title`   | Alarm title                                         |
| `time`    | Time in `HH:MM` format                              |
| `days`    | Recurring days, `0` = Sunday through `6` = Saturday |
| `dates`   | Specific dates in `YYYY-MM-DD` format               |
| `color`   | Optional ARGB hexadecimal color                     |
| `enabled` | Enable or disable the alarm, defaults to `true`     |

Each alarm must specify either `days` or `dates`.

## License

GPL-3.0-or-later. See `LICENSE`.