[Text Book] IoT Class Material - CoAP, OCF, and IoTivity

Title: Internet of Things
Subject of the Book:
IoT Essential Technologies:
CoAP Protocol,
OCF Specification;
& IoT Implementation
• Table of Contents
Chapter 1. IoT Overview
Chapter 2. IoT App Discussion
Chapter 3. REST Overview
Chapter 4. CoAP Overview
Chapter 5. CoAP Message Format
Chapter 6. CoAP Message Transmission
Chapter 7. OCF Overview
Chapter 8. OCF Resource Model
Chapter 9. OCF Interaction Model
Chapter 10. IoT App Implementation
Edited by Prof. Chung

Chapter 1. IoT Overview
<Figure from OCF>
Today, we can often hear about the word: IoT(Internet of Things). What is the definition of
the IoT? Actually, there is no standard definition. Simply, things connected to the internet(or
networked), we call them a IoT device. Networked things are not new concept. In the year
2004, “Ubiquitous” was the keyword. The definition of the ubiquitous were connecting
everything to the network and making access-able by everyone, anytime, and anywhere. The
ubiquitous movement was partially successful. It had been implemented only in a large
hospital or factory.
“Ubiquitous” vs. “IoT”

The concept of the ubiquitous was similar to the today’s IoT. Then, what are the differences
between ubiquitous and IoT. There are three key-differences:
1. Lack of global standard protocol: For the ubiquitous, there was not sufficient effort to
form a global standard for the inter-operation between devices and applications. This
led to the difficulty to create the service that could be enabled by inter-operating.
2. Not stable network connection: For the ubiquitous, at that time, the internet service
was unstable. For the large scale of connecting remote devices, the local network
connection was not sufficient.
3. High cost to make an application: A sensor price in year 2004 was 1.3 US dollar. The
sensor price is getting cheaper and cheaper. In the year 2020, a sensor price is
expected to be down to 0.38 US dollar. High cost of the sensor led the ubiquitous
failed to apply in home appliances.
Today’s IoT
<Figure from Cisco>

The number of IoT devices connected to the internet keeps increasing and in the year 2020, it
will reach to the 50 billions. In Google’s prediction, there will be 212 billions connected
sensors and a half(47%) of the connections will be machine-to-machine connection. Another
prediction by Google in 2020 is in each day an average internet user will generate 1.5 GB
data, a self-driving car will generate 4,400 GB data, a connected plane will generate 40,000
GB data, and a connected factory will generate 1,000,000 GB data.
The key-factors for the fast spreading of IoT are:
1. (Networked)sensor cost is down and widely used.
2. Network is widely connected and become more stable.
3. Big companies(e.g. Samsung, Intel, MS, Qualcomm, etc.) are working together for a
IoT global standard.
<Figure from OCF>
Before, the data is from applications in rich devices. The rich device means it has sufficient
computing and storage power to process heavy services such as Web Services and HTTP

protocol. Each application on the device used a proprietary protocol to communicate with
corresponding services.
<Figure from OCF>
Now, the data is from enormous number of constrained devices. The constrained device does
not have sufficient computing power for the heavy protocol such as HTTP. So there is an
alternative protocol called CoAP(The Constrained Application Protocol) that is a specialized
web transfer protocol for use with constrained nodes and constrained(e.g., low-power, lossy)
networks. The IoT services evolve from isolated to aggregated and to mashup services.
IoT Related Research Area
1. (Networked)Devices collect data from sensors: IoT research such as connectivity,
protocol, auto-configuration, and resource modeling
2. Collected data will be accumulated enormously in cloud: Big-data research such as
data processing, and data modeling

3. Analyzing the data for new insight: A.I. research such as machine learning, and data
analysis.
The future of IoT world needs trinity of above research. IoT will generate big-data; and from
the big-data, through the A.I. new insight will be discovered; and the big-data and A.I.
research needs to give feedback to IoT research.

Chapter 2. IoT App Discussion
There are many IoT applications in the world. The definition of IoT application can be the
application works with the things that are connected to the internet(or networked). There
seems to be vertical domains such as smart home, wearables, smart city, smart grid, industrial
internet, connected car, connected health, smart retail, smart supply chain, and smart farming.
However, IoT applications are becoming more and more inter-discipline and hard to
explicitly distinguish which vertical that the application lies.
To analyze the IoT application, or in general, it is good to ask below four key questions:
1. Who is the target?
It is important to make clear that who will be the beneficiary of the application. This
can be a farmer (in broad sense), a parking space owner, a specific system (not just a
human), or etc. Defining the target helps to identify the area of the contribution.

2. What do they need?
Once we have identified the target, then we need to find their needs. It is not a good
idea to apply the technology when there is no need of it. Defining the need helps to
identify the actual contribution.
3. Where does it apply?
Once we have found the need, it needs to be break down into more details in
structural and operational. We need to find the gap where the technology can be
applied, and make the existing process or structure more effective, efficient, and user-
satisfactory.
4. How does it work?
After we decide where to apply the technology, it needs to be technically explained in
as detail as possible in the level, which others can follow the steps that have been
taken to make it more usable.
Example of IoT Application Analysis Assignment:

Chapter 3. REST Overview
IoT connects things using the Internet, and the most common architecture to communicate
between things on the Internet is RESTful architecture. REST stands for REpresentational
State Transfer. The REST is not an architectural specification. It is design guideline.
There are two key-words in REST, that are Resource & URI.
– Resource
• Something that can be stored in a server
• Something that can be represented as a stream of bits
– Data in DB (String, Integer, Array, blob, etc.)
– A document file (PDF, ppt, doc, etc.)
– Plain text result (String, Number, etc.)
– URI = Uniform Resource Identifier
• An address of a resource
• At least one URI to a resource
• If a resource does not have any URI
– It is not a resource
• URI is structured and (good to be) descriptive
– https://tools.ietf.org/html/rfc3986
– E.g.

URI Format: RFC3986
For the RESTful architecture HTTP URL is commonly used. URL stands for Uniform
Resource Locator, and is a aubset of URI. It follows the grammer of the URI. The details of
the URL can be found at https://tools.ietf.org/html/rfc1808. It is used to identify a resource by
providing a means of locating the resource by describing its primary access mechanism.
For example: HTTP URL

• URL is used to locate a network resource
• Access mechanism = HTTP protocol
REST is best used to manage systems by decoupling the information that is produced and
consumed from the technologies that produce and consume it.
• RESTful Architecture
– Exposing resources using URI (mostly URL)
• Any information that can be addressed can be a resource.
– Statelessness Request/Response
• Every HTTP request happens in complete isolation.
• There is no specific ordering of requests.
– Context-free interactions
• Each interaction contains all of the information necessary to
understand the request.
– Representational state of a resource
• Corresponding resource information will be responded in a certain
representation.
• E.g. HTML, JSON, XML, PDF, PPT, DOC, etc.
• There needs pre-negotiation for a representation.
• E.g.
• (Not only) HTTP request “Accept” header
• example.com/xml/20170619
• example.com/news/20170619.hindi
– Uniform Operation Interface

• HTTP Provides 4 basic methods called CRUD
• Create
• POST: Create a new resource
• Read
• GET: Retrieve representation of resource
• Update
• PUT: Update (or create) existing resource
• Delete
• DELETE: Delete an existing resource
The following will explain the details of each method: POST, GET, PUT, and DELETE.
• POST
– On successful creation, return HTTP status 201 (Created) returning a Location
header with a link to the newly-created resource with the 201 HTTP status.
• Location: /customers/{new id}
– POST is not idempotent. Making two identical POST requests will most-likely
result in two resources containing the same information.
– E.g.
• POST http://www.example.com/customer
• POST http://www.example.com/customer/1234/order
• GET
– On successful read, return HTTP status 200 (OK), or 404 (Not Found) if ID
not found or invalid.
– This method is considered safe. That is, they can be called without risk of data
modification.

• Calling it once has the same effect as calling it 10 times, or none at all.
– GET is idempotent, which means that making multiple identical requests ends
up having the same result every time.
• GET should not modify any resources on the server.
– E.g.
• GET http://www.example.com/customer/1234
• GET http://www.example.com/customer/1234/orders
• PUT
– On successful update, return HTTP status 200 (OK), 204 (No Content) if not
returning any content in the body, or 404 (Not Found) if ID not found or
invalid, or 405 (Method Not Allowed).
– This method is often utilized for update capability. However, PUT can also be
used to create a resource in the case where the resource ID is chosen by the
client instead of by the server.
– PUT is not a safe operation, because it modifies (or creates) state on the server,
but it is idempotent. In other words, if you create or update a resource using
PUT and then make that same call again, the resource is still there and still has
the same state as it did with the first call.
– E.g.
• PUT http://www.example.com/customer/1234
• PUT http://www.example.com/customer/1234/order/5678
• DELETE
– On successful deletion, return HTTP status 200 (OK) along with a response
body, possibly the representation of the deleted item, or return HTTP status

204 (No Content) with no response body, or 404 (Not Found) if ID not found
or invalid.
– HTTP-spec-wise, DELETE operations are idempotent. However, the response
can be different 200 response for the first delete and 404 responses after the
deletion.
– E.g.
• DELETE http://www.example.com/customer/1234
• DELETE http://www.example.com/customer/1234/order
• POST vs. PUT (for creation)
– PUT:
• Client is in charge of deciding which URI resource should have
• Send new representation overwriting current one
– POST:
• Server is in charge of deciding which URI resource should have
• Create new resource
Each method will get a HTTP status code as a response. The details are explained in
https://tools.ietf.org/html/rfc2616.
The format of a HTTP response message:

• RESTful architecture
– simple, intuitive, scalable (simply more servers), and adapting HTTP concept
(generic, stateless, protocol)
• Following REST design 100% is not practical.
– In practice
• There needs unRESTful at times such as Login/Logout
• Every request have Authentication/Authorization data
– Authentication
» deals with user account validation
– Authorization
» deals with user access validation to certain features
• The server may not support all CRUD basic operations

Chapter 4. CoAP Overview
HTTP vs. CoAP
Before we learn about CoAP, it is useful to know about HTTP protocol. HTTP has a request
and response trasmission mechnism. Because it works on TCP protocol, the connection is
reliable and HTTP does not need to have retransmission mechanism.
The URL resolution of HTTP protocol:

RESTful GET request example:
What are the requirements for IoT devices?

As shown in the figure above, there are several requirements for CoAP to be used for the IoT
devices instead of HTTP protocol. The CoAP protocol is a standard track
(https://tools.ietf.org/html/rfc7252) in IETF under CoRE(Constrained RESTful
Environments) Work Group since December 2009 and finalized June 2014.
• Internet Engineering Task Force (IETF)

– The mission Statement
• The IETF is to make the Internet work better by producing high quality,
relevant technical documents that influence the way people design, use,
and manage the Internet.
– E.g. TCP/IP, HTTP, CoAP, etc.
• CoAP is
– RESTful protocol
– For constrained devices and networks
– Easy to proxy to/from HTTP
• CoAP is not
– A general replacement for HTTP
– HTTP compression
– Restricted to isolated/constrained networks
• Features
– Asynchronous Transaction Model
– UDP with reliability and multicast support
– GET, POST, PUT, DELETE methods
– URI support
– Small size header
– DTLS based security
– Subset of MIME types
– Subset of HTTP response codes
– Etc.

Chapter 5. CoAP Message Format
Version (Ver): 2-bit unsigned integer. Indicates the CoAP version number.
Implementations of this specification MUST set this field to 1 (01 binary). Other
values are reserved for future versions. Messages with unknown version numbers
MUST be silently ignored.
Type (T): 2-bit unsigned integer. Indicates if this message is of type Confirmable (0),
Non-confirmable (1), Acknowledgement (2), or Reset (3).
Token Length (TKL): 4-bit unsigned integer. Indicates the length of the variable-
length Token field (0-8 bytes). Lengths 9-15 are reserved, MUST NOT be sent, and
MUST be processed as a message format error.
Code: 8-bit unsigned integer, split into a 3-bit class (most significant bits) and a 5-bit
detail (least significant bits), documented as "c.dd" where "c" is a digit from 0 to 7 for
the 3-bit subfield and "dd" are two digits from 00 to 31 for the 5-bit subfield. The
class can indicate a request (0), a success response (2), a client error response (4), or a
server error response (5). As a special case, Code 0.00 indicates an Empty message. In
case of a request, the Code field indicates the Request Method; in case of a response,
a Response Code.

Message ID: 16-bit unsigned integer. Used to detect message duplication and to
match messages of type Acknowledgement/Reset to messages of type
Confirmable/Non- confirmable.
Token: The Token value may be 0 to 8 bytes as given by the Token Length field. The
Token value is used to correlate requests and responses. Every request carries a client-
generated token that the server MUST echo (without modification) in any resulting
response.
Options: An Option can be followed by the end of the message, by another Option, or
by the Payload Marker and the payload. CoAP defines a number of options that can
be included in a message.
Payload Marker (11111111): If payload of non-zero length presents, one-byte Payload
Marker (0xFF) indicates the end of options and the start of the payload. The payload
data extends from after the marker to the end of the UDP datagram, i.e., the Payload
Length is calculated from the datagram size. The absence of the Payload Marker
denotes a zero-length payload.
CoAP Option Format

- Option Delta: Difference between this option type and the previous
- Length: Length of the option value
- Value: The value of Length bytes immediately follows Length
– Each option instance in a message specifies the Option Number of the defined
CoAP option, the length of the Option Value, and the Option Value itself.
– Instead of specifying the Option Number directly, the instances MUST appear
in order of their Option Numbers and a delta encoding is used between them:
the Option Number for each instance is calculated as the sum of its delta and
the Option Number of the preceding instance in the message.
• For the first instance in a message, a preceding option instance with
Option Number zero is assumed.
• Multiple instances of the same option can be included by using a delta
of zero.

Option Length: 4-bit unsigned integer. A value between 0 and 12 indicates the length of the
Option Value, in bytes. Three values are reserved for special constructs:
- 13: An 8-bit unsigned integer precedes the Option Value and indicates the Option
Length minus 13.
- 14: A 16-bit unsigned integer in network byte order precedes the Option Value and
indicates the Option Length minus 269.
- 15: Reserved for future use. If the field is set to this value, it MUST be processed as
a message format error.
CoAP Options

Critical / Elective
– Options fall into one of two classes:
• "critical" or "elective"
– The difference between these is how an unrecognized option will be handled
in an endpoint.
• Upon reception, unrecognized options of class "elective" MUST be
silently ignored.
• Unrecognized options of class "critical" that occur in a Confirmable
request MUST cause the return of a 4.02 (Bad Option) response.
• Unrecognized options of class "critical" that occur in a Confirmable
response, or piggybacked in an Acknowledgement, MUST cause the
response to be rejected (silently ignored).
• Unrecognized options of class "critical" that occur in a Non-
confirmable message MUST cause the message to be rejected (silently
ignored).

– Odd numbers indicate a critical option, while even numbers indicate an
elective option.
– Note: whether critical or elective, an option is never "mandatory" (it is always
optional).
Proxy Unsafe or Safe-to-Forward and NoCacheKey
– Options are also classified based on how a proxy is to deal with the option if it
does not recognize it.
• Unsafe: An option that would need to be understood by a proxy
receiving the message in order to safely forward the message
• Safe-to-Forward: An option that is intended to be safe for forwarding
by a proxy that does not understand it.
– NoCacheKey indicates the option is not intented to be cached.
Repeatable
– An option that is repeatable MAY be included one or more times in a message.
• An option that is not repeatable MUST NOT be included more than
once in a message.
Uri-Host, Uri-Port, Uri-Path, and Uri-Query
– They are used in a request to specify the target resource in CoAP server.
• The Uri-Host Option specifies the Internet host of the resource being
requested. E.g. “224.0.1.187”
• The Uri-Port Option specifies the transport-layer port number of the
resource. E.g. “5683” (if it is empty or not given, then the default port
5683 is assumed.)
• Each Uri-Path Option specifies one segment of the absolute path to the
resource. E.g. “oc”, “core”

• Each Uri-Query Option specifies one argument parameterizing the
resource. E.g. “rt=alpha.light”
– E.g. coap://224.0.1.187/oc/core?rt=alpha.light
Proxy-Uri and Proxy-Scheme
– The Proxy-Uri Option MUST take precedence over any of the Uri-Host, Uri-
Port, Uri-Path or Uri-Query options.
• An endpoint receiving a request with a Proxy-Uri Option that is unable
or unwilling to act as a forward-proxy for the request MUST cause the
return of a 5.05 (Proxying Not Supported) response.
– E.g. CoAP-HTTP Proxying: Enables CoAP clients to access resources on
HTTP servers through an intermediary. This is initiated by including the
Proxy-Uri or Proxy-Scheme Option with an "http" or "https" URI in a CoAP
request to a CoAP-HTTP proxy.
Content-Format
– The Content-Format Option indicates the representation format of the message
payload.
• The representation format is given as a numeric Content-Format
identifier that is defined in the "CoAP Content - Formats" registry.
More information: https://www.iana.org/assignments/core-
parameters/core-parameters.xhtml
– In the absence of the option, no default value is assumed, i.e., the format will
need to be inferred by the application (the representation format may be pre-
negotiated).
Accept

– The CoAP Accept option can be used to indicate which Content-Format is
acceptable to the client.
• If no Accept option is given, the client does not express a preference
(thus no default value is assumed).
– If the preferred Content- Format cannot be returned, then a 4.06 "Not
Acceptable" MUST be sent as a response, unless another error code takes
precedence for this response.
Max-Age
– The Max-Age Option indicates the maximum time a response may be cached
before it is considered not fresh.
• The option value is an integer number of seconds.
• A default value of 60 seconds is assumed in the absence of the option
in a response.
ETag
– An entity-tag is intended for use as a resource identifier for differentiating
between representations of the same resource that vary over time.
• It is generated by the server providing the resource, which may
generate it in any number of ways including a version, checksum, hash,
or time. (Pre-negotiation may be required)
If-Match / If-None-Match
– The If-Match Option MAY be used to make a request conditional on the value
of an ETag for the target resource.
• If-Match is generally useful for resource update requests, such as PUT
requests, as a means for protecting against accidental overwrites when
multiple clients are acting in parallel on the same resource.

– The If-Match Option can occur multiple times. If any of the options match,
then the condition is fulfilled.
– If there is one or more If-Match Options, but none of the options match, then
the condition is not fulfilled.
– In case of If-None-Match, if the target resource exists, then the condition is
not fulfilled.
Location-Path / Location-Query
– If a resource has been created on the server by the POST request, the response
returned by the server SHOULD have a 2.01 (Created) Response Code and
SHOULD include the URI of the new resource in a sequence of one or more
Location-Path and/or Location-Query Options.
• Otherwise (no Location-*), the resource was created at the request URI.
Size1
– It is used to indicate the maximum size of request entity that the server is able
and willing to handle.
• The Response Code 4.13 is "Request Entity Too Large".
• The response SHOULD include a Size1 Option to indicate the
maximum size of request entity the server is able and willing to handle.
– The other main use is with block-wise transfers.
• https://tools.ietf.org/html/rfc7959
– If nothing is known about the size of the headers, good upper bounds are 1152
bytes for the message size and 1024 bytes for the payload size.
CoAP Message Example

Chapter 6. CoAP Message Transmission
The followings are the terminology to understand the message transmission.
• Endpoint
– A CoAP endpoint is the source or destination of a CoAP message.
• Normally, the endpoint is solely identified by an IP address and a UDP
port number.
• Sender
– The originating endpoint of a message.
• Source Endpoint
• Recipient
– The destination endpoint of a message.
• Destination Endpoint
• Client
– The originating endpoint of a request
• The destination endpoint of a response
• Server
– The destination endpoint of a request
• The originating endpoint of a response
• Origin Server
– The server on which a given resource resides or is to be created.
• Intermediary
– A CoAP endpoint that acts both as a server and as a client towards an origin
server.
• A common form of an intermediary is a proxy.

• Proxy
– An intermediary that mainly is concerned with forwarding requests and
relaying back responses, possibly performing caching, namespace translation,
or protocol translation in the process.
• Empty message
– A message with a Code of 0.00; neither a request nor a response. An Empty
message only contains the 4-byte header.
• A ping operation is implemented by sending an empty message to
which the peer responds with an empty reset (RST) message.
• Reset Message
– A Reset message indicates that a specific message (Confirmable or Non-
confirmable) was received, but some context is missing to properly process it.
• This condition is usually caused when the receiving node has rebooted
and has forgotten some state that would be required to interpret the
message.
• Confirmable Message
– Some messages require an acknowledgement. These messages are called
"Confirmable". When no packets are lost, each Confirmable message elicits
exactly one return message of type Acknowledgement or type Reset.
• Non-confirmable Message
– Some other messages do not require an acknowledgement. This is particularly
true for messages that are repeated regularly for application requirements,
such as repeated readings from a sensor.
• Acknowledgement Message

– An Acknowledgement message acknowledges that a specific Confirmable
message arrived. By itself, an Acknowledgement message does not indicate
success or failure of any request encapsulated in the Confirmable message, but
the Acknowledgement message may also carry a Piggybacked Response.
• Piggybacked Response
– A piggybacked Response is included right in a CoAP Acknowledgement
(ACK) message that is sent to acknowledge receipt of the Request for this
Response.
• Separate Response
– When a Confirmable message carrying a request is acknowledged with an
Empty message (e.g., because the server doesn't have the answer right away),
a Separate Response is sent.
• Transmission Model Overview
– CoAP over UDP
• Possible to extend to TCP, SMS, etc.
– Simple Message Exchanging
• Between endpoints
– Confirmable or Non-Confirmable Messages

• Using Acknowledgement
– RESTful
• REST Request/Response (using piggybacked)
• CRUD operations and Response Code
• Basic Transmission Model
– CoAP messages are exchanged asynchronously between CoAP endpoints.
– As CoAP is bound to unreliable transport (UDP), CoAP messages may arrive
out of order, appear duplicated, or go missing without notice.
• CoAP implements a lightweight reliability mechanism:
• Simple stop-and-wait retransmission reliability with
exponential back-off for Confirmable messages.
• Duplicate detection for both Confirmable and Non-confirmable
messages.
• Messages Transmitted Reliably
– The reliable transmission of a message is initiated by marking the message as
Confirmable in the CoAP header.
– A recipient MUST either (a) acknowledge a Confirmable message with an
Acknowledgement message or (b) reject the message (sending a Reset
message) if the recipient lacks context to process the message properly.
• The Acknowledgement message MUST echo the Message ID of the
Confirmable message and MUST be Empty or carry a response.
• The Reset message MUST echo the Message ID of the Confirmable
message and MUST be Empty.

– The sender retransmits the Confirmable message at exponentially increasing
intervals, until it receives an acknowledgement (or Reset message) or runs out
of attempts.
• a CoAP endpoint MUST keep track of for each Confirmable message
it sends while waiting for an acknowledgement (or reset): a timeout
and a retransmission counter.
• ACK_TIMEOUT = 2 seconds
• ACK_RANDOM_FACTOR = 1.5
• MAX_RETRANSMIT = 4
– The initial timeout is set to a random duration between ACK_TIMEOUT and
(ACK_TIMEOUT * ACK_RANDOM_FACTOR).
– The initial retransmission counter is set to 0, and when the timeout is triggered
and the retransmission counter is less than MAX_RETRANSMIT, the
message is retransmitted.
• Messages Transmitted without Reliability
– A message can be transmitted less reliably by marking the message as Non-
confirmable.
• A Non-confirmable message MUST NOT be acknowledged by the
recipient, and there can be Non-confirmable response message.
– Rejecting a Non-confirmable message MAY involve sending a matching
Reset message.
– There is no way for the sender to detect if a Non- confirmable message was
received or not.

• A sender MAY choose to transmit multiple copies of a Non-
confirmable message within MAX_TRANSMIT_SPAN (default 45
seconds).
• Message Correlation
– The Message ID is a 16-bit unsigned integer that is generated by the sender of
a Confirmable or Non-confirmable message and included in the CoAP header.
• The Message ID MUST be echoed in the Acknowledgement or Reset
message by the recipient.
– The recipient SHOULD silently ignore any duplicated messages.
– The same Message ID MUST NOT be reused (in communicating with the
same endpoint) within the EXCHANGE_LIFETIME (default 247 seconds).
– For an Acknowledgement or Reset message to match a Confirmable or Non-
confirmable message:
• The Message ID and source endpoint of the Acknowledgement or
Reset message MUST match the Message ID and destination endpoint
of the Confirmable or Non-confirmable message.
– The Token is used to match a response with a request.
• Every request carries a client-generated token that the server MUST
echo (without modification) in any resulting response.

• Congestion Control
– Basic congestion control for CoAP is provided by the exponential back-off
retransmission mechanism.
– In order not to cause congestion, clients (including proxies) MUST strictly
limit the number of simultaneous outstanding interactions (not responded
transaction) that they maintain to a given server to 1 by default.
• Request/Response Semantics
– CoAP operates under a similar request/response model as HTTP
• A CoAP endpoint in the role of a "client" sends one or more CoAP
requests to a "server", which services the requests by sending CoAP
responses.
• However, unlike HTTP, requests and responses are not sent over a
previously established connection but are exchanged asynchronously
over CoAP messages. And the request and response are not one-to-one
mapping (e.g. Observe)
Examples:

Example: The client sends a Non-confirmable GET request to a multicast address: all nodes
in link-local scope.

Chapter 7. OCF Overview
There has been changes in IoT world such as lower cost computer power and lower cost
communications. Now it is realistic to put sufficient computing power and communication in
small and fixed function devices for IoT. Devices you were going to buy will now be smart
and connected. These leads to explosion in the amount of data and in the number of control
points.
Total economic value to be generated by the IoT in 2025 is $11.1 trillion by McKinsey IoT
report 2015, and $5.2 trillion (47% of the value) will be unlocked by interoperability. Then,
how to enable interoperability?
• Requirements:
– Common discovery and addressing scheme
– Common data modelling scheme
– Common interaction model
– End-to-end security, data protection and data privacy
– Need to work across different OS’s, platforms, manufacturers, service
providers and vertical markets
– Need to be transport agnostic and work across many physical layers
– Need to scale from constrained devices to smart devices to the Cloud
– Implementations must be certifiable
There are standards in vertical domains.

<Figure from OCF>
There are standards’ fragmented landscape.

There are many standards in IoT world. Then, why OCF(Open Connectivity Foundation)?
Simply, OCF is the biggest industrial connectivity standard organization for IoT. The
followins are more detail reasons.
– OCF is among the largest industry-led efforts to develop a secure
interoperability specification across the IoT ecosystem
– OCF has many liaison relationships with other consortia and standards bodies
active in the IoT space
– OCF represents industry coalescing around previously separate industry
efforts
– OCF is creating an open specification for secure, interoperable IoT, will
certify compliant devices, and intends to serve as a trusted brand for
consumers
– OCF has endorsed security as a key element of its work, and has a dedicated
security work group

– Specifications developed by OCF, as well as the open source reference
implementation (IoTivity), are publicly available
– OCF is an open consensus based organization, anyone can obtain basic
membership at no cost
– Decisions in OCF are made by consensus, with the participation of board and
working group members
– Work in OCF is ongoing, with new features and requirements being specified
– OCF welcomes the input of all stakeholders, including those with policy
interests to ensure the public interest in IoT is addressed
OCF Overview
<Figure from OCF>
Open source reference implementaion for OCF

<Figure from OCF>
• High Level Goals
– Make it easy for developers to deal with the complexity of IoT
communications.
– Provide a common data model that developers can use to interface with all
IoT devices and their underlying data.
– Establish an architectural foundation that can achieve the necessary scalability.
– Focus the architecture around interoperability.
– Supports the needs of multiple vertical market.
• Since many use cases span multiple vertical markets.
– Provide a path towards future consolidation of standards.
• Key Concepts
– Free IPR License (Code: Apache 2.0 & Spec: RAND-Z)
• License covers both code, standards and related IPR
• License applies to members and affiliates of members

– Support for IoT optimized protocols (e.g. CoAP)
• Specific considerations for constrained devices
• Fully compliant towards RESTful architecture
• Built-in discovery and subscription mechanisms
– Standard (spec) and Open Source to allow flexibility creating solutions
• Able to address all types of devices, form-factors, companies and
markets with the widest possibility of options
• Open Source is just one implementation to solve a problem
– Certification and Logo program
• Certification Program
– Available to members only
– Required to get RAND-Z IPR protection
– Current - Logo Program
• Limited, manual compliance testing
– Plugfest: inter-operation testing
• IoTivity only
– Future – Full Certification
• Full OCF compliance tests
– Utilizing CTT (Compliance Test Tool)
• Independent Cert Lab-based interop testing
– Against golden devices running IoTivity
• Ability to certify alternative implementations
• OCF conceptual framework

<Figure from OCF>
• Core Framework Specification v1.1
① Discovery: Common method for device discovery (IETF CoRE – Constrained Restful
Environments)

② Messaging: Constrained device support as default (IETF CoAP) as well as protocol
translation via intermediaries
③ Common Resource Model: Real world entities defined as data models (resources)
④ CRUDN: Simple Request/Response mechanism with Create, Retrieve, Update,
Delete and Notify commands
⑤ Device Management: Network connection settings and remote
monitoring/reset/reboot functions
⑥ ID & Addressing: OCF IDs and addressing for OCF entities (Devices, Clients,
Servers, Resources)
⑦ Security: Basic security for network, access control based on resources, key
management etc.

Chapter 8. OCF Resource Model
Any physical or software artifact on a device that needs to be manipulated or made visible
across the network can be a resource model.
Resource model can have common properties and resource specific properties.
14
Resource URI :/a/light1
rt: oic.ex.light
if: oic.if.rw
prop: discoverable,
observable
n: myHallWayLight
State: 0 (OFF)
Dim Level: 0
Resource URI :/a/fan1
rt: oic.ex.fan
if: oic.if.rw
prop: discoverable
n: myKitchenFan
State: 1 (ON)
Speed: 10
The resource can have a link property that composed of more than one resources.

• Resource Model Specification
– OIC Specification v1.1
• OIC SmartHome Device Specification v1.1.0
• OIC Resource Type Specification v1.1.0
– oneIoTa
• Collection of RAML/JSON Schema for resource types
– This does not fully describe the specifications.
» Not yet about device types
• https://oneiota.org
• Sample of Resource Types

• Sample of OIC Resource Type Specification v1.1.0

• Sample of Smart Home Device Types
• Sample of OIC SmartHome Device Specification v1.1.0

• Sample of oneIoTa
• Uniform Resource Identifier (URI)
– Relative Reference
• Form: /<path>?<query>

• Example: /oic/res?rt=oic.r.switch.binary
– Query: OIC Separator is ‘;’, not ‘&’
• Example: Resource

• OCF Security Model (OIC 1.1)
– Transport Layer: OIC supports end-to-end device protection
• DTLS
– DTLS is a derivation of SSL protocol but under UDP protocol.
– Resource Layer: ACL(Access Control List)s allow intended interactions while
preventing unintended interactions

• ACL Permissions
– Resource, interface, wild-card
– CRUDN
– Service Layer: Secure device ownership helps prevent attacks when devices
are added to the network
• Device Account in Cloud

Chapter 9. OCF Interaction Model
• Common Interaction Model (Transport Agnostic)
– CREATE
• Create a new Resource on the Server
– RETRIEVE
• Get the current State or representation of a Resource from a Server
– UPDATE
• Request a partial or complete update to the information stored in a
Resource
– DELETE
• Remove a Resource from the Server
– NOTIFY
• Request asynchronous notification of state changes in a Resource
• Special-cased to support OBSERVE for publish/subscribe support
• Resource Access Architecture

• Example Request-Response Flow
• Example Request-Response Flow: Resource Discovery
• Example Request-Response Flow: READ Operation

• Example Request-Response Flow: UPDATE Operation
• Example Request-Response Flow: OBSERVE Operation

Chapter 10. IoT App Implementation
IoTivity is the open source reference implementation of OCF standards. This chapter explains
how to download IoTivity, compile on Ubuntu system, and execute a IoTivity sample.
Overview of the IoTivity:
• IoTivity: Messaging Protocol
– Based on CoAP
• RFC 7252
• IoTivity: OCF payload
– Encoded using CBOR
• RFC 7049
• IoTivity: Connectivity Abstraction
– Multiple connectivity types
• Dual-stack IPv4 / IPv6
• Bluetooth Low Energy using GATT
• Bluetooth EDR using RFCOMM

• Downloads for IoTivity:
1. Ubuntu 14.04.1 LTS (Trusty Tahr) 32-bit PC (i386) desktop image from http://old-
releases.ubuntu.com/releases/trusty/
2. IoTivity 1.2.0 Source Download (.tar.gz) from
https://www.iotivity.org/downloads/iotivity-1.2.0
a. Run Ubuntu$ git clone -b 1.2-rel --depth 1 https://github.com/iotivity/iotivity
• Compiling for IoTivity:
1. Installing Build Environment: Run Ubuntu$ sudo apt-get install build-essential git
scons libtool autoconf valgrind doxygen wget unzip
2. Installing External Libraries: Run Ubuntu$ sudo apt-get install libboost-dev libboost-
program-options-dev libboost-thread-dev uuid-dev libexpat1-dev libglib2.0-dev
libsqlite3-dev libcurl4-gnutls-dev
3. Go to the IoTivity folder: Run Ubuntu$ cd iotivity
a. If you have downloaded iotivity-1.2.0.tar.gz, then Run Ubuntu$ tar -zxvf
iotivity-1.2.0.tar.gz
4. Run Ubuntu$ scons
a. This will show you an error.
5. Run Ubuntu$ git clone https://github.com/01org/tinycbor.git extlibs/tinycbor/tinycbor
-b v0.4
6. Run Ubuntu$ scons
a. The compile will take about half an hours (It varies according to the system)

• Executing IoTivity Samples:
1. Sample source codes: Run Ubuntu$ cd
resource/csdk/stack/samples/linux/SimpleClientServer
2. Sample execution files: Run Ubuntu$ cd
out/linux/x86/release/resource/csdk/stack/samples/linux/SimpleClientServer
3. Run Ubuntu$ ./ocserver -o 0
a. Creating Light Resource
4. Run Ubuntu$ ./occlient -u 0 -t 1 -c 0
a. Discovering Resources

a. Discovering Resources and Send GET request
a. Discovering Resources and Send POST request

a. Discovering Resources and Send OBSERVE request

Note: Sample execution files will be updated after scons compilation. Try to edit sample
source codes and Run Ubuntu$ scons

APPENDIX. IoTivity Programmer’s Guide
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).
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:
• Resource registration
• Resource discovery
• Device discovery with filtering
• Property attributes (get/ set/ observe)
• Resource tree (resources with sub-resources)
• Presence notification service defined as a virtual resource (not detailed in this
document)
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.
• The Constrained Application Protocol (CoAP) -
https://datatracker.ietf.org/doc/rfc7252
• Constrained RESTful Environments (CoRE) Link Format -
https://datatracker.ietf.org/doc/rfc6690
• Observing Resources in CoAP - https://datatracker.ietf.org/doc/draft-ietf-core-
observe
• CoRE Interfaces (expired draft) - https://datatracker.ietf.org/doc/draft-ietf-core-
interfaces
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 0xXXXX MID Generated by sender

Field Value
Short
Hand
Notes
ID 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
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.
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
Registering a Resource
Registering a resource requires two basic items:
• A handler to process requests from the stack, and
• A URI path to register the resource. The URI path should be rooted (in other
words, start with a slash). The stack will construct the fully qualified URI by
adding the URI authority to the provided URI path. For example, given a
service running on port 5683 in a device at IP address 192.168.1.1, if the
application registers a resource with a URI path "/light/1", the resulting fully
qualified URI is "oc://192.168.1.1:5683/light/1", which uniquely identifies the
resource's location (IP address port and path).
Note: Only one resource can be registered at a given URI.
Step 1
Assuming the application has created a valid OCPlatform object, the application
registers a new resource with the stack by calling OCPlatform::registerResource(...).
In this example, the call would take the form:
platform.registerResource(&handle, "/light/1", "light",
"oc.mi.def", handler, OC_DISCOVERABLE);
The handle is a reference to the resource that is used on other APIs. The URI path
("/light/1") is where the resource can be located on this server. The URI path is
unique; this call will fail if the application attempts to register another resource using
an existing URI. The resource type ("light") and interface ("oc.mi.def") are properties
of the resource used in the discovery process. The handler is a function called from
the stack to process requests. The flags control how the stack should handle the
resource. The OC_DISCOVERABLE flag indicates that the resource should be
reported if a client performs a resource discovery on this server.
Step 2:
The OCPlatform::registerResource(...) method delegates the call to the appropriate
instance of the stack (in-process or out-of-process via IPC).

Step 3:
The internal registerResource(...) method constructs a C++ entity handler and
registers it with the C SDK using OCCreateResource(...).
OCCreateResource(&handle, "light", "oc.mi.def", "/light/1",
handler, OC_DISCOVERABLE);
Many of these parameters are passed through to the C SDK directly. However, the
entity handler is a proxy function for the handler passed from
OCPlatform::registerResource(...).
Register Resource in C++ [Server]
OCResourceHandle resourceHandle;
std::string resourceURI = "/light/1";
std::string resourceTypeName = "alpha.light";
std::string resourceInterface = DEFAULT_INTERFACE;
uint8_t resourceProperty = OC_DISCOVERABLE | OC_OBSERVABLE;
OCStackResult result =
platform.registerResource(resourceHandle, resourceURI,
resourceTypeName, resourceInterface, &entityHandler,
resourceProperty);
if (OC_STACK_OK == result)
{
//Successfull
}
Finding a Resource
This operation returns all resources of given type on the network service. This
operation is sent via multicast to all services. However, the filter limits the responders
to just those that support the resource type in the query. Currently only exact
matches are supported.
Notes:
• Assuming that the client has a properly initialized OCPlatform object, a C++
SDK client can discover resources by calling OCPlatform::findResources(...).
platform.findResources("",
"coap://224.0.1.187/oc/core?rt=alpha.light",
findHandler)

The first parameter is the URI authority (target host), which, when empty, indicates
that this is for all nodes. The second parameter ("/oc/core?rt=alpha.light") is the URI
path and URI query. The URI path ("/oc/core") indicates the resource and the URI
query ("rt=alpha.light") is the filter.
• The SDK call findResources(...) internally delegates the call directly to the in-
process or to the out-of process stack via IPC based on the stack
configuration.
• Within the stack, findResource(...) calls the C API function
OCDoResource(...). In this example, the call is OCDoResource(&handle,
OC_REST_GET, "/oc/core?rt=alpha.light", 0, 0, OC_NON_CONFIRMABLE,
...)
• OCDoResource determines which transport is needed to dispatch the request
and delegates the call. In the case of CoAP, the following calls are made:
o Calls OCDoCoapResource(OC_REST_GET,
OC_NON_CONFIRMABLE, token, "/oc/core?rt=alpha.light", 0). The
token in this example is a nonce that ties a CoAP response back to the
CoAP request. Internally, this method creates the CoAP PDU for
dispatching.
o Calls coap_send(context, host, pdu), which is a wrapper for the
implementation below.
o Calls coap_send_impl(context, host, packet), which dispatches the
packet to the socket and does the appropriate CoAP bookkeeping.
o Calls OCSend(socket, buffer, size...), which is a wrapper for the socket
implementation as the functions for dispatching a UDP packet can vary
in the embedded systems.
• Servers that offer the resource on the network will reply to the query. The
message pump evoked from the OCProcess(...) function in the C SDK
receives these response packets and dispatches them to the callback
associated with the original request based on the CoAP message ID. These
responses will come back at the timing defined by their servers. The client
stack has timeouts for these responses that are listed in the appendices.
• As previously mentioned, the stack matches the response to the original
request using the message ID and send the results to the callback associated
with the request. At this level, the raw payload is presented in JSON format. It
is the responsibility of the callback passed to OCDoResource(...) to parse this
result.
• The C++ SDK provides a callback to OCDoResource(...) that will parse the
results, construct collections of OCResource objects from the response, and
pass them to a C++ client using the handler passed to the
platform.findResource(...) method. The handler will be called once for each
resource server that responds to the query.
Notes:
• Some of the API call parameters have been omitted for brevity.

• The findResource() method can be used in the following ways:
o Find all resources on the network that match the provided criteria
o Query a specific (single) server for the resources that it provides
matching the provided criteria
• The findResource() method may be used multiple times to find a resource
• The findResource() callback is called from the message pump thread in
multithreaded environments
• Blocking in the findResource() callback will block other stack processing
including servicing the network I/O which can cause delays and missed
packets.
Notes:
• The discovery request under CoAP is handled like any other resource GET
request. The request can be received via unicast or multicast, but the
response, if any, is always sent via unicast.
• The stack dispatches the request to an entity handler defined by the stack.
• The handler for "/oc/core", processes the URI query, if any, and builds a list of
resources that match the criteria and returns the result in JSON to the
network transport.
• In the case of CoAP, if the request is made to all nodes (multicast) and the
resource list is empty, no response is sent to the clients. If the request is
directed (unicast) or the resource list has results, the response is sent unicast
back to the client.
Register Resource in C++ [Client]
// Callback to found resources
void foundResource(std::shared_ptr<OCResource> resource)
{
std::string resourceURI;
std::string hostAddress;
try
{
// Do some operations with resource object.
if(resource)
{
std::cout<<"DISCOVERED Resource:"<<std::endl;
// Get the resource URI
resourceURI = resource->uri();
std::cout << "tURI of the resource: " << resourceURI <<
std::endl;
// Get the resource host address
hostAddress = resource->host();

std::cout << "tHost address of the resource: " <<
hostAddress << std::endl;
// Get the resource types
std::cout << "tList of resource types: " << std::endl;
for(auto &resourceTypes : resource->getResourceTypes())
{
std::cout << "tt" << resourceTypes << std::endl;
}
// Get the resource interfaces
std::cout << "tList of resource interfaces: " <<
std::endl;
for(auto &resourceInterfaces : resource-
>getResourceInterfaces())
{
std::cout << "tt" << resourceInterfaces <<
std::endl;
}
if(resourceURI == "/a/light1")
{
// Found interested resource
}
}
else
{
// Resource is invalid
std::cout << "Resource is invalid" << std::endl;
}
}
catch(std::exception& e)
{
//log
}
}
try
{
OCPlatform platform(cfg);
// Find all resources
platform.findResource("",
"coap://224.0.1.187/oc/core?rt=alpha.light",
&foundResource);
}catch(OCException& e)
{
//Handle Error
}

Over the air Request
The request is sent to all nodes on the network:
Field Value Note(s)
Address 224.0.1.187:5683 Multicast packet
Header NON, GET, MID=0x7d40
Multicast discovery request should
be non-confirmable
URI-Path oc
"/oc/core?rt=alpha.light"URI-Path core
URI-Query rt=alpha.light
Accept application/json
Over the air Response(s)
Assuming that all of the representative devices (see Representative Devices) are
online, three responses are expected. Only the three devices with light resources
respond; the list of resources has been filtered to contain just the resources that
match the criteria.
From 192.168.1.11:
Field Value Explanation
Address 192.168.1.1:5683 Client Address
Header ACK, CONTENT, MID=0x7d40 Success w/content
Content
Format
application/json

Payload
[ { "href" : "/light/1",
"rt":["alpha.light"],
"if":["oc.mi.def"], "obs":1} ]
From 192.168.1.12:
Content
Format
application/json
Payloa
[ { "href" : "/light/2",
From 192.168.1.13:
Content
Format
application/json
Payload
[ { "href" : "/light/1",
"if":["oc.mi.def"], "obs":1}, { "href" :
"/light/2", "rt":["alpha.light"],

Querying Resource State [GET]
This operation fetches the value of a simple resource. In this example, we fetch the
state from the light resource.
Steps:
1. The client application calls resource.get(...) to retrieve a representation from the
resources.
2. The call is marshalled to the stack which is either running in-process or out-of-process
(daemon).
3. The C API is called to dispatch the request. The call may look like the following:
OCDoResource(OC_REST_GET, "//192.168.1.11/light/1, 0, 0,
OC_CONFIRMABLE, callback);
4. Where CoAP is used as a transport, the lower stack will send a GET request to the
target server.
5. 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.
6. 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).
7. The C++ SDK passes it up the C++ handler associated with the OCResource.
8. The handler returns the result code and representation to the SDK.
9. The SDK marshals the result code and representation to the C++ entity handler.
10. The entity handler returns the result code and representation to the CoAP protocol.
11. The CoAP protocol transports the results to the client device.
12. The results are returned the OCDoResource callback.
13. The results are returned to the C++ client application's asyncResultCallback.
Querying resource State [GET] in C++ [Client]
// Local function to get representation of light resource
void getLightRepresentation(std::shared_ptr<OCResource>
resource)
{
if(resource)
{
std::cout << "Getting Light Representation..."<<std::endl;
// Invoke resource's get API with the callback parameter
QueryParamsMap test;
resource->get(test, &onGet);
}
}
// callback handler on GET request
void onGet(const OCRepresentation& rep, const int eCode)
{

if(eCode == SUCCESS_RESPONSE)
{
std::cout << "GET request was successful" << std::endl;
AttributeMap attributeMap = rep.getAttributeMap();
std::cout << "Resource URI: " << rep.getUri() <<
std::endl;
for(auto it = attributeMap.begin(); it !=
attributeMap.end(); ++it)
{
std::cout << "tAttribute name: "<< it->first << "
value: ";
for(auto valueItr = it->second.begin(); valueItr != it-
>second.end(); ++valueItr)
{
std::cout <<"t"<< *valueItr << " ";
}
std::cout << std::endl;
}
std::vector<OCRepresentation> children =
rep.getChildren();
for(auto oit = children.begin(); oit != children.end();
++oit)
{
std::cout << "Child Resource URI: " << oit->getUri() <<
std::endl;
attributeMap = oit->getAttributeMap();
{
value: ";
for(auto valueItr = it->second.begin(); valueItr !=
it->second.end(); ++valueItr)
{
}
}
}
putLightRepresentation(curResource);
}
else
{
std::cout << "onGET Response error: " << eCode <<
std::endl;
std::exit(-1);
}
}

Querying resource State [GET] in C++ [Server]
// Handling GET request in Entity handler
if(requestType == "GET")
{
cout << "tttrequestType : GETn";
// Check for query params (if any)
QueryParamsMap queryParamsMap = request-
>getQueryParameters();
cout << "tttquery params: n";
for(QueryParamsMap::iterator it = queryParamsMap.begin();
it != queryParamsMap.end(); it++)
{
cout << "tttt" << it->first << ":" << it->second <<
endl;
}
// Process query params and do required operations ..
// Get the representation of this resource at this point
and send it as response
// AttributeMap attributeMap;
OCRepresentation rep;
rep = myLightResource.getRepresentation();
if(response)
{
// TODO Error Code
response->setErrorCode(200);
auto findRes = queryParamsMap.find("if");
if(findRes != queryParamsMap.end())
{
response->setResourceRepresentation(rep, findRes-
>second);
}
else
{
response->setResourceRepresentation(rep,
DEFAULT_INTERFACE);
}
}
}
Over the air request
In this example, we are querying state from one of the lights. At this point, the
resource was discovered by its type, and we understand its interface and the
attributes that the resource exposes.
Field Value Note(s)

Field Value Note(s)
Header CON, GET, MID=0x7d42 Confirmation is requested
URI-Path light
"/light/1"
URI-Path 1
Accept application/json
Assuming that the request is valid, we expect the following reply from the resource.
From 192.168.1.11:
Header ACK, CONTENT, MID=0x7d42 Success w/Content
Content
Type
application/json
Payload
{
"power" : 0,
"level" : 10
}

Setting a resource state [PUT]
This operation sets the value of a simple resource. In this example, we turn on a light
resource and set the brightness to 50%.
Steps:
1. The client application calls resource.put(...) to set representation of resource. Example
call: resource.put(attributeMap, queryParamsMap, &onPut);
2. Client SDK internally calls the setResourceAttributes function of the client wrapper.
Example call: OCDoResource(OC_REST_PUT, "//192.168.1.11/light/1, 0, 0,
OC_CONFIRMABLE, callback);
3. Send PUT request to remote device
4. The OCProcess() service function (server-side message pump) reads the packet from
the socket and dispatches the request to the entity handler for the provided URI.
5. The entity handler, which was provided by an upper layer when the resource was
registered, parses the representation and in the case of the C++ API passes the results
to the upper layer handler. In a C only environment, the results would also be
processed in the entity handler.
6. The upper layer entity handler written by the app developer/vendor is invoked, and
the response is formed accordingly.
7. The upper layer entity handler returns success or failure with a response.
8. Returns success or failure to lower layer for transmission to client.
11. Result is formatted and sent over network to client
12. The OCProcess() service function (client-side message pump) reads results and passes
the results back to the client application via the callback passed to OCDoResource
Set Resource's State [PUT] in C++ [Client]
void putLightRepresentation(std::shared_ptr<OCResource>
resource)
{
if(resource)
{
OCRepresentation rep;
std::cout << "Putting light representation..."<<std::endl;
// Create AttributeMap
AttributeMap attributeMap;
// Add the attribute name and values in the attribute map
AttributeValues stateVal;
stateVal.push_back("true");
AttributeValues powerVal;

powerVal.push_back("10");
attributeMap["state"] = stateVal;
attributeMap["power"] = powerVal;
// Create QueryParameters Map and add query params (if
any)
QueryParamsMap queryParamsMap;
rep.setAttributeMap(attributeMap);
// Invoke resource's put API with attribute map, query map
and the callback parameter
resource->put(rep, queryParamsMap, &onPut);
}
}
// callback handler on PUT request
void onPut(const OCRepresentation& rep, const int eCode)
{
{
std::cout << "PUT request was successful" << std::endl;
{
value: ";
{
}
}
std::vector<OCRepresentation> children =
rep.getChildren();
for(auto oit = children.begin(); oit != children.end();
++oit)
{
attributeMap = oit->getAttributeMap();
{

value: ";
for(auto valueItr = it->second.begin(); valueItr !=
it->second.end(); ++valueItr)
{
}
}
}
}
else
{
std::cout << "onPut Response error: " << eCode <<
std::endl;
std::exit(-1);
}
Set Resource's State [PUT] in C++ [Server]
//Entity handle sample for PUT
if(requestType == "PUT")
{
cout << "tttrequestType : PUTn";
// Check for query params (if any)
QueryParamsMap queryParamsMap = request-
>getQueryParameters();
cout << "tttquery params: n";
for(auto it = queryParamsMap.begin(); it !=
queryParamsMap.end(); it++)
{
cout << "tttt" << it->first << ":" << it->second <<
endl;
}
// Get the representation from the request
OCRepresentation rep = request-
>getResourceRepresentation();
myLightResource.setRepresentation(rep); // See code
snippet below
// Do related operations related to PUT request // See
code snippet below
rep = myLightResource.getRepresentation();
if(response)
{

response->setErrorCode(200);
auto findRes = queryParamsMap.find("if");
if(findRes != queryParamsMap.end())
{
response->setResourceRepresentation(rep, findRes-
>second);
}
else
{
response->setResourceRepresentation(rep,
DEFAULT_INTERFACE);
}
}
}
void setRepresentation(OCRepresentation& light)
{
AttributeMap attributeMap = light.getAttributeMap();
if(attributeMap.find("state") != attributeMap.end() &&
attributeMap.find("power") != attributeMap.end())
{
cout << "ttt" << "Received representation: " << endl;
cout << "tttt" << "power: " <<
attributeMap["power"][0] << endl;
cout << "tttt" << "state: " <<
attributeMap["state"][0] << endl;
m_state = attributeMap["state"][0].compare("true") == 0;
m_power= std::stoi(attributeMap["power"][0]);
}
}
OCRepresentation getRepresentation()
{
OCRepresentation light;
light.setUri(m_lightUri);
std::vector<std::string> interfaces;
//interfaces.push_back(m_lightInterface);
light.setResourceInterfaces(interfaces);
std::vector<std::string> types;
//types.push_back(m_lightType);
light.setResourceTypes(types);

AttributeMap attributeMap;
AttributeValues stateVal;
if(m_state)
{
stateVal.push_back("true");
}
else
{
stateVal.push_back("false");
}
AttributeValues powerVal;
powerVal.push_back(to_string(m_power));
attributeMap["state"] = stateVal;
attributeMap["power"] = powerVal;
light.setAttributeMap(attributeMap);
return light;
}
In this example, we are pushing state to one of the lights. At this point, the resource
was discovered by its type, and we understand its interface and the attributes
exposed by the resource.
Field Value Note(s)
Header CON, PUT, MID=0x7d41 Confirmation is requested
URI-Path light
"/light/1"
URI-Path 1
Content-Type application/json

Field Value Note(s)
Payload
{
"power" : 1,
"level" : 5
}
Assuming that the request is valid and the resource is able to complete the transition,
the following represents a successful change in state.
From 192.168.1.13:
Header
ACK, CHANGED,
MID=0x7d41
Success (changed)
Observing resource state [Observe]
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 confirmable or non-confirmable. If
the client returns a RST 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 NOTFOUND status to all
observers.
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.
Steps:
1. The client application calls resource.observe(...) to retrieve a representation from the
resources.
2. The call is marshalled to the stack which is either running in-process or out-of-process
(daemon).
3. The C API is called to dispatch the request. The call may look like this:
OCDoResource(OC_REST_GET | OC_REST_OBSERVE, "//192.168.1.11/light/1, 0,
0, OC_CONFIRMABLE, callback);
4. 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.
5. 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.
6. 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).
7. The C++ SDK passes it up the C++ handler associated with the OCResource.
8. The handler returns the result code and representation to the SDK.
9. The SDK marshals the result code and representation to the C++ entity handler.
10. The entity handler returns the result code and representation to the CoAP protocol.
11. The CoAP protocol transport the results to the client device.
12. The results are returned to the OCDoResource callback.
13. The results are returned to the C++ client application's asyncResultCallback.
14. 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.
15. 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.
16. For each observer of a changed resource, the entity handler is called to generate a
representation that is transmitted to the observing clients.

17. 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.
18. 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.
19. The C API callback passes the final results to the C++ client application's
asyncResultCallback.
20. When the C++ client no longer desires to receive notifications from the server, it calls
observation cancellation method cancelObserve().
21. The C++ cancellation method calls the OCCancel() function from the C API.
22. OCCancel() finds the observation that is associated with the operation and sends an
observe deregistration request to the server.
Observing resource state [Observe] in C++ [Client]
if (OBSERVE_TYPE_TO_USE == ObserveType::Observe)
std::cout << endl << "Observe is used." << endl << endl;
else if (OBSERVE_TYPE_TO_USE == ObserveType::ObserveAll)
std::cout << endl << "ObserveAll is used." << endl <<
endl;
QueryParamsMap test;
curResource->observe(OBSERVE_TYPE_TO_USE, test,
&onObserve);
// callback
void onObserve(const OCRepresentation& rep, const int& eCode,
const int& sequenceNumber)
{
{
std::cout << "OBSERVE RESULT:"<<std::endl;
std::cout << "tSequenceNumber: "<< sequenceNumber <<
endl;
{
value: ";
{
}

}
if(observe_count() > 30)
{
std::cout<<"Cancelling Observe..."<<std::endl;
OCStackResult result = curResource->cancelObserve();
std::cout << "Cancel result: "<< result <<std::endl;
sleep(10);
std::cout << "DONE"<<std::endl;
std::exit(0);
}
}
else
{
std::cout << "onObserve Response error: " << eCode <<
std::endl;
std::exit(-1);
}
}
Observing resource state [Observe] in C++ [Server]
// Handling observe in server's entity handler
if(requestFlag == RequestHandlerFlag::ObserverFlag)
{
pthread_t threadId;
cout << "ttrequestFlag : Observern";
gObservation = 1;
static int startedThread = 0;
// Observation happens on a different thread in
ChangeLightRepresentation function.
// If we have not created the thread already, we will
create one here.
if(!startedThread)
{
pthread_create (&threadId, NULL,
ChangeLightRepresentation, (void *)NULL);
startedThread = 1;
}
// ChangeLightRepresentaion is an observation function,
// which notifies any changes to the resource to stack
// via notifyObservers
void * ChangeLightRepresentation (void *param)
{
// This function continuously monitors for the changes

while (1)
{
sleep (5);
if (gObservation)
{
// If under observation if there are any changes to the
light resource
// we call notifyObservors
//
// For demostration we are changing the power value and
notifying.
myLightResource.m_power += 10;
cout << "nPower updated to : " <<
myLightResource.m_power << endl;
cout << "Notifying observers with resource handle: " <<
myLightResource.getHandle() << endl;
OCStackResult result =
OCPlatform::notifyObservers(myLightResource.getHandle());
if(OC_STACK_NO_OBSERVERS == result)
{
cout << "No More observers, stopping notifications" <<
endl;
gObservation = 0;
}
}
}
return NULL;
}
The following observation request is basically a GET request with the observation
option set.
Fields Value Notes
Header
CON, GET, MID=0x7d44,
TOK=0x3f
Confirmation requested
Observe Register (0) This indicates registration

Fields Value Notes
URI-Path Light "/light/1 "
URI-Path 1
Accept application/json Requesting result in JSON
Over the air response(s)
A successful observe request would be similar to the following:
Header
ACK, CONTENT, MID=0x7d44,
TOK=0x3f
Success w/content
Observe 12 Sequence number for ordering
Max-Age 30
Indicates that the value is fresh
for 30 seconds.
It also indicates that the server
should send an
update within this time period.
Content
Type
application/json
Payload
{
"power" : 0,

"level" : 10
}
Subsequent Notifications from 192.168.1.1
If the light resource is being observed and the light transitions from an off state to an
on state, a notification is sent to the client from the server. The following is an
example of such a notification:
Header
CON, CONTENT, MID=0x7D45,
TOK=0x3f
Content, Can be confirmable or
non-confirmable
Observe 15
Monotonically increasing until
overflow
Max-Age 30
Indicates that the value is fresh
for 30 seconds.
It also indicates that the server
should send an
update within this time period.
Payload
{
"power" : 1,
"level" : 10

}
Since the above notification was marked confirmable, the client should acknowledge
the notification with a packet such as the following:
Header ACK, MID=0x7D45, TOK=0x3f Success

[Text Book] IoT Class Material - CoAP, OCF, and IoTivity

More Related Content

What's hot

Similar to [Text Book] IoT Class Material - CoAP, OCF, and IoTivity

Recently uploaded

[Text Book] IoT Class Material - CoAP, OCF, and IoTivity