You are here

Programmer's Guide

This document covers the architecture and basic operations of the Iotivity Resource API stack, including samples of protocol, flows, APIs and some use cases. It is intended to provide context for developers using IoTivity APIs and to provide a high level architectural overview.

Stack Blocks

The Resource API stack consists of several thin layers of software. In unconstrained environments such as Android*, iOS*, or Microsoft* Windows*, the stack provides APIs in C and C++ that allow developers to talk to both constrained and unconstrained devices via IP networks, with potential support for additional network protocols and wireless technologies. In the first release, the key technologies for connectivity include UDP/IP and the Constrained Application Protocol (CoAP).

stack_diagram.png

Terminology

Device A constrained device that has the Thin Block stack installed which enabled one or more services for other Thin Block or Unified Block devices to consume.

Resource A resource is a component in a server that can be viewed and controlled by another Thin Block or Unified Block device. There are different resource types, for example a temperature sensor, a light controller etc.

Resources can be arranged in a hierarchal manner to form a resource tree. This generic method of structure enables modeling of many different resource topologies.

  • Example: A light controller is a resource.
  • Example: A light array is a set of resources organized in a flat (non-hierarchical) manner.
  • Example: A garage door opener is a resource; it could host two resources - light and lock.

A more detailed description of resources and resource management along with code snippets is provided later in this document.

Operations Operations are actions that a Thin Block or Unified Block can perform on attributes associated with a particular resource. Resource attributes can have different operations based on the nature of the resource type. Fundamentally, these are GET and PUT operations. Additionally, attributes can be declared observable to enable remote devices to subscribe to changes.

  • Example: One of the child resources on the garage door opener is the light control; it has a GET operation that allows a device to get the current light state (on/off).

Functionality

The initial release of IoTivity includes functionality for:

External References

The following references may provide additional guidance.

Note: In some places, the IoTivity design may differ from the CoRE specifications. In these cases, consider the CoRE specifications as informative, but not definitive, on the Iotivity design and architecture.

Protocol Message Format(s)

The OIC protocol (abbreviated to OC in code) is a REST-like interface similar to HTTP and CoAP. However, it is a higher level abstraction of those protocols to allow for additional transports including Bluetooth Classic, Bluetooth Smart (BLE), Zigbee or others in the future. To that end, every attempt has been made to keep CoAP and HTTP specific aspects from being expressed directly in the OIC protocol. The following sections describes how specific transports are used to support the OIC protocol and abstractions.

Constrained Application Protocol (CoAP)

Constrained Application Protocol is one of the IoTivity supported transports. It is designed to be used in very simple devices and is particularly targeted for small, low power devices like sensors, switches, etc. The protocol is modeled after HTTP and provides easy translation between HTTP and CoAP. It is UDP-based (instead of TCP), providing support for multicast.

CoAP is now a standard (RFC7252) as defined by the Internet Engineering Task Force (IETF) CoRE Working Group. Additional RFCs and drafts cover higher order behaviors.

Message format The following table contains a brief overview of the contents of a CoAP packet. Use it as a cheat sheet for the following discussion. For details on the Constrain Resource Protocol, see http://datatracker.ietf.org/doc/rfc7252/?include_text=1.

Field

Value

Short

Hand

Notes

Address

<Device IPD>:<port>

224.0.1.187:5683

 

Device IP address and port multicast group IP address and port

Version

Version 1 (01b)

 

Constant

Type

Confirmable (00b)

Non-confirmable (01b)

Acknowledgement (10b)

Reset (11b)

CON

NON

ACK

RST

 

Token

Length

Xxxxb

 

Length of the token. Valid values are between 0 and 8.

Code

Request (0.xx)

Success (2.xx)

Client error (4.xx)

Server error (5.xx)

 

Common requests and responses:

GET (0.01)

CREATED (2.01)

CHANGED (2.04)

CONTENT (2.05)

Message

ID

0xXXXX

MID

Generated by sender

Allows receiver to de-duplicate requests

Token

 

TOK

Generated by client to match REQ to RESP

Options

 

*

Contains the URI path and query, request and response headers

Payload

 

 

 

Short-hand notation

The following two tables provide examples of request and response packets with explanations on the meaning of the short-hand notation used through the description of the queries and replies.

Note: Acknowledgements can come back separate from content. For the purposes of understanding the semantics of the query and responses, we will assume that all responses come back immediately. In production, requests can be acknowledged and the contents sent back at a later time. In addition, retry logic, de-duplication, congestion control and other features of the CoAP protocol libraries are neglected here.

Request example

In this example, the request is to the CoRE "core" resource in the well-known namespace. It provides a simple example of a multicast request to a compound URI with a query section.

Fields

Sample Values

Explanation

Address

224.0.1.187:5683

Multicast packet address

Header

NON, GET, MID=0x7D40

Non-confirmable

GET (code=0.01)

Message ID = 0x7D40

Token

0x7555

Token Length = 2

Token = 0x7555

URI-Path

oc

"/oc/core?rt=core.sensor&if=core.mi.ll"

URI-Path

core

URI-Query

rt=core.sensor

URI-Query

if=core.mi.ll

Acknowledged response example

In this example, the response is returned.

Note The payload in this example is for demonstration of the packet format and not a valid discovery response.

Fields

Sample Values

Explanation

Address

192.168.0.0:5683

Unicast packet

Header

ACK, CONTENT, MID=0x7D40

Non-confirmable

Content (code=2.05)

Message ID = 0x7D40

Token

0x7555

Token Length = 2

Token = 0x7555

Payload

"Sample Payload"

Raw content