Connected Devices/Projects/Project Link/Taxonomy

Taxonomy Documentation

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

Current REST API

Account

• To create account:
  • POST http://localhost:3000/users/setup {"email": "a@b.com","username":"admin","password": "00000000"}
• To login:
  • POST http://localhost:3000/users/login (Header contains Authorization: Basic <base64 encode of username:password)

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"
  • GET http://localhost:3000/api/v1/services { "tags": "location: kitchen", "channels": { "feature": "oven/temperature-celcius" } }

Example with 2 selectors:

• Get services with tag "location: kitchen" or "location: entrance":
  • GET http://localhost:3000/api/v1/services [{ tags: "location: kitchen" }, {tags: "location: entrance"}]

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

• Get all services:
  • GET http://localhost:3000/api/v1/services

Tags

• Assign Tags to a service
  • POST http://localhost:3000/api/v1/services/tags {"services": selector(s), "tags": tag(s)}

• Remove Tags of a service
  • DELETE http://localhost:3000/api/v1/services/tags {"services": selector(s), "tags": tag(s)}

• Example
  • POST http://localhost:3000/api/v1/services/tags {"services":[{"id":"thinkerbell-root-service"}],"tags":["location:living-room"] }

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 `feature`: accept only channels that implement a given feature (e.g. "oven/temperature-celcius").

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

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

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

Tags

• Assign Tags to a channel
  • POST http://localhost:3000/api/v1/channels/channel/tags {"channel": selector(s), "tags": tag(s)}

• Remove Tags of a channel
  • DELETE http://localhost:3000/api/v1/channels/channel/tags {"channel": selector(s), "tags": tag(s)}

Specific services and channels

Time

• Get the current time

   PUT http://localhost:3000/api/v1/channels/get {"kind":"CurrentTime"}
   PUT http://localhost:3000/api/v1/channels/get {"kind":"CurrentTimeOfDay"}

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"}, "value": {"Unit": {}}}

• 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"}
• 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"}
• Get list of services that can take image (snapshot)
  • POST http://localhost:3000/api/v1/services {"setters":[{"kind":{"adapter":"Adapter","kind":"snapshot","type": "Json", "vendor":"DLink"} }]}

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"}

• Add push subscription

   PUT http://localhost:3000/api/v1/channels/set {"select": {"id": "setter:subscribe.webpush@link.mozilla.org"}, 
   "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": {"id": "setter:unsubscribe.webpush@link.mozilla.org"}, 
   "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)

• Set resources to receive notifications on
  • PUT http://localhost:3000/api/v1/channels/set {"select": {"id": "setter:resource.webpush@link.mozilla.org"}, "value": {"Json": {"resources":["res1", "res2"]}}}
• Trigger notification
  • PUT http://localhost:3000/api/v1/channels/set {"select": {"id": "setter:notify.webpush@link.mozilla.org"}, "value": {"Json": {"resource":"res1","message":"push_message_data"}}}

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":"getter:available.4.001788fffe25681a.philips_hue@link.mozilla.org"}

Turn all the lights off

PUT http://localhost:3000/api/v1/channels/set {"select":{"kind":"LightOn"},"value":{"OnOff":"Off"}}