Traits Reference

This is the reference documentation for Traits at Yonomi.

The capabilities and functionality of a device are determined by the Traits that it implements. Traits in turn are composed of Properties, Actions, and States. Below is a comprehensive reference of all currently available traits and information on their various components.

For a more detailed walk-through of how you can interact with your devices via Traits, see the Trait Reference document.

Additional reference documentation:

  • Datatype Reference - All datatypes that can be used within the traits system.
  • Error Reference - A list of the error codes that can be returned when interacting with your devices via traits.

BatteryLevel Trait

Functionality for devices that report their current battery level.

Properties

There are no properties for the BatteryLevel trait.

Actions

There are no actions for the BatteryLevel trait.

States

These state fields are how the current state of any device that implements BatteryLevel trait are surfaced.

Field Name Datatype Description
percentage int Current battery level percentage of the device.

Value must be between 0 and 100, inclusive.
status nullable<BatteryStatus> A qualitative description of the current battery level of the device.

This is a nullable datatype, which means it can either be null or BatteryStatus
  • When set to null: The battery status is optionally null.


See the BatteryStatus datatype documentation.

Constraints

Trait Constraints are additional expectations that must be met any time a device’s state or properties are updated. The BatteryLevel trait has the following constraints:

    Notifications

    There are no notifications for the BatteryLevel trait.

    Brightness Trait

    Functionality for devices that can have their brightness adjusted.

    Properties

    There are no properties for the Brightness trait.

    Actions

    The following actions are how you interact with devices that implement the Brightness trait.

    Action Name Description Details
    setBrightnessPercentage Set the absolute brightness of this device. brightness (int) parameter - The new absolute brightness value. Value must be between 0 and 100, inclusive.

    States

    These state fields are how the current state of any device that implements Brightness trait are surfaced.

    Field Name Datatype Description
    brightness int Current absolute brightness level of this device.

    Value must be between 0 and 100, inclusive.

    Notifications

    There are no notifications for the Brightness trait.

    Color Trait

    Functionality for devices that can be set to a specific color.

    Properties

    There are no properties for the Color trait.

    Actions

    The following actions are how you interact with devices that implement the Color trait.

    Action Name Description Details
    setColor Set the absolute color value of this device. color (HSBColorValue) parameter - The new HSB color value. See the HSBColorValue datatype documentation.

    States

    These state fields are how the current state of any device that implements Color trait are surfaced.

    Field Name Datatype Description
    color HSBColorValue Current HSB color of this device.

    See the HSBColorValue datatype documentation.

    Notifications

    There are no notifications for the Color trait.

    ColorTemperature Trait

    Describes a light appearance provided by a light bulb

    Properties

    The properties for the ColorTemperature trait are set per-device, and define the configuration around how a device implements this trait.

    Property Name Datatype Description
    supportedColorTemperatureRange range<int> The allowed range that the device supports for color temperature in Kelvin This is a range datatype, which is an object with a min and max property (of type int):
    • min: The lowest value in Kelvin that the device can be set to
    • max: The highest value in Kelvin that the device can be set to

    Actions

    The following actions are how you interact with devices that implement the ColorTemperature trait.

    NOTE: the configuration of a device’s trait properties may impact the functionality of these actions.

    Action Name Description Details
    setColorTemperature Set the device’s color temperature in Kelvin colorTemperature (int) parameter - The device’s color temperature in Kelvin.

    NOTE: This action has the following additional validations that must pass:
    • parameter@colorTemperature must be within range specified in property@supportedColorTemperatureRange

    States

    These state fields are how the current state of any device that implements ColorTemperature trait are surfaced.

    Field Name Datatype Description
    colorTemperature int Current color temperature of the device in Kelvin.

    Constraints

    Trait Constraints are additional expectations that must be met any time a device’s state or properties are updated. The ColorTemperature trait has the following constraints:

      Notifications

      There are no notifications for the ColorTemperature trait.

      Lock Trait

      Functionality for devices that can be locked or unlocked.

      Properties

      The properties for the Lock trait are set per-device, and define the configuration around how a device implements this trait.

      Property Name Datatype Description
      supportsIsJammed boolean Indicates if the lock supports reporting its state as jammed implying that its lock status cannot be determined.

      Actions

      The following actions are how you interact with devices that implement the Lock trait.

      NOTE: the configuration of a device’s trait properties may impact the functionality of these actions.

      Action Name Description Details
      setLocked Lock (true) or unlock (false) the device. lock (boolean) parameter - True to lock, false to unlock.

      States

      These state fields are how the current state of any device that implements Lock trait are surfaced.

      Field Name Datatype Description
      isLocked boolean Indicates whether the device is currently locked.
      isJammed boolean Indicates whether the device is currently jammed, hence the locked status couldn’t be determined.

      Constraints

      Trait Constraints are additional expectations that must be met any time a device’s state or properties are updated. The Lock trait has the following constraints:

      • isJammed state cannot be set when property supportsIsJammed is false

      Notifications

      These notifications allow the platform to surface INFO, WARNING, and ERRORs from the device based on the type value in the notification.

      Notification Name Datatype Details
      errorDeviceOffline null Error thrown if the device is offline

      Type: ERROR - ApplicationError - TransientError
      lockNotification LockNotification The device’s isLocked state has changed

      Type: INFO

      See the LockNotification datatype documentation.

      PinCodeCredential Trait

      Functionality for devices that can be accessed via a PIN code credential.

      Properties

      The properties for the PinCodeCredential trait are set per-device, and define the configuration around how a device implements this trait.

      Property Name Datatype Description
      maxNumberOfPinCodeCredentials int The maximum number of PIN code credentials that may be registered on a device.
      maxNumberOfSchedulesPerPinCodeCredential int The maximum number of schedules that may be included on a PIN code credential.
      supportedPinCodeCredentialNameRange range<int> The allowed number of characters in a name for this device’s PIN code credentials. This is a range datatype, which is an object with a min and max property (of type int):
      • min: The minimum number of characters in the PIN code credential name.
      • max: The maximum number of characters in the PIN code credential name.
      supportedPinCodeRange range<int> The allowed number of digits in a PIN code for this device’s PIN code credentials. This is a range datatype, which is an object with a min and max property (of type int):
      • min: The minimum number of digits in a PIN code.
      • max: The maximum number of digits in a PIN code.
      maxNumberOfRecurringSchedulesPerPinCodeCredential int The maximum number of recurring schedules that may be included on a PIN code credential.
      maxNumberOfTemporarySchedulesPerPinCodeCredential int The maximum number of temporary schedules that may be included on a PIN code credential.
      exclusiveSchedules boolean If this is set, temporary and recurring schedules cannot be mixed on a PIN code credential.

      Actions

      The following actions are how you interact with devices that implement the PinCodeCredential trait.

      NOTE: the configuration of a device’s trait properties may impact the functionality of these actions.

      Action Name Description Details
      createPinCodeCredential Add a PIN code credential to the device. pinCodeCredential (PinCodeCredential) parameter - The PIN code credential to add to list of PIN code credentials. See the PinCodeCredential datatype documentation.

      NOTE: This action has the following additional validations that must pass:
      • state@pinCodeCredentials must not already include a PIN code credential with the same pinCode in parameter@pinCodeCredential.
      • The PIN code in parameter@pinCodeCredential must be within the minimum and maximum number of allowed digits.
      • The number of characters in the name field of parameter@pinCodeCredential must be within the range specified in property@supportedPinCodeCredentialNameRange if property@supportedPinCodeCredentialNameRange is defined.
      • The number of schedules in the schedule field of parameter@pinCodeCredential must be less than or equal to the number specified in property@maxNumberOfSchedulesPerPinCodeCredential if property@maxNumberOfSchedulesPerPinCodeCredential is defined.
      updatePinCodeCredential Update an existing PIN code credential on the device. pinCodeCredential (PinCodeCredential) parameter - The PIN code credential to update in the list of PIN code credentials. See the PinCodeCredential datatype documentation.

      NOTE: This action has the following additional validations that must pass:
      • state@pinCodeCredentials must include a PIN code credential with the given PIN code pinCode in parameter@pinCodeCredential.
      • The PIN code in parameter@pinCodeCredential must be within the minimum and maximum number of allowed digits.
      • The number of characters in the name field of parameter@pinCodeCredential must be within the range specified in property@supportedPinCodeCredentialNameRange if property@supportedPinCodeCredentialNameRange is defined.
      • The number of schedules in the schedule field of parameter@pinCodeCredential must be less than or equal to the number specified in property@maxNumberOfSchedulesPerPinCodeCredential if property@maxNumberOfSchedulesPerPinCodeCredential is defined.
      deletePinCodeCredential Revoke access for the PIN code credential with pinCode from the device. pinCode (string) parameter - The pinCode of the PIN code credential to remove.

      NOTE: This action has the following additional validations that must pass:
      • state@pinCodeCredentials must include a PIN code credential with the given PIN code pinCode equivalent to parameter@pinCode.
      addPinCodeCredential DEPRECATED: use createPinCodeCredential or BetaPinCodeCredentials Trait: Add a PIN code credential to the device. pinCodeCredential (PinCodeCredentialListItem) parameter - The PIN code credential to add to list of PIN code credentials. See the PinCodeCredentialListItem datatype documentation.

      NOTE: This action has the following additional validations that must pass:
      • state@pinCodeCredentialList must not already include a PIN code credential with the same pinCode in parameter@pinCodeCredential.
      • The PIN code in parameter@pinCodeCredential must be within the minimum and maximum number of allowed digits.
      • The number of characters in the name field of parameter@pinCodeCredential must be within the range specified in property@supportedPinCodeCredentialNameRange if property@supportedPinCodeCredentialNameRange is defined.
      • Should not allow setting recurringSchedules and alwaysActive
      • Should not allow setting temporarySchedules and alwaysActive
      • The number of schedules in the schedule field of parameter@pinCodeCredential must be less than or equal to the number specified in the sum total of property@maxNumberOfRecurringSchedulesPerPinCodeCredential and property@maxNumberOfRecurringSchedulesPerPinCodeCredential if property@maxNumberOfTemporarySchedulesPerPinCodeCredential is defined.
      • The number of recurring schedules in the recurringSchedules field of parameter@pinCodeCredential must be less than or equal to the number specified in property@maxNumberOfSchedulesPerPinCodeCredential if property@maxNumberOfRecurringSchedulesPerPinCodeCredential is defined.
      • The number of temporary schedules in the temporarySchedules field of parameter@pinCodeCredential must be less than or equal to the number specified in property@maxNumberOfSchedulesPerPinCodeCredential if property@maxNumberOfTemporarySchedulesPerPinCodeCredential is defined.
      • If temporary and recurring schedules are exlusive, then only one list may be populated.
      modifyPinCodeCredential DEPRECATED: use updatePinCodeCredential or BetaPinCodeCredentials Trait: Update an existing PIN code credential on the device. pinCodeCredential (PinCodeCredentialListItem) parameter - The PIN code credential to update in the list of PIN code credentials. See the PinCodeCredentialListItem datatype documentation.

      NOTE: This action has the following additional validations that must pass:
      • state@pinCodeCredentialList must include a PIN code credential with the given PIN code pinCode in parameter@pinCodeCredential.
      • The PIN code in parameter@pinCodeCredential must be within the minimum and maximum number of allowed digits.
      • The number of characters in the name field of parameter@pinCodeCredential must be within the range specified in property@supportedPinCodeCredentialNameRange if property@supportedPinCodeCredentialNameRange is defined.
      • The number of recurring schedules in the recurringSchedule field of parameter@pinCodeCredential must be less than or equal to the number specified in property@maxNumberOfRecurringSchedulesPerPinCodeCredential if property@maxNumberOfRecurringSchedulesPerPinCodeCredential is defined.
      • The number of temporary schedules in the temporarySchedule field of parameter@pinCodeCredential must be less than or equal to the number specified in property@maxNumberOfTemporarySchedulesPerPinCodeCredential if property@maxNumberOfTemporarySchedulesPerPinCodeCredential is defined.
      removePinCodeCredential DEPRECATED: use deletePinCodeCredential or BetaPinCodeCredentials Trait: Revoke access for the PIN code credential with pinCode from the device. pinCode (string) parameter - The pinCode of the PIN code credential to remove.

      NOTE: This action has the following additional validations that must pass:
      • state@pinCodeCredentialList must include a PIN code credential with the given PIN code pinCode equivalent to parameter@pinCode.

      States

      These state fields are how the current state of any device that implements PinCodeCredential trait are surfaced.

      Field Name Datatype Description
      pinCodeCredentials list Current list of PIN code credentials that have been granted access to the device.

      See the PinCodeCredential datatype documentation.
      pinCodeCredentialList list Current list of PIN code credentials that have been granted access to the device.

      See the PinCodeCredentialListItem datatype documentation.

      Constraints

      Trait Constraints are additional expectations that must be met any time a device’s state or properties are updated. The PinCodeCredential trait has the following constraints:

      • If property@maxNumberOfPinCodeCredentials is provided, the number of items in the state@pinCodeCredentials list state must not exceed it.
      • If property@maxNumberOfPinCodeCredentialList is provided, the number of items in the state@pinCodeCredentialList list state must not exceed it.

      Notifications

      These notifications allow the platform to surface INFO, WARNING, and ERRORs from the device based on the type value in the notification.

      Notification Name Datatype Details
      errorDeviceOffline null Error thrown if the device is offline

      Type: ERROR - ApplicationError - TransientError

      Power Trait

      Functionality for devices that can be turned on or off.

      Properties

      The properties for the Power trait are set per-device, and define the configuration around how a device implements this trait.

      Property Name Datatype Description
      supportsDiscreteOnOff boolean Indicates if the device actually has distinct On and Off features as opposed to a single power button.

      Actions

      The following actions are how you interact with devices that implement the Power trait.

      NOTE: the configuration of a device’s trait properties may impact the functionality of these actions.

      Action Name Description Details
      setOn Whether to turn the device on or off. Should update to reflect argument is only a boolean. on (boolean) parameter - Whether to turn the device on (true) or off (false).

      States

      These state fields are how the current state of any device that implements Power trait are surfaced.

      Field Name Datatype Description
      isOn boolean Whether a device’s power state is on or off.

      Constraints

      Trait Constraints are additional expectations that must be met any time a device’s state or properties are updated. The Power trait has the following constraints:

        Notifications

        These notifications allow the platform to surface INFO, WARNING, and ERRORs from the device based on the type value in the notification.

        Notification Name Datatype Details
        errorDeviceOffline null Error thrown if the device is offline

        Type: ERROR - ApplicationError - TransientError

        ThermostatSetting Trait

        Functionality for devices that are used to control and monitor temperature.

        Properties

        The properties for the ThermostatSetting trait are set per-device, and define the configuration around how a device implements this trait.

        Property Name Datatype Description
        availableThermostatModes set<ThermostatMode> Supported modes by the device. This is a set datatype, which is an array (of ThermostatMode items) that cannot have any repeated items. See the ThermostatMode datatype documentation.
        availableFanModes set<FanMode> Supported fan modes by the device. This is a set datatype, which is an array (of FanMode items) that cannot have any repeated items. See the FanMode datatype documentation.
        heatSetPointRange nullable<DynamicFloatRange> The allowable range to set the device to in Celsius when heating. This is a nullable datatype, which means it can either be null or DynamicFloatRange
        • When set to null: Heat set point values used in thermostat actions are not validated.
        See the DynamicFloatRange datatype documentation.
        coolSetPointRange nullable<DynamicFloatRange> The allowable range to set the device to in Celsius when cooling. This is a nullable datatype, which means it can either be null or DynamicFloatRange
        • When set to null: Cool set point values used in thermostat actions are not validated.
        See the DynamicFloatRange datatype documentation.
        allowedTargetTemperatureModes nullable<set<ThermostatMode>> The allowed thermostat mode(s) for the setTargetTemperature action. This is a nullable datatype, which means it can either be null or set<ThermostatMode>
        • When set to null: The current thermostat mode is not validated when executing setTargetTemperature.
        This is a set datatype, which is an array (of ThermostatMode items) that cannot have any repeated items. See the ThermostatMode datatype documentation.
        allowedTargetTemperatureRangeModes nullable<set<ThermostatMode>> The allowed thermostat mode(s) for the setTargetTemperatureRange action. This is a nullable datatype, which means it can either be null or set<ThermostatMode>
        • When set to null: The current thermostat mode is not validated when executing setTargetTemperatureRange.
        This is a set datatype, which is an array (of ThermostatMode items) that cannot have any repeated items. See the ThermostatMode datatype documentation.

        Actions

        The following actions are how you interact with devices that implement the ThermostatSetting trait.

        NOTE: the configuration of a device’s trait properties may impact the functionality of these actions.

        Action Name Description Details
        setThermostatMode Set the mode of the device. mode (ThermostatMode) parameter - The mode to set the device to. See the ThermostatMode datatype documentation.

        NOTE: This action has the following additional validations that must pass:
        • The mode provided in the mode parameter must be present in the availableThermostatModes property.
        setTargetTemperature Set the target temperature of the device for the associated mode. targetTemperature (float) parameter - The temperature to set the device to in Celsius.

        NOTE: This action has the following additional validations that must pass:
        • The current thermostat mode state must be one of the values in the allowedTargetTemperatureModes property.
        • The targetTemperature must be within the coolSetPointRange property.
        • The targetTemperature must be within the heatSetPointRange property.
        setFanMode Set the fan mode of the device. fanMode (FanMode) parameter - The fan mode to set the device to. See the FanMode datatype documentation.

        NOTE: This action has the following additional validations that must pass:
        • The mode provided in the fanMode parameter must be present in the availableFanModes property.
        setTargetTemperatureRange Set a temperature range for the device while in a mode that supports a TargetTemperatureRange (auto). setPointLow (float) parameter - The low temperature, in Celsius, to set on the device while in a TargetTemperatureRange mode (auto).

        setPointHigh (float) parameter - The high temperature, in Celsius, to set on the device while in a TargetTemperatureRange mode (auto).

        NOTE: This action has the following additional validations that must pass:
        • The current thermostat mode state must be one of the values in the allowedTargetTemperatureRangeModes property.
        • The low temperature must be less than the high temperature.
        • The setPointHigh must be within the coolSetPointRange max and min.
        • The setPointLow must be within the heatSetPointRange max and min.
        setThermostatModeAndTargetTemperature Set the mode of the device and optionally the targetTemperature. mode (ThermostatMode) parameter - The thermostat mode to set the device to. See the ThermostatMode datatype documentation.

        targetTemperature (nullable<float>) parameter - (optional) The optional temperature value to set the device to, in Celsius. This is a nullable datatype, which means it can either be null or float
        • When set to null: It is optional whether or not to provide the targetTemperature.


        NOTE: This action has the following additional validations that must pass:
        • The mode provided in the mode parameter must be present in the availableThermostatModes property.
        • The parameter for mode included in the request must be one of the values in the allowedTargetTemperatureModes property.
        • The targetTemperature must be within the coolSetPointRange property.
        • The targetTemperature must be within the heatSetPointRange property.
        setThermostatModeAndTargetTemperatureRange Set the mode of the device and optionally the targetTemperature range. mode (ThermostatMode) parameter - The thermostat mode to set the device to. See the ThermostatMode datatype documentation.

        range (ThermostatRange) parameter - (optional) The optional range to set the thermostat to. See the ThermostatRange datatype documentation.

        NOTE: This action has the following additional validations that must pass:
        • The passed in thermostat mode must be one of the values in the allowedTargetTemperatureRangeModes property.
        • The low temperature must be less than the high temperature.
        • The setPointHigh must be within the coolSetPointRange max and min.
        • The setPointLow must be within the heatSetPointRange max and min.

        States

        These state fields are how the current state of any device that implements ThermostatSetting trait are surfaced.

        Field Name Datatype Description
        mode ThermostatMode Current mode of the device, within the range of values as defined by availableThermostatModes.

        See the ThermostatMode datatype documentation.
        targetTemperature float Single temperature set point the device is currently programmed at.
        ambientTemperature float Current observed temperature in temperatureUnit.
        setPointHigh float Higher end of the range for auto mode.
        setPointLow float Lower end of the range for auto mode.
        ambientHumidity float Observed humidity.
        targetHumidity float Single humidity set point the device is currently programmed at.
        fanMode FanMode Current Fan mode of the device, within the range of values as defined by availableFanModes.

        See the FanMode datatype documentation.

        Constraints

        Trait Constraints are additional expectations that must be met any time a device’s state or properties are updated. The ThermostatSetting trait has the following constraints:

        • the mode state must be a member of the availableThermostatModes property
        • the fanMode state must be a member of the availableFanModes property

        Notifications

        There are no notifications for the ThermostatSetting trait.

        Beta Traits

        Beta Traits are traits we're currently building. They're not quite production-ready, and there's even a chance they won't be released. We're taking this approach because we want your input! As we gather feedback, we are likely to make updates - including breaking changes. These traits are issued for an entire tenant, so we recommend configuring a development or test environment to review their design and functionality.

        To enable the entire Beta trait catalog in your development environment, please contact your Yonomi Customer Success representative.

        BetaCardCredential Trait

        (BETA) Functionality for devices that can be accessed via a card credential.

        Properties

        The properties for the BetaCardCredential trait are set per-device, and define the configuration around how a device implements this trait.

        Property Name Datatype Description
        maxNumberOfCardCredentials int The maximum number of card credentials that may be registered on a device.

        Actions

        The following actions are how you interact with devices that implement the BetaCardCredential trait.

        NOTE: the configuration of a device’s trait properties may impact the functionality of these actions.

        Action Name Description Details
        createCardCredential Add a card credential to the device. cardCredential (BetaCardCredential) parameter - The card credential to add to list of card credentials. See the BetaCardCredential datatype documentation.

        NOTE: This action has the following additional validations that must pass:
        • state@cardCredentials must not already include a card credential with the given credential id in parameter@cardCredential.
        • The card credential in parameter@cardCredential must fit within 1024 bits.
        updateCardCredential Update an existing card credential on the device. cardCredential (BetaCardCredential) parameter - The card credential to update in the list of card credentials. See the BetaCardCredential datatype documentation.

        NOTE: This action has the following additional validations that must pass:
        • state@cardCredentials must include a card credential with the given card credential id equivalent to parameter@id.
        • The card credential in parameter@cardCredential must fit within 1024 bits.
        deleteCardCredential Revoke access for the card credential with id from the device. id (string) parameter - The id of the card credential to remove.

        NOTE: This action has the following additional validations that must pass:
        • state@cardCredentials must include a card credential with the given card credential id equivalent to parameter@id.

        States

        These state fields are how the current state of any device that implements BetaCardCredential trait are surfaced.

        Field Name Datatype Description
        cardCredentials list Current list of card credentials that have been granted access to the device.

        See the BetaCardCredential datatype documentation.

        Constraints

        Trait Constraints are additional expectations that must be met any time a device’s state or properties are updated. The BetaCardCredential trait has the following constraints:

        • If property@maxNumberOfCardCredentials is provided, the number of items in the state@cardCredentials list state must not exceed it.

        Notifications

        There are no notifications for the BetaCardCredential trait.

        BetaCardCredentials Trait

        (BETA) Functionality for devices that can be accessed via a card credential.

        Properties

        The properties for the BetaCardCredentials trait are set per-device, and define the configuration around how a device implements this trait.

        Property Name Datatype Description
        maxNumberOfCardCredentials int The maximum number of card credentials that may be registered on a device.

        Actions

        The following actions are how you interact with devices that implement the BetaCardCredentials trait.

        NOTE: the configuration of a device’s trait properties may impact the functionality of these actions.

        Action Name Description Details
        createCardCredential Add a card credential to the device. cardCredential (CardCredentialCreateItem) parameter - The card credential to add to list of card credentials. See the CardCredentialCreateItem datatype documentation.

        NOTE: This action has the following additional validations that must pass:
        • state@cardCredentials must not already include a card credential with the given credential id in parameter@cardCredential.
        • The card credential in parameter@cardCredential must fit within 1024 bits.
        updateCardCredential Update an existing card credential on the device. cardCredential (CardCredentialItem) parameter - The card credential to update in the list of card credentials. See the CardCredentialItem datatype documentation.

        NOTE: This action has the following additional validations that must pass:
        • state@cardCredentials must include a card credential with the given card credential id equivalent to the id property of parameter@cardCredential.
        • The card credential in parameter@cardCredential must fit within 1024 bits.
        deleteCardCredential Revoke access for the card credential with id from the device. id (string) parameter - The id of the card credential to remove.

        NOTE: This action has the following additional validations that must pass:
        • state@cardCredentials must include a card credential with the given card credential id equivalent to parameter@id.

        States

        These state fields are how the current state of any device that implements BetaCardCredentials trait are surfaced.

        Field Name Datatype Description
        cardCredentials list Current list of card credentials that have been granted access to the device.

        See the CardCredentialItem datatype documentation.

        Constraints

        Trait Constraints are additional expectations that must be met any time a device’s state or properties are updated. The BetaCardCredentials trait has the following constraints:

        • If property@maxNumberOfCardCredentials is provided, the number of items in the state@cardCredentials list state must not exceed it.

        Notifications

        These notifications allow the platform to surface INFO, WARNING, and ERRORs from the device based on the type value in the notification.

        Notification Name Datatype Details
        errorDeviceOffline null Error thrown if the device is offline

        Type: ERROR - ApplicationError - TransientError

        BetaConnectivity Trait

        Indication on whether device is online or offline status.

        Properties

        There are no properties for the BetaConnectivity trait.

        Actions

        There are no actions for the BetaConnectivity trait.

        States

        These state fields are how the current state of any device that implements BetaConnectivity trait are surfaced.

        Field Name Datatype Description
        status BetaConnectivityStatus A description of the connectivity of the device.

        See the BetaConnectivityStatus datatype documentation.

        Notifications

        There are no notifications for the BetaConnectivity trait.

        BetaFirmware Trait

        Functionality for devices that report their current firmware version.

        Properties

        There are no properties for the BetaFirmware trait.

        Actions

        The following actions are how you interact with devices that implement the BetaFirmware trait.

        Action Name Description Details
        scheduleLatestFirmwareUpdate Initiate the download and installation of the latest firmware for the device at the specified time. scheduleAt (datetime) parameter - The time to initiate the firmware update process.

        NOTE: This action has the following additional validations that must pass:
        • parameter@scheduleAt must be a date in the future
        installLatestFirmwareUpdate Initiate the download and installation of the latest firmware for the device immediately.

        States

        These state fields are how the current state of any device that implements BetaFirmware trait are surfaced.

        Field Name Datatype Description
        version nullable<string> Current firmware version of the device.

        This is a nullable datatype, which means it can either be null or string
        • When set to null: The firmware version is optionally null.
        lastUpdated nullable<datetime> The time that the device’s firmware was reported as updated to the cloud.

        This is a nullable datatype, which means it can either be null or datetime
        • When set to null: Last updated is optionally null.
        installScheduledAt nullable<datetime> The time that the device’s firmware was scheduled to be installed.

        This is a nullable datatype, which means it can either be null or datetime
        • When set to null: Scheduled at is optionally null.
        installedAt nullable<datetime> The time that the device’s firmware was installed.

        This is a nullable datatype, which means it can either be null or datetime
        • When set to null: Installed at is optionally null.
        downloadScheduledAt nullable<datetime> The time that the device’s firmware was scheduled to be downloaded.

        This is a nullable datatype, which means it can either be null or datetime
        • When set to null: Download Scheduled at is optionally null.
        updateAvailability UpdateAvailability Whether this device has an update available or not.

        See the UpdateAvailability datatype documentation.

        Notifications

        There are no notifications for the BetaFirmware trait.

        BetaLightEffects Trait

        Devices that support different lighting effects.

        Properties

        The properties for the BetaLightEffects trait are set per-device, and define the configuration around how a device implements this trait.

        Property Name Datatype Description
        supportedColorTemperatureRange range<int> The allowed range that the device supports for color temperature in Kelvin This is a range datatype, which is an object with a min and max property (of type int):
        • min: The lowest value in Kelvin that the device can be set to
        • max: The highest value in Kelvin that the device can be set to
        supportedLightEffects set<LightEffects> The light effects that this device supports. This is a set datatype, which is an array (of LightEffects items) that cannot have any repeated items. See the LightEffects datatype documentation.
        supportedTransitionPeriodRange range<int> The range of values in milliseconds that the transition period can be set to. This is a range datatype, which is an object with a min and max property (of type int):
        • min: The lowest value in milliseconds that the transition period can be set to.
        • max: The highest value in milliseconds that the transition period can be set to.

        Actions

        The following actions are how you interact with devices that implement the BetaLightEffects trait.

        NOTE: the configuration of a device’s trait properties may impact the functionality of these actions.

        Action Name Description Details
        setBrightnessPercentageWithTransition Set the absolute brightness percentage of this device over a period of time. brightness (int) parameter - The new absolute brightness value. Value must be between 0 and 100, inclusive.

        transition (int) parameter - The period of time in milliseconds to transition to the new value.

        NOTE: This action has the following additional validations that must pass:
        • parameter@transition must be within range specified in property@supportedTransitionPeriodRange
        • This light is not configured to support changing brightness over a transition period.
        setColorWithTransition Set the absolute color value of this device over a period of time. color (HSBColorValue) parameter - The new HSB color value. See the HSBColorValue datatype documentation.

        transition (int) parameter - The period of time in milliseconds to transition to the new value.

        NOTE: This action has the following additional validations that must pass:
        • parameter@transition must be within range specified in property@supportedTransitionPeriodRange
        • This light is not configured to support changing color over a transition period.
        setColorTemperatureWithTransition Set the device’s color temperature in Kelvin colorTemperature (int) parameter - The device’s color temperature in Kelvin.

        transition (int) parameter - The period of time in milliseconds to transition to the new value.

        NOTE: This action has the following additional validations that must pass:
        • parameter@colorTemperature must be within range specified in property@supportedColorTemperatureRange
        • parameter@transition must be within range specified in property@supportedTransitionPeriodRange
        • This light is not configured to support changing color temperature over a transition period.

        States

        There are no states for the BetaLightEffects trait.

        Constraints

        Trait Constraints are additional expectations that must be met any time a device’s state or properties are updated. The BetaLightEffects trait has the following constraints:

          Notifications

          There are no notifications for the BetaLightEffects trait.

          BetaNoiseDetected Trait

          Functionality for devices that detect and report noise.

          Properties

          There are no properties for the BetaNoiseDetected trait.

          Actions

          There are no actions for the BetaNoiseDetected trait.

          States

          There are no states for the BetaNoiseDetected trait.

          Notifications

          These notifications allow the platform to surface INFO, WARNING, and ERRORs from the device based on the type value in the notification.

          Notification Name Datatype Details
          infoNoiseDetected null Notification sent when noise exceeding a pre-configured threshold is detected.

          Type: INFO

          BetaPinCodeCredentials Trait

          Functionality for devices that can be accessed via a PIN code credential.

          Properties

          The properties for the BetaPinCodeCredentials trait are set per-device, and define the configuration around how a device implements this trait.

          Property Name Datatype Description
          maxNumberOfPinCodeCredentials int The maximum number of PIN code credentials that may be registered on a device.
          maxNumberOfSchedulesPerPinCodeCredential int The maximum number of schedules that may be included on a PIN code credential.
          supportedPinCodeCredentialNameRange range<int> The allowed number of characters in a name for this device’s PIN code credentials. This is a range datatype, which is an object with a min and max property (of type int):
          • min: The minimum number of characters in the PIN code credential name.
          • max: The maximum number of characters in the PIN code credential name.
          supportedPinCodeRange range<int> The allowed number of digits in a PIN code for this device’s PIN code credentials. This is a range datatype, which is an object with a min and max property (of type int):
          • min: The minimum number of digits in a PIN code.
          • max: The maximum number of digits in a PIN code.
          maxNumberOfRecurringSchedulesPerPinCodeCredential int The maximum number of recurring schedules that may be included on a PIN code credential.
          maxNumberOfTemporarySchedulesPerPinCodeCredential int The maximum number of temporary schedules that may be included on a PIN code credential.
          exclusiveSchedules boolean If this is set, temporary and recurring schedules cannot be mixed on a PIN code credential.

          Actions

          The following actions are how you interact with devices that implement the BetaPinCodeCredentials trait.

          NOTE: the configuration of a device’s trait properties may impact the functionality of these actions.

          Action Name Description Details
          createPinCodeCredential Add a PIN code credential to the device. pinCodeCredential (PinCodeCredentialCreateItem) parameter - The PIN code credential to add to list of PIN code credentials. See the PinCodeCredentialCreateItem datatype documentation.

          NOTE: This action has the following additional validations that must pass:
          • state@pinCodeCredentials must not already include an ID with the same id in parameter@pinCodeCredential.
          • The PIN code in parameter@pinCodeCredential must be within the minimum and maximum number of allowed digits.
          • The number of characters in the name field of parameter@pinCodeCredential must be within the range specified in property@supportedPinCodeCredentialNameRange if property@supportedPinCodeCredentialNameRange is defined.
          • Should not allow setting recurringSchedules and alwaysActive
          • Should not allow setting temporarySchedules and alwaysActive
          • The number of schedules in the schedule field of parameter@pinCodeCredential must be less than or equal to the number specified in the sum total of property@maxNumberOfRecurringSchedulesPerPinCodeCredential and property@maxNumberOfRecurringSchedulesPerPinCodeCredential if property@maxNumberOfTemporarySchedulesPerPinCodeCredential is defined.
          • The number of recurring schedules in the recurringSchedules field of parameter@pinCodeCredential must be less than or equal to the number specified in property@maxNumberOfSchedulesPerPinCodeCredential if property@maxNumberOfRecurringSchedulesPerPinCodeCredential is defined.
          • The number of temporary schedules in the temporarySchedules field of parameter@pinCodeCredential must be less than or equal to the number specified in property@maxNumberOfSchedulesPerPinCodeCredential if property@maxNumberOfTemporarySchedulesPerPinCodeCredential is defined.
          • If temporary and recurring schedules are exclusive, then only one list may be populated.
          updatePinCodeCredential Update an existing PIN code credential on the device. pinCodeCredential (PinCodeCredentialItem) parameter - The PIN code credential to update in the list of PIN code credentials. See the PinCodeCredentialItem datatype documentation.

          NOTE: This action has the following additional validations that must pass:
          • state@pinCodeCredentials must include a PIN code credential with the given PIN code id in parameter@pinCodeCredential.
          • The PIN code in parameter@pinCodeCredential must be within the minimum and maximum number of allowed digits.
          • The number of characters in the name field of parameter@pinCodeCredential must be within the range specified in property@supportedPinCodeCredentialNameRange if property@supportedPinCodeCredentialNameRange is defined.
          • The number of recurring schedules in the recurringSchedule field of parameter@pinCodeCredential must be less than or equal to the number specified in property@maxNumberOfRecurringSchedulesPerPinCodeCredential if property@maxNumberOfRecurringSchedulesPerPinCodeCredential is defined.
          • The number of temporary schedules in the temporarySchedule field of parameter@pinCodeCredential must be less than or equal to the number specified in property@maxNumberOfTemporarySchedulesPerPinCodeCredential if property@maxNumberOfTemporarySchedulesPerPinCodeCredential is defined.
          deletePinCodeCredential Revoke access for the PIN code credential with id from the device. id (string) parameter - The pinCode of the PIN code credential to remove.

          NOTE: This action has the following additional validations that must pass:
          • state@pinCodeCredentials must include a PIN code credential with the given id id equivalent to parameter@id.

          States

          These state fields are how the current state of any device that implements BetaPinCodeCredentials trait are surfaced.

          Field Name Datatype Description
          pinCodeCredentials list Current list of PIN code credentials that have been granted access to the device.

          See the PinCodeCredentialItem datatype documentation.

          Constraints

          Trait Constraints are additional expectations that must be met any time a device’s state or properties are updated. The BetaPinCodeCredentials trait has the following constraints:

          • If property@maxNumberOfPinCodeCredentials is provided, the number of items in the state@pinCodeCredentials list state must not exceed it.
          • If property@maxNumberOfPinCodeCredentials is provided, the number of items in the state@pinCodeCredentials list state must not exceed it.

          Notifications

          These notifications allow the platform to surface INFO, WARNING, and ERRORs from the device based on the type value in the notification.

          Notification Name Datatype Details
          errorDeviceOffline null Error thrown if the device is offline

          Type: ERROR - ApplicationError - TransientError
          errorPinCodeNameAlreadyExists PinCodeAlreadyExistsNotificationDatatype Error thrown if trying to write a PIN code with a name that already exists on that device.

          Type: ERROR - ApplicationError - NonTransientError

          See the PinCodeAlreadyExistsNotificationDatatype datatype documentation.
          errorPinCodeAlreadyExists PinCodeNameAlreadyExistsNotificationDatatype Error thrown if trying to write a PIN code that already exists on that device.

          Type: ERROR - ApplicationError - NonTransientError

          See the PinCodeNameAlreadyExistsNotificationDatatype datatype documentation.

          BetaRelock Trait

          (BETA) Functionality for devices that can be automatically relocked.

          Properties

          The properties for the BetaRelock trait are set per-device, and define the configuration around how a device implements this trait.

          Property Name Datatype Description
          relockDelayValidRange nullable<DynamicIntRange> Optional range in seconds that relock can be configured within. This is a nullable datatype, which means it can either be null or DynamicIntRange
          • When set to null: The minimum and maximum number of seconds the auto relock can be set for.
          See the DynamicIntRange datatype documentation.

          Actions

          The following actions are how you interact with devices that implement the BetaRelock trait.

          NOTE: the configuration of a device’s trait properties may impact the functionality of these actions.

          Action Name Description Details
          setRelockDelay Set the relock delay for the device. relockDelay (int) parameter - Value of the desired relock state.

          NOTE: This action has the following additional validations that must pass:
          • If a range is defined, the new relock delay must be within that range.
          • The auto relock property cannot be below 0.

          States

          These state fields are how the current state of any device that implements BetaRelock trait are surfaced.

          Field Name Datatype Description
          relockDelay int Time in seconds before the device automatically locks itself.

          Notifications

          There are no notifications for the BetaRelock trait.

          BetaWaterPresent Trait

          Functionality for devices that detect and report water leaks.

          Properties

          There are no properties for the BetaWaterPresent trait.

          Actions

          There are no actions for the BetaWaterPresent trait.

          States

          These state fields are how the current state of any device that implements BetaWaterPresent trait are surfaced.

          Field Name Datatype Description
          waterPresent boolean Current status of whether or not water is detected by the device.

          Notifications

          There are no notifications for the BetaWaterPresent trait.

          ← Traits Overview
          Trait Datatypes →