Hypermedia Design for Machine Interfaces

Part 2 – Hypermedia Architecture and Demonstrator for a Web of

Things

Hypermedia Architecture• Web of Things system architecture and demonstrator

using the Hypermedia Collection with resource type semantics

• HATEOAS discovery and client-server state machine • Implements the W3C Web of Things interaction model• Scripted applications based on a consistent Thing Object

Model• Public resource at thingschema.org for semantics• Uses IETF CoRE RD, Link-Format, SenML• Pluggable protocols; Common CRUD interface allows

CoAP, HTTP, MQTT, Websockets, etc.

Base Schema

Resource Model

Application Logic

Thing Object Model

(Deferred Interface)

Hypermedia System Architecture

Domain Schema

Resources

Hypermedia Controls

Discovery

Domain Model

Hypermedia Client

Resource Logic

(Physical I/O)

Networks

Client

Server

Public Resource

Tools

Base Schema

Resource Model

Application Logic

Thing Object Model

(Deferred Interface)

Model Driven Resource Construction

Domain Schema

Resources

Hypermedia Controls

Discovery

Domain Model

Hypermedia Client

Resource Logic

(Physical I/O)

Base Schema

Resource Model

Application Logic

Thing Object Model

(Deferred Interface)

HATEOAS Driven Discovery

Domain Schema

Resources

Hypermedia Controls

Discovery

Domain Model

Hypermedia Client

Resource Logic

(Physical I/O)

Base Schema

Resource Model

Application Logic

Thing Object Model

(Deferred Interface)

HATEOAS Driven Interaction

Domain Schema

Resources

Hypermedia Controls

Discovery

Domain Model

Hypermedia Client

Resource Logic

(Physical I/O)

Modular ArchitectureProtocol Abstraction

Application Logic

Common CRUD Requests

MQTT

Common CRUD Responses

Resource Model

Resources

Resource Model

Thing Object Model

HTTP CoAP

Common Server

Common Client

Pluggable Protocols

Resource Logic

WS

Base Schema

Resource Model

Application Logic

Thing Object Model

(Deferred Interface)

Information Model

Domain Schema

Resources

Hypermedia Controls

Discovery

Domain Model

Hypermedia Client

Resource Logic

(Physical I/O)

Networks

Client

Server

Public Resource

Tools

Information Model• Base Schema based on W3C Interaction Model– Events, Actions, Properties

• Descriptions and explanations, not tags; learning not matching

• Incremental reveal discovery– light => brightness => change => (targetBrightness,

transitionTime)• Enables index search – Discover “light+brightness+change”

Base Schema – WoT Interaction Model

{ "class": "action", "comment": "Action class", "mayHave": [ "actuation", "notification", "params" ], "subClassOf": "WoTinteractionModel", "usedBy": [ "thing", "capability" ]},

Base Schema

Resource Model

Application Logic

Thing Object Model

(Deferred Interface)

Domain Schema

Domain Schema

Resources

Hypermedia Controls

Discovery

Domain Model

Hypermedia Client

Resource Logic

(Physical I/O)

Networks

Client

Server

Public Resource

Tools

Domain Schema

• Domain Schema is based on a simple information model and schema

• Logical entities are constrained by range and domain terms

• Domain specific terms are mapped to the information model to prodice a domain schema

• Domain schema is used in resource construction and discovery

Domain Schema and Model• Reusable terms with mayHave and usedBy definitions

– “brightness” is used by “light” but not “motion sensor”– “brightness” may have “change” action but not “reverse”

class: brightness,type: capability,description: “brightness control”usedBy: [ light ],mayHave: [

currentBrightness, targetBrightness,stepBrightness, moveBrightness, change, step, move, stop, propertyValueChange ],

params: {_targetValue: _targetBrightness,

_stepSize: _stepBrightness, _moveRate: _moveBrightness},}

Domain Model Example "@context": "http://thingschema.org", "resource": [ { "type": "light", "name": "light", "properties": [ { "type": "currentstate", "name": "currentState" }, { "type": "targetstate", "name": "targetState" }, { "type": "delaytime", "name": "delayTime" }

Resource Model Construction

• The Resource Model is made of Collections, Links, and Forms

• Resource Model Instances are constructed from Domain Model instances

• A Domain Model applies structural constraints to a Domain Schems and informs the constructor which resources to instantiate and how

Base Schema

Resource Model

Application Logic

Thing Object Model

(Deferred Interface)

Resource Model

Domain Schema

Resources

Hypermedia Controls

Discovery

Domain Model

Hypermedia Client

Resource Logic

(Physical I/O)

Networks

Client

Server

Public Resource

Tools

Resource Model• Hypermedia Collections use Content Format

to select resource interaction• Uses “sub” link relation to create a resource

tree, collections of collections• Properties, forms, items, and collection

subresources may be mixed in a collection• Resource Type (the “rt” link attribute) is used

to select domain functionality for resources

Resource Model

Link ItemLink FormLinkLink

Link (self)

(sub)

Link

Collection

Link ItemLinkLinkLink

Form

Link ItemSub Resource Collection

Collection

LinkLink

Collection

Link

HATEOAS State Machines

• Describe the coupling between the application and resources for Discovery and Interaction Model operations

• Application state machine is coupled with resource state machine through requests and responses

• State diagrams show a sequence of operations from request to response

HATEOAS

Response

Request

Application Logic

Resource

State Machine - Discovery

App logic

Start

Error

Query

Build TOM

Capture Link

Request

Response

found

err

errerr

done

done

submit

rst

req

rejectfu

lfill

adde

d

State Machine - Interaction

App logic

Start

Error

Request Wait

Process Resp

Retry

Request

Response

fail

err

errerr

done

done

send

rst

req

rejectfu

lfill

retr

y

State Machine – Subscribe/Invoke

App logic

Start

Error

Select Form

UpdateState

Submit Form

Request

Response

got form

err

errerr

done

done

send

rst

req

rejectfu

lfill

Track State

more

update

Base Schema

Resource Model

Application Logic

Thing Object Model

(Deferred Interface)

Thing Object Model

Domain Schema

Resources

Hypermedia Controls

Discovery

Domain Model

Hypermedia Client

Resource Logic

(Physical I/O)

Networks

Client

Server

Public Resource

Tools

Thing Object Model

• Thing Object Model (TOM) is a container for a set of resource references

• Application may use the domain schema to understand terms describing TOM resources

• Provides discovery and interaction model abstractions in the form of a scripting API

• Client State Machines, Discovery, and Form Logic

Interaction Model

• Interaction model is a set of functional abstractions that enable application state machines to be standardized

• The W3C Interaction model consists of Properties, Events, and Actions

• Properties are resource elements• Actions and Events are behaviors• The TOM maps actions and events to hypermedia

forms and POST operations

Interaction Model Classes

WoT Interaction Model

Index PropertyEvent Action

CapabilitySubscription Notification Actuation

Thing

subClassOf

Interaction Model Relationships

PropertyEvent Action

(Capability)

Subscription

Notification

Actuation

Thing

Index

Capability

Notification

Capability

Index

has

pointsTo

Interaction Model – TOM elements• Action

– Invoke (returns handle to actuation)– updateActuation– getActuations

• Event– Subscribe (returns handle to subscription)– updateSubscription– getsubscriptions

• Property– getValue– setValue

Promise+• New pattern is needed for application scripts to handle recurring

events like notifications from subscriptions and actuations• Deferred patern can be extended • Fulfill may happen more than once• Promise can be extended to include a handle to modify the work

in progress• Some modifications (e.g. cancel) will result in the Promise being

fulfilled a final time or rejected• Maybe a third option like “complete” in addition to fulfill and

reject:promise = deferred(subscribe(…), fulfillHandler, completeHandler, rejectHandler)

Common CRUD REST Layer Abstraction

• Transport independent REST abstraction layer• Does not use REST for message transport• Instead, create a common abstraction layer• Map abstraction to HTTP and CoAP request

and response fields• Encapsulate the abstraction in WS and MQTT

payloads

Dictionary Mapping of Common REST Transaction Layer

{"uriPath": ["/","a", "b"], "uriQuery": {"rt": "test", "obs": "", "if": "core.b"}"contentFormat": "application/link-format+json","options": {}"method": "GET","payload": null,"response": { "status": "Success", "code": "204", "reason": "No Content", "contentFormat": "application/link-format+json", "payload": "[{"href":"","rel":"self","rt":"index"}]" }}

Common CRUD

(IP)

Send/Rcv

(PHY)

Send/Rcv

URI Topic, URI

(IP)

Send/Rcv

(PHY)

(IP)

Pub/Sub

(PHY)

(IP)

Trx

(PHY)

URIURI

REST REST REST

CoAP HTTP MQTT WS CCML

URI

RESTREST

• Map abstraction to HTTP and CoAP request and responses• Encapsulate the abstraction in WS and MQTT payloads

Consistent Resource Identifiers: Cross-Protocol Hyperlinking

http://example.com:8000/b31/env/light/onoff

coap://example.com:5683/b31/env/light/onoff

ws://example.com:80/b31/env/light/onoff

mqtt://example.com:1883/b31/env/light/onoff

Mapped to URI

Mapped to URI

Part Topic --- Part Payload

Encapsulated in Payload

Demonstrator and Reference Implementation

• Machine Hypermedia Toolkit is an open source reference implementation

https://github.com/connectIOT/MachineHypermediaToolkit

• Demonstrator resource on Github for tutorial introduction

https://github.com/connectIOT/HypermediaDemo

Resources…• These slideshttp://www.slideshare.net/michaeljohnkoster/hypermedia-system-architecture-for-a-web-of-things-56982166

• Blog Articlehttp://iot-datamodels.blogspot.com/2015/10/hypermedia-design-for-machine-interfaces.html

• Demo Resourcehttps://github.com/connectIOT/HypermediaDemo

• Reference Implementation (work in progress)https://github.com/connectIOT/MachineHypermediaToolkit

• CoRE Interfaceshttps://datatracker.ietf.org/doc/draft-ietf-core-interfaces/

• Link-Formathttps://tools.ietf.org/html/rfc6690 , https://tools.ietf.org/html/draft-ietf-core-links-json-04

• SenML-01https://datatracker.ietf.org/doc/draft-jennings-core-senml/01/