HomeKit
Aperture can appear in the Apple Home app as a bridge. Each camera becomes a motion sensor, and an Aperture Security accessory arms and disarms Aperture from your iPhone, iPad or Mac. This page shows how to switch the bridge on, pair it, and what to expect from it.
Before you start
Section titled “Before you start”The bridge announces itself on your network over mDNS (Bonjour), which uses UDP port 5353. avahi-daemon, the mDNS service many Linux distributions install, binds that port exclusively. With avahi running, the Home app cannot find the bridge, and Aperture’s own aperture-discovery service (which makes aperture.local work) breaks too.
The installer refuses to run while avahi-daemon is present. If it was installed later, turn it off:
systemctl is-active avahi-daemonsudo systemctl disable --now avahi-daemon avahi-daemon.socketThe first command should print inactive (or report that the unit does not exist).
Your iPhone or iPad and the server must be on the same network segment, because mDNS does not cross routers or VLANs without a repeater.
Switch the bridge on
Section titled “Switch the bridge on”- Open Integrations and select ONVIF & HomeKit.
- Switch on Apple Home (HomeKit). The bridge starts at once, without a restart, and the row shows Running.
- Under the switch, Aperture shows the pairing code, formatted
123-45-678. The copy button next to it copies the code.
If the bridge cannot be built, the switch stays off and an error starting with “could not start HomeKit:” appears under the list. If the row shows Failed to start, the bridge started but then stopped, for example because of a port clash. The reason appears in red under the row’s description, and the server log has the details:
journalctl -u aperture -n 100 | grep -i homekitThe environment variable APERTURE_HOMEKIT_ENABLED="true" in /etc/aperture/aperture.env only sets the starting value of this switch the first time Aperture starts. After that, the switch in the app is what counts.
Pair it in the Home app
Section titled “Pair it in the Home app”- On your iPhone or iPad, open the Home app and tap Add Accessory.
- Choose More options. Aperture appears in the list of nearby accessories.
- Tap it and enter the pairing code shown in Aperture.
- The Home app warns that the accessory is not certified. That is expected for any bridge that is not part of Apple’s certification programme; confirm to continue.
- Assign the bridge and its accessories to rooms.
The pairing code is generated once per installation and kept, so every Aperture has its own code and it does not change between restarts. Pairing data lives in /var/lib/aperture/data/homekit on the server.
What appears in Home
Section titled “What appears in Home”| Accessory | What it does |
|---|---|
| Aperture | The bridge itself, which everything else hangs off. |
| Aperture Security | A security system. Arming it in Home arms Aperture; disarming it disarms Aperture. |
| One motion sensor per camera | Named after the camera. Turns on when Aperture’s motion detection opens an event on that camera and turns off 20 seconds after the latest event. |
The armed state is shared with the rest of Aperture: arming from Home, from the alarms controls or from Home Assistant all change the same setting, and the Home app catches up within about 5 seconds when it is changed elsewhere. Any arm mode you choose in Home (Home, Away or Night) arms Aperture; Aperture always reports itself to Home as armed Away or Disarmed.
Motion sensors follow Aperture’s own motion detection, so a camera with Motion detection switched off never triggers its sensor. Audio events and object recognition do not trigger the sensors.
With the sensors in Home you can build Home automations such as “when Garage detects motion, turn on the garage light”.
Which cameras appear
Section titled “Which cameras appear”A camera gets a motion sensor when it is Enabled and Show in Home Assistant & HomeKit is on in its settings. New UniFi Protect cameras start with that switch off; see UniFi Protect.
The accessory list is fixed when the bridge starts. After you add, delete, enable, disable or rename a camera, or change its Show in Home Assistant & HomeKit switch, the Home app sees the change only after the bridge starts again: restart Aperture, or switch Apple Home (HomeKit) off and on.
sudo systemctl restart apertureLimits
Section titled “Limits”- No video. Cameras are motion sensors only; there is no live view or recording in the Home app.
- Motion only from motion detection. People, vehicles, packages and sound do not appear in Home.
- One network segment. The Home app finds the bridge over mDNS, so it must be on the same network as the server, or your network must repeat mDNS between segments. Away from home, a Home hub (an Apple TV, HomePod or iPad) relays the accessories as it does for any HomeKit device.
- Changing TCP port. The bridge listens on a TCP port the system chooses each time it starts. A host firewall that only opens fixed ports blocks it; allow the bridge’s traffic from your local network instead.
Troubleshooting
Section titled “Troubleshooting”- Aperture does not appear in Add Accessory. Check that the row shows Running, that avahi-daemon is not running on the server, and that your phone is on the same network as the server.
- The row shows Failed to start. Read the log as shown above. A bridge that stops on its own switches itself to not running, so the switch never shows a green light for a bridge that is down.
- A camera is missing or has an old name. Restart the bridge as described in Which cameras appear.
Related: Alarms · Home Assistant · ONVIF and RTSP · Motion detection