User Tools

Site Tools


This is an old revision of the document!

Cloud Interface in IoTivity

This is a contribution proposal about cloud/server interface of OIC devices. Currently, IoTivity doesn't have the capability to interact with internet service provided by cloud. So, this feature enriches the OIC device functionality and extends the coverage of OIC device interoprability.

We'd like to propose the CoAP over TCP as the cloud interface protocol. The CoAP over TCP specification describes the consistency with CoAP standard( RFC7252 ) except header construction. So, it can be the most suitable candidate for cloud interface for OIC device.

Scenario and sequences

Initially, following two scenarios are considered.

1. OIC device send event notification to the Cloud service. For example, log data can be sent from device to cloud server and the device can request appropriate service to cloud server ( eg, personalized ad, remote diagnosis, etc )

2. The Cloud service send device control command to the OIC device according to the rules defined by user.

For any kind of cloud service, OIC device should support cloud interface.


  • Basically, protocol follows by CoAP over TCP draft
  • The first nibble of initial byte is used 0~15(13~15 is special value) in the Header of CoAP over TCP.
  • Simple Header Format about 8-bit length(nibble is 13) is in below.
  • Only message type transported when using CoAP over TCP is the Non-Confirmable message (NON).
  • Message ID is meaningless and thus elided.
  • This feature will be supported optional through build option set.
  • Use URI Scheme
    • “coap+tcp:” “” host [ “:” port ] path-abempty [ “?” query ] * “coaps+tcp:” “” host [ “:” port ] path-abempty [ “?” query ]
  • Use TLS ( RFC7301 ) to guarantee secure transmission ( 2nd phase )
  • Support keep alive ( 2nd phase )
  • Support auto-reconnection to recover abnormal disconnection ( 2nd phase )
  • Support IPv6 ( 2nd phase )


<Event notification>

<Device control>

<RI Interface>

Contribution approach

Cloud CI(Cloud Interface) server side

  • Use Netty framework ( )
  • Contribution ‘CoAP over TCP codec’ part only
  • User wants to enable cloud interface, he/she should setup the Netty framework.

Device side

  • Some enumerations represent TCP transport type will be added in RI layer( octypes.h )
  • OCTransportFlags::OC_IP_USE_V4_TCP
  • OCConnectivityType::CT_IP_USE_V4_TCP
  • Some interface will be added in RI layer to get information from application, this should be required to connect and register device at cloud service (RegisterResourceToCloud(..), UnregisterResourceToClould(..))
    • IP, Port parameter for Connection/Disconnection
      • Even though the OIC device is resource server, the device should try to connect the Cloud service. Because the information of Cloud server depends on the application. the information of Cloud service should be passed from application.
      • So, IoTivity should provide the interface through parameter of RegisterResourceToCloud(..), UnregisterResourceToClould(..) Method in OCPlatform.
    • payload, Payload Size parameter for Register
      • To send device information. its resource information is depends on Resource Directory of RD Server.
      • since Resource Data Type will be required by RD server. this Resource data should be included in Payload parameter of new RegisterResource(…) by Application.
      • Again, since OCResource of RI can't be covered for resource data of RD server, it should be provided from Application as new RegisterResource(…, payload, payloadSize) directly.
  • Some interface will be not added in CA layer.
    • new RegisterResource / UnregisterResource API of RI will be called SendRequest of CA finally.
      • if there was no TCP session with Cloud server, TCP adapter will be checked and then CA will try to connect with CI server before send request to register resource.
      • For the register, CA can use CoAP advertising flow. If the transport type is TCP, CA sends registration information to Cloud server, else CA sends multicast message according to the selected transport types.
      • when UnregisterResource(..) is called from Base API, sendRequest of CA will be called in first and then TCP disconnect will be tried.
    • Some data structures will be modified in CA layer
      • CATransportAdapter_t::CA_TCP_ADAPTER ( 1 « 4 ) will be added
      • To store the CI server information, tcpsockets structure will be added.
      • To store the CI server list, u_arraylist_t will be added.
    • This logic will be implemented in other adapter.(catcpadapter - ci(cloud interface))
typedef enum {
    CA_DEFAULT_ADAPTER         = 0,
    CA_ADAPTER_IP              = (1 << 0),
    CA_ADAPTER_GATT_BTLE       = (1 << 1),
    CA_ADAPTER_RFCOMM_BTEDR    = (1 << 2),
    CA_ADAPTER_REMOTE_ACCESS   = (1 << 3),
    CA_ADAPTER_TCP             = (1 << 4), // CoAP over TCP
    CA_ALL_ADAPTERS            = 0xffffffff
} CATransportAdapter_t;
  • To handle different header for TCP, we are going to change libcoap interface.
    • Add parameter to all APIs using coap_hdr_t to decide which header should be constructed
      • typedef enum { coap_udp = 0, coap_tcp = 1 } coap_transport_type;
    • coap_hdr_t will be changed.
    • As coap header is changed, some API in libcoap will be also changed as per transport type.


In order to ensure that the connection between an OIC Devices, when using CoAP over TCP, OIC Device should send application layer KeepAlive messages. (Please refer the Core Specification Project B documents ( 12.6. CoAP serialization over TCP ))

  • The reason to support application layer KeepAlive are as follows :
    • TCP KeepAlive only guarantees that a connection is alive at the network layer, but not at the application layer.
    • Interval of TCP KeepAlive is configurable only using kernel parameters and is OS dependent. ( eg. 2 hours by default in Linux )
  • Detailed Features
    • Use Fixed Ping resource
      • URI: /oic/ping, Type ID:, Interfaces:
    • Fixed Interval Time
      • Start from 2 minutes and increases in multiples of 2 up to 64 minutes.
    • Disconnect logic
      • OIC Client does not receive the response with 1 minutes.
      • OIC Server does not receive a PUT request within interval time.
  • Base Layer Changes
    • Support a resource of type
    • Maintain the OIC Device Information connected by CoAP over TCP to send KeepAlive message.
      • New API be added in RI & CA Layer (to pass the change of connection state from CA to RI)


  • What is Netty Framework ?
    • Netty is an asynchronous event-driven application/framework making it easy for users to write network socket programs. Originally It was developed by JBoss, and now being developed and maintained by the Netty Project Community. It supports HTTP, websocket, SSL/TLS and so on. The latest version is 4.0.30 final(stable) and 5.0.0 Alpah2(development) when this document is written.
    • Official home page :
  • How to build CoAP/TCP codec for Netty?
    • 'CoAP/TCP codec for Netty' is a CoAP/TCP implementation for Netty based on “draft-tschofenig-core-coap-tcp-tls-04.txt”. This adds the functionality for encoding/decoding CoAP over TCP messages to Netty framwork. The repository has complete source codes for Netty framework including the CoAP/TCP codec for Netty.
proposal_for_cloud_interface_in_iotivity.1449040050.txt.gz · Last modified: 2015/12/02 07:07 by Hyuna Jo