Hub device APIs (and corresponding schema/translators)

[tjaffri]

The device interaction APIs will need to be updated to support relationships between devices and their parent (hub) devices. (We may look to the OCF device relationship model for inspiration/alignment.) This is closely related to the onboarding framework task, in how we streamline the process of onboarding a hub with many attached devices. So the same person should own the design.

This includes prior discussion on "hub as a device", which I will paste below.

[tjaffri]

Problem statements

1. The current OpenT2T alpha on Github has an onboarding model where users onboard individual things. In cases, where the user has a hub with N things connected, the user has to onboard each device individually. There is currently no way to onboard a hub, and then magically get all the devices connected to the hub onboarded at the same time.
2. Similarly, the current OpenT2T alpha on Github does not have a model for managing the hub itself (rather than the devices connected to it). Examples include enumerating devices connected to the hub, their status, managing the account on the hub, etc.
3. Finally, the current OpenT2T alpha does not have any guidance for how to manage accounts. For example, the user could have an account on the Wink service and have multiple hubs hooked up to that service. In an app that hosts OpenT2T, we want the user to be able to see all the hubs (and all the devices associated with each hub) as they switch accounts. We need to think about advanced accounts scenarios as well, e.g. family accounts and delegation.

We would like feedback on whether the problem statement is captured accurately above.

Proposal

1. Accounts are an app-level concept. We don’t add anything directly to OpenT2T for accounts, but apps that host OpenT2T write account UX and get account Ids, access tokens, etc out of that flow (these credentials are then used by the rest of the stack)
2. Hubs are things too. We create a new schema, org.OpenT2T.Sample.SuperPopular.Hub. Proposed schema for now should contain:
   1. Power state management (on/off)
   2. Enumerate devices
   3. Onboarding for a hub requires an account Id, access token, etc. Basically what you get from setting up an account.
3. We implement translators for each hub, e.g. the Wink hub, Samsung smart things hub, etc. We implement the org.OpenT2T.Sample.SuperPopular.Hub schema in these translators. When users onboard hubs directly (now they can, since they are just devices) we enumerate the devices and then for each device initiate onboarding automatically (downloading the associated translator if needed).
4. Things connected via hubs reference the corresponding hub’s onboarding type, e.g. the Wink hub onboarding type. Further, things connected via hubs already provide “filter parameters” to narrow down the search for that type of device on that hub, e.g. see here for the Wink temperature sensor.
5. We create a new attribute in the onboarding type for hubs, e.g. the Wink hub onboarding type to reference the associated device, specifically in this case the associated translator for that hub as mentioned above under Inspect translator metadata and instantiate translators from a local cache #3. When a device connected to a hub is onboarded directly, we also start onboarding for that hub (unless already onboarded) and onboard other devices attached to that hub as well (we can build simple UX to ask the user if they want to set up the other devices attached to the hubs at the same time as onboarding the device).
6. Things not connected via hubs continue to reference onboarding types as they do today, e.g. onboarding type Bluetooth, Z-Wave, etc. Further, they can provide “filter parameters” to narrow down the search on that transport, e.g. see here for the Bluetooth heart rate sensor. No change in this regard.

Summary

I think the only real technical change is #5 (in terms of a small metadata change in the onboarding type). Other than that, the rest is completely in line with our existing thinking… as long as we remember “hubs are things too”.

Updated Wink Hub Onboarding (Proposed)

Current version is at https://github.com/openT2T/onboarding/blob/master/org.OpenT2T.Onboarding.WinkHub/org.OpenT2T.Onboarding.WinkHub.xml

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://standards.freedesktop.org/dbus/introspect-1.0.dtd"[]>
<!--  This is the metadata for a category of things that are connected via the Wink Hub. -->
<node>
    <interface name="com.OpenT2T.Onboarding.WinkHub">
        <!-- Defines the metadata required to start onboarding.
             These input parameters are unique to a particular device type that supports this onboarding type,
             e.g. auth URLs, RF bands, regular expressions to find the device on a common bus, etc. -->
        <method name="onboard">
            <arg name="name" type="s" direction="in" />
            <arg name="idKeyFilter" type="s" direction="in" />
        </method>
        <!-- Get the things required for this onboarding type (these are onboarded first, if not onboarded already) -->
        <!-- This could return one or more hub devices required for any device with this onboarding type: e.g. translator-wink-hub -->
        <method name="requiredThings">
          <arg name="thingTranslators" type="s" direction="out" />
        </method>
        <!-- Defines the metadata returned by onboarding. This is converted to the props array on the device
             object, which is passed in to translators that implement this onboarding type at runtime. -->
        <signal name="success">
            <arg name="access_token" type="s" direction="in" />
            <arg name="id" type="s" direction="in" />
            <arg name="message" type="s" direction="in" />
        </signal>
        <!-- Called when there is an error during onboarding -->
        <signal name="error">
            <arg name="type" type="s" direction="out"/>
            <arg name="message" type="s" direction="out"/>
        </signal>
    </interface>
</node>

New Hub Translator i.e. Hubs are also devices (Proposed)

###1. Hub Schema (common to all hubs):**

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE node PUBLIC "-//freedesktop//DTD D-BUS Object Introspection 1.0//EN" "http://standards.freedesktop.org/dbus/introspect-1.0.dtd"[]>
<node>
  <interface name="org.OpenT2T.Sample.SuperPopular.Hub">
    <!-- Sets the power state of the hub -->
    <method name="setPowerState">
      <arg name="state" type="b" direction="in" />
    </method>
    <!-- Gets the power state of the hub -->
    <method name="getPowerState">
      <arg name="state" type="b" direction="out" />
    </method>
    <!-- Enumerates devices connected to the hub -->
    <method name="enumerateDevices">
      <arg name="idKeyFilter" type="s" direction="in" />
    </method>
    <!-- Called when there is an error during usage of this translator -->
    <signal name="error">
        <arg name="type" type="s" direction="out"/>
        <arg name="message" type="s" direction="out"/>
    </signal>
  </interface>
</node>

2. Package.json (for sample Wink Hub)

{
  "name": "translator-wink-hub",
  "version": "1.0.0",
  "description": "",
  "dependencies": {},
  "devDependencies": {
    "async": "~1.5.2",
    "opent2t-onboarding-oauth2": "^1.0.1",
    "optimist": "0.6.1"
  },
  "author": "",
  "license": "MIT"
}

3. Translator Manifest (for sample Wink Hub)

<?xml version="1.0" encoding="utf-8"?>
<manifest>
  <!-- associated voice handler -->
  <voice id="" />
  <!-- associated schema -->
  <schema id="org.OpenT2T.Sample.SuperPopular.Hub" />
  <!-- associated onboarding module -->
  <onboarding id="org.OpenT2T.Onboarding.OAuth2">
    <arg name="name" value="" />
  </onboarding>
</manifest>

4. Translator node script (for sample Wink Hub)

'use strict';

// logs device state
function logDeviceState(device) {
    if (typeof (device) !== 'undefined') {
        console.log('  device.name          : ' + device.name);
        console.log('  device.props         : ' + device.props);
    } else {
        console.log('device is undefined');
    }
};

// module exports, implementing the schema
module.exports = {

    device: null,

    initDevice: function(dev) {
        this.device = dev;

        console.log('Javascript initialized.');
        logDeviceState(this.device);
    },

    setPowerState: function() {
        console.log('setPowerState called.');

        // call the Wink API to set the power state of this hub.
    },

    getPowerState: function() {
        console.log('getPowerState called.');

        // call the Wink API to get the power state of this hub.
    },

    enumerateDevices: function(idKeyFilter) {
        console.log('enumerateDevices called with value: ' + idKeyFilter);

        // call the Wink API to enumerate all the devices connected to this hub.
    },

    disconnect: function() {
        console.log('disconnect called.');
        logDeviceState(this.device);
    }
};