docs/guides/ProgrammersGuide.txt

   1 /*!\r
   2 \r
   3 \r
   4 @page OCGuides Programmer's Guide\r
   5 \r
   6 \r
   7 This document captures the architecture and basic operations of the Iotivity Resource API including sample coverage of protocol, flows, APIs and some use cases. It is intended to create context for the developers using IoTvitity API and provide a high level architectural overview of the framework. \r
   8 \r
   9 @section Stack_Blocks Stack Blocks\r
  10 \r
  11 The Resource API stack consists of several thin layers of software. In unconstrained environments like Android, iOS, 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 IP, UDP and the Constrained Application Protocol (CoAP).\r
  12 @image html stack_diagram.png\r
  13 \r
  14 @section Terminology Terminology\r
  15 \r
  16 <b>Device</b>\r
  17 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
  18 \r
  19 <b>Resource</b>\r
  20 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
  21 \r
  22 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
  23 \r
  24 @li Example: A light controller could be a resource.\r
  25 @li Example: A light array could be a set of resources organized in a flat (non-hierarchical manner).\r
  26 @li Example: A garage door opener could be a resource, it could host two resources \96 light and lock.\r
  27 \r
  28 A more detailed description of resources and management of resources along with code snippets is provided later in this document.\r
  29 \r
  30 <b>Operations</b>\r
  31 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 support remote devices to subscribe to changes to it.\r
  32 \r
  33 @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
  34 \r
  35 @section Functionally Functionally\r
  36 \r
  37 The initial release of IoTivity includes functionally for:\r
  38  @li @ref Guide_Register_Resource "Resource registration"\r
  39  @li @ref Guide_Find_Resource "Resource discovery"\r
  40  @li Device discovery with filtering\r
  41  @li Property attributes (@ref Guide_GET "get"/ @ref Guide_PUT "set"/ @ref Guide_Observe "observe")\r
  42  @li Resource tree (resources having sub-resources)\r
  43  @li Presence notification service defined as a virtual resource (not detailed in this document)\r
  44 \r
  45 @section External_References External References \r
  46 \r
  47 The following references may provide guidance to this document.\r
  48  @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
  49 \r
  50  @li The Constrained Application Protocol (CoAP) - https://datatracker.ietf.org/doc/rfc7252\r
  51  @li Constrained RESTful Environments (CoRE) Link Format - https://datatracker.ietf.org/doc/rfc6690\r
  52  @li Observing Resources in CoAP - https://datatracker.ietf.org/doc/draft-ietf-core-observe\r
  53  @li CoRE Interfaces (expired draft) - https://datatracker.ietf.org/doc/draft-ietf-core-interfaces\r
  54 \r
  55 \r
  56 \r
  57 */\r