iotivity 0.9.0

[platform/upstream/iotivity.git] / resource / docs / guides / ProgrammersGuide.txt

/*!\r
\r
\r
@page OCGuides Programmer's Guide\r
\r
\r
This document covers the architecture and basic operations of the Iotivity Resource API stack, including sample coverage of protocol, flows, APIs and some use cases. It is intended to provide context for the developers using IoTivity APIs and provide a high level architectural overview.\r
\r
@section Stack_Blocks Stack Blocks\r
\r
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++ which 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).
\r
@image html stack_diagram.png\r
\r
@section Terminology Terminology\r
\r
<b>Device</b>\r
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.\r
\r
<b>Resource</b>\r
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.\r
\r
Resources can be arranged in a hierarchal manner to form a tree of resources. This generic method of structure enables one to model many different topologies of resources.\r
\r
@li Example: A light controller could be a resource.\r
@li Example: A light array could be a set of resources organized in a flat (non-hierarchical) manner.\r
@li Example: A garage door opener could be a resource; it could host two resources - light and lock.\r
\r
A more detailed description of resources and management of resources along with code snippets is provided later in this document.\r
\r
<b>Operations</b>\r
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 on it based on the nature of the resource type. Fundamentally, these are GET and PUT operations. Additionally, attributes can also be declared to be observable to enable remote devices to subscribe to changes.\r
\r
@li 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).\r
\r
@section Functionally Functionally\r
\r
The initial release of IoTivity includes functionally for:\r
 @li @ref Guide_Register_Resource "Resource registration"\r
 @li @ref Guide_Find_Resource "Resource discovery"\r
 @li Device discovery with filtering\r
 @li Property attributes (@ref Guide_GET "get"/ @ref Guide_PUT "set"/ @ref Guide_Observe "observe")\r
 @li Resource tree (resources having sub-resources)\r
 @li Presence notification service defined as a virtual resource (not detailed in this document)\r
\r
@section External_References External References \r
\r
The following references may provide guidance to this document.\r
 @note In some places, the IoTivity design may differ from the CoRE specifications. In these cases, please consider the CoRE specifications as informative but not definitive on the Iotivity design and architecture.\r
\r
 @li The Constrained Application Protocol (CoAP) - https://datatracker.ietf.org/doc/rfc7252\r
 @li Constrained RESTful Environments (CoRE) Link Format - https://datatracker.ietf.org/doc/rfc6690\r
 @li Observing Resources in CoAP - https://datatracker.ietf.org/doc/draft-ietf-core-observe\r
 @li CoRE Interfaces (expired draft) - https://datatracker.ietf.org/doc/draft-ietf-core-interfaces\r
\r
@section Protocol Protocol Message Format(s)\r
\r
The OIC protocol (abbreviated to OC in code) is a REST-like interface similar to HTTP and CoAP. However, it is   a one level up abstraction of the those protocols to allow the addition of 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  describe how specific transports are used to support the OIC protocol and abstractions.\r
\r
@subsection Protocol_CoAP Constrained Application Protocol (CoAP)\r
\r
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.\r
\r
CoAP is now a standard (RFC7252) as defined by the Internet Engineering Task Force (IETF) Constrained RESTful environments (CoRE) Working Group. Additional RFCs and drafts cover higher order behaviors.\r
\r
<b>Message format</b>\r
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.\r
\r
<table cellspacing="0" cellpadding="0" border=1>\r
\r
<tr>\r
<th valign="top" ><p>Field</p></th>\r
<th valign="top" ><p>Value</p></th>\r
<th valign="top" ><p>Short</p>\r
\r
<p>Hand</p></th>\r
<th valign="top" ><p>Notes</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Address</p></th>\r
<th valign="top" ><p>&lt;Device IPD&gt;:&lt;port&gt;</p>\r
\r
<p>224.0.1.187:5683</p></th>\r
<th valign="top" ><p><br />\r
</p></th>\r
<th valign="top" ><p>Device IP address and port multicast group IP address and port</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Version</p></th>\r
<th valign="top" ><p>Version 1 (01b)</p></th>\r
<th valign="top" ><p><br />\r
</p></th>\r
<th valign="top" ><p>Constant</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Type</p></th>\r
<th valign="top" ><p>Confirmable (00b)</p>\r
\r
<p>Non-confirmable (01b)</p>\r
\r
<p>Acknowledgement (10b)</p>\r
\r
<p>Reset (11b)</p></th>\r
<th valign="top" ><p>CON</p>\r
\r
<p>NON</p>\r
\r
<p>ACK</p>\r
\r
<p>RST</p></th>\r
<th valign="top" ><p><br />\r
</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Token</p>\r
\r
<p>Length</p></th>\r
<th valign="top" ><p>Xxxxb</p></th>\r
<th valign="top" ><p><br />\r
</p></th>\r
<th valign="top" ><p>Length of the token. Valid values are between 0 and 8.</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Code</p></th>\r
<th valign="top" ><p>Request (0.xx)</p>\r
\r
<p>Success (2.xx)</p>\r
\r
<p>Client error (4.xx)</p>\r
\r
<p>Server error (5.xx)</p></th>\r
<th valign="top" ><p><br />\r
</p></th>\r
<th valign="top" ><p>Common requests and responses:</p>\r
\r
<p>GET (0.01)</p>\r
\r
<p>CREATED (2.01)</p>\r
\r
<p>CHANGED (2.04)</p>\r
\r
<p>CONTENT (2.05)</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Message</p>\r
\r
<p>ID</p></th>\r
<th valign="top" ><p>0xXXXX</p></th>\r
<th valign="top" ><p>MID</p></th>\r
<th valign="top" ><p>Generated by sender</p>\r
\r
<p>Allows receiver to de-duplicate requests</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Token</p></th>\r
<th valign="top" ><p><br />\r
</p></th>\r
<th valign="top" ><p>TOK</p></th>\r
<th valign="top" ><p>Generated by client to match REQ to RESP</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Options</p></th>\r
<th valign="top" ><p><br />\r
</p></th>\r
<th valign="top" ><p>*</p></th>\r
<th valign="top" ><p>Contains the URI path and query, request and response headers</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Payload</p></th>\r
<th valign="top" ><p><br />\r
</p></th>\r
<th valign="top" ><p><br />\r
</p></th>\r
<th valign="top" ><p><br />\r
</p></th>\r
</tr>\r
\r
</table>\r
\r
\r
<b>Short-hand notation</b>\r
\r
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.\r
\r
@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.\r
\r
<b>Request example</b>\r
\r
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.\r
\r
\r
<table cellspacing="0" cellpadding="0" border=1>\r
\r
<tr>\r
<th valign="top" ><p>Fields</p></th>\r
<th valign="top" ><p>Sample Values</p></th>\r
<th valign="top" ><p>Explanation</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Address</p></th>\r
<th valign="top" ><p>224.0.1.187:5683</p></th>\r
<th valign="top" ><p>Multicast packet address</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Header</p></th>\r
<th valign="top" ><p>NON, GET, MID=0x7D40</p></th>\r
<th valign="top" ><p>Non-confirmable</p>\r
\r
<p>GET (code=0.01)</p>\r
\r
<p>Message ID = 0x7D40</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Token</p></th>\r
<th valign="top" ><p>0x75, 0x55</p></th>\r
<th valign="top" ><p>Token Length = s</p>\r
\r
<p>Token = 0x75, 0x55</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>URI-Path</p></th>\r
<th valign="top" ><p>oc</p></th>\r
<th rowspan="4" valign="top" ><p>"/oc/core?rt=sensor&if=core.ll"</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>URI-Path</p></th>\r
<th valign="top" ><p>core</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>URI-Query</p></th>\r
<th valign="top" ><p>rt=sensor</p></th>\r
<th valign="middle" ><p><br />\r
</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>URI-Query</p></th>\r
<th valign="top" ><p>if=core.ll</p></th>\r
<th valign="middle" ><p><br />\r
</p></th>\r
</tr>\r
\r
</table>\r
\r
<b>Acknowledged response example</b>\r
\r
In this example, the response is returned.\r
@note The payload in this example is for demonstration of the packet format and not a valid discovery response.\r
\r
<table cellspacing="0" cellpadding="0" border=1>\r
\r
<tr>\r
<th valign="top" ><p>Fields</p></th>\r
<th valign="top" ><p>Sample Values</p></th>\r
<th valign="top" ><p>Explanation</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Address</p></th>\r
<th valign="top" ><p>192.168.0.0:5683</p></th>\r
<th valign="top" ><p>Unicast packet</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Header</p></th>\r
<th valign="top" ><p>ACK, CONTENT, MID=0x7D40</p></th>\r
<th valign="top" ><p>Non-confirmable</p>\r
\r
<p>Content (code=2.05)</p>\r
\r
<p>Message ID = 0x7D40</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Token</p></th>\r
<th valign="top" ><p>0x75, 0x55</p></th>\r
<th valign="top" ><p>Token Length = 2</p>\r
\r
<p>Token = 0x75, 0x55</p></th>\r
</tr>\r
\r
<tr>\r
<th valign="top" ><p>Payload</p></th>\r
<th valign="top" ><p>"Sample Payload"</p></th>\r
<th valign="top" ><p>Raw content</p></th>\r
</tr>\r
\r
</table>\r
\r
\r
\r
\r
*/\r