Presenting Erroneous Accessory State to the User

This page is still in DRAFT state

TLDR: Your accessory should always be reachable and fully operational.

HomeKit is designed around the philosophy that, if an accessory is reachable over the network (i.e. has published a HomeKit service), the accessory should work. This is analogous to the expectation that users would have with 'non-smart' devices, e.g. a light switch will always work, a door will always open when you push the handle, and a lock will always open with a key. This 'zero downtime' expectation is extremely important for smart home accessories to be viable alternatives to their 'dumb' equivalents, because the failure mode is so disastrous: for example, being able to unlock your front door less than 100% of the time means that, sooner or later, you will be stuck outside your house. One of the ways that Apple 'nudges' developers to create 'zero downtime' devices is by deliberately not offering any practical way for accessories to signal to HomeKit that they are not operational. (Prior to iOS 11, HomeKit did provide for an 'unreachable' flag, but this has now been removed.)

It is possible, inside of a Characteristic's GET handler, to throw an error. This will usually force the Apple Home app UI to show 'No Response' for the accessory, but this 'No Response' state will generally persist for a long time (e.g. until the Apple Home app is closed and re-opened), even if you then return a valid value for the Characteristic, because once in a 'No Response' state, the Apple Home app no longer checks for characteristic updates. So, this is almost certainly not what you ever want to do to signal a transient error state.

For accessories to get Apple's MFi/HomeKit certification, they must be fully operational over the local network only. As such, accessory vendors have full end-to-end control and so, with careful design, can effectively guarantee 'zero downtime' and so there is no reason for a failure condition to exist. However, many HAP-NodeJS/Homebridge accessories do leverage a vendor's cloud service for device control (NB this would not pass HomeKit certification), and so there are sometimes circumstances where HAP-NodeJS's HomeKit service is accessible over the network, but the device may not be controllable.

So, first and foremost, when developing HAP-NodeJS accessories (or Homebridge plug-ins) try to control the device using a local API if at all possible. If this is not possible, plug-in developers should state clearly to their users that the plug-in relies on a cloud API, and so downtime is possible, to create realistic expectations, and also produce clear, human-readable output explaining what has happened in the Homebridge log if this situation occurs. (Unfortunately, almost no plug-ins actually do this.) In addition, exercise a high level of care when developing code to (1) retry failed API calls if needed, and (2) make sure any possible errors are handled cleanly and do not lead to unhandled exceptions or unhandled promise rejections, which can result in Homebridge passing an error state back to HomeKit (or even shut down).

Below, we describe some mechanisms to signal a 'not ready' state to a user if there is absolutely no alternative.

Using dedicated, Accessory-specific characteristic values

Some services expose characteristics that can be used to encode a 'not ready' or a 'safe default' state (e.g. AirQuality characteristic has an unknown value, or for example a sensor can return a not-detected state).

Using the StatusActive Characteristic

Almost all services support StatusActive as an optional characteristic. If StatusActive is set to false, this does not affect HomeKit's operation per se, but it will show 'Status Active - No' in the accessory's settings page in the Apple Home app. This will provide a visual cue to the user that the accessory is not operational.

Fatal Errors

In severe error cases that require user attention use HapStatusError with values of HAPStatus (e.g. service communication failure, most of the others have special meaning). Again please note that this will force all accessories on the bridge into a 'No Response' state for an extended period of time (often until the Apple Home app is closed and re-opened), and so is almost certainly the wrong course of action.