Droplit.io Portal
API Reference

Behaviors

Choreograph device actions.

Overview

Devices can perform several tasks, such as dimming a light or adjusting the volume of a speaker. Behaviors enable several tasks to be scheduled into routines that can be performed either manually or in response to triggers, such as service events. Behaviors can be used to simplify the execution of complex procedures, allow for expedient transitions between personal settings, and perform acts when certain conditions are met.

API Index

Behaviors

Actions

Actions

Actions are the individual duties that the behavior is asked to execute. Actions are capable of updating the service properties of several devices either all at once, or over a period of time. The latter is a special type of action, an animation, wherein the individual device state changes are spread out over a defined timeline.

Each behavior has one main action that is initially invoked in order to kickstart the behavior. Each action, however, may be executed individually.

Actions may be executed immediately after one another, or they may be asked to wait for a trigger event before executing.

Schedules

Schedules define when, and how often, an animation action is executed. A schedule determines the start time of the animation, and the frequency with which it reoccurs.

Triggers

Triggers are hooks that listen for service notifications, such as service events, changes in device service properties, or other API calls. Actions may wait for trigger events to occur before executing.

Creating a Behavior

A behavior is defined within a behavior file. This file contains all the configuration information for the behavior, and it is this file that is included in API requests to create or update behaviors. While a behavior file may be of any type, JSON and JSON5 are natively supported.

A behavior file contains several primary properties:

  • name: the unique name of the behavior
  • engine: the version number of the behavior engine to be used
  • description: a brief description of the behavior
  • main: the name of the default action to initially execute
  • parameters: uniquely named variables for use within constants, schedules, and actions
  • constants: uniquely named constants for use within schedues and actions
  • schedules: definition for when an animation action executes
  • actions: tasks for the behavior to execute

🚧

WARNING

The name of the behavior cannot be changed once it is made.

parameters

The values of the properties of the parameters object are initialized when the behavior is enabled with the inclusion of a parameters object in the body of the request. Parameters must be uniquely named, and it is convention to prefix them with @. Individual parameters may optionally be made required.

There are three types of parameters:

  • device: the ID of a particular device
  • group: either a single device ID or an array of device IDs
  • value: any type of traditional data, including:
    • null
    • boolean
    • string
    • number
    • object
    • array

It is necessary that each parameter contain a type property, to indicate the kind of data to expect, and a boolean required property, to indicate if the particular parameter is required for the operation of the behavior.

constants

Constants are used for storing static configuration information. It is convention to prefix them with $.

actions

Actions contain several tasks to be performed, such as service property updates and service method calls. These tasks are organized into either sequences, which perform all the included tasks sequentially, or timelines, which perform the tasks according to a defined itinerary. Actions also include triggers that use hooks to listen for relevant service notifications that, when detected, will initiate the execution of the action.

Timelines

Timelines allow tasks to be performed according to a specified itinerary of events. A task may be placed on a point along the timeline to be performed at a certain time relative to the other tasks.

Within the timeline object, time objects, whose names are of the format hh:mm:ss, are placed. These time objects include tasks to be performed at the specified time.

Timelines may also contain a repeat object, which contains the period and iterations properties. period specifies the total length, in seconds, of the timeline. If the period specified is less than the longest time object, the value of period will be silently changed to the time designated by that object. iterations specifies how many times the timeline will be repeated during a single execution of the animation action.

schedules

Schedules determine the start time, the start offset, and the reoccurrence frequency of a behavior's actions. The start time is given in ISO 8601 format yyyy-mm-ddT00:00:00.000Z, and determines the time at which an action is to be executed. The start offset is where in an animation action's timeline the action is to begin; an animation may be initialized at any point, not just the beginning. An action may be set to repeat at a set interval or until certain conditions, such as when a number of repetitions are made or an end time is reached, have been met.

Sample Behavior File

{
    "name": "sample",
    "engine": "1.0",
    "description": "Sample behavior file to demonstrate the behavior engine",
    "main": "",
    "parameters": {
        "@device1": {
            "type": "device",
            "required": true
        },
        "@device2": {
            "type": "device",
            "required": true
        },
        "@group": {
            "type": "group",
            "required": false
        },
        "@sonos": {
            "type": "device",
            "required": true
        }
    },
    "constants": {
        "$brightness": 100,
        "$onFull": {
            "BinarySwitch.switch": "on",
            "DimmableSwitch.brightness": "$brightness"
        },
        "$off": {
            "BinarySwitch.switch": "off"
        }
    },
    "schedules": {
        "schedule1": {
            "enabled": false,
            "startOffset": 0,
            "startTime": "2018-04-04T00:32:54.813Z",
            "reoccurence": {
                "secondly": {
                    "interval": 2
                }
            }
        }
    },
    "actions": {
        "turnOn": {
            "sequence": {
                "@device1": "$onFull",
                "@device2": "$onFull"
            }
        },
        "turnOff": {
            "sequence": {
                "@device1": "$off",
                "@device2": "$off"
            }
        },
        "groupOn": {
            "sequence": [
                {
                    "@group": "$onFull"
                }
            ]
        },
        "animation": {
            "timeline": {
                "repeat": {
                    "period": 4,
                    "iterations": 7
                },
                "0": {
                    "/invoke": "turnOff"
                },
                "0:01": {
                    "@device1": "$onFull"
                },
                "0:02": [
                    {
                        "@device2": "$onFull"
                    }
                ]
            }
        },
        "animation2": {
            "schedules": "schedule1",
            "timeline": {
                "0:0": {
                    "/invoke": "turnOff"
                },
                "0:01": {
                    "@device1": "$onFull",
                    "@device2": "$onFull"
                }
            }
        },
        "triggerd": {
            "triggers": {
                "hooks": {
                    "@sonos": {
                        "BinarySwitch.switch": {"/changed.to": "on"}
                    }
                }
            },
            "sequence": {"/invoke": "animation2"}
        }
    }
}