Install on Raspberry Pi

Little Printer Bridge - Setup Guide

The code in this repository can be used to turn a Raspberry Pi and WiFi dongle into a bridge device for the Little Printer.

---

Note on another alternative

I'm almost done testing another alternative which uses a cheap ESP32 microcontroller. This will be smaller, cheaper and just as plug-and-play - you only need to set your WiFi credentials. This will be shared soon, so if you don't already have a Raspberry pi and Zigbee dongle laying around, you might want to wait for a little bit.

---

Little Printer Server

The new bridge also uses a new server, found at littleprinter.jaspervanloenen.com.

This server has a few upgrades compared to earlier ones:

• Regular login (no X / Twitter account needed)
• Support for updating the printer's personality (the face printed after every message)
• Offers a simple browser based design tool
• Actively in development

If your want, you can also use the new bridge with the older Sirius based servers, like the Nord Projects' one at littleprinter.nordprojects.co. See the comment at step 7 below.

Parts needed

To create your new bridge device you need a few parts:

1. A Raspberry Pi and power supply - I used the older Raspberry Pi Zero W model (the non-W model does not have WiFi).
2. An SD card - an 8GB card is fine - and an SD card reader for flashing and editing its contents.
3. A Zigbee adapter - the Sonoff ZBDongle-E and M24 have been tested to work.
4. Zigbee adapters plugged directly into a Raspberry Pi are known to receive a lot of interference, so you might want to use a USB extension cable to create some distance.

Notes on the Zigbee adapter

• Confirmed to work:
  • Sonoff ZBDongle-E
  • Sonoff Dongle M24
• Be sure to use Zigbee firmware 7.4.4. Currently firmware 8.0.0 won't work. Sonoff dongles can be flashed directly from Sonoff's website - though only in Chrome!

---

Support

Did you find this tool useful? Feel free to support my open source tools - especially when using them commercially:

Installing software

In short, these are the steps needed to install the Python bridge:

1. use the Raspberry Pi Imager program to download the latest Raspberry OS Lite image and flash it to an SD card
2. Open the boot partition of the SD card and paste below scripts into network-config and user-data
3. Eject the SD card, insert it into the Raspberry Pi, and power it on

Below you'll find the extended instructions with screenshots.

Sidenotes

• If you want to log in to the Raspberry Pi, the default username and password are bridge and littleprinterlives. You can change these in /bootfs/user-data after flashing (but before the first boot).
• For security reasons SSH is disabled in this image by default. You can change this in the /bootfs/user-data file. Make sure to at least change the password, or better yet, disable password login and use a keyfile.

---

Step by step

1. Select model

Download the Raspberry Pi Imager software and run it. Select the Raspberry Pi model you are using (in my case the Zero W)

2. Select Raspberry OS (other)

Select Raspberry Pi OS (other) to get a list of alternatives

3. Select the latest Lite OS

We don't need the desktop environment so select Raspberry Pi OS Lite.

4. Select your SD card

Select the SD card you want to write the image to. Double-check you are selecting the right device!

5. Skip Customisation

In the next screens you can customize your image: just press Skip customisation to skip this section

4. Start writing the image to the card

Check the settings and click WRITE to start writing the image to the SD card. This can take a while.

Note: if Raspberry Pi Imager asks whether you want to apply OS customisation settings, click No. WiFi is configured in the next step instead.

5. Set up WiFi credentials

When it's done, a partition called bootfs should appear in your file explorer (you might need to remove and re-insert the SD card).

Open bootfs and find the file called network-config. Open it in a text editor and fill in your WiFi network name and password:

network:
  version: 2
  wifis:
    wlan0:
      dhcp4: true
      # Change this to your country code (ISO 3166-1 alpha-2)
      regulatory-domain: "NL"
      access-points:
        "YourNetworkName":
          password: "YourPassword"
      optional: false

Replace YourNetworkName and YourPassword with your WiFi credentials. Optionally update regulatory-domain to your country code (e.g. GB, US, DE) and save the file.

7. Create the startup script

Now in the same directory open the file user-data and replace its contents with the script below.

This is also the point where you can change the server to use if you want. Look for OPTION A and OPTION B. If you don't make any changes the server at https://littleprinter.jaspervanloenen.com will be used.

#cloud-config

hostname: little-printer-bridge
manage_etc_hosts: true

timezone: Europe/Amsterdam
keyboard:
  layout: us

# Create bridge user
users:
  - name: bridge
    groups: users,adm,dialout,audio,netdev,video,plugdev,cdrom,games,input,gpio,spi,i2c,render,sudo
    shell: /bin/bash
    lock_passwd: false
    passwd: "$6$boqkDuR6gaVxXbFA$glw/miVRIqHulbFK0Bebyyov0NKQ3z7tlyUS7RYkXGjDozcEiSG.jSw2IDSI/ghItMpaJx/92Zajr.v6ebqmU1"

rpi:
  interfaces:
    i2c: true
    spi: true

# SSH disabled by default for security
# enable_ssh: true

# Update system packages
package_update: true
packages:
  - libopenjp2-7
  - python3-pip
  - git
  - libfreetype-dev

# Create service file
write_files:
  - path: /etc/systemd/system/little-printer-bridge.service
    permissions: '0644'
    owner: root:root
    content: |
      [Unit]
      Description=Little Printer Bridge Script
      After=network-online.target
      Wants=network-online.target

      [Service]
      Type=simple
      User=bridge
      WorkingDirectory=/opt/little-printer-bridge
      ExecStartPre=/bin/sh -c 'until ping -c1 1.1.1.1 > /dev/null 2>&1; do sleep 2; done'

      # OPTION A: use the new server at https://littleprinter.jaspervanloenen.com
      ExecStart=/opt/little-printer-bridge/venv/bin/python3 -m bridge.main --lp-server --lp-server-url wss://littleprinter.jaspervanloenen.com/api/v1/connection

      # OPTION B: use the 'old' Sirius server at https://littleprinter.nordprojects.co
      # ExecStart=/opt/little-printer-bridge/venv/bin/python3 -m bridge.main --sirius --sirius-server wss://littleprinter.nordprojects.co/api/v1/connection

      Restart=on-failure
      RestartSec=10

      [Install]
      WantedBy=multi-user.target

runcmd:
  # Clone the repository into /opt
  - git clone https://github.com/javl/little-printer-bridge.git /opt/little-printer-bridge

  # Transfer folder ownership to the bridge user so it can generate config.json
  - chown -R bridge:bridge /opt/little-printer-bridge

  # Create virtual env
  - python3 -m venv /opt/little-printer-bridge/venv

  # Install python requirements into venv
  - /opt/little-printer-bridge/venv/bin/pip install -r /opt/little-printer-bridge/bridge/requirements.txt

  # Tell systemd to find the file created by write_files, then boot it up
  - systemctl daemon-reload
  - systemctl enable little-printer-bridge.service
  - systemctl start little-printer-bridge.service

  # Disable cloud-init for subsequent boots
  - touch /etc/cloud/cloud-init.disabled

8. Start the Pi and print!

That's it! Safely eject the SD card and insert it into your Raspberry Pi. Connect your Zigbee dongle and power the Pi.

The Pi will take some time to install everything and will reboot a couple of times. On my RPi Zero W it took about 20 minutes. If you have a screen and keyboard connected you can log in and run tail -f /var/log/cloud-init* to display the logs to keep track of progress.

While this is going on you can prepare the pairing steps (which will also indicate when the installation is finished):

1. Plug in your Little Printer.
2. Open it up and use something like a paperclip to press the button on the inside. Hold it until the light on top turns off.
3. Put the paper back, and close the printer.
4. The light will now blink, indicating it is searching for a bridge.
5. Wait for the bridge to finish installing: once it is done the printer will detect it and the light on top will turn solid white.
6. Press the button on top of the printer to have it print it's claim code.
7. Enter the claim code on the website to link the printer to your account.