184
edits
Connected Devices/Projects/Project Link/Taxonomy: Difference between revisions
Connected Devices/Projects/Project Link/Taxonomy (view source)
Revision as of 11:03, 16 June 2016
, 16 June 2016→Specific services and channels: Updated camera examples
(→WebPush: add the new auth parameter) |
(→Specific services and channels: Updated camera examples) |
||
| (4 intermediate revisions by the same user not shown) | |||
| Line 16: | Line 16: | ||
* (optional) string `id`: accept only a service with a given id; | * (optional) string `id`: accept only a service with a given id; | ||
* (optional) string array of string `tags`: accept only services with all the tags in the array; | * (optional) string array of string `tags`: accept only services with all the tags in the array; | ||
* (optional) object or array of objects ` | * (optional) object or array of objects `channels` (see ChannelSelector): accept only services with channels matching all the selectors in this array; | ||
Generally, except for (de)assigning tags, '''using an id is considered a bad idea''', as this ties the application to a specific device, and this will fail if the device is replaced (consider that this is equivalent to using an IP address instead of a domain name). | Generally, except for (de)assigning tags, '''using an id is considered a bad idea''', as this ties the application to a specific device, and this will fail if the device is replaced (consider that this is equivalent to using an IP address instead of a domain name). | ||
| Line 24: | Line 23: | ||
Example with 1 selector: | Example with 1 selector: | ||
* Get services with tag "location: kitchen" and channel | * Get services with tag "location: kitchen" and a channel with feature "oven/temperature-celcius" | ||
** GET http://localhost:3000/api/v1/services { tags: "location: kitchen", | ** GET http://localhost:3000/api/v1/services { "tags": "location: kitchen", "channels": { "feature": "oven/temperature-celcius" } } | ||
Example with 2 selectors: | Example with 2 selectors: | ||
| Line 46: | Line 45: | ||
* Example | * Example | ||
** POST http://localhost:3000/api/v1/services/tags {"services":[{"id":"thinkerbell-root-service"}],"tags":[" | ** POST http://localhost:3000/api/v1/services/tags {"services":[{"id":"thinkerbell-root-service"}],"tags":["location:living-room"] } | ||
== Channels == | == Channels == | ||
| Line 54: | Line 53: | ||
A selector is an object with the following fields: | A selector is an object with the following fields: | ||
* (required for Fetch/Send, optional in other cases) string `feature`: accept only channels that implement a given feature (e.g. "oven/temperature-celcius") | |||
* (optional) string id: accept only a channel with a given id; | * (optional) string id: accept only a channel with a given id; | ||
* (optional) string `service`: accept only channels of a service with a given id; | * (optional) string `service`: accept only channels of a service with a given id; | ||
* (optional) string|array of string `tags`: accept only channels with all the tags in the array; | * (optional) string|array of string `tags`: accept only channels with all the tags in the array; | ||
* (optional) string|array of string `service_tags`: accept only channels of a service with all the tags in the array; | * (optional) string|array of string `service_tags`: accept only channels of a service with all the tags in the array; | ||
Generally, except for (de)assigning tags, '''using an id is considered a bad idea''', as this ties the application to a specific device, and this will fail if the device is replaced (consider that this is equivalent to using an IP address instead of a domain name). | Generally, except for (de)assigning tags, '''using an id is considered a bad idea''', as this ties the application to a specific device, and this will fail if the device is replaced (consider that this is equivalent to using an IP address instead of a domain name). | ||
| Line 68: | Line 66: | ||
* Fetch values from all channels matching any of the selectors | * Fetch values from all channels matching any of the selectors | ||
POST http://localhost:3000/api/v1/channels selector(s) | |||
<br/> | <br/> | ||
Example: | Example: | ||
POST http://localhost:3000/api/v1/channels [{"tags": "location: entrance", "feature": "oven/temperature-celcius"}] | |||
=== Sending === | === Sending === | ||
| Line 79: | Line 77: | ||
* Send one values to all channels matching any of the selectors: | * Send one values to all channels matching any of the selectors: | ||
PUT http://localhost:3000/api/v1/channels/set {"select": selector(s), "value": value} | PUT http://localhost:3000/api/v1/channels/set {"select": selector(s), "value": value} | ||
or | or | ||
* Send a bunch of values to all channels matching any of the selectors: | * Send a bunch of values to all channels matching any of the selectors: | ||
PUT http://localhost:3000/api/v1/channels/set [{"select": selector(s), "value": value}, {"select": selector(s), "value: value}, ...] | PUT http://localhost:3000/api/v1/channels/set [{"select": selector(s), "value": value}, {"select": selector(s), "value": value}, ...] | ||
Values are defined by Adapters, so you should check the documentation of individual adapters to see what is possible. | |||
==== Example (with CURL) ==== | ==== Example (with CURL) ==== | ||
| Line 90: | Line 90: | ||
The following snippet displays "Hello world" on all the devices that support Log, in particular the console. | The following snippet displays "Hello world" on all the devices that support Log, in particular the console. | ||
curl -X PUT http://localhost:3000/api/v1/channels/set -d '{"select":{" | curl -X PUT http://localhost:3000/api/v1/channels/set -d '{"select":{"feature":"log/append-text"},"value":{"String":"Hello, world"}}' | ||
=== Tags === | === Tags === | ||
* Assign Tags to a channel | * Assign Tags to a channel | ||
** POST http://localhost:3000/api/v1/channels/ | ** POST http://localhost:3000/api/v1/channels/channel/tags {"channel": selector(s), "tags": tag(s)} | ||
* Remove Tags of a channel | * Remove Tags of a channel | ||
** DELETE http://localhost:3000/api/v1/channels/ | ** DELETE http://localhost:3000/api/v1/channels/channel/tags {"channel": selector(s), "tags": tag(s)} | ||
= Specific services and channels = | = Specific services and channels = | ||
== Time == | == Time == | ||
* Get the current time | * Get the current time | ||
PUT http://localhost:3000/api/v1/channels/get {" | PUT http://localhost:3000/api/v1/channels/get {"feature":"clock/time-of-day-seconds"} | ||
PUT http://localhost:3000/api/v1/channels/get {" | PUT http://localhost:3000/api/v1/channels/get {"feature":"clock/time-timestamp-rfc-3339"} | ||
== Camera == | == Camera == | ||
* Take a picture with camera | * Take a picture with camera | ||
PUT http://localhost:3000/api/v1/channels/set {"select": {"id": "setter:snapshot.ae67e622-7a66-465e-bab0-28107b2df980@link.mozilla.org", "feature": "camera/store-snapshot"}, "value": {}} | |||
* Get list of images taken | * Get list of images taken | ||
PUT http://localhost:3000/api/v1/channels/get {"id":"getter:image_list.ae67e622-7a66-465e-bab0-28107b2df980@link.mozilla.org", "feature": "camera/x-image-list"} | |||
* Download the last taken picture | * Download the last taken picture | ||
PUT http://localhost:3000/api/v1/channels/get {"id":"getter:image_newest.ae67e622-7a66-465e-bab0-28107b2df980@link.mozilla.org", "feature": "camera/x-latest-image"} | |||
* Get list of services that can take image (snapshot) | * Get list of services that can take image (snapshot) | ||
POST http://localhost:3000/api/v1/services {"channels":[{"feature": "camera/store-snapshot"} }]} | |||
== Recipe == | == Recipe == | ||
| Line 137: | Line 136: | ||
conditions: one or more of { | conditions: one or more of { | ||
source: one or more of Selectors (see section on channels) | source: one or more of Selectors (see section on channels) | ||
feature: see [http://fxbox.github.io/taxonomy/doc/foxbox_taxonomy/services/enum.ChannelKind.html#json documentation of channel kinds] | |||
range: see [http://fxbox.github.io/taxonomy/doc/foxbox_taxonomy/values/enum.Range.html#json documentation of ranges] | range: see [http://fxbox.github.io/taxonomy/doc/foxbox_taxonomy/values/enum.Range.html#json documentation of ranges] | ||
duration: (optional) floating point number of seconds | duration: (optional) floating point number of seconds | ||
| Line 143: | Line 142: | ||
execute: one or more of { | execute: one or more of { | ||
destination: one or more Selectors (see section on channels) | destination: one or more Selectors (see section on channels) | ||
feature: see [http://fxbox.github.io/taxonomy/doc/foxbox_taxonomy/services/enum.ChannelKind.html#json documentation of channel kinds] | |||
value: see [http://fxbox.github.io/taxonomy/doc/foxbox_taxonomy/values/enum.Value.html#json documentation of values] | value: see [http://fxbox.github.io/taxonomy/doc/foxbox_taxonomy/values/enum.Value.html#json documentation of values] | ||
} | } | ||
| Line 164: | Line 163: | ||
"ThinkerbellRule":{ | "ThinkerbellRule":{ | ||
"name":"Hello, Thinkerbell", | "name":"Hello, Thinkerbell", | ||
"source":"{\"name\": \"Hello, Thinkerbell\", \"rules\":[{\"conditions\":[{\"source\":[{\"id\":\"OpenZWave/72057594126794752 (Sensor)\"}],\" | "source":"{\"name\": \"Hello, Thinkerbell\", \"rules\":[{\"conditions\":[{\"source\":[{\"id\":\"OpenZWave/72057594126794752 (Sensor)\"}],\"feature\":\"door/is-open\",\"range\":{\"Eq\":{\"OpenClosed\":\"Open\"}}}],\"execute\":[{\"destination\":[{\"feature\":\"log/append-text\"}],\"feature\":\"log/append-text\",\"value\":{\"String\":\"Closed\"}}]}]}" | ||
} | } | ||
} | } | ||
| Line 172: | Line 171: | ||
Example: | Example: | ||
POST http://localhost:3000/api/v1/services HTTP/1.1 {" | POST http://localhost:3000/api/v1/services HTTP/1.1 {"channels": [{"feature": "thinkerbell/source"}]} | ||
== WebPush == | == WebPush == | ||
* Get current subscriptions | * Get current subscriptions | ||
PUT http://localhost:3000/api/v1/channels/get {" | PUT http://localhost:3000/api/v1/channels/get {"feature": "webpush/subscribe"} | ||
* Get current resources receiving notifications on | * Get current resources receiving notifications on | ||
PUT http://localhost:3000/api/v1/channels/get {" | PUT http://localhost:3000/api/v1/channels/get {"feature": "webpush/resource"} | ||
* Add push subscription | * Add push subscription | ||
PUT http://localhost:3000/api/v1/channels/set {"select": {" | PUT http://localhost:3000/api/v1/channels/set {"select": {"feature": "webpush/subscribe"}, | ||
"value": {"Json": {"subscriptions":[{"push_uri":"http://push.service/t54wtresfesfd","public_key":"base64_encoded_key","auth":"optional_base64_auth_data"}]}}} | "value": {"Json": {"subscriptions":[{"push_uri":"http://push.service/t54wtresfesfd","public_key":"base64_encoded_key","auth":"optional_base64_auth_data"}]}}} | ||
* Remove push subscription | * Remove push subscription | ||
PUT http://localhost:3000/api/v1/channels/set {"select": {" | PUT http://localhost:3000/api/v1/channels/set {"select": {"feature": "webpush/unsubscribe"}, | ||
"value": {"Json": {"subscriptions":[{"push_uri":"http://push.service/t54wtresfesfd","public_key":"base64_encoded_key","auth":"optional_base64_auth_data"}]}}} | "value": {"Json": {"subscriptions":[{"push_uri":"http://push.service/t54wtresfesfd","public_key":"base64_encoded_key","auth":"optional_base64_auth_data"}]}}} | ||
| Line 264: | Line 262: | ||
=== Examples === | === Examples === | ||
==== Check availability of an individual light ==== | ==== Check availability of an individual light ==== | ||
PUT http://localhost:3000/api/v1/channels/get {"id":" | PUT http://localhost:3000/api/v1/channels/get {"id":"channel:available.4.001788fffe25681a.philips_hue@link.mozilla.org"} | ||
==== Turn all the lights off ==== | ==== Turn all the lights off ==== | ||
PUT http://localhost:3000/api/v1/channels/set {"select":{" | PUT http://localhost:3000/api/v1/channels/set {"select":{"feature":"light/is-on"},"value":{"OnOff":"Off"}} | ||