homecamera

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 hc. 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
• 3D-Printed Enclosure
• Persistent Snapshots
• Completely written in Go
• Runs on multiple platforms (Linux, 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

1. build and run cmd/hkcam/main.go by running make run 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 with attached camera module.

Pre-configured Raspbian Image

You can use a pre-configured Raspbian Stretch Lite image, where everything is already configured.

You only need to

1. download the pre-configured Raspbian image and copy onto an sd card; download

• Note: This image only works on a Raspberry Pi Zero

1. install Etcher.app and flash the downloaded image onto your sd card.

You can do the same on the command line as well.

On macOS you have to find the disk number for your sd card

# find disk
diskutil list

You will see entries for /dev/disk0, /dev/disk1…, your sd card may have the disk number 3 and will be mounted at /dev/disk3

# unmount disk (eg disk3)
diskutil unmountDisk /dev/rdisk3

# copy image on disk3
sudo dd bs=1m if=~/Downloads/raspbian-stretch-lite-2019-04-08-hkcam-v0.0.9-armv6.img of=/dev/rdisk3 conv=sync

1. add your WiFi credentials so that the Raspberry Pi can connect to your WiFi

• create a new text file at /Volumes/boot/wpa_supplicant.conf with the following content

ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
ssid="<ssid>"
psk="<password>"
}

• replace <ssid> with the name of your WiFi, and <password> with the WiFi password.

1. insert the sd card into your Raspberry Pi and power it up. (After a reboot it may take up to several minutes until the camera is accessible via HomeKit – see issue #136.)

2. open any HomeKit app and add the camera to HomeKit (pin for initial setup is 001 02 003)

Manual Configuration

If you want, you can configure your Raspberry Pi manually. This setup requires more configuration. I've made an Ansible playbook to configure your RPi with just one command.

The easiest way to get started is to

1. configure your Raspberry Pi

• install Raspbian
• enable ssh (and WiFi if needed)
• connect a camera module

1. create ssh key and copy them to the Raspberry Pi

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

3 run the rpi playbook

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

1. open any HomeKit app and add the camera to HomeKit (pin for initial setup is 001 02 003)

These steps require ansible to be installed. On macOS you can install it via Homebrew.

brew install ansible

What does the playbook do?

The ansible playbook configures the Raspberry Pi in a way that is required by hkcam. It does that by connecting to the RPi via ssh and running commands on it. You can do the same thing manually on the shell but ansible is more convenient.

Here are the things that the ansible playbook does.

1. Installs the required packages
   • ffmpeg – to stream video from the camera via RTSP to HomeKit
   • v4l2loopback - to create a virtual video device to access the video stream by multiple ffmpeg processes
   • runit – to run hkcam as a service
2. Downloads and installs the latest hkcam release
3. Edits /boot/config.txt to enable access to the camera
4. Edits /etc/modules to enable the bcm2835-v4l2 and v4l2loopback kernel modules
5. Restarts the RPi

After the playbook finishes, the RPi is ready to be used as a HomeKit camera.

Additional Steps

• I recommend to change the password of the pi user, once you have configured your Raspberry Pi.
• If you want to have multiple cameras on your network, you have to make sure that the hostnames are unqiue. By default the hostname of the Raspberry Pi is raspberrypi.local.
• SSH is enabled in the hkcam image. You may want to disable it.

Debugging

If experience issues with the hkcam daemon, you can find log outputs at /var/log/hkcam/current.

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.

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 3, as you can see from the following screenshots.

Services	Live Streaming	List of Snapshots

Snapshot	Automation

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
• func SetupFFMPEGStreaming(cam *accessory.Camera, cfg ffmpeg.Config) ffmpeg.FFMPEG
• type Assets
  • func NewAssets() *Assets
• type AssetsMetadataResponse
• type CameraAssetMetadata
• 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 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"

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