Home Automation blog

Skip to Content

NodeRed HomeKit Service reference

Article image for NodeRed HomeKit Service reference

Posted by Chris

Date posted:

NodeRed's HomeKit package has a distinct lack of documentation and/or examples which I found to be a bit of a roadblock. This post aims to remedy the situation. What follows is a list of Services and Characteristics that can (and how to) be implemented.

Each code example is typically going to use a Function node as an input node to each HomeKit node. You could also use an Inject node to send a JSON object to each HomeKit node. As seen in this example:

{
	"TargetDoorState": 1
}

Services


AirPurifier

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.Active = 0;
characteristic.TargetAirPurifierState = 0;
characteristic.CurrentAirPurifierState = 0;

msg.payload = characteristic;
return msg;

AirQualitySensor

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.AirQuality = 0;

msg.payload = characteristic;
return msg;

BatteryService

Note: This service is unsupported by the native Apple Home app. 3rd party apps and Siri only.

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.BatteryLevel = 100;
characteristic.ChargingState = 0;
characteristic.StatusLowBattery = 0;

msg.payload = characteristic;
return msg;

CameraRTPStreamManagement

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.SelectedRTPStreamConfiguration = '';
characteristic.SetupEndpoints = '';
characteristic.SupportedAudioStreamConfiguration = '';
characteristic.StreamingStatus = '';
characteristic.SupportedVideoStreamConfiguration = '';
characteristic.SupportedRTPConfiguration = '';

msg.payload = characteristic;
return msg;

CarbonDioxideSensor

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.CarbonDioxideDetected = 0;

msg.payload = characteristic;
return msg;

CarbonMonoxideSensor

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.CarbonMonoxideDetected = 0;

msg.payload = characteristic;
return msg;

ContactSensor

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.ContactSensorState = 1;

msg.payload = characteristic;
return msg;

Door

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.CurrentPosition = 0;
characteristic.TargetPosition = 0;
characteristic.PositionState = 2;

msg.payload = characteristic;
return msg;

Doorbell

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.ProgrammableSwitchEvent = 0;

msg.payload = characteristic;
return msg;

Fan

Note: Might depreciated in future versions. See Fanv2

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.On = false;

msg.payload = characteristic;
return msg;

Fanv2

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.Active = 1;

msg.payload = characteristic;
return msg;

Faucet

Note: This service is unsupported by the native Apple Home app. 3rd party apps and Siri only.

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.Active = 1;

msg.payload = characteristic;
return msg;

FilterMaintenance

Note: This service is unsupported by the native Apple Home app. 3rd party apps and Siri only.

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.FilterChangeIndication = 0;

msg.payload = characteristic;
return msg;

GarageDoorOpener

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.ObstructionDetected = false;
characteristic.TargetDoorState = 1;
characteristic.CurrentDoorState = 1;

msg.payload = characteristic;
return msg;

HeaterCooler

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.CurrentHeaterCoolerState = 0;
characteristic.TargetHeaterCoolerState = 0;
characteristic.CurrentTemperature = 0;

msg.payload = characteristic;
return msg;

HumidifierDehumidifier

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.Active = 0;
characteristic.CurrentHumidifierDehumidifierState = 0;
characteristic.TargetHumidifierDehumidifierState = 0;
characteristic.CurrentRelativeHumidity = 0;

msg.payload = characteristic;
return msg;

HumiditySensor

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.CurrentRelativeHumidity = 0;

msg.payload = characteristic;
return msg;

IrrigationSystem

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.Active = 0;
characteristic.ProgramMode = 0;
characteristic.InUse = 0;

msg.payload = characteristic;
return msg;

LeakSensor

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.LeakDetected = 0;

msg.payload = characteristic;
return msg;

LightSensor

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.CurrentAmbientLightLevel = 0;

msg.payload = characteristic;
return msg;

Lightbulb

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.On = 0;
characteristic.Brightness = 0;

msg.payload = characteristic;
return msg;

LockMechanism

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.LockTargetState = 0;
characteristic.LockCurrentState = 0;

msg.payload = characteristic;
return msg;

Microphone

Note: This service is unsupported by the native Apple Home app. 3rd party apps and Siri only.

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.Mute = false;

msg.payload = characteristic;
return msg;

MotionSensor

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.MotionDetected = false;

msg.payload = characteristic;
return msg;

OccupancySensor

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.OccupancyDetected = false;

msg.payload = characteristic;
return msg;

Outlet

Required characteristics:

Optional characteristics:

  • None
var characteristic = {};

characteristic.On = 0;
characteristic.OutletInUsec = false;

msg.payload = characteristic;
return msg;

PlaybackDeviceService

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.PlaybackState = 2;

msg.payload = characteristic;
return msg;

SecuritySystem

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.SecuritySystemTargetState = 3;
characteristic.SecuritySystemCurrentState = 3;

msg.payload = characteristic;
return msg;

Slat

Note: This service is unsupported by the native Apple Home app. 3rd party apps and Siri only.

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.CurrentSlatState = 0;
characteristic.SlatType = 0;

msg.payload = characteristic;
return msg;

SmokeSensor

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.SmokeDetected = 0;

msg.payload = characteristic;
return msg;

Speaker

Note: This service is unsupported by the native Apple Home app. 3rd party apps and Siri only.

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.Mute = false;

msg.payload = characteristic;
return msg;

StatelessProgrammableSwitch

Required characteristics:

Optional characteristics:

  • None
var characteristic = {};

characteristic.ProgrammableSwitchEvent = 0;

msg.payload = characteristic;
return msg;

Switch

Required characteristics:

Optional characteristics:

  • None
var characteristic = {};

characteristic.On = 0;

msg.payload = characteristic;
return msg;

TemperatureSensor

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.CurrentTemperature = 0;

msg.payload = characteristic;
return msg;

Thermostat

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.CurrentHeatingCoolingState = 0;
characteristic.TargetTemperature = 0;
characteristic.TemperatureDisplayUnits = 0;
characteristic.CurrentTemperature = 0;
characteristic.TargetHeatingCoolingState = 0;

msg.payload = characteristic;
return msg;

Valve

Note: This service is unsupported by the native Apple Home app. 3rd party apps and Siri only.

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.Active = 0;
characteristic.ValveType = 0;
characteristic.InUse = 0;

msg.payload = characteristic;
return msg;

Window

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.CurrentPosition = 0;
characteristic.TargetPosition = 0;
characteristic.PositionState = 2;

msg.payload = characteristic;
return msg;

WindowCovering

Required characteristics:

Optional characteristics:

var characteristic = {};

characteristic.CurrentPosition = 0;
characteristic.TargetPosition = 0;
characteristic.PositionState = 2;

msg.payload = characteristic;
return msg;