IP Camera

iOS 10 added support for IP Camera to HomeKit. The IP Camera protocol is mostly based on RTP with the optional requirement for SRTP. HAP-NodeJS updated to support IP Camera with v0.4.0.

To use IP Camera with HAP-NodeJS, you will need construct a camera object and invoke Accessory. configureCameraSource(camera) to inform HAP-NodeJS the accessory supports IP Camera. You can use Camera.js as the reference and modify from there.

Please notice that due to protocol limitation, it's not possible to expose multiple cameras via a single HAP Endpoint. Aka trying to add a camera to a bridged accessory may result unexpected behavior.

High Level Overview of Camera Object

A camera object in HAP-NodeJS must implements the following:

• services

Array of Service

iOS expects a CameraControl service and a CameraRTPStreamManagement service. The accessory can provide multiple CameraRTPStreamManagement services to iOS. To simplify the stream parameter negotiation, HAP-NodeJS provides a helper class StreamController which handles the stream request from iOS device. For more information about StreamController, please refer to section StreamController.

The number of CameraRTPStreamManagement services determines the number of concurrent streams the accessory can support. Apple recommends accessory to support at least two concurrent streams.

• handleSnapshotRequest(request, callback(error, snapshot))

This method will be invoked when iOS device requests snapshot from the accessory. The request contains width and height of the requested snapshot. The callback is a function that expects error or snapshot image buffer.

iOS expects the snapshot to be under JPEG format. Please try to honor the requested width and height and not send a huge snapshot back to callback. HomeKit on iOS may crash when it receives a huge snapshot.

StreamController

StreamController is a helper class which manages CameraRTPStreamManagement service and handles stream negotiation from iOS device. The constructor takes in Identifier, Options and the StreamDelegate object.

Identifier

Identifier is used to differentiate CameraRTPStreamManagement services. It must be unique for each StreamController.

Options

Options is used to determine the accessory's streaming capabilities.

{
  proxy: bool, // Accessory needs RTP/RTCP MUX Proxy
  srtp: bool, // Accessory supports SRTP AES_CM_128_HMAC_SHA1_80
  video: {
    resolutions: [
      [1920, 1080, 30], // Width, Height, framerate
      [320, 240, 15], // Apple Watch requires this configuration
      ...
    ],
    codec: {
      profiles: [0, 1, 2], // Enum, please refer StreamController.VideoCodecParamProfileIDTypes
      levels: [0, 1, 2] // Enum, please refer StreamController.VideoCodecParamLevelTypes
    }
  },
  audio: {
    codecs: [
      {
        type: "OPUS", // Audio Codec, as of iOS 10.1, HomeKit only supports OPUS and AAC-eld
        samplerate: 24 // Sample Rate, Apple Watch only supports 16KHz
      },
      {
        type: "AAC-eld",
        samplerate: 16
      }
    ]
  }
}

StreamDelegate

StreamController expects a delegate object that handles the actual streaming request to iOS device. The delegate object needs to implement the following:

• prepareStream(request, callback(response))

This method will be invoked when iOS device tries to start video stream. The request contains information like sessionID, targetAddress and other informations that will be used to setup RTP/RTCP stream. The callback expects a response which contains information supplied by accessory to setup RTP/RTCP stream. For more information about request and response, please refer to section Prepare Stream.

• handleStreamRequest(request)

This method will be invoked when iOS device requests accessory to start, stop or reconfigure the RTP stream. The request will contain basic information like sessionID along with other parameters that will be helpful for streaming. For more information about handling stream request, please refer to section Handle Stream Request.

Prepare Stream

Handle Stream Request