Why isn’t my homebridge config.json working?

So you’ve managed to get your homebridge system up and running. You’ve added some accessories and devices but suddenly your homebridge is failing to launch!  I’ve had this issue a few times and it’s always down to an incorrectly formatted config.json file. This post will be pretty obvious to veteran developers but for beginners it can be a real pain..

The configuration file in Homebridge uses JSON (JavaScript Object Notation) which is a lightweight data-interchange format. It’s easy for humans to read and write. It’s easy for machines to parse and generate. It’s also based on a subset of the JavaScript Programming Language.

There are 4 main sections to a homebridge config file.

Homebridge Settings – “bridge“:
Homebridge Accessories – “accessories“:
Homebridge Platforms – “platforms“:
Homebridge Devices – “devices“:

Validation

The main issue to your config.json not operating correctly is probably down to a missed , : or “ and this can be a real pain to find.

When making any changes to your config files i’d recommend editing it in a JSON validation tool.

The one I use is here – JSONlint.com

This will validate your changes or highlight errors so you can fix them before editing the file on your server and should save you countless hours trying to figure out whats wrong.

So now we know how to check for errors we should talk about the format the config file should be in.

A basic configuration:

This would get your homebridge running and includes the information for the main section but it does not include any devices or platforms.

A platform would be a brand of equipment. LightwaveRF, Harmony or Nest for example

A Device would be a physical device within that platform. E.G A LWRF dimmer switch inside the lightwaverf platform.

Username – Should be the MAC address of your servers ethernet port and this must not change.

Pin – This is the pin you use when connecting to homebridge in the Apple Home app you can set this to whatever you like.

{
  "bridge": {
    "name": "Homebridge",
    "username": "xx:xx:xx:xx:xx:xx",
    "port": 51826,
    "pin": "xxx-x-xxx"
  },

  "description": "This is a sample description"
}

To add a platform we need to add the platform syntax into this config file.

You can see in the below example that we have a Wemo Switch accessory and a platform for lightwave RF and one of it’s devices. You can also see all the {} and [] which need to be correct or it will never work, this is where the validator can save you loads of time.

{
  "bridge": {
    "name": "Homebridge",
    "username": "CC:22:xx:xx:xx:xx",
    "port": 51826,
    "pin": "xxx-xx-xxx"
  },

  "description": "This is an example configuration file with one fake accessory and one fake platform. You can use this as a template for creating your own configuration file containing devices you actually own.",

  "accessories": [{
    "accessory": "WeMo",
    "name": "Coffee Maker"
  }],

  "platforms": [{
    "platform": "LightWaveRF",
    "name": "LightWaveRF",
    "ip_address": "10.0.x.xx",

    "devices": [{
      "roomId": 1,
      "roomName": "LivingRoom",
      "deviceId": 1,
      "deviceName": "MyLight",
      "deviceType": "D"
    }]
  }]
}

So now you understand the format and structure to your config.json file hopefully your installation will be smooth.