Actors
An actor refers to a prototype of a entity that participates in an activity.
-
Device actors - A device is a physical object.
-
Group actors - A group is a collection (possibly hierarchical) of physical objects. Information about groups can be found in the documentation on activities.
-
Pseudo actors - Pseudo actors are software-only constructs. At present, there is one type of pseudo-actor: the place.
###The place pseudo-actor
At present, there is one place actor, 'place/1', which refers to the steward's physical location,
-
name - a user-friendly name
-
status - green, blue, indigo, or red - for reporting steward health
-
solar - dawn, morning-twilight, sunrise, morning, daylight, evening, sunset, evening-twilight, dusk, night, noon, and nadir
-
physical - a string
-
coordinates - [latitude, longitude] -or- [latitude, longitude, elevation]
There are two events that may be monitored:
-
'cron' - the associated parameter is a cron expression
-
'solar' - the associated parameter is any of the values above (note that noon and nadir are precise moments in time, whilst the others are time ranges)
The 'set' task may be used to update the name, physical, and coordinates parameters. Note that changing the physical parameter will not update the coordinates parameter.
Actors are managed by authorized clients using the
/manage/api/v1/actor/
path prefix, e.g.,
{ path : '/api/v1/actor/list'
, requestID : '1'
, options : { depth: all }
}
To list the properties of a single actor, an authorized client sends:
{ path : '/api/v1/actor/list/ID'
, requestID : 'X'
, options : { depth: DEPTH }
}
where ID corresponds to the actorID of the actor to be deleted, X is any non-empty string, and DEPTH is either 'flat', 'tree', or 'all'
If the ID is omitted, then all actors are listed, e.g., to find out anything about everything, an authorized client sends:
{ path : '/api/v1/actor/list'
, requestID : '2'
, options : { depth: 'all' }
}
To have an actor perform a particular task, an authorized client sends:
{ path : '/api/v1/actor/PREFIX'
, requestID : 'X'
, perform : 'TASK'
, parameter : 'PARAMS'
}
where PREFIX corresponds to a device taxonomy, X is any non-empty string, TASK identifies the particular task, and PARAMS provides the parameters, e.g.,
{ path : '/api/v1/actor/perform/device/lighting'
, requestID : '3'
, perform : 'off'
, parameter : ''
}
tells all devices to perform the 'off' task.