Products Firewalla Gold SE Firewalla Gold Pro Firewalla Gold Plus Firewalla Purple Firewalla Purple SE Firewalla Wi-Fi SD Product Comparison Product Reviews

Articles in this section

See more

Guide: Install HomeBridge on Firewalla

Avatar
Support
  • Updated
Follow

Please note:

  • This is a tech doc for advanced users. Specific docker containers are not formally supported by Firewalla. We recommend checking with other Firewalla users or experts on individual docker containers if you have trouble.
  • Installing Homebridge on Firewalla Gold series boxes should work o.k. at this time. Installing on Firewalla Purple series boxes and below is not recommended due to disk and memory limitations.  If you have a Firewalla Purple box we recommend running Homebridge somewhere else. This can be a computer, Raspberry Pi, NAS, etc.
  • Incorrect settings of port forwarding may result in ports being opened on your WAN interface.

Thanks to Michael Bierman for his effort on this topic to sort everything out.

 

Homebridge is a server you can run on your home network that can connect many devices that aren't certified to work with Apple Homekit. It is a bridge between HomeKit and these devices which allows you to use Siri to control them.

 

1. Login to Firewalla via SSH. You will find the credential on your Firewalla app, Settings > Advanced > Configurations > SSH Console. The username is always, "pi"

 

2. Create the file, /home/pi/.firewalla/run/docker/homebridge/docker-compose.yaml.

# make homebridge storage directory
mkdir /home/pi/.firewalla/run/docker/homebridge/

# change directory
cd /home/pi/.firewalla/run/docker/homebridge/
# edit with your favorite editor, like vi
vi /home/pi/.firewalla/run/docker/homebridge/docker-compose.yaml

 

Add the following to docker-compose.yaml

version: '2'
services:
  homebridge:
    image: homebridge/homebridge:ubuntu
    container_name: homebridge
    restart: always
    network_mode: host
    environment:
      - PGID=1000
      - PUID=1000
      - HOMEBRIDGE_CONFIG_UI=1
      - HOMEBRIDGE_CONFIG_UI_PORT=8581
      - TZ=Australia/Sydney
      - ENABLE_AVAHI=0
    volumes:
      - '/data/homebridge:/homebridge'
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
  • Adjust the  TZ option to match your current location - see list of timezone names here.
  • If you are running something else on port 8080, change HOMEBRIDGE_CONFIG_UI_PORT to another port.
  • Note the logging options are recommended to prevent using up all your valuable space on your Firewalla. (see https://github.com/homebridge/docker-homebridge/issues/399) 
  • Note YAML only supports space characters for indents, not tabs. Use either two or four spaces for each level of indent as you prefer.

3. Run the following commands to install and start HomeBridge:

cd /home/pi/.firewalla/run/docker/homebridge
sudo systemctl start docker
sudo docker-compose up --detach

 

You can run this command and confirm the homebridge container running in docker.

sudo docker ps
# CONTAINER ID        IMAGE                    COMMAND             CREATED              STATUS              PORTS               NAMES
# cfb1c63c8b36        homebridge/homebridge:ubuntu   "/init"             About a minute ago   Up About a minute                       homebridge
 
4. Login at http://fire.walla:8581/ (or use Firewalla's IP). The default homebridge user/password is admin/admin.

Homebridge Status Page

5. Go to the "more options" (three dots) menu and open the Homebridge, Settings menu and find Network.

Homebridge Settings Menu with Network sub-settings

If you open Homebridge's Network Interfaces you will see all of Firewalla's network interfaces. Choose the one that contains your Apple TV or HomePod as homebridge needs to connect to them. Note you may see bonds as shown below if you are using LAG or, bridges if you are not. Either way, you can simply choose the IP of the network you are running homekit on. 

Homebridge selectable Network Interfaces

Choose "Ciao".

Save when done.

6. Click restart on the upper right corner and you should be able to pair HomeBridge with your HomeKit (Home app) now.

 

Persisting and restarting

The docker service and homebridge container won't automatically start after a system reboot, to do so, create the following folder and file

/home/pi/.firewalla/config/post_main.d/start_homebridge.sh
mkdir /home/pi/.firewalla/config/post_main.d/
cd /home/pi/.firewalla/config/post_main.d/
nano start_homebridge.sh
and add this to start_homebridge.sh 
#!/bin/bash

sudo systemctl start docker
sudo systemctl start docker-compose@homebridge
 

now docker and homebridge will automatically start when Firewalla reboots. 

 

See https://help.firewalla.com/hc/en-us/articles/360054056754-Customized-Scripting- for more on running scripts at boot time.

 

To Check Docker Containers

sudo docker logs homebridge

 This lets you confirm how the startup went, what port you are running on, and tons of other diagnostic information. 

 

To Reset Docker Containers

In case the docker service doesn't start, please follow this guide to reset your docker service. 

 

Tracking Firewalla CPU temperature

Here's an example of a plugin that adds some monitoring of Firewalla itself in Homekit. If you want to track the CPU temperatures of firewalla in Homekit:

  1. Install the homebridge-linux-temperature plugin

  2. Add the following to the Accessory part of Homebridge config.json: 

    Firewalla Gold

 "accessories": [

        {
            "accessory": "LinuxTemperature",
            "name": "Firewalla Core Temp",
            "sensor_path": "/sys/class/thermal/thermal_zone0/temp",
            "divisor": 1000
        },
        {
            "accessory": "LinuxTemperature",
            "name": "Firewalla Core 0 Temp",
            "sensor_path": "/sys/bus/platform/devices/coretemp.0/hwmon/hwmon1/temp2_input",
            "divisor": 1000
        },
        {
            "accessory": "LinuxTemperature",
            "name": "Firewalla Core 1 Temp",
            "sensor_path": "/sys/bus/platform/devices/coretemp.0/hwmon/hwmon1/temp3_input",
            "divisor": 1000
        },
        {
            "accessory": "LinuxTemperature",
            "name": "Firewalla Core 2 Temp",
            "sensor_path": "/sys/bus/platform/devices/coretemp.0/hwmon/hwmon1/temp4_input",

            "divisor": 1000
        },
        {
            "accessory": "LinuxTemperature",
            "name": "Firewalla Core 3 Temp",
            "sensor_path": "/sys/bus/platform/devices/coretemp.0/hwmon/hwmon1/temp5_input",
            "divisor": 1000
        },


Firewalla Purple

Note that this plugin does not currently work with Firewalla Purple. The sensor path is as follows in case it gets fixed in the future.

"sensor_path": "/sys/class/thermal/thermal_zone0/temp",

Homebridge Plugin currently does not work with Firewalla Purple but the sensor path is available when fixed in the future.

Homebridge Accessories with all Office devices CPU temperatures shown

And you can see FIrewalla's CPU temperatures in Homekit (Eve app shown below.)


Example Firewalla CPU Temperatures in Homekit

 

Docker Configuration Reference

This table contains important commands to help you manage your docker container. 

  File Location / Command
Config File Path /homebridge/config.json (inside container shell)
Storage Path /homebridge (inside container shell)
Restart Command sudo docker restart homebridge
Stop Command sudo docker stop homebridge
Start Command sudo docker start homebridge
View Logs Command sudo docker logs -f homebridge

 

Updating Homebridge docker 

cd /home/pi/.firewalla/run/docker/homebridge
sudo docker container stop homebridge && sudo docker container rm homebridge
sudo docker-compose up -d
sudo docker ps

 

Important Note: Preserve Resources

Docker containers can range from small to fairly large and the upgrade process means downloading a new image before deleting the old container. So be sure to use docker prune to get rid of unused containers and images or you may easily run out of space on Firewalla. 

sudo docker system prune
 

 

Known Issue

On ubuntu 22.04 and later, when docker starts up, it may load a kernel module br_netfilter which conflicts with ubuntu 22.04 if you are using Smart Queue. Dockers managed by Firewalla will automatically handle this, but if you create docker instance, you may need to run:

sudo rmmod br_netfilter

after starting docker service or the firewalla routing function may break.

This is due to a Linux Kernel bug which we plan to fix in our 1.976 release.

 

References

 

All product names, logos, and brands are the property of their respective owners. All company, product and service names used in this website are for identification purposes only. Use of these names, logos, and brands does not imply endorsement.

 

Related articles

Comments

83 comments

Sort by Date Votes
  • Avatar
    Sergio Lopez

    @Michael Thanks. I tried that command you suggested and this is what I get:

    pi@firewalla:~ (Firewalla Gold) $ sudo docker ps
    Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

    Could it be a different problem that doesn't require reinstalling since the issue also happens with my other PiHole docker?

    0
    Comment actions Permalink
  • Avatar
    Michael Bierman

    @Sergio, Then docker isn't running. You can try running these commands. 

    If that doesn't work, easiest thing to do is is reinstall. 

    0
    Comment actions Permalink
  • Avatar
    Michael Turchin

    Just installed and can get to the UI in a browser, however, the admin/admin default credentials do not allow me to log in. Any suggestions?

    0
    Comment actions Permalink
  • Avatar
    Tiago Buffon

    How do I update Node.js?

    I have the following message, and I want to make sure I'm following the proper procedures:

    Homebridge v1.7.0 requires Node.js v18.15.0 or later. You are currently running Node.js v18.13.0.

    Please upgrade Node.js before updating Homebridge.

    0
    Comment actions Permalink
  • Avatar
    Michael Bierman

    Hi @Tiago,

    Are you running homebridge/homebridge? If so, I believe it will take care of the update. If you are running oznu/homebridge it may be out of date. 

    https://github.com/homebridge/homebridge/wiki/How-To-Update-Node.js/

    0
    Comment actions Permalink
  • Avatar
    Tiago Buffon

    Hi @Michael,

    It is installed following the guide on this page.

    I also tried to run the update instructions up here with no success.

    0
    Comment actions Permalink
  • Avatar
    Michael Bierman

    I noticed that the guide changed. It used to suggest oznu/homebridge now it uses homebridge/homebridge. See the link I provided. Homebridge changed how they distribute. If you installed a while back, likely you should switch the distribution.

    0
    Comment actions Permalink
  • Avatar
    Tiago Buffon

    Thank you for being so supportive.

    I installed it last Tuesday, Oct/31/2023.
    Is there a way to uninstall and install again to see if it gets updated? Or might the docker service need to be updated?

    0
    Comment actions Permalink
  • Avatar
    Michael Bierman

    @Tiago, 

    You can edit your YAML file and use the update script gist.github.com/mbierman/6cf22430ca0c2ddb699ac8780ef281ef 

    0
    Comment actions Permalink
  • Avatar
    Tiago Buffon

    @Micheal

    Worked, thanks

    1
    Comment actions Permalink
  • Avatar
    StackIOI
    • Edited

    Is this thing working? I'm running this docker-compose.yaml (fresh install)

    version: '2'
    services:
      homebridge:
        image: homebridge/homebridge:ubuntu
        container_name: homebridge
        restart: always
        network_mode: host
        environment:
          - PGID=1000
          - PUID=1000
          - HOMEBRIDGE_CONFIG_UI=1
          - HOMEBRIDGE_CONFIG_UI_PORT=8581
          - TZ=America/Panama
          - ENABLE_AVAHI=0
        volumes:
          - '/mnt/data/docker/homebridge/data:/homebridge'
        logging:
          driver: "json-file"
          options:
            max-size: "10m"

    the container spins up but the application never runs, it loops with these internal errors

    Re-installing homebridge...
    node[261]: ../src/node_platform.cc:68:std::unique_ptr<long unsigned int> node::WorkerThreadsTaskRunner::DelayedTaskScheduler::Start(): Assertion `(0) == (uv_thread_create(t.get(), start_thread, this))' failed.
     1: 0xb85bc0 node::Abort() [node]
     2: 0xb85c3e  [node]
     3: 0xbf30fe  [node]
     4: 0xbf31e1 node::NodePlatform::NodePlatform(int, v8::TracingController*, v8::PageAllocator*) [node]
     5: 0xb438f3 node::InitializeOncePerProcess(std::vector<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >, std::allocator<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > > > const&, node::ProcessFlags::Flags) [node]
     6: 0xb43f4b node::Start(int, char**) [node]
     7: 0x7f9889ce3d90  [/lib/x86_64-linux-gnu/libc.so.6]
     8: 0x7f9889ce3e40 __libc_start_main [/lib/x86_64-linux-gnu/libc.so.6]
     9: 0xac1f4e _start [node]
    Aborted (core dumped)
    /opt/homebridge/bin/node[258]: ../src/node_platform.cc:68:std::unique_ptr<long unsigned int> node::WorkerThreadsTaskRunner::DelayedTaskScheduler::Start(): Assertion `(0) == (uv_thread_create(t.get(), start_thread, this))' failed.
     1: 0xb85bc0 node::Abort() [/opt/homebridge/bin/node]
     2: 0xb85c3e  [/opt/homebridge/bin/node]
     3: 0xbf30fe  [/opt/homebridge/bin/node]
     4: 0xbf31e1 node::NodePlatform::NodePlatform(int, v8::TracingController*, v8::PageAllocator*) [/opt/homebridge/bin/node]
     5: 0xb438f3 node::InitializeOncePerProcess(std::vector<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> >, std::allocator<std::__cxx11::basic_string<char, std::char_traits<char>, std::allocator<char> > > > const&, node::ProcessFlags::Flags) [/opt/homebridge/bin/node]
     6: 0xb43f4b node::Start(int, char**) [/opt/homebridge/bin/node]
     7: 0x7ff7e996ad90  [/lib/x86_64-linux-gnu/libc.so.6]
     8: 0x7ff7e996ae40 __libc_start_main [/lib/x86_64-linux-gnu/libc.so.6]
     9: 0xac1f4e _start [/opt/homebridge/bin/node]

    and in my data directory /config.json

    {
        "mdns": {
        "interface": "192.168.99.1"
    },
        "bridge": {
        "name": "Homebridge FWG",
        "username": "5V:20:6G:1A:1B:9C",
        "port": 52175,
        "pin": "822-72-948"
    },
        "accessories": [],
        "platforms": [
            {
                "name": "Config",
                "port": 8581,
                "platform": "config"
            }
        ]
    }

    I have NPM, Unifi and Pi-Hole running flawlessly in my FWG... anyone else with this same issue? Or did you manage to make it work?

    FWG Box Version 1.9770
    Docker Version 19.03.6
    Operating System: Ubuntu 18.04.3 LTS
    Architecture: x86_64

    0
    Comment actions Permalink
  • Avatar
    Michael Bierman

    Hi StackIOI, 

    Your config looks different than mine. I'm not sure why that is.

    Probably the easiest approach would be to stop your docker and remove the container and try this installer: github.com/mbierman/homebridge-installer which will configure things properly. Alternatively you can step through the tutorial here step by step and try and find the problem. 

    0
    Comment actions Permalink
  • Avatar
    StackIOI
    • Edited

    @Michael Bierman thank you for the reply.. sadly I have the same result.. did try your installer, and as before, the container spins up but internally fails, and starts to loop the "Re-installing homebridge..." errors. Seems something is broken with Node in the latest image.

    0
    Comment actions Permalink
  • Avatar
    Michael Bierman

    What OS are you running?

    0
    Comment actions Permalink
  • Avatar
    StackIOI

    FWG Box Version 1.9770
    Docker Version 19.03.6
    Operating System: Ubuntu 18.04.3 LTS
    Architecture: x86_64

    0
    Comment actions Permalink
  • Avatar
    Aaron
    • Edited

    Hey I tried to update Node.js to version 20.x and the response back it that is the docker is already up to date. 

    Let me know if anyone has any ideas. Here are the logs:

    Logs: The plugin "homebridge-appletv-enhanced" requires Node.js version of ^20.11.1 || ^18.19.1 which does not satisfy the current Node.js version of

    SSH:

    v18.19.0.pi@Firewalla:~/.firewalla/run/docker/homebridge (Firewalla) $ sudo docker-compose pull
    Pulling homebridge ... done
    pi@Firewalla:~/.firewalla/run/docker/homebridge (Firewalla) $ sudo docker-compose up -d
    homebridge is up-to-date

    0
    Comment actions Permalink
  • Avatar
    Sergio Lopez
    • Edited

    Noticed the cameras weren't loading the other day in the home app.

    The Homebridge app is giving errors with issueToken is invalid and Unable to retrieve access token.

    I've followed the directions on Github to retrieve "issueToken", "cookies", and the "nest_token", but still getting the errors:

    [3/30/2024, 2:10:37 PM] [homebridge-nest-cam] issueToken is invalid
    [3/30/2024, 2:10:37 PM] [homebridge-nest-cam] Unable to retrieve access token.

    Other devices/lights work on homebridge and the home app. Just Nest is what I"m having issues with.
    I also tried logging out of Nest and re-doing all the parameters again. Nothing.
    Any suggestions?

    0
    Comment actions Permalink
  • Avatar
    Michael Bierman

    @Aaron you updated node in homebridge? 

    0
    Comment actions Permalink
  • Avatar
    Michael Bierman

    @Sergio this seems like more of a homebridge question than firewalla. There are some great discussion groups. In this case, I'd suggest checking with the plugin owner/team. 

    0
    Comment actions Permalink
  • Avatar
    Sergio Lopez

    @Michael - thanks for the suggestion, I went and checked a homebridge forum and they mentioned their problems when away in V1.8.X - it seems like mine Firewalla is running v1.6.1, so I need to try to update it.  I'm going to do some digging thorugh here to see if I find the instructions to upgrade to the latest version and see if that resolves my problems.

    0
    Comment actions Permalink
  • Avatar
    Michael Bierman

    @Sergio, 

    Try 

    cd /home/pi/.firewalla/run/docker/homebridge
    sudo docker container stop homebridge && sudo docker rm homebridge
    sudo docker-compose up -d
    sudo docker ps  
    0
    Comment actions Permalink
  • Avatar
    mmyrberg

    What's the preferred way of keeping the homebridge components up to date?  I realize I can log into homebridge and see whether the different components are up to date but I was wondering if there was an automated way to keep everything up to date. 

    0
    Comment actions Permalink
  • Avatar
    Jarrod True

    Hello - I have everything working right now but, in regard to the homebridge-linux-temperature plugin, turns out the sensor path on my Firewalla Gold Pro is /sys/bus/platform/devices/coretemp.0/hwmon/hwmon4/...  No idea why it's hwmon4 rather than hwmon1 like the guide suggests. Again, once I figured that out, everything is working but just curious why that is. Is that normal for Firewalla Gold Pro and is the guide maybe a tad dated? Thanks, Jarrod

    0
    Comment actions Permalink

Please sign in to leave a comment.