Repository navigation
HomeKit Terminology
This page tries to give you an introduction to terminology used in HomeKit. A pretty detailed resource on
how HomeKit works is the HomeKit Accessory Protocol (HAP) specification. Apple now shares it with members of the
MFi Program (see the Apple Home - Apple Developer website).
You don't need it to use HAP-NodeJS: every service and characteristic HAP-NodeJS supports is listed in the
API documentation.
The Homebridge wiki also has a HomeKit Glossary of Terms.
- Accessory: An accessory is a representation for the actual physical device. An accessory consists of multiple services.
-
Service: A service is a way of grouping the functionality of a certain device type. Common services are
Switch,LightbulborOutlet. A service consist of multiple required and optional characteristics. There are multiple Apple predefined services which can be found in the HAP specification (and in HAP-NodeJS asService.*). Apple predefined services are the only services which can be controlled with the Home app or using Siri. -
Characteristic: A characteristic is the actual control point to interact with functionality of a service.
For example, the
Switchservice has the required characteristicOn. Characteristics can be read or written to (additionally they can also send updates, so called events). The characteristic defines a certainformatfor their value. TheOncharacteristic defines a format ofbool, meaning it accepts a value oftrueorfalse, which represent on or off. TheOncharacteristic is not only used for theSwitchservice, but also for example for theOutletservice. It's basically used for any service which can be turned on or off.
To illustrate the above terms imagine the following example:
You got a motion sensor which incorporates a temperature sensor and a light level sensor. Your implementation would
expose one accessory (representing the one physical device) exposing three services: a MotionSensor service, a
TemperatureSensor service and a LightSensor service, as these are all the functionalities your device supports.
You can look up the characteristics defined for the given service in the HAP specification, or in the HAP-NodeJS API documentation. All services define a set of
required characteristics you must implement (and are automatically added by HAP-NodeJS) and may define a set of
optional characteristics you may implement if you want to support the given functionality.
-
Bridge: In general all HomeKit devices would only expose a single accessory. An exception to this is a
Bridgeaccessory. ABridgeis a special type of accessory which is able to add multiple accessories. Like for example a Philips Hue bridge would bridge multiple Lights and connect them to your local network.
- (HomeKit) controller: this term is used to refer to any client communicating with our HAP server. Most of the time this would be an iPhone, iPad or Mac running the Home app, or a Home Hub.
- Home Hub: A Home Hub is a HomeKit controller which is able to provide remote access to other HomeKit controllers. It also runs your automations. Apple's guide lists Apple TV and HomePod (including HomePod mini) as Home Hubs.
- Raspberry Pi
- Debian, Ubuntu
- CentOS, Fedora, Red Hat
- Arch, Manjaro
- Docker
- Virtual Machine (Windows & macOS)
- Windows
- macOS
- Synology DSM 7
- Other Platforms
- Basic Troubleshooting
- Backup and Restore
- Child Bridges
- Config File
- Connect To HomeKit
- FFmpeg for Homebridge
- HomeKit Glossary of Terms
- iOS Apps
- mDNS Options
- Remote Access
- Useful Links
- Basic Troubleshooting
- Config Options
- Enabling Accessory Control
- Enabling UI with Docker
- Homebridge Service Command
- Manual Configuration
- Reverse Proxy: Apache
- Reverse Proxy: Nginx and SSL
- Manage Homebridge Version
- Manage Homebridge UI Version
- Manage Plugin Version
- Manage Node Version
- Updating To Homebridge v2
Raspberry Pi Image
- Pi Image Home
- Getting Started
- Supported Raspberry Pi Models
- Find the IP Address
- Connect Via SSH
- Connect Via VNC (old)
- Set the Date and Time
- SSL / HTTPS Access
- Disable the WiFi Setup Portal
- Reset WiFi
- Upgrade to the Latest Image
- Update Homebridge and Node.js
- Enable Debug or Insecure Mode
- Install Pi-hole
- Install AdGuard Home
- Install deCONZ (ConBee / RaspBee)
- Migrate From HOOBS
- Fix Eero Router Connectivity
Docker
Synology Package
HAP-NodeJS
- Developer Docs
- API Reference
- Plugin Templates
- Other Links (Internal)
- Other Links (External)