hkcam

package module
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 16, 2022 License: Apache-2.0 Imports: 23 Imported by: 1

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

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. ELP 1080p

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/ Raspberry Pi Imager

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

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

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

  • Write the operating system on the sd card by clicking on Write Raspberry Pi Imager

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

More options
  • Select Camera and confirm that the accessory is uncertified
Select Accessory
  • Enter the pin 001-02-003 and Continue
Select Accessory

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
Services Live streaming Snapshots
Snapshot Automation
Snapshot Automation

Looking for an Enclosure

Desk mount Wall mount

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

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

TypeAssets is the uuid of the Assets characteristic

View Source 
const TypeCameraControl = "19BDAD9E-6102-48D5-B413-3F11253706AE"
View Source 
const TypeDeleteAssets = "3982EB69-1ECE-463E-96C6-E5A7DF2FA1CD"

TypeDeleteAssets is the uuid of the DeleteAssets characteristic

View Source 
const TypeGetAsset = "6A6C39F5-67F0-4BE1-BA9D-E56BD27C9606"
View Source 
const TypeTakeSnapshot = "E8AEE54F-6E4B-46D8-85B2-FECE188FDB08"

Variables

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

Source Files

View all Source files

Directories

Path Synopsis
cmd
hkcam
Package ffmpeg lets you access the camera via ffmpeg to stream video and to create snapshots.
 Package ffmpeg lets you access the camera via ffmpeg to stream video and to create snapshots.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.