Settings reference

PaperPi's settings are in one file, /etc/paperpi/paperpi.toml (TOML: name = value lines under headings in square brackets). The web interface changes it for you; this page lists every setting, for reading or for editing the file by hand. A file only needs the settings that differ from the default. After editing it, run sudo paperpi reload to use the changes without a restart.

paperpi example-config prints a complete example with every setting as a comment.

The first line of the file is config_version = 1.

The screen: [display]

type, model, width, height and mode apply at the next start of PaperPi; the others at once. The screens and their model names are in Supported screens.

Setting	Default	What it does
type	required	The kind of screen: "virtual" (writes PNG files), "it8951" (Waveshare's IT8951 board) or "waveshare" (Waveshare's small screens)
rotation	0	Turn the picture, in degrees. One of: 0, 90, 180, 270
color	true	false: draw in gray, even on a color screen
fallback_clock	true	Show a small clock when no plugin has anything to show (strongly recommended: without it, an empty screen looks like a broken one)
splash_time	60	At start, show PaperPi's version and web address this many seconds before the plugins (0: not at all). With no plugin ready to show, it is shown until one is
width	1200	Virtual screen only: width in pixels
height	825	Virtual screen only: height in pixels
mode	"gray16"	Virtual screen only: what it can show. One of: "bw", "gray4", "gray16", "7color", "rgb"
model	"9.7"	Real screens, and required for them: the screen model. For it8951 its size in inches: "6", "7.8", "9.7" or "10.3"; for waveshare the name of Waveshare's file for it, e.g. "epd7in5_V2"
vcom	-1.9	it8951 only, and required: the voltage printed on the screen's ribbon cable, e.g. -1.9 (between -3.0 and -0.5). Each screen has its own; a wrong value gives poor contrast
max_refresh	4	After this many fast refreshes in a row, the next one is a full refresh, which removes most leftovers of earlier images (0 = never force one)
clean_every	3600	Seconds between cleaning refreshes, which flash the screen white to remove all leftovers of earlier images; also at the first write after a start (0 = never; else at least 600)
on_exit	"clear"	When PaperPi is stopped on purpose (Ctrl+C, systemctl stop, shutdown): make the screen blank, or keep the last picture. After a crash the picture stays. One of: "clear", "keep"

The defaults of width, height and mode are those of the 9.7" screen. model and vcom show examples: they have no default.

The web interface: [web]

enabled, address and port apply at the next start; the others at once.

Setting	Default	What it does
enabled	true	false: no web interface
address	"0.0.0.0"	The network address the web interface listens on: "0.0.0.0" for every device on the home network, "127.0.0.1" for this Pi only
port	8080	The web interface's port
login	true	false: no password; anyone on the home network can change the settings
password_hash	not set	The web password, scrambled so it can't be read back. Written by the web interface. For a new password: run sudo paperpi reset-password (or remove this line), restart or reload PaperPi, and open the web interface

Settings every plugin has

Each plugin on the screen is one [[plugin]] block. Every block has an id (made by the web interface: the plugin type and 8 letters and digits) and a type (which plugin), and can have the settings below. Its own settings are on the plugin's page. "The plugin's suggestion" is on that page too.

Setting	Default	What it does
id	required	Required. Unique ID of this plugin: up to 40 letters, digits, _ and - (when checking that it is unique, capitals don't count and - is the same as _). It names the plugin's storage folder, so changing it starts with an empty folder
type	required	Which plugin, e.g. basic_clock
name	not set	Name shown in the web interface; leave it out to show the ID
enabled	true	Show this plugin
level	the plugin's suggestion	When it is shown: alert, interrupt or rotation. Leave it out to use the plugin's suggestion
display_time	120	Seconds on screen per turn, when several plugins take turns
refresh	the plugin's suggestion	Seconds between updates (at least 5). Leave it out to use the plugin's suggestion
time_limit	60	Seconds one update may take before it is stopped
layout	the plugin's suggestion	Which layout (see the plugin's page). Leave it out to use the first
alert_reminder	3600	Alert plugins only: seconds before a dismissed alert comes back, if the plugin still reports it
alert_max_time	86400	Alert plugins only: seconds after which an alert is dismissed by itself, in case the plugin is stuck
storage_mb	the plugin's suggestion	Most megabytes this plugin may keep in its storage folder; over it, the files changed longest ago are removed first. Leave it out to use the plugin's suggestion
storage_days	the plugin's suggestion	Files the plugin has not changed for this many days are removed (0 = keep them). Leave it out to use the plugin's suggestion