OpenCAL Device Software

Overview

The OpenCAL device software runs headless on a Raspberry Pi 5 and orchestrates all printer hardware: the stepper motor, LED array, projector, camera, and 20×4 LCD display. The user interacts entirely through a rotary encoder and the LCD menu; no external monitor is needed during normal operation.

For a full reference of the on-device menus and encoder controls, see Controls & Operation. The print files the printer plays are prepared with Tomo (see the Tomo section).

Source code and releases are hosted on GitHub: OpenCAL on GitHub

Installation

There are two ways to get the OpenCAL software onto your Raspberry Pi 5. Both produce a bootable SD card image; choose the pathway that fits your needs.

Pathway 1: Pre-Built Image (Provided)

A curated, fully-tested image is available for download here:

OpenCAL Pi 5 image (opencal_pi5.img.gz)

This image has been validated against the OpenCAL V2 hardware and includes all configuration needed to run out of the box.

Steps:

  1. Download the opencal_pi5.img.gz file from the link above.

  2. Flash it to a microSD card (16 GB or larger) using Raspberry Pi Imager or Balena Etcher.

  3. Insert the card into the Raspberry Pi 5 and power on.

The system will boot directly into the OpenCAL interface. On first login you will be prompted to change the default password (OpenCAL1!).

Pathway 2: GitHub Releases (Automated Images)

NOTE: These images are in the experimental stage. Hardware and software configuration may differ from the provided image above, and some features may not behave identically.

Automated images are built by a GitHub Actions workflow and published to the Releases tab of the OpenCAL repository whenever a new version tag is pushed.

Key characteristics of automated images:

  • Lightweight — built on a bare-minimum Debian Bookworm base (bookworm-minbase) with only the packages strictly required to run OpenCAL. No desktop environment or extra utilities are included.

  • Auto-configured boot sequence — greetd autologs in as the opencal user, launches the Wayfire Wayland compositor, and a systemd user service starts python -m opencal automatically once the Wayland socket is available.

  • Difference from the provided image — because the automated image strips the OS to essentials, certain Pi configuration tweaks or additional tools present in the hand-provided image may be absent.

Steps:

  1. Navigate to the Releases page and download the latest .img.gz asset.

  2. Flash it to a microSD card using Raspberry Pi Imager or Balena Etcher (same as Pathway 1).

  3. Insert the card and power on the Raspberry Pi 5.

Updating the Software

The OpenCAL software on the Pi is a clone of the GitHub repository (located at /home/opencal/OpenCAL). To pull the latest version, fetch the newest code from the main branch and restart the service.

  1. Open a terminal on the Pi — connect a keyboard, or SSH in as the opencal user.

  2. Move into the OpenCAL repository and pull the latest code:

    cd /home/opencal/OpenCAL
git pull origin main

  3. If the update changed dependencies, refresh them inside the virtual environment:

    source .venv/bin/activate
pip install -r requirements.txt
deactivate

  4. Restart the OpenCAL service so the new code takes effect:

    sudo systemctl restart opencal.service

Note

If you have edited opencal/utils/config.json for your hardware, git pull may report a conflict on that file. Back up your version first (cp opencal/utils/config.json ~/config.backup.json), then re-apply your settings after updating.

Tip

Run git status before pulling to see whether you have local changes, and git log -1 afterward to confirm you are on the latest commit.

FAQ / Troubleshooting

This section covers common configuration and debugging questions. Additional Q&A pairs will be added as they arise.

Q: How do I change GPIO pin assignments or I2C addresses to match my hardware?

All hardware configuration lives in opencal/utils/config.json inside the OpenCAL repository (located at /home/opencal/OpenCAL/opencal/utils/config.json on a flashed image). Edit this file to update GPIO pin numbers, the I2C port and address for the LCD, LED count, stepper driver settings, and similar low-level parameters. After saving, restart the service for changes to take effect:

sudo systemctl restart opencal.service

Q: How do I adjust OpenCAL defaults such as rotation speed, LED color, or projector print size?

These values are also stored in opencal/utils/config.json. Key parameters include:

  • stepper_motor.default_rpm — default motor speed in RPM (factory default: 9).

  • led_array.default_color — the LED array colour as a 4-channel value (factory default: [0, 240, 0, 0], which displays as red).

  • projector.default_print_size — initial print size as a percentage of full projector width (factory default: 100).

After editing, restart the service as shown above.

Q: How do I view logs or debug software and hardware issues?

To follow live OpenCAL logs on a running image:

journalctl --user -u opencal.service -f

For hardware-specific debugging, the OpenCAL repository ships several standalone test scripts that exercise individual subsystems without starting the full application:

  • camera_test.py — verifies the PiCamera2 is detected and can capture frames.

  • stepper_test.py — runs the stepper motor through basic movements.

  • lcd_test.py — writes test strings to the LCD display.

Run any of these directly with:

cd /home/opencal/OpenCAL
source .venv/bin/activate
python camera_test.py