Install on Raspberry Pi

Little Printer Zigbee Bridge - Setup Guide

The simplest way to fully replace your old bridge device is to use a Raspberry Pi. You don't need a very fast one for this to work: I like to use a Raspberry Pi Zero W as they are easy to find second-hand, are small and pretty cheap. Do make sure to get the W model as the original Raspberry Pi Zero doesn't have WiFi.

The new bridge device you'll create will connect to your network over WiFi and by default communicates with the server at littleprinter.jaspervanloenen.com.

A few improvement to this server compared to previous ones are:

• No more login using X / Twitter
• Support for updating the printer's personality (the face printed after every message
• A simple browser based design tool
• Actively in development: so new functions will be added soon

Alternatively, you can also Nord Projects' 'old' Little Printer Sirius instance by changing the server the bridge uses in the code at step 7 (search for 'OPTION B').

Note on another alternative

I’ve also been working on an ESP32 based bridge which is cheaper, smaller and completely plug-and-play, so if you just want to replace your bridge you might want to wait for a little bit to see if this will suit you more.

Even more notes:

• This shouldn't be needed, but 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 booting).
• 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.

---

Support

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

What you need

• A micro SD card (a 'small' one like 8GB is fine)
• An SD card reader to read the card on your computer
• Raspberry Pi Zero W (or any other model)
• Power adapter for the Raspberry Pi
• A Zigbee USB dongle - I'm using the Sonoff ZBDongle-E
• An USB A to micro USB adapter (if you use a model that doesn't have full size USB ports, like the Zero)
• 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.

Installing software

In short, these are the steps needed to install the Zigbee 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.

---

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 following:

#cloud-config

hostname: little-printer-zigbee-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-zigbee-bridge.service
    permissions: '0644'
    owner: root:root
    content: |
      [Unit]
      Description=Little Printer Zigbee Bridge Script
      After=network-online.target
      Wants=network-online.target

      [Service]
      Type=simple
      User=bridge
      WorkingDirectory=/opt/little-printer-zigbee-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-zigbee-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-zigbee-bridge/venv/bin/python3 -m bridge.main --sirius

      Restart=on-failure
      RestartSec=10

      [Install]
      WantedBy=multi-user.target

runcmd:
  # Clone the repository into /opt
  - git clone https://github.com/javl/little-printer-zigbee-bridge.git /opt/little-printer-zigbee-bridge
  
  # Transfer folder ownership to the bridge user so it can generate config.json
  - chown -R bridge:bridge /opt/little-printer-zigbee-bridge

  # Create virtual env
  - python3 -m venv /opt/little-printer-zigbee-bridge/venv
  
  # Install python requirements into venv
  - /opt/little-printer-zigbee-bridge/venv/bin/pip install -r /opt/little-printer-zigbee-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-zigbee-bridge.service
  - systemctl start little-printer-zigbee-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.