DOCSEARCHbyAlgolia
Submit Docs

nrchkb HomeKit Wiki

website·Indexed 29 days ago

https://nrchkb.github.io/

A technical reference for HomeKit services and characteristics, providing UUIDs, data formats (such as tlv8, uint8, and int), and implementation details. Includes documentation for services like Thermostat and Wi Fi Satellite, along with specific characteristics for target state control, network configuration, and device capabilities, supported by Node-RED flow samples and JSON payloads.

Tokens
78.5K
Snippets
358
Records
585
Agent score
73%

What's inside nrchkb

  1. Overview of NRCHKB HomeKit simulation for Node-RED

    NRCHKB (node-red-contrib-homekit-bridged) is a collection of Node-RED nodes designed to simulate native Apple HomeKit accessories. It allows Node-RED flows to set accessory states visible in the iOS and MacOS Home apps, and conversely, passes commands from the Home app or Siri back into Node-RED flows.

  2. Television Service Overview and Requirements

    The Television Service (UUID: 000000D8-0000-1000-8000-0026BB765291) allows for controlling a TV's power state and integrating linked services such as Input Sources and Television Speakers. For complex linked services to display correctly in the iOS Home app, they must be configured as standalone accessories.

  3. Implement Garage Door Opener service in HomeKit

    The Garage Door Opener service (UUID: 00000041-0000-1000-8000-0026BB765291) is used to control and monitor garage doors. For safety, it is recommended to use at least three sensors: one for 'fully opened', one for 'fully closed', and one for 'obstruction detected'.

  4. Implement a HomeKit Valve service

    The Valve service (UUID: 000000D0-0000-1000-8000-0026BB765291) is used to represent irrigation valves or similar motorized/solenoid components. To function correctly in Home.app, it requires three mandatory characteristics: Active, InUse, and ValveType.

  5. Implement an Occupancy Sensor service

    The Occupancy Sensor service (UUID: 00000086-0000-1000-8000-0026BB765291) is used to detect presence. It is described as a more sensitive and energy-efficient alternative to a Motion Sensor. To function, it requires the OccupancyDetected characteristic. Other optional characteristics include Name, StatusActive, StatusFault, StatusLowBattery, and StatusTampered.

  6. Understand the Status Node output schema

    When triggered, the Status Node outputs a payload containing the following details about the selected HomeKit Service:

    • displayName: The display name of the service.
    • UUID: The Service UUID per HAP specification.
    • subtype: An internal value used by nrchkb.
    • constructorName: The service name per HAP specification.
    • hiddenService: Boolean indicating if the service is hidden.
    • primaryService: Boolean indicating if the service is the primary service.
    • characteristics: A list of characteristics currently being used by the service.
    • optionalCharacteristics: A list of all optional characteristics the service could potentially use.
    {
  "payload": {
    "displayName": "My Fav Switch",
    "UUID": "00000049-0000-1000-8000-0026BB765291",
    "subtype": "01b45824-9beb-4b19-bb0c-3b4c9e3fe2ba",
    "constructorName": "Switch",
    "hiddenService": false,
    "primaryService": false,
    "characteristics": [
      {
        "displayName": "Name",
        "UUID": "00000023-0000-1000-8000-0026BB765291",
        "eventOnlyCharacteristic": false,
        "constructorName": "Name",
        "value": "My Fav Switch",
        "props": {
          "format": "string",
          "perms": ["pr"],
          "maxLen": 64
        }
      },
      {
        "displayName": "On",
        "UUID": "00000025-0000-1000-8000-0026BB765291",
        "eventOnlyCharacteristic": false,
        "constructorName": "On",
        "value": false,
        "props": {
          "format": "bool",
          "perms": ["ev", "pr", "pw"]
        }
      }
    ],
    "optionalCharacteristics": [
      {
        "displayName": "Name",
        "UUID": "00000023-0000-1000-8000-0026BB765291",
        "eventOnlyCharacteristic": false,
        "constructorName": "Name",
        "value": "",
        "props": {
          "format": "string",
          "perms": ["pr"],
          "maxLen": 64
        }
      }
    ]
  }
}

  7. Implement the Heater Cooler service

    The Heater Cooler service (UUID: 000000BC-0000-1000-8000-0026BB765291) is used as an Air Conditioner accessory supporting three modes: Auto, Heat, and Cool. It can optionally control fan speed and swing mode. Additionally, it can be implemented as a Linked Service for the Faucet service to manage water heating via common temperature control.

  8. Light Bulb service overview

    The Light Bulb service (UUID: 00000043-0000-1000-8000-0026BB765291) is used to represent light fixtures in HomeKit. The only required characteristic is On. Other optional characteristics include Brightness, ColorTemperature, Hue, Saturation, and transition controls.

  9. Configure Host Node for Home.app integration

    The Host Node links service nodes to the Apple Home app. It can be configured in two modes:

    • Bridge: When added to Home.app, it adds all associated services related to that bridge.
    • Accessory: The bridge acts as the accessory itself. This allows you to define a specific service type and display a corresponding logo in Home.app. This mode is recommended for groups of services like Televisions or Smart Speakers to avoid display issues.

    Important Note on Subflows: If a Bridge is created within a subflow, a new Bridge will be created for every instance of that subflow. If created outside a subflow, the Bridge is reused.

  10. Implement a Window Covering service

    The Window Covering service (UUID: 0000008C-0000-1000-8000-0026BB765291) allows control of blinds, curtains, or shutters.

    Key Implementation Details:

    • Position State: While an official characteristic, it is implicitly derived by comparing CurrentPosition to TargetPosition (e.g., if Current > Target, the state is 'Decreasing').
    • UI Feedback: In the Home app, a spinning icon appears when CurrentPosition and TargetPosition are not equal. If the state is changed by an external system, both characteristics should be updated to ensure the UI reflects the correct state.
    • Minimal Setup: A minimal implementation requires only position-related characteristics.

  11. Carbon Dioxide Sensor Service Overview

    The Carbon Dioxide Sensor service (UUID: 00000097-0000-1000-8000-0026BB765291) is used to monitor CO2 levels. Note that the Apple Home app does not display the CO2 level on the device icon; users must open the device preferences in the Home app to view the current value.

  12. Camera Control service overview and characteristics

    The Camera Control service (UUID: 00000111-0000-1000-8000-0026BB765291) allows integration of cameras into HomeKit. It is recommended to add only one camera per bridge, treating the camera as the parent service with 'motion' and 'doorbell' as linked services.

    Characteristics:

    • On: Required (✓)
    • CurrentHorizontalTiltAngle: Optional
    • CurrentVerticalTiltAngle: Optional
    • TargetHorizontalTiltAngle: Optional
    • TargetVerticalTiltAngle: Optional
    • NightVision: Optional
    • OpticalZoom: Optional
    • DigitalZoom: Optional
    • ImageRotation: Optional
    • ImageMirroring: Optional
    • Name: Optional