User Tools

Site Tools


resource_observe

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
resource_observe [2016/07/14 14:21]
Ziran Sun
resource_observe [2017/12/18 08:42] (current)
Taehyoung Shim [Sample Application] QueryParamsMqp() "us" -> "use"
Line 1: Line 1:
-Observe happens at Resource ​level and operates in server/​client model. Handling of observation registration is application specific. Server application decides whether resource is observable and when to send the observe notification. Client application fetches and registers as an observer for the resource. Notifications from the server to the client may be confirmable or non-confirmable,​ which can be specified in application via QoS levels. ​+====== ​Resource ​Observation ======
  
-Additionally,​ attributes can be declared observable to enable remote devices to subscribe to changes 
  
 +This operation fetches and registers as an observer for the value of a simple resource. In this example, we fetch the state of the light resource. For more implementation details, see "​Observing Resources in CoAP" listed in the referenced documents. (https://​datatracker.ietf.org/​doc/​draft-ietf-core-observe/?​include_text=1)
  
 +The handling of observation registration is application specific. It should not be assumed that a resource is observable, or a resource can handle any specific number of observers. If the server responds with a success (2.xx) code, the registration is considered successful.
  
 +Notifications from the server to the client may be CON (confirmable) or NON (non-confirmable) message. If the client returns a RST (Reset) message, the observation registration should be dropped immediately. If the client fails to acknowledge a number of confirmable requests, the server should assume that the client has abandoned the observation and drop the registration.
  
 +If the observed resource is removed, the server sends a NOT FOUND status (4.04) to all observers.
  
-=== Flow ===+If an observed resource fails to notify a client before the max-age of a resource value update, the client should attempt to re-register the observation.
  
-Once initialization has been setup server side, server can declare resource property attributes to be observable ​to enable ​remote devices to subscribe to changes.+===== Sequence Diagram ===== 
 +{{:​observe.png?​800|}} 
 + 
 +  - The client application calls OCResource.observe(...) to retrieve a representation from the resources. 
 +  - The call is marshalled to the stack which is either running in-process or out-of-process (daemon). 
 +  - The C API is called to dispatch the request. The call may look like this: <​code>​ OCDoResource(OC_REST_GET | OC_REST_OBSERVE,​ "//​192.168.1.11/​light/​1,​ 0, 0, OC_CONFIRMABLE,​ callback);</​code>​ 
 +  - Where CoAP is used as a transport, the lower stack will send a GET request to the target server. The primary difference between a GET request and an observe request is that the observe request contains an observe option indicating that, in addition to querying this resource, the client wishes to get notifications if/when the resource state changes. 
 +  - On the server side, the OCProcess() function (message pump) receives and parses the request from the socket, then dispatches it to the correct entity handler based on the URI of the request. The request to the entity handler will indicate that the request is both a query and subscription request. The entity handler MAY take note of this, but it is not responsible to tracking the observers. The stack tracks the observers of record. 
 +  - Where the C++ API is used the C++ entity handler parses the payload and marshals it to the client application depending on if the server stack is running in-process or out-of-process (daemon). 
 +  - The C++ SDK passes it up the C++ handler associated with the OCResource. 
 +  - The handler returns the result code and representation to the SDK. 
 +  - The SDK marshals the result code and representation to the C++ entity handler. 
 +  - The entity handler returns the result code and representation to the CoAP protocol. 
 +  - The CoAP protocol transport the results to the client device. 
 +  - The results are returned to the OCDoResource callback. 
 +  - The results are returned to the C++ client application'​s asyncResultCallback. 
 +  - If the entity handler has registered observers, it will periodically be called with the observe flag set so that it may sample or poll underlying hardware to determine if the state has changes. 
 +  - When the application has deemed that the resource state has changed either via polling (entity handler observe) or via external signal, the application should call OCNotifyObservers(). This tells the stack the observers need updating. 
 +  - For each observer of a changed resource, the entity handler is called to generate a representation that is transmitted to the observing clients. 
 +  - Where CoAP is used as a transport, a packet with content is sent to the devices that have observing clients. The packets may be confirmable or non-confirmable based on application needs. 
 +  - The client-side OCProcess function (message pump) receives the message and matches it to the original request based on the CoAP token ID and dispatches the appropriate C API callback. 
 +  - The C API callback passes the final results to the C++ client application'​s asyncResultCallback. 
 +  - When the C++ client no longer desires to receive notifications from the server, it calls observation cancellation method cancelObserve(). 
 +  - The C++ cancellation method calls the OCCancel() function from the C API. 
 +  - OCCancel() finds the observation that is associated with the operation and sends an observe deregistration request to the server. 
 + 
 +===== Call Flow ===== 
 + 
 +Once initialization has been setup on the server side, the server can declare resource property attributes to be observable ​and allow remote devices to subscribe to changes.
  
 {{:​iotivity-flow-observe.png?​nolink|}} {{:​iotivity-flow-observe.png?​nolink|}}
  
 +===== Sample Application =====
  
-=== Sample Application ​===+The simpleserver and simpleclient examples are a good place to learn about resource observation:
  
-There are couple of Samples in resource ​directory provide ​examples ​to use observe APIs.+  * [[https://​gerrit.iotivity.org/​gerrit/​gitweb?​p=iotivity.git;​a=blob;​f=resource/​examples/​simpleserver.cpp;​hb=HEAD|iotivity/​resource/​examples/​simpleserver.cpp]] 
 +  * [[https://​gerrit.iotivity.org/​gerrit/​gitweb?​p=iotivity.git;​a=blob;​f=resource/​examples/​simpleclient.cpp;​hb=HEAD|iotivity/​resource/examples/​simpleclient.cpp]]
  
-  * Sample with basic observe feature for server side: resource/​examples/​simpleserver.cpp 
-  * Sample with basic observe feature for client side: resource/​examples/​simpleclient.cpp 
  
 +Step 1: The server declares the resource attribute as "​OC_OBSERVABLE"​ when creating the resource.
 +  ​
 <​code>​ <​code>​
   uint8_t resourceFlag = OC_DISCOVERABLE | OC_OBSERVABLE;​   uint8_t resourceFlag = OC_DISCOVERABLE | OC_OBSERVABLE;​
Line 35: Line 68:
 </​code>​ </​code>​
  
-=== References : ===+Step 2: The client sets observation on the resource. 
 + 
 +<​code>​ 
 +OCResource::​observe(OBSERVE_TYPE_TO_USE,​ QueryParamsMap(),​ &​observeHandler,​ qos); 
 +</​code>​ 
 + 
 +The client specifies how it wants to observe via OBSERVE_TYPE_TO_USE. QueryParamsMap() use the map which can have the query parameter name and value. observeHandler is the callback that handles the observation result. qos is specifies the communication quality, e.g. specifying the notification to be confirmable or non-confirmable. 
 + 
 +An example of observehandler can look like the following:​ 
 + 
 +<​code>​ 
 +void onObserve(const HeaderOptions /​*headerOptions*/,​ const OCRepresentation&​ rep, 
 +                    const int& eCode, const int& sequenceNumber) 
 +
 +  /* 
 +  * Function body 
 +  */ 
 +
 +</​code>​ 
 +===== Next Steps ===== 
 + 
 +Once you've completed this section, proceed to the next section on [[resource_presence|resource presence]] 
 + 
 +===== Additional Resources =====
  
 Previously published documentation which this (living) wiki page is based on : Previously published documentation which this (living) wiki page is based on :
 +
 [[https://​www.iotivity.org/​documentation/​linux/​programmers-guide/​observing-resource-state-observe]] [[https://​www.iotivity.org/​documentation/​linux/​programmers-guide/​observing-resource-state-observe]]
resource_observe.1468506064.txt.gz · Last modified: 2016/07/14 14:21 by Ziran Sun