📦 Installation Guide¶

Welcome to the Inkycal installation guide.
Whether you're installing Inkycal on a Raspberry Pi, setting it up on a desktop system, or using the preconfigured InkycalOS-Lite image, this guide will walk you through each step.

🚀 1. Choose Your Installation Method¶

Inkycal can be installed in three different ways:

Method	Recommended For	Difficulty	Notes
InkycalOS-Lite (preconfigured)	Raspberry Pi Zero / Zero W	⭐ Very Easy	Fastest and most reliable method
Install on Raspberry Pi OS	Full control, custom setups	⭐⭐ Medium	Requires manual configuration
Install on non-GPIO devices	Development, preview, debugging	⭐ Easy	No display output

🎯 2. Using InkycalOS-Lite (Recommended)¶

If you want the fastest, most reliable installation, use the prebuilt InkycalOS-Lite image.

✅ What you get:¶

Fully configured Raspberry Pi OS Lite
SPI enabled
Dependencies preinstalled
Inkycal installed & autostart configured
Best possible performance on Pi Zero

📥 How to get it¶

InkycalOS-Lite is available to supporters of the project.

Sponsor the repo through the GitHub Sponsors button. Use the one-time option for InkycalOS-Lite.
Forward the sponsor confirmation email to the address shown after sponsoring.
Once your email is registered, visit the InkycalOS-Lite download page to retrieve your download link.
New releases are distributed to registered supporters by email.

▶️ Flashing InkycalOS-Lite¶

Install Raspberry Pi Imager.
Insert your microSD card.
Flash the downloaded InkycalOS-Lite image.
Reinsert the card so the boot partition (bootfs) becomes visible on your computer.

🌐 Setting up user-data and network¶

Raspberry Pi Imager does not pre-fill the custom InkycalOS-Lite user-data/network setup, so prepare those files separately:

Open the Inkycal Raspberry Pi config page.
Fill in your network and login details.
Generate and download the configuration files.
Copy both files into the visible bootfs partition on the SD card and allow overwrite if prompted.

🧩 Add `settings.json`¶

Generate your config from the settings.json generator.
Make sure you add at least one module.
Copy settings.json into the bootfs partition as well.

▶️ First boot¶

Insert the microSD card into the Raspberry Pi.
Power on the device.
Inkycal will look for settings.json in the boot partition and render automatically if the file is valid.

If you want to adjust the layout later, simply generate a new settings.json and replace the existing file.

For a focused walkthrough, see:

InkycalOS-Lite Setup

🔐 SSH access (if something goes wrong)¶

If the display does not show the expected dashboard, connect over SSH:

ssh inky@inkycal.local

Use the password you configured in the Raspberry Pi config step.

Then run:

cd $HOME/Inkycal
source venv/bin/activate
python inky_run.py

This prints the real error instead of leaving you with a blank screen.

🆘 InkycalOS-Lite troubleshooting¶

Some flicker during refresh is normal for e-paper displays.
If the screen stays blank, double-check wiring/orientation on the display connector.
If rendering fails, regenerate settings.json or debug over SSH.
If you need help, join the community Discord: https://discord.gg/sHYKeSM

You're done. 🎉

🐍 3. Install on Raspberry Pi OS¶

This path gives you full control while still using the current Python installer for the final setup steps. It is recommended for advanced users, developers, and custom hardware setups.

Step 1 — Flash Raspberry Pi OS¶

Use Raspberry Pi Imager and write:

✅ Recommended version used in the automated Raspberry Pi test workflow:
Raspberry Pi OS Lite (Trixie, armhf, 2025-11-24)

This is the exact base image referenced in .github/workflows/test-on-rpi.yml.

Configure in Imager:

Setting	Value
Hostname	`inkycal`
SSH	Enable
Username	choose one
Password	choose one
Wi-Fi	Configure if needed
Timezone	Your local timezone

Step 2 — Prepare the SD Card¶

Generate your settings.json in the Inkycal Web UI
https://inkycal.aceinnolab.com/ui
Copy settings.json to the root of the SD card.

Insert the SD card into the Pi and boot.

Step 3 — Connect via SSH¶

After ~2–3 minutes, connect:

ssh username@inkycal.local

(on Windows/macOS you can also use Termius)

Step 4 — Raspberry Pi Setup¶

Expand filesystem:

sudo raspi-config --expand-rootfs

Enable SPI:

sudo raspi-config nonint do_spi 0

Set timezone (optional):

sudo dpkg-reconfigure tzdata

Or set it later from the installer menu with:

Set timezone (raspi-config)

Required for 12.48" only:

wget http://www.airspayce.com/mikem/bcm2835/bcm2835-1.71.tar.gz
tar zxvf bcm2835-1.71.tar.gz
cd bcm2835-1.71/
sudo ./configure && sudo make && sudo make check && sudo make install

If you use python3 installer.py, WiringPi is now installed automatically during Install / Repair Inkycal.

Step 5 — Install Dependencies¶

Update system:

sudo apt-get update -y

Enable swap (strongly recommended on the Raspberry Pi Zero)

sudo sh -c 'mkdir -p /etc/rpi/swap.conf.d &&
cat <<EOF | cmp -s - /etc/rpi/swap.conf.d/80-use-swapfile.conf || cat <<EOF >/etc/rpi/swap.conf.d/80-use-swapfile.conf
[Main]
Mechanism=swapfile

[File]
FixedSizeMiB=1024
EOF
EOF'

Prevent memory overflow while installing:

export TMPDIR=/var/tmp

Step 6 — Clone & Install Inkycal¶

Clone the repo

cd $HOME
git clone https://github.com/aceinnolab/Inkycal
cd Inkycal

Install apt dependencies (single source: apt_packages.txt)

sudo apt-get update -y
sudo apt-get install -y $(tr '\n' ' ' < apt_packages.txt)

Create virtual environment:

python -m venv venv
source venv/bin/activate

Install dependencies using piwheels to avoid multi-hour builds:

pip install --upgrade pip wheel setuptools --index-url https://www.piwheels.org/simple --extra-index-url https://pypi.org/simple
pip install -e . --index-url https://www.piwheels.org/simple --extra-index-url https://pypi.org/simple
pip install -r raspberry_os_requirements.txt --index-url https://www.piwheels.org/simple --extra-index-url https://pypi.org/simple

The installer on Raspberry Pi OS¶

The installer is Python-only and provides an arrow-key menu on Raspberry Pi OS:

cd $HOME/Inkycal
python3 installer.py

It covers: - install/repair - update flow - service generation for your real username and path - swap setup on Raspberry Pi Zero, with confirmation and duplicate detection - timezone updates via raspi-config - permission repair (common sudo mishaps) - timed display test with model selection - local web UI service setup - a full wipe option that removes installer-managed system changes and can delete the cloned folder

By default, first startup after boot also shows a monochrome splash with Inkycal and the current version before modules render. You can disable this via "show_startup_splash": false in settings.json.

For a dedicated walkthrough, see:

Installer Guide

Step 7 — Finish with the installer¶

Run the installer to complete service installation, swap setup, and the display test:

python3 installer.py

If you are on a Raspberry Pi Zero, the installer will ask whether to set up swap and will skip it if it already exists.

Inkycal creates Inkycal/logs/inkycal.log and rotates logs daily (max 14 rotations). The installer-managed service uses /tmp/inkycal.lock, ensuring only one instance runs at a time.

The installer can also set up the lightweight local web UI service:

inkycal.service → main dashboard runtime
inkycal-webui.service → local control panel

For the web UI workflow, see:

Local Web UI

Install on Non-GPIO Devices (Development Mode)¶

You can run Inkycal on macOS, Linux, Windows — useful for:

Debugging
Developing new modules
Rendering previews

You won’t be able to show images on real hardware.

git clone https://github.com/aceinnolab/Inkycal
cd Inkycal
python3 -m venv venv
source venv/bin/activate
pip install -e .

Run:

python inky_run.py

PiSugar Support¶

If you’re using a PiSugar battery board, see:

PiSugar Battery Support

This covers:

Driver installation
Configuration
Auto-shutdown
Power monitoring

🤝 Community support¶

If you get stuck during installation, the community is happy to help.

Join the Discord support server: https://discord.gg/sHYKeSM
Open GitHub issues for reproducible bugs
Include logs or the exact terminal error when asking for help

🆘 Troubleshooting Summary¶

Display stays white

Likely missing BCM2835 driver for 12.48”.

Slow installation on Pi Zero W

Use piwheels + swap (already covered above).

settings.json missing

Ensure it is placed at: * /boot/settings.json * Same directory as inky_run.py