Errata‎ > ‎RaspberryPi‎ > ‎

HomePi V3: Apple AirPrint/Play/Homekit on Raspberry Pi

Last Update:  24 Jan 2019 

*** 2021: The HomePi Recipe has been moved to tech.tpedersen.net/raspberry-pi/pi-recipes/homepi-apple ***

http://ventures.tpedersen.net/images/black_diamond_icon.gif
Here's the updated step-by-step rebuild of our HomePi server using DietPi as the foundation.  Basically notes-to-self, but may be useful to others.  Decided to use DietPi to upgrade to Stretch instead of stock Raspbian ... MUCH Easier!  Feel free to drop me a line with suggestions or comments.

Background

Our HomePi integrates our existing home printer, stereo and 'smart' devices with Apple Devices - Airplay/print and Homekit.   See original DIY Apple AirPlay/Print HowTo for Backgrounder.

DietPi is my new favorite.  It's a lightweight version of Raspbian OS that includes a nice collection of optimized/ready-to-run software packages including many of our HomePi services.  It runs great, is easy to maintain and really simplified the HomePi rebuild.  

Hardware

Not much change:  A new (upgraded?) USB sound board; a fresh/new MicroSD card and new power supply with an on/off switch.  Our HomePi hardware profile: 
Software

Dietpi was biggest change here.  It provides a lite version Raspbian Stretch and a library of optimized Pi software packages including shairport-sync and CUPS. Much better environmentals too: updates, backup facilities, admin utilities, etc.  

DietPi Install Notes

Sept 2020 Note:  HomePi was recently rebuilt.  HomePi V4 step-by-step is simpler but does not include AirPrint services due to introduction of a new/smart printer in our home.  The latest Homebridge Installation process was also simplified ... HomePi V4 recipe @ ventures.tpedersen.net/errata/raspberrypi/homepiv4

Notes to self on OS Prep (DietPi IS Raspbian) and some optimized packages
  • Download latest DietPi and Etcher.  Follow DietPi Quickstart Guide
    // used DietPi_RPi-ARMv6-Stretch.7z (~90MB Download) //
  • Easiest to start DietPi install with Ethernet, keyboard & monitor then switch to ssh after first boot
  • Automatically resizes partitions, forces password changes and updates itself (~5min)
  • Config tweaks via SSH and DietPi-config utility.  Minimally, set the following:
    • DietPi-Config/Audio Options->Soundcard=usb-dac
      // For shairport-sync w/ usb sound //
    • DietPi-Config/Language&Regional->Local=en.US.UTF-8 + Timezone + Keyboard[us]
      // Season to taste, keyboard and country! //
    • DietPi-Config/Network Adapters->WiFi
      // I setup WiFi @ this point and disconnect ethernet on next boot - Remember to Apply/Restart Net // 
    • DietPi-Config/Security->Change Hostname
      // Changing Hostname will force reboot //
  • Install Software via SSH and DietPi-Software utility
    • Software Optimized - Check the following
      • Media Systems->Shairport Sync (for AirPlay)
      • System Stats->RPi-Monitor (nice web-based monitor)
      • Printing->CloudPrint (aka cups for AirPrint)
      • Homebridge is still a manual install process, see below
    • Remember to scroll down to do actual Install - select Go >> Start installation for selected software 
  • Final/Favorite tweaks 'n such via command line:
    • Install favorite editor if you don't like nano.  I like joe:  apt-get install joe
    • Disabled WiFi Power Management to be safe
      $ iwconfig wlan0 power off
    • <may be more>

AirPrint (CUPS)

CUPS is fully installed via DietPi-Software when we selected DietPi CloudPrint option above.  CUPS Documentation @ https://www.cups.org/documentation.html
  • I disable the Google Cloudprintd service - no need, simply interested in CUPS for AirPrint services.
    Use dietpi-services utility to mark it down and disabled *not* systemctl.
    $ dietpi-services stop cloudprintd
    $ dietpi-services disable cloudprintd
  • Configure printer(s) via https://<HomePI IP address>:631
    • Log in to CUPS administration using system user & password (dietpi root works)
    • Administration page: check "Share Printers" and "Allow Remote Admin"
    • Administration/Add Printer - "Discovered Network Printers" found our Dell M5200 w/ a couple of tweaks:

AirPlay (Shairport-sync)

Shairport-sync is also fully installed via DietPi-Software utility!  Project page @ https://github.com/mikebrady/shairport-sync
  • One quick edit to config file @ /usr/local/etc/shairport-sync.conf.  Change the device "name" to something descriptive or it let it default to hostname - 'name' shows on ipad/iphone/itunes.
    general =
    {
      name = "Family Room Bose";
      interpolation = "soxr";
    };

  • Apples Support's HowTo Use AirPlay or AirPlay Mirroring on your iPhone, iPad, or iPod touch

HomeKit (HomeBridge)

Not so easy for HomeBridge. It's not currently part of DietPi software library ... manual install required.  This will take some time, count on an hour with minimal plugin playtime!  Homepage info @ https://github.com/nfarina/homebridge and Raspberry Pi specifics @ https://github.com/nfarina/homebridge/wiki/Running-HomeBridge-on-a-Raspberry-Pi.
  • One preliminary - check for plugins for your smart devices before you go through install - just to make sure you'll be able to control your device.  Go to https://www.npmjs.com and search for  "homebridge-<your dev>".  For example "homebridge-wemo"  or "homebridge-" to browse the library.
  • Note - no need for sudo if you are logged in as DietPi root
  • You'll need c++ compiler and software build packages to make it through this.  Install these via
    dietpi-software->Additional Software - Select following:
    • Node.js: javascript runtime
    • Build-Essentials: common packages for compile
    • Git Client: git clone etc
      • // Remember to scroll down to do Install - select Go >> Start installation for selected software //
  • Install Avahi and other Dependencies (pretty sure these did not go in with DietPi Avahi)

    $ apt-get install libavahi-compat-libdnssd-dev

  • HomeBridge Install:  From README @ https://github.com/nfarina/homebridge/blob/master/README.md
    // Quite a few warnings 'deprecated' but nothing to worry about(?) //

    $ npm install -g --unsafe-perm homebridge

  • Fire it up, it will complain about no plugins, but should see it run & offer a pairing code,  <ctl>C to kill

    $ homebridge 

  • Create config.json file in /root/.homebridge directory see README if you have probs, it could be your editor
  • Plugins Installation:  Steps are dependent on the smart device.   Plugins are also installed using npm and typically  have their own readme/instructions and a snippet to add to your config.json file.  Get plugins by searching for "homebridge-" on https://www.npmjs.com.  Expect some trial/error and fiddling to get plugins working
  • Testing:  Once Plugins are installed,  Fire up Homebridge again and test.  I do initial tests in a terminal window to keep an eye on message chatter.  Make a note of the homebridge pin, you'll use this on IOS devices - PIN display will also get buried when you turn homebridge into a service! 
  • To start Homebridge when RPI boots, create a systemd service from https://github.com/nfarina/homebridge/wiki/Running-HomeBridge-on-a-Raspberry-Pi#running-homebridge-on-bootup-systemd
    • Create /etc/default/homebridge file using example from https://gist.github.com/johannrichard/0ad0de1feb6adb9eb61a/#file-homebridge

      $ cat /etc/default/homebridge

      # Defaults / Configuration options for homebridge
      # The following settings tells homebridge where to find the config.json file
      # and where to persist the data (i.e. pairing and others)
      HOMEBRIDGE_OPTS=-U /var/lib/homebridge

      # If you uncomment the following line, homebridge will log more
      # You can display this via systemd's journalctl: journalctl -f -u homebridge
      # DEBUG=*

    • Create /etc/systemd/system/homebridge.service file using example from https://gist.github.com/johannrichard/0ad0de1feb6adb9eb61a/#file-homebridge-service
    • Check homebridge location - response should be /usr/local/bin on DietPi 

       $ which homebridge
      /usr/local/bin/homebridge

    • Edit /etc/systemd/system/homebridge.service - set ExecStart to homebridge location (e.g. usr/bin/) 

      $ cat /etc/systemd/system/homebridge.service

      [Unit]
      Description=Node.js HomeKit Server 
      After=syslog.target network-online.target

      [Service]
      Type=simple
      User=homebridge
      EnvironmentFile=/etc/default/homebridge
      # Adapt this to your specific setup (could be /usr/bin/homebridge)
      # See comments below for more information
      ExecStart=/usr/local/bin/homebridge $HOMEBRIDGE_OPTS
      Restart=on-failure
      RestartSec=10
      KillMode=process

      [Install]
      WantedBy=multi-user.target

    • Set execute permissions for service

      $ chmod +x /etc/systemd/system/homebridge.service

    • Add Homebridge system account, user and group created, no home directory (-M)

      $ useradd -M --system homebridge
    • Create system dir and copy config.json file for new homebridge service - set ownership and write

      $ mkdir /var/lib/homebridge
      $ chmod +w /var/lib/homebridge 
      $ chown -R homebridge:homebridge /var/lib/homebridge 
      $ cp /root/.homebridge/config.json /var/lib/homebridge/.

    • Enable/Run/Check the service

      $ systemctl daemon-reload
      $ systemctl enable homebridge
      $ systemctl start homebridge
      $ systemctl status homebridge

    • Check /var/log/daemon.log if anything goes bump.

      $ cat /var/log/daemon.log | more

    • Reboot to get the witches out and test service startup

      $ sudo shutdown now -r
  • Set up phone via https://support.apple.com/en-us/HT204893
    • if you forgot your pin/scan code dig it out of systemd journal

      sudo journalctl -u homebridge

  • Debugging:  Troubleshooting Guide @ https://github.com/nfarina/homebridge/wiki/Basic-Trouble-Shooting
    • Running in terminal window is very helpful 
    • See Also:  Common Issues section in the README

  • Apple Home info @ https://www.apple.com/ios/home/