Accepts a function that will be called to retrieve the current value of a Characteristic. The function must return a valid Characteristic value for the Characteristic type. May optionally return a promise.
Accepts a function that will be called when setting the value of a Characteristic. If the characteristic supports Perms.WRITE_RESPONSE and the request requests a write-response value, the returned value will be used. May optionally return a promise.
Removes the CharacteristicGetHandler handler which was configured using onGet.
Removes the CharacteristicSetHandler which was configured using onSet.
This method acts similarly to updateValue by setting the current value of the characteristic without calling any CharacteristicEventTypes.SET or onSet handlers. The difference is that this method forces an event notification sent (updateValue only sends one if the value changed). This is especially useful for characteristics like Characteristic.ButtonEvent or Characteristic.ProgrammableSwitchEvent.
The new value.
Optionalcontext: anyPassed to the CharacteristicEventTypes.CHANGE event handler.
Updates the properties of this characteristic. Properties passed via the parameter will be set. Any parameter set to null will be deleted. See CharacteristicProps.
Partial properties object with the desired updates.
This method can be used to set up additional authorization for a characteristic. For one, it adds the Perms.ADDITIONAL_AUTHORIZATION permission to the characteristic (if it wasn't already) to signal support for additional authorization to HomeKit. Additionally, an AdditionalAuthorizationHandler is set up which is called before a write request is performed.
Additional Authorization Data can be added to SET request via a custom iOS App. Before hap-nodejs executes a write request it will call the AdditionalAuthorizationHandler with 'authData' supplied in the write request. The 'authData' is a base64 encoded string (or undefined if no authData was supplied). The AdditionalAuthorizationHandler must then return true or false to indicate if the write request is authorized and should be accepted.
Handler called to check additional authorization data.
This updates the value by calling the CharacteristicEventTypes.SET event handler associated with the characteristic.
This acts the same way as when a HomeKit controller sends a /characteristics request to update the characteristic.
An event notification will be sent to all connected HomeKit controllers which are registered
to receive event notifications for this characteristic.
This method behaves like a updateValue call with the addition that the own CharacteristicEventTypes.SET event handler is called.
The new value.
Note: If you don't want the CharacteristicEventTypes.SET to be called, refer to updateValue.
Sets the state of the characteristic to an errored state.
If a onGet or CharacteristicEventTypes.GET handler is set up, the errored state will be ignored and the characteristic will always query the latest state by calling the provided handler.
If a generic error object is supplied, the characteristic tries to extract a HAPStatus code from the error message string. If not possible a generic HAPStatus.SERVICE_COMMUNICATION_FAILURE will be used. If the supplied error object is an instance of HapStatusError the corresponding status will be used.
This doesn't call any registered onSet or CharacteristicEventTypes.SET handlers.
Have a look at the Presenting Erroneous Accessory State to the User guide for more information on how to present erroneous state to the user.
The error object
Note: Erroneous state is never pushed to the client side. Only, if the HomeKit client requests the current state of the Characteristic, the corresponding HapStatusError is returned. As described above, any onGet or CharacteristicEventTypes.GET handlers have precedence.
This updates the value by calling the CharacteristicEventTypes.SET event handler associated with the characteristic.
This acts the same way as when a HomeKit controller sends a /characteristics request to update the characteristic.
An event notification will be sent to all connected HomeKit controllers which are registered
to receive event notifications for this characteristic.
This method behaves like a updateValue call with the addition that the own CharacteristicEventTypes.SET event handler is called.
The new value.
Optionalcontext: anyPassed to the CharacteristicEventTypes.SET and CharacteristicEventTypes.CHANGE event handler.
Note: If you don't want the CharacteristicEventTypes.SET to be called, refer to updateValue.
This updates the value of the characteristic. If the value changed, an event notification will be sent to all connected HomeKit controllers which are registered to receive event notifications for this characteristic.
The new value or a Error or HapStatusError.
Note: Refer to the respective overloads for CharacteristicValue or HapStatusError for respective documentation.
This updates the value of the characteristic. If the value changed, an event notification will be sent to all connected HomeKit controllers which are registered to receive event notifications for this characteristic.
The new value.
Sets the state of the characteristic to an errored state. If a onGet or CharacteristicEventTypes.GET handler is set up, the errored state will be ignored and the characteristic will always query the latest state by calling the provided handler.
If a generic error object is supplied, the characteristic tries to extract a HAPStatus code from the error message string. If not possible a generic HAPStatus.SERVICE_COMMUNICATION_FAILURE will be used. If the supplied error object is an instance of HapStatusError the corresponding status will be used.
Have a look at the Presenting Erroneous Accessory State to the User guide for more information on how to present erroneous state to the user.
The error object
Note: Erroneous state is never pushed to the client side. Only, if the HomeKit client requests the current state of the Characteristic, the corresponding HapStatusError is returned. As described above, any onGet or CharacteristicEventTypes.GET handlers have precedence.
This updates the value of the characteristic. If the value changed, an event notification will be sent to all connected HomeKit controllers which are registered to receive event notifications for this characteristic.
The new value.
Optionalcontext: anyPassed to the CharacteristicEventTypes.CHANGE event handler.
This method can be used to gain an Iterator to loop over all valid values defined for this characteristic.
The range of valid values can be defined using three different ways via the CharacteristicProps object (set via the setProps method):
The method will automatically detect which type of valid values definition is used and provide the correct Iterator for that case.
Note: This method is (obviously) only valid for numeric characteristics.
StaticAccessStaticAccessStaticAccessStaticAccessoryStaticAccessoryStaticActiveStaticActiveStaticActivityStaticAdministratorStaticAirStaticAirStaticAirStaticAirStaticAppStaticAssetStaticAudioStaticBatteryStaticBrightnessStaticButtonStaticCameraStaticCarbonStaticCarbonStaticCarbonStaticCarbonStaticCarbonStaticCarbonStaticCCAEnergyStaticCCASignalStaticCharacteristicStaticCharacteristicStaticChargingStaticClosedStaticColorStaticConfigurationStaticConfiguredStaticContactStaticCoolingStaticCryptoStaticCurrentStaticCurrentStaticCurrentStaticCurrentStaticCurrentStaticCurrentStaticCurrentStaticCurrentStaticCurrentStaticCurrentStaticCurrentStaticCurrentStaticCurrentStaticCurrentStaticCurrentStaticCurrentStaticCurrentStaticDataStaticDataStaticDiagonalStaticDigitalStaticDisplayStaticEventStaticEventStaticEventStaticFilterStaticFilterStaticFirmwareStaticFirmwareStaticFirmwareStaticHardwareStaticHardwareStaticHeartStaticHeatingStaticHoldStaticHomeStaticHueStaticIdentifierStaticIdentifyStaticImageStaticImageStaticInputStaticInputStaticInStaticIsStaticLeakStaticListStaticLockStaticLockStaticLockStaticLockStaticLockStaticLockStaticLogsStaticMACRetransmissionStaticMACTransmissionStaticManagedStaticManuallyStaticManufacturerStaticMaximumStaticMetricsStaticModelStaticMotionStaticMultifunctionStaticMuteStaticNameStaticNetworkStaticNetworkStaticNetworkStaticNFCAccessStaticNFCAccessStaticNightStaticNitrogenStaticObstructionStaticOccupancyStaticOnStaticOperatingStaticOpticalStaticOutletStaticOzoneStaticPairingStaticPairStaticPairStaticPasswordStaticPeriodicStaticPictureStaticPingStaticPM10StaticPM2_StaticPositionStaticPowerStaticProductStaticProgrammableStaticProgrammableStaticProgramStaticReceivedStaticReceiverStaticRecordingStaticRelativeStaticRelativeStaticRelayStaticRelayStaticRelayStaticRemainingStaticRemoteStaticResetStaticRotationStaticRotationStaticRouterStaticSaturationStaticSecurityStaticSecurityStaticSecurityStaticSelectedStaticSelectedStaticSelectedStaticSelectedRTPStreamStaticSelectedStaticSerialStaticServiceStaticServiceStaticSetStaticSetupStaticSetupStaticSetupStaticSignalStaticSiriStaticSiriStaticSiriStaticSiriStaticSiriStaticSiriStaticSiriStaticSlatStaticSleepStaticSleepStaticSmokeStaticSoftwareStaticStagedStaticStatusStaticStatusStaticStatusStaticStatusStaticStatusStaticStreamingStaticSulphurStaticSupportedStaticSupportedStaticSupportedStaticSupportedStaticSupportedStaticSupportedStaticSupportedStaticSupportedStaticSupportedStaticSupportedStaticSupportedStaticSupportedRTPConfigurationStaticSupportedStaticSupportedStaticSupportedStaticSupportedStaticSwingStaticTapStaticTargetStaticTargetStaticTargetStaticTargetStaticTargetStaticTargetStaticTargetStaticTargetStaticTargetStaticTargetStaticTargetStaticTargetStaticTargetStaticTargetStaticTargetStaticTargetStaticTemperatureStaticThirdStaticThreadStaticThreadStaticThreadStaticThreadStaticTokenStaticTransmitStaticTunnelStaticTunneledStaticTunneledStaticTunneledStaticValveStaticVersionStaticVideoStaticVOCDensityStaticVolumeStaticVolumeStaticVolumeStaticWakeStaticWANConfigurationStaticWANStatusStaticWaterStaticWiStaticWiStaticWi
Characteristic represents a particular typed variable that can be assigned to a Service. For instance, a "Hue" Characteristic might store a 'float' value of type 'arcdegrees'. You could add the Hue Characteristic to a Service in order to store that value. A particular Characteristic is distinguished from others by its UUID. HomeKit provides a set of known Characteristic UUIDs defined in HomeKit.ts along with a corresponding concrete subclass.
You can also define custom Characteristics by providing your own UUID. Custom Characteristics can be added to any native or custom Services, but Siri will likely not be able to work with these.