hkcam

README

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

• Multistream Support

• Persistent Snapshots

• Runs on multiple platforms (Linux, macOS)

• 3D-Printed Enclosure

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

1. build and run cmd/hkcam/main.go by running go run cmd/hkcam/main.go in Terminal
2. open any HomeKit app and add the camera to HomeKit (pin for initial setup is 001 02 003)

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

brew install git
brew install go
brew install ffmpeg

Raspberry Pi

If you want to create your own surveillance camera, you can run hkcam on a Raspberry Pi. You can use a camera module or attach an USB camera.

I love those ELP 1080P USB cameras, which are IP66 waterproof and also work in the dark.

---

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

1. Insert the sd card in your Raspberry Pi

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

3. 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)

4. Install ffmpeg apt-get install ffmpeg

5. 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

1. 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 -db=/var/lib/hkcam/data -multi_stream=true -verbose

1. 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,

Multistream

Normally in HomeKit a camera stream can only be viewed by once device at a time. If a second devices wants to 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. This is very annoying.

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.

Services	Live Streaming	List of Snapshots

Snapshot	Automation

Looking for an Enclosure

The 3D-printed enclosure is designed for a 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.

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.

Documentation

Index

• Constants
• Variables
• func SetupFFMPEGStreaming(cam *accessory.Camera, cfg ffmpeg.Config) ffmpeg.FFMPEG
• type Assets
  • func NewAssets() *Assets
• type AssetsMetadataResponse
• type CameraAssetMetadata
• type CameraControl
  • func NewCameraControl() *CameraControl
  • func (cc *CameraControl) SetupWithDir(dir string)
• type DeleteAssets
  • func NewDeleteAssets() *DeleteAssets
• type DeleteAssetsRequest
• type GetAsset
  • func NewGetAsset() *GetAsset
• type GetAssetRequest
• type TakeSnapshot
  • func NewTakeSnapshot() *TakeSnapshot

Constants

const TypeAssets = "ACD9DFE7-948D-43D0-A205-D2F6F368541D"

TypeAssets is the uuid of the Assets characteristic

const TypeCameraControl = "19BDAD9E-6102-48D5-B413-3F11253706AE"

const TypeDeleteAssets = "3982EB69-1ECE-463E-96C6-E5A7DF2FA1CD"

TypeDeleteAssets is the uuid of the DeleteAssets characteristic

const TypeGetAsset = "6A6C39F5-67F0-4BE1-BA9D-E56BD27C9606"

const TypeTakeSnapshot = "E8AEE54F-6E4B-46D8-85B2-FECE188FDB08"

Variables

var RefDate = time.Date(2019, 4, 1, 0, 0, 0, 0, time.UTC)

RefDate represents the reference date used to generate asset ids. Short ids are prefered and therefore we use 1st April 2019 as the reference date.

Functions

func SetupFFMPEGStreaming

func SetupFFMPEGStreaming(cam *accessory.Camera, cfg ffmpeg.Config) ffmpeg.FFMPEG

SetupFFMPEGStreaming configures a camera to use ffmpeg to stream video. The returned handle can be used to interact with the camera (start, stop, take snapshot…).

Types

type Assets

type Assets struct {
	*characteristic.Bytes
}

Assets contains a list of assets encoded as JSON. A valid JSON looks like this. `{"assets":[{"id":"1.jpg", "date":"2019-04-01T10:00:00+00:00"}]}` Writing to this characteristic is discouraged.

func NewAssets

func NewAssets() *Assets

type AssetsMetadataResponse

type AssetsMetadataResponse struct {
	Assets []CameraAssetMetadata `json:"assets"`
}

type CameraAssetMetadata

type CameraAssetMetadata struct {
	ID   string `json:"id"`
	Date string `json:"date"`
}

type CameraControl

type CameraControl struct {
	TakeSnapshot *TakeSnapshot
	Assets       *Assets
	GetAsset     *GetAsset
	DeleteAssets *DeleteAssets

	CameraSnapshotReq func(width, height uint) (*image.Image, error)
	// contains filtered or unexported fields
}

func NewCameraControl

func NewCameraControl() *CameraControl

func (*CameraControl) SetupWithDir

func (cc *CameraControl) SetupWithDir(dir string)

type DeleteAssets

type DeleteAssets struct {
	*characteristic.Bytes
}

DeleteAssets is used to handle request to delete assets. A valid JSON looks like this. `{"ids":["1.jpg"]}` Reading the value of this characteristic is discouraged.

func NewDeleteAssets

func NewDeleteAssets() *DeleteAssets

type DeleteAssetsRequest

type DeleteAssetsRequest struct {
	IDs []string `json:"ids"`
}

type GetAsset

type GetAsset struct {
	*characteristic.Bytes
}

GetAsset is used to get the raw data of an asset. After writing a valid JSON to this characteristic, the characteristic value will be the raw data of the requested asset. A valid JSON looks like this. `{"id":"1.jpg","width":320,"height":240}`

func NewGetAsset

func NewGetAsset() *GetAsset

type GetAssetRequest

type GetAssetRequest struct {
	ID     string `json:"id"`
	Width  uint   `json:"width"`
	Height uint   `json:"height"`
}

type TakeSnapshot

type TakeSnapshot struct {
	*characteristic.Bool
}

TakeSnapshot is used to take a snapshot. After writing `true` to this characteristic, a snapshot is taked and persisted on disk.

func NewTakeSnapshot

func NewTakeSnapshot() *TakeSnapshot