Connected Devices/Projects/Project Link/Taxonomy

From MozillaWiki
Jump to: navigation, 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 `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).

List of Services

Example with 1 selector:

  • Get services with tag "location: kitchen" and a channel with feature "oven/temperature-celcius"

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:

  • (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 `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;


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
   POST http://localhost:3000/api/v1/channels selector(s)


Example: 

   POST http://localhost:3000/api/v1/channels [{"tags": "location: entrance", "feature": "oven/temperature-celcius"}]

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

Values are defined by Adapters, so you should check the documentation of individual adapters to see what is possible.


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":{"feature":"log/append-text"},"value":{"String":"Hello, world"}}'

Tags

Specific services and channels

Time

  • Get the current time
   PUT http://localhost:3000/api/v1/channels/get {"feature":"clock/time-of-day-seconds"}
   PUT http://localhost:3000/api/v1/channels/get {"feature":"clock/time-timestamp-rfc-3339"}

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
   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
   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)
   POST http://localhost:3000/api/v1/services {"channels":[{"feature": "camera/store-snapshot"} }]}

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)
       feature: 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)
       feature: 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)\"}],\"feature\":\"door/is-open\",\"range\":{\"Eq\":{\"OpenClosed\":\"Open\"}}}],\"execute\":[{\"destination\":[{\"feature\":\"log/append-text\"}],\"feature\":\"log/append-text\",\"value\":{\"String\":\"Closed\"}}]}]}"
         }
      }
   }
  • List available Recipes

Example: 

   POST http://localhost:3000/api/v1/services HTTP/1.1 {"channels": [{"feature": "thinkerbell/source"}]}

WebPush

  • Get current subscriptions
   PUT http://localhost:3000/api/v1/channels/get {"feature": "webpush/subscribe"}
  • Get current resources receiving notifications on
   PUT http://localhost:3000/api/v1/channels/get {"feature": "webpush/resource"}
  • Add push subscription
   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"}]}}}
  • Remove push subscription
   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"}]}}}

(the following have not been reviewed)

Lights

Sample service entry for a Philips Hue Lightstrip Plus: 

 [
   {
     "adapter": "philips_hue@link.mozilla.org",
     "getters": {
       "getter:available.4.001788fffe25681a.philips_hue@link.mozilla.org": {
         "adapter": "philips_hue@link.mozilla.org",
         "id": "getter:available.4.001788fffe25681a.philips_hue@link.mozilla.org",
         "kind": {
           "adapter": "Philips Hue Adapter",
           "kind": "available",
           "typ": "OnOff",
           "vendor": "foxlink@mozilla.com"
         },
         "mechanism": "getter",
         "service": "service:4.001788fffe25681a.philips_hue@link.mozilla.org",
         "tags": []
       },
       "getter:power.4.001788fffe25681a.philips_hue@link.mozilla.org": {
         "adapter": "philips_hue@link.mozilla.org",
         "id": "getter:power.4.001788fffe25681a.philips_hue@link.mozilla.org",
         "kind": "LightOn",
         "mechanism": "getter",
         "service": "service:4.001788fffe25681a.philips_hue@link.mozilla.org",
         "tags": []
       }
     },
     "id": "service:4.001788fffe25681a.philips_hue@link.mozilla.org",
     "properties": {
       "manufacturer": "Philips",
       "model": "LST002",
       "name": "Hue lightstrip plus 1",
       "type": "Light/ColorLight"
     },
     "setters": {
       "setter:power.4.001788fffe25681a.philips_hue@link.mozilla.org": {
         "adapter": "philips_hue@link.mozilla.org",
         "id": "setter:power.4.001788fffe25681a.philips_hue@link.mozilla.org",
         "kind": "LightOn",
         "mechanism": "setter",
         "service": "service:4.001788fffe25681a.philips_hue@link.mozilla.org",
         "tags": []
       }
     },
     "tags": [
       "type:Light/ColorLight"
     ]
   }
 ]

Channels

getter:availability

Response: 

{"OnOff":"Off"} when light not ready to receive commands (f.e. no external power)
{"OnOff":"On"} when light ready to receive commands

getter:power

Response: 

{"OnOff":"Off"} when the light is completely turned off
{"OnOff":"On"} when the light is turned on

setter:power

Value: 

{"OnOff":"Off"} to turn the light off
{"OnOff":"On"} to turn the light on

Examples

Check availability of an individual light

PUT http://localhost:3000/api/v1/channels/get {"id":"channel:available.4.001788fffe25681a.philips_hue@link.mozilla.org"}

Turn all the lights off

PUT http://localhost:3000/api/v1/channels/set {"select":{"feature":"light/is-on"},"value":{"OnOff":"Off"}}
Retrieved from "https://wiki.mozilla.org/index.php?title=Connected_Devices/Projects/Project_Link/Taxonomy&oldid=1137043"