Metadata-Version: 2.4
Name: kindle-dashboard
Version: 3
Summary: A minimalist PNG dashboard shown as an always-on screensaver on Kindle e-readers.
Keywords: kindle,dashboard,screensaver,epaper,ereader
Author: QasimK
Author-email: QasimK <noreply@QasimK.io>
License-Expression: AGPL-3.0-or-later
License-File: LICENSE.txt
Classifier: Development Status :: 5 - Production/Stable
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Utilities
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Dist: pillow>=12.1.1
Requires-Python: >=3.14
Project-URL: Repository, https://codeberg.org/QasimK/kindle-dashboard
Project-URL: Issues, https://codeberg.org/QasimK/kindle-dashboard/issues
Project-URL: Changelog, https://codeberg.org/QasimK/kindle-dashboard/src/branch/main/CHANGELOG.md
Description-Content-Type: text/markdown

# Kindle Dashboard

A minimalist Python web service that renders a greyscale PNG dashboard for Kindle-sized screens.

## Usage Guide

### The Dashboard

![Kindle Dashboard screenshot](dashboard.png)

- The time and battery are shown in the top-right
- The next significant rainfall window is shown in the top-left (>1 mm precipitation)
- Cloud cover is shown as a darkness band at the top of the graph
- Temperature is shown as a line graph, with the daily low and high points marked
- The temperature guide lines are spaced at 5 °C
- Sunrise and sunset are indicated subtly
- Precipitation is shown as bars at the bottom, with the peak labelled
- Precipitation guide lines are spaced every 0.2 mm
- When showers dominate rain, the precipitation bars are dotted

Depending on your online screensaver configuration, the information will be somewhat out-of-date - notably the time.

Weather data is retrieved from Open-Meteo in the forecast location's local timezone.

Quick guide to standing in rain for one hour:

- 0.1mm: you'll be dry
- 0.3mm: you'll be damp
- 0.5mm: you'll be wet
- 0.7mm: you'll be soaked
- 0.9mm: you'll be dripping

### Prerequisites

- Python 3.14+

### On Your Kindle

Put the dashboard on your Kindle using <https://github.com/FalconFour/onlinescreensaverPW2>.

### Running the Server

The simplest way is using [uv](https://docs.astral.sh/uv/).

Try it out without installing: `WEATHER_LATITUDE=5 WEATHER_LONGITUDE=-5 uvx kindle-dashboard`.

Or, install for your user, and run from there:

```bash
uv tool install kindle-dashboard
kindle-dashboard
```

The server serves the dashboard image on `http://127.0.0.1:42137/`, by default.

There is an [example systemd service file](contrib/kindle-dashboard.service).

### Configuration

- `HOST` (default: `127.0.0.1`)
- `PORT` (default: `42137`)
- `IMAGE_WIDTH` (default: `600`)
- `IMAGE_HEIGHT` (default: `800`)
- `RENDER_SUPERSAMPLE_SCALE` (default: `2`)
- `WEATHER_UPDATE_SECS` (default: `1800`)
- `NEXT_RAIN_GAP_TOLERANCE_HOURS` (default: `1`; merges rain events separated by dry gaps up to this many hours)
- `WEATHER_LATITUDE` (optional; must be set together with `WEATHER_LONGITUDE`)
- `WEATHER_LONGITUDE` (optional; must be set together with `WEATHER_LATITUDE`)
- `LOG_LEVEL` (default: `INFO`; standard Python logging levels)
- `LOG_SYSTEMD` (optional; set `1`/`true` to force systemd log format, `0`/`false` to disable auto-detect)

The weather graph is shown shown if the latitude and longitude variables are set.

When `JOURNAL_STREAM` is present (typical under systemd), logging automatically switches to systemd-compatible output.


## Development Guide

### Development

```bash
uv sync
```

- `bin/fix` applies automatic linting fixes (run this first)
- `bin/check` runs linting, type checks, and release validation
- `bin/test` runs the test suite

```bash
uv run kindle-dashboard
```

### Build and Publish

```bash
bin/publish
```

### Development Notes

- Precipitation bars represent the hour interval ending at the API timestamp (for example, a value at `16:00` is drawn for `15:00-16:00`).
- The Kindle Basic 7th Generation has a 16-level greyscale display.
