hkcam

hkcam is an open-source implementation of an HomeKit IP camera. It uses ffmpeg to access the camera stream and publishes the stream to HomeKit using hap. The camera stream can be viewed in a HomeKit app. For example my Home+ app works perfectly with hkcam.

Features

• Live streaming via HomeKit
• Works with any HomeKit app (ex. Home+)
• Multistream Support
• Persistent Snapshots
• Built-in Web Interface
• Runs on multiple platforms (Raspberry Pi OS, macOS)

Get Started

hkcam uses Go modules and therefore requires Go 1.11 or higher.

Mac

The fastest way to get started is to

1. download the project on a Mac with a built-in iSight camera

git clone https://github.com/brutella/hkcam && cd hkcam

2. build and run cmd/hkcam/main.go by running task hkcam in Terminal
3. open any HomeKit app and add the camera to HomeKit (pin for initial setup is 001 02 003)
4. view the web ui by entering the url http://localhost:8080

These steps require git, go, task and ffmpeg to be installed. On macOS you can install them via Homebrew.

brew install git
brew install go
brew install go-task/tap/go-task
brew install ffmpeg

Raspberry Pi

You can use a camera module or USB camera with a Raspberry Pi to create your own surveillance camera.

For example the ELP 1080P USB camera dome is great for outdoor use. It is IP66 waterproof and has built-in IR LEDs for night vision. This camera gets you good quality and great performance when running hkcam on the latest Raspberry Pi OS.

A cheaper alternative is a camera module attached via ribbon cable. You'll have to enable Legacy Camera Support when using a camera module on Raspberry Pi OS. That's why this option is not ideal in my opinion.

---

How to Install on a Raspberry Pi?

Follow these steps to install hkcam and all the required libraries on a Raspberry Pi OS Lite (32-bit).

1. Download and run the Raspberry Pi Imager from https://www.raspberrypi.com/software/

• Choose OS → Raspberry Pi OS (other) → Raspberry Pi OS Lite (32-bit)

• Insert a sd card into your computer and choose it as the storage

• Click on the settings icon and enable SSH, Set username and password and configure wifi

• Write the operating system on the sd card by clicking on Write

2. Insert the sd card in your Raspberry Pi

3. Connect your camera (in my case the ELP 1080P) and power supply

4. Connect to your Raspberry Pi via SSH (the first boot may take a while, so be patient) ssh pi@raspberrypi.local (enter your previously configured password)

5. Install ffmpeg apt-get install ffmpeg

6. Install v4l2loopback apt-get install v4l2loopback-dkms

• Enable v4l2loopback module at boot by creating a file /etc/modules-load.d/v4l2loopback.conf with the content

v4l2loopback

• Specify which loopback file should be created by the module (in our case /dev/video99) by creating the file /etc/modprobe.d/v4l2loopback.conf with the content

options v4l2loopback video_nr=99

• Restart the Raspberry Pi and verify that the file /dev/video99 exists

7. Install hkcam

• Download the latest release from https://github.com/brutella/hkcam/releases

wget https://github.com/brutella/hkcam/releases/download/v0.1.0/hkcam-v0.1.0_linux_arm.tar.gz

• Extract the archive with tar -xzf hkcam-v0.1.0_linux_arm.tar.gz
• Run hkcam by executing the following command

./hkcam -data_dir=/var/lib/hkcam/data -multi_stream=true -port=8080 -verbose

8. Add the camera to HomeKit

• Launch the Apple Home-app and tap + → Add Accessory

• Tap More Options...

• Select Camera and confirm that the accessory is uncertified

• Enter the pin 001-02-003 and Continue

If everything works as expected, you have to configure hkcam as a daemon – so that hkcam is automatically run after boot. This can be done in different way – systemd is recommended,

How to install with Ansible?

I've made an Ansible playbook which configures your Raspberry Pi and installs hkcam. The following steps require ansible to be installed. On macOS you can install it via Homebrew.

brew install ansible

---

First install Raspberry Pi OS, as described above. Then create ssh key and copy them to the Raspberry Pi.

ssh-keygen
ssh-copy-id pi@raspberrypi.local

After that you can execute the playbook with the following command.

cd ansible && ansible-playbook rpi.yml -i hosts

Once the command finishes, your camera can be added to HomeKit.

Multistream

Normally in HomeKit a camera stream can only be viewed by one device at a time. If a second device wants to view the stream, the Apple Home app shows

Camera Not Available Wait until someone else in this home stops viewing this camera and try again.

hkcam allows multiple devices to view the same stream by setting the option -multi_stream=true. That's neat.

Persistent Snapshots

In addition to video streaming, hkcam supports Persistent Snapshots. Persistent Snapshots is a way to take snapshots of the camera and store them on disk. You can then access them via HomeKit.

Persistent Snapshots are currently supported by Home+, as you can see from the following screenshots.

Taking snapshots in automations is also supported.

Web Interface

When running hkcam at a specific port (by specifying -port=...), you can access the web interface at the url http://{ip-address}:{port} with a browser. The web interface shows the recent snapshot and lets you install updates.

Raspberry Pi Zero W

I do get kernel panics when running hkcam with an ELP 1080P USB camera. Updating /boot/config.txt with the following changes resolve those kernel panics.

arm_freq=800
arm_freq_max=900
arm_freq_min=700

Raspberry Pi Zero W Enclosure

I've also designed an enclosure for the Raspberry Pi Zero W and standard camera module. You can use a stand to put the camera on a desk, or combine it with brackets of the Articulating Raspberry Pi Camera Mount to mount it on a wall. The 3D-printed parts are available as STL files here.

This enclosure is not waterproof and should not be used outside. Instead, you should use an ELP 1080P camera and connect it via USB to a Raspberry Pi.

Contact

Matthias Hochgatterer

Website: http://hochgatterer.me

Github: https://github.com/brutella

Twitter: https://twitter.com/brutella

License

hkcam is available under the Apache License 2.0 license. See the LICENSE file for more info.