Connected Devices/Projects/Project Link/Taxonomy

From MozillaWiki
< Connected Devices‎ | Projects‎ | Project Link
Revision as of 16:20, 8 April 2016 by Yoric (talk | contribs) (→‎WebPush: Some reviews)
Jump to navigation Jump to search

Taxonomy Documentation

Github Link: http://fxbox.github.io/taxonomy/doc/foxbox_taxonomy/index.html

Current REST API

Account

Services

Services may requested by selector. A service selector is an object with the following fields:

  • (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) object or array of objects `getters` (see GetterSelector): accept only services with channels matching all the selectors in this array;
  • (optional) object or array of objects `setters` (see SetterSelector): 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).

List of Services

Example with 1 selector:

  • Get services with tag "location: kitchen" and channel kind "OvenTemperature"

Example with 2 selectors:

As a shortcut, providing no argument will locate all services:

Tags

Channels

Channels are designed to be used by selector.

A selector is an object with the following fields:

  • (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|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|object `kind` (see ChannelKind): accept only channels of a given kind.

While each field is optional, at least one field must be provided.

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).


Fetching

  • Fetch values from all channels matching any of the selectors
   PUT http://localhost:3000/api/v1/channels/get selector(s)


Example: 

   PUT http://localhost:3000/api/v1/channels/get [{"tags": "location: entrance", kind: "OpenClosed"}

Sending

  • Send one values to all channels matching any of the selectors:
   PUT http://localhost:3000/api/v1/channels/set {"select": selector(s), "value": value}

or

  • 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}, ...]

See http://fxbox.github.io/taxonomy/doc/foxbox_taxonomy/values/enum.Value.html for the full documentation on values.

Example (with CURL)

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":{"kind":"Log"},"value":{"String":"Hello, world"}}'

Tags


Specific services and channels

Time

Camera

Recipe

A recipe is a set of *rules*.

Each rule is triggered when *all* its *conditions* are true. A condition is specified by a set of channels to watch and a range of values that make it true - the condition becomes true once *any* of the channels it watches provides a value that fits the range.

Once a rule is triggered, it *executes*. An execution sends one value to a set of channels.


Once a rule is triggered, it won't be triggered again until at least one of the conditions has become false and true again.

Format: 

 {
   name: "Some name",
   rules: one or more of {
     conditions: one or more of {
       source: one or more of Selectors (see section on channels)
       kind: see documentation of channel kinds
       range: see documentation of ranges
       duration: (optional) floating point number of seconds
     }
     execute: one or more of {
       destination: one or more Selectors (see section on channels)
       kind: see documentation of channel kinds
       value: see documentation of values
     }
   }
 }


  • Send Recipe

Example: 

   PUT http://localhost:3000/api/v1/channels/set
   
   {
      "select":{
         "kind":"AddThinkerbellRule"
      },
      "value":{
         "ThinkerbellRule":{
            "name":"Hello, Thinkerbell",
            "source":"{\"name\": \"Hello, Thinkerbell\", \"rules\":[{\"conditions\":[{\"source\":[{\"id\":\"OpenZWave/72057594126794752 (Sensor)\"}],\"kind\":\"OpenClosed\",\"range\":{\"Eq\":{\"OpenClosed\":\"Open\"}}}],\"execute\":[{\"destination\":[{\"kind\":\"Log\"}],\"kind\":\"Log\",\"value\":{\"String\":\"Closed\"}}]}]}"
         }
      }
   }
  • List available Recipes

Example: 

   POST http://localhost:3000/api/v1/services HTTP/1.1 {"getters": [{"kind": "ThinkerbellRuleSource"}]}

WebPush

Note: In the future, there will be a ChannelKind (or equivalent) to replace the id.

  • Get current subscriptions
   PUT http://localhost:3000/api/v1/channels/get {"id": "getter:subscription.webpush@link.mozilla.org"}
  • Get current resources receiving notifications on
   PUT http://localhost:3000/api/v1/channels/get {"id": getter:resource.webpush@link.mozilla.org"}

(the following lines have not been reviewed)

Retrieved from "https://wiki.allizom.org/index.php?title=Connected_Devices/Projects/Project_Link/Taxonomy&oldid=1126712"