Characteristics - NRCHKB/node-red-contrib-homekit-bridged GitHub Wiki

Characteristics are the values sent to the service item. They are generally true/false or number values. All services have at least one required characteristic. For example the switch has only the required characteristic of On.

Characteristic Properties

The HomeKit service node has a section called "Characteristic Properties". This section is used to define limits or initialize which characteristics you may send to your specific item.

screen shot 2019-03-08 at 7 09 01 am

The characteristic properties do not set any value in the item, instead they tell HomeKit that the item will be using that characteristic and define limits on the valid values.

Here are some examples of how Characteristic Properties work. These will be moved to their respective example pages as more documentation is written (help wanted).

On/off bulb (No optional characteristics: empty JSON object)

{}

Dimmable bulb (Enable optional characteristic Brightness)

{
    "Brightness":true
}

Color changing bulb (Enable optional characteristics Brightness, Hue, Saturation)

{
    "Brightness":true,
    "Hue":true,
    "Saturation":true
}

Color Temperature bulb

It is also possible to define the range of the lightbulb if it has a light which can change temperature.
You should watch out, that this values are in Reciprocal megakelvin so you have to 'convert' to this if your lamp is using Kelvin values (1000000 / Kelvin).

{
    "ColorTemperature": {
         "minValue": 150,
         "maxValue": 500
    }
}

Dimmable bulb with 5% increments

{
    "Brightness":{
        "minStep":5
    }
}

Security system with no "night" mode

{
    "SecuritySystemCurrentState":
        {
            "validValues": [0,1,3,4]
        },
    "SecuritySystemTargetState":
        {
            "validValues": [0,1,3,4]
        }
}

Valve with only "irrigation" valve type (will show in Home app as sprinkler)

{
    "ValveType":
    {
        "minValue":1,
        "maxValue":1
    }
}

General Characteristics

Some characteristics are available to almost all services but do not do much to change the use of the item in the Home app. For example Active, Tampered, or Fault. These characteristics are optional and are used to show extra status information in the Home app.

This list is not meant to be a comprehensive or exhaustive list of general characteristics.

Characteristic Format Accepted Values Notes
StatusActive bool true,false true indicates the accessory is active and has no errors
StatusTampered int 0, 1 0: Normal, 1: Tampered
StatusFault int 0, 1 0: Normal, 1: Fault

When these values are used, the detail screen of your accessory will show new fields under "status" to display these values. Example:

img_15d3a50a9181-1

Available Characteristics

Here is a list of Characteristics. Use this table to help determine which values and formats may be sent to each service node.

Characteristic Format Accepted values Notes
AccessControlLevel int 0-2
AccessoryFlags int
Active int 0,1 0: inactive, 1: active. Default: 0
ActivityInterval int >=0
AdministratorOnlyAccess bool true,false
AirParticulateDensity float 0-1000
AirParticulateSize int 0,1 0: 2.5M, 1: 10M. Default: 0
AirQuality int 0,1,2,3,4,5 0: unknown,1: excellent,2: good,3: fair,4: inferior,5: poor
AudioFeedback bool
BatteryLevel int 0-100
Brightness int 0-100
CameraOperatingModeIndicator int 0,1 0: disable, 1: enable. Default: 0
CarbonDioxideDetected int 0,1 0: normal, 1: abnormal. Default: 0
CarbonDioxideLevel float 0-100000
CarbonDioxidePeakLevel float 0-100000
CarbonMonoxideDetected int 0,1 0: normal, 1: abnormal. Default: 0
CarbonMonoxideLevel float 0-100
CarbonMonoxidePeakLevel float 0-100
CCAEnergyDetectThreshold int
CCASignalDetectThreshold int
CharacteristicValueTransitionControl TLV8
ChargingState int 0: not charging, 1: charging, 2: not chargeable. Default: 0
ColorTemperature int 140-500
ContactSensorState int 0,1 0: detected, 1: not detected. Default: 0
CoolingThresholdTemperature float 10-35
CurrentAirPurifierState int 0,1,2 0: inactive, 1: idle, 2: active. Default: 0
CurrentAmbientLightLevel float 0.0001-100000
CurrentDoorState int 0,1,2,3,4 0: open, 1: closed, 2: opening, 3: closing, 4: stopped. Default: 0
CurrentFanState int 0,1,2 0: inactive, 1: idle, 2: active. Default: 0
CurrentHeaterCoolerState int 0,1,2,3 0: inactive, 1: idle, 2: heating, 3: cooling. Default: 0
CurrentHeatingCoolingState int 0,1,2 0: off, 1: heat, 2: cool. Default: 0
CurrentHorizontalTiltAngle int -90-90
CurrentHumidifierDehumidifierState int 0,1,2,3 0: inactive, 1: idle, 2: humidifying, 3: dehumidifying. Default: 0
CurrentPosition int 0-100
CurrentRelativeHumidity float 0-100
CurrentSlatState int 0,1,2 0: fixed, 1: jammed, 2: swinging. Default: 0
CurrentTemperature float 0-100
CurrentTiltAngle int -90-90
CurrentTransport bool true,false
CurrentVerticalTiltAngle int -90-90
DataStreamHAPTransport TLV8
DataStreamHAPTransportInterrupt TLV8
DigitalZoom float
EventRetransmissionMaximum int
EventSnapshotsActive int 0,1 0: disable, 1: enable. Default: 0
EventTransmissionCounters int
FilterChangeIndication int 0,1 0: filter ok, 1: change filter. Default: 0
FilterLifeLevel float 0-100
FirmwareRevision string
HardwareRevision string
HeatingThresholdTemperature float 0-25 step: 0.1
HoldPosition bool true,false
HomeKitCameraActive int 0,1 0: off, 1: on. Default: 0
Hue float 0-360 step: 1
Identify bool true,false
ImageMirroring bool true,false
ImageRotation float 0-270 step: 90
InUse int 0,1 0: not in use, 1: in use. Default: 0
IsConfigured int 0,1 0: not configured, 1: configured
LeakDetected int 0,1 0: not detected, 1: detected. Default: 0
LockControlPoint TLV8
LockCurrentState int 0,1,2,3 0: unsecured, 1: secured, 2: jammed, 3: unknown. Default: 0
LockLastKnownAction int 0,1,2,3,4,5,6,7,8 0: secured physically interior, 1: unsecured physically interior, 2: secured physically exterior, 3: unsecured physically exterior, 4: secured by keypad, 5: unsecured by keypad, 6: secured remotely, 7: unsecured remotely, 8: secured by timeout. Default: 0
LockManagementAutoSecurityTimeout int Seconds
LockPhysicalControls int 0,1 0: lock disabled, 1: lock enabled. Default: 0
LockTargetState int 0,1 0: unsecured, 1: secured. Default: 0
Logs TLV8
MACRetransmissionMaximum int
MACTransmissionCounters binary data
ManagedNetworkEnable int 0,1,2 0: disabled, 1: enabled, 2: unknown. Default: 0
ManuallyDisabled int 0,1 0: enabled, 1: disabled. Default: 0
Manufacturer string
Model string
MotionDetected bool true,false
Mute bool true,false
Name string
NetworkAccessViolationControl TLV8
NetworkClientProfileControl TLV8
NetworkClientStatusControl TLV8
NightVision bool true,false
NitrogenDioxideDensity float 0-1000 step: 1
ObstructionDetected bool true,false
OccupancyDetected int 0,1 0: not detected, 1: detected
On bool true,false
OperatingStateResponse TLV8
OpticalZoom float
OutletInUse bool true,false
OzoneDensity float 0-1000 step: 1
PairingFeatures int
PairingPairings TLV8
PairSetup TLV8
PairVerify TLV8
PasswordSetting TLV8
PeriodicSnapshotsActive int 0,1 0: disable, 1: enable
Ping binary data
PM10Density float 0-1000 step: 1
PM2_5Density float 0-1000 step: 1
PositionState int 0,1,2 0: deing, 1: increasing, 2: stopped. Default: 0
ProductData
ProgrammableSwitchEvent int 0,1,2 0: single press, 1: double press, 2: long press
ProgramMode int 0,1,2 0: no program scheduled, 1: program scheduled, 2: manual mode. Default: 0
ReceivedSignalStrengthIndication int
ReceiverSensitivity int
RecordingAudioActive int 0,1 0: disable, 1: enable. Default: 0
RelativeHumidityDehumidifierThreshold float 0-100
RelativeHumidityHumidifierThreshold float 0-100 step: 1
RemainingDuration int 0-3600 step: 1
ResetFilterIndication int 0,1 0: not indicated, 1: indicated. Default: 0
RotationDirection int 0,1 0: clockwise, 1: anticlockwise. Default: 0
RotationSpeed float 0-100 step: 1
RouterStatus int 0,1 0:y. 1: noty. Default: 0
Saturation float 0-100 step: 1
SecuritySystemAlarmType int 0,1 0: no alarm, 1: alarm. Default: 0
SecuritySystemCurrentState int 0,1,2,3,4 0: stay armed, 1: away armed, 2: night armed, 3: disarmed, 4: alarm triggered. Default: 0
SecuritySystemTargetState int 0,1,2,3 0: stay armed, 1: away armed, 2: night armed, 3: disarmed. Default 0
SelectedCameraRecordingConfiguration TLV8
SelectedRTPStreamConfiguration TLV8
SerialNumber string
ServiceLabelIndex int 0-255
ServiceLabelNamespace int 0,1 0: dots, 1: numerals. Default: 0
SetDuration int 0-3600
SetupEndpoints TLV8
SetupTransferTransport TLV8
SignalToNoiseRatio int
SlatType int 0,1 0: horizontal, 1: vertical. Default: 0
SleepInterval int >=0
SmokeDetected int 0,1 0: not detected, 1: detected. Default: 0
StatusActive bool true,false
StatusFault int 0,1 0: no fault, 1: fault. Default: 0
StatusJammed int 0,1 0: not jammed, 1: jammed. Default: 0
StatusLowBattery int 0,1 0: normal, 1: low. Default: 0
StatusTampered int 0,1 0: not tampered, 1: tampered. Default: 0
StreamingStatus TLV8
SulphurDioxideDensity float 0-1000 step: 1
SupportedAudioRecordingConfiguration TLV8
SupportedAudioStreamConfiguration TLV8
SupportedCameraRecordingConfiguration TLV8
SupportedCharacteristicValueTransitionConfiguration TLV8
SupportedDiagnosticsSnapshot TLV8
SupportedRouterConfiguration TLV8
SupportedRTPConfiguration TLV8
SupportedTransferTransportConfiguration TLV8
SupportedVideoRecordingConfiguration TLV8
SupportedVideoStreamConfiguration TLV8
SwingMode int 0,1 0: disabled, 1: enabled. Default: 0
TargetAirPurifierState int 0,1 0: manual, 1: auto. Default: 0
TargetAirQuality int 0,1,2 0: excellent, 1: good, 2: fair. Default: 0
TargetDoorState int 0,1 0: open, 1: closed. Default: 0
TargetFanState int 0,1 0: manual, 1: auto. Default: 0
TargetHeaterCoolerState int 0,1,2 0: auto, 1: heat, 2: cool. Default: 0
TargetHeatingCoolingState int 0,1,2,3 0: off, 1: heat, 2: cool, 3: auto. Default: 0
TargetHorizontalTiltAngle int -90-90 step: 1
TargetPosition int 0-100
TargetRelativeHumidity float 0-100 step: 1
TargetSlatState int 0,1 0: manual, 1: auto. Default: 0
TargetTemperature float 10-38 step: 0.1. In celsius
TargetTiltAngle int -90-90 step: 1
TargetVerticalTiltAngle int -90-90 step: 1
TemperatureDisplayUnits int 0,1 0: celsius, 1: fahrenheit. Default: 0
ThirdPartyCameraActive int 0,1 0: off, 1: on. Default: 0
TransmitPower int
TransmitPowerMaximum int
ValveType int 0,1,2,3 0: generic valve, 1: irrigation, 2: shower head, 3: water faucet. Default: 0
Version string
VideoAnalysisActive int
VOCDensity float 0-1000 step: 1
Volume int 0-100
WakeConfiguration TLV8
WANConfigurationList TLV8
WANStatusList TLV8
WaterLevel float 0-100
WiFiCapabilities int
WiFiConfigurationControl TLV8
WiFiSatelliteStatus int 0,1,2 0: unknown, 1: connected, 2: not connected. Default: 0