Gateway Capability Schema

[benfrancis]

A schema to describe a Web of Things Gateway (with a things resource which lists all the things it exposes).

Could have an action for "reboot".

See also WebThingsIO/api#91

[rzr]

I would add a load level property and event for when "out of storage"

[hobinjk]

I think there's a complementary capability here like "Computer" or "OperatingSystem" which has all the nice load, memory, disk, and other system parameters in addition to reboot/shutdown actions.

The Gateway capability then could stay limited to only the critical information necessary to be a gateway. I think this would be the list of things, addThing/removeThing/unpairThing actions, and thingAdded/thingRemoved/thingUnpaired/thingUnreachable events.

[rzr]

Also backup/import and reset ~/.mozilla-iot would be useful too

[benfrancis]

Some late feedback...

I've provided some feedback on the corresponding spec change but to summarise, in future I think we should restructure this slightly by:

• Making the gateway itself a web thing with its own Thing Description and capability schema
• Replace the Things resource with links in the gateway's Thing Description
• Link to the gateway-wide WebSocket endpoint in the links member of the gateway's Thing Description
• Make "pair", "unpair" etc. actions in the gateway's Thing Description (so there don't need to be special actions which can't have an ID associated with them)

[benfrancis]

What should the properties, actions and events be for the Gateway capability schema? Some thoughts below...

Properties

• None.

Actions

• AddThingAction
  • input:
    • type: string - id of thing to add
• RemoveThingAction
  • input:
    • type: string - id of thing to remove

Events

• ThingAddedEvent
  • type: string - id of thing that was added
• ThingRemovedEvent
  • type: string - id of thing that was removed

Questions:

1. Do we need PairAction and UnpairAction, separate from AddThingAction and RemoveThingAction? This is tricky because we need to stay fairly abstract and the pair/unpair mechanism only applies to certain underlying protocols like Zigbee and Z-Wave. It doesn't apply to native web things or many Wi-Fi devices for example.
2. Should RebootAction be part of a separate schema, e.g. some kind of power management schema which could apply to lots of different types of devices?
3. Do we need events to tell a client when a device becomes available and not available (i.e. drops off the network)?

{
  "title": "WebThings Gateway",
  "@context": "https://iot.mozilla.org/schemas/",
  "@type": "Gateway",
  "properties": {},
  "actions": {
    "reboot" {
    },
    "pair": {
      "name": "Add Device",
      "@type": "AddThingAction",
      "input": {
        "type": "string"
      }
    },
    "unpair": {
      "name": "Remove Device",
      "@type": "RemoveThingAction",
      "input": {
        "type": "string"
      }
    }
  },
  "events": {
    "deviceAdded": {
      "name": "Device Added",
      "@type": "ThingAddedEvent"
      "type": "string"
    },
    "deviceRemoved": {
      "name": "Device Added",
      "@type": "ThingRemovedEvent"
      "type": "string"
    }
  },
  "security": { ... }
  "links": [
    {
      "rel": "item",
      "href": "/things/thing1"
    },
    {
      "rel": "item",
      "href": "/things/thing2"
    }
  ]
}

Note: The links member contains links to Thing Descriptions of devices managed by the gateway, as a replacement for the current Things resource. I don't think this link relation type should be defined in this schema, it should be defined in the Web Thing Description specification. Let's discuss that in WebThingsIO/api#91

[mrstegeman]

Properties

• None.

Right now we have nothing. I can think of lots of things that would be hardware-specific, but none that are inherent to any generic gateway. I still think we need a top-level metadata member for things like software version, serial number, etc.

Actions

• AddThingAction

  • input:

    • type: string - id of thing to add

• RemoveThingAction

  • input:

    • type: string - id of thing to remove

We do both of these via the REST API right now, by doing POST /things and DELETE /things/<id>. If we want to use the generic WebThing API, then actions make sense. However, for adding a thing to a gateway, it seems like you'd need more than an ID... If it's a web thing, you'd at least need a URL. If it's something else, e.g. Zigbee, you'd need a full thing description.

Events

• ThingAddedEvent

  • type: string - id of thing that was added

• ThingRemovedEvent

  • type: string - id of thing that was removed

I don't think we currently have any events for the gateway itself, but these would make sense. Again, I think it might make sense to include a thing description with the added event, but not entirely necessary in this case.

Questions:

1. Do we need PairAction and UnpairAction, separate from AddThingAction and RemoveThingAction? This is tricky because we need to stay fairly abstract and the pair/unpair mechanism only applies to certain underlying protocols like Zigbee and Z-Wave. It doesn't apply to native web things or many Wi-Fi devices for example.

This goes back to what I was saying above. It depends on if we want to only assume that a gateway can handle web things, or if it could always handle multiple protocols. Also, for other protocols, we currently use the "pair" action as an indicator that the adapters should perform their device discovery routine and present any new devices that are found.

2. Should RebootAction be part of a separate schema, e.g. some kind of power management schema which could apply to lots of different types of devices?

I don't think it necessarily needs to be a part of any high-level schema. It could just be a standalone action schema that anything could use.

3. Do we need events to tell a client when a device becomes available and not available (i.e. drops off the network)?

We actually have that in our gateway implementation, although we do it through the things WebSocket. It would definitely be a good formal addition.

[raidnet-ms]

The pair action could be used for auto connecting wifi things to local AP.

The thing could connect to the gateway with wifi direct (on a hidden SSID) and the gateway would share SSID and password of its AP.

[benfrancis]

Note: I'm currently tracking work on the W3C's WoT Discovery specification which includes a proposed directory API, which as I understand it exposes the directory as a web thing. This may or may not be a starting point for a gateway capability.