User Tools

Site Tools


iotivity_cloud_-_programming_guide

IoTivity Cloud - Programming Guide

IoTivity Cloud project consists of 4 servers and sample clients. This page will guide you how to setup and run cloud servers and clients. The sample clients will guides you to understand features and how to make other clients for cloud.

This page is targeting IoTivity release, ver 1.2.0.


Build servers

The cloud projects are located under {IoTivity root}/cloud folder. The folder name represent project itself. Account, Interface, Resource-directory and MessageQueue is java 8 based projects. Stack is base project for other server projects. So you should build Stack project first. You can also refer README file in each folder how to build and run. All java projects are maven ready. We assume that maven installed. Otherwise install it from http://maven.apache.org

~iotivity/cloud/stack $ mvn install -Dmaven.test.skip=true

After stack installation, you can build other projects.

~iotivity/cloud/resourcedirectory $ mvn install -Dmaven.test.skip=true
~iotivity/cloud/account $ mvn install -Dmaven.test.skip=true
~iotivity/cloud/messagequeue $ mvn install -Dmaven.test.skip=true
~iotivity/cloud/interface $ mvn install -Dmaven.test.skip=true

The Account and Resource-directory server requires mongodb to store data. MessageQueue server requires Apache Kafka to manage topics. We assume that mongodb(port number 27017, default), Kafka zookeeper and Kafka broker are runs on same machine where Account, Resourcedirectory and MessageQueue deployed.

Build clients

The cloud clients are based on IoTivity C/C++ stack. They are tested under Ubuntu 12.04 32/64bit machines.

~iotivity $ scons cloud WITH_TCP=yes RELEASE=yes TARGET_TRANSPORT=IP WITH_CLOUD=yes WITH_MQ=PUB,SUB

To build your own clients(Resource server/client), IoTivity stack must compiled using 'WITH_TCP=yes' and 'TARGET_TRANSPORT=IP' options. If you also need MessageQueue feature, additional 'WITH_MQ=PUB,SUB' option required. You can get compiled samples here.


~iotivity/out/linux/{ARCH}/release/cloud/samples/client


You can find aircon_controlee, aircon_controller, group_invite_sample, mq_publisher, mq_subscriber, thin_room_light.

Run servers

To run IoTivity Cloud project, Resource-directory, Account and Message Queue server must online before Interface server. Because Interface server requires address, port number of Resource-directory, Account and Message Queue server. We assume that mongodb, Apache Zookeeper, Apache Kafka and these four servers are deployed on same machine.

* Run Resource Directory server

~iotivity/cloud/resourcedirectory/target $ java -jar CloudResourceDirectory-0.0.1-SNAPSHOT.jar 5684 127.0.0.1 27017 0

* Run Account server

~iotivity/cloud/account/target $ java -jar CloudAccount-0.0.1-SNAPSHOT.jar 5685 127.0.0.1 27017 0

* Run Message Queue server

~iotivity/cloud/messagequeue/target $ java -jar CloudMessageQueue-0.0.1-SNAPSHOT.jar 5686 127.0.0.1 2181 127.0.0.1 9092 0

* Run Interface server

~iotivity/cloud/interface/target $ java -jar CloudInterface-0.0.1-SNAPSHOT.jar 5683 127.0.0.1 5684 127.0.0.1 5685 127.0.0.1 5686 80 8000 0

Note. The Account server requires external https internet access for OAuth 2 integration. If your network is under proxy, you should tell proxy address to JVM like below.

* Run Account server under proxy

~iotivity/cloud/account/target $ java -Dhttps.proxyHost=10.1.1.1 -Dhttps.proxyPort=8080 -jar CloudAccount-0.0.1-SNAPSHOT.jar 5685

If your proxy also requires custom certificate to make proper https connection, you can use JVM keytool to install it. https://sourceforge.net/projects/ssltools/


Run client

There are couple of clients in IoTivity Cloud project. This section will guide how to run one of sample.

~iotivity/out/linux/x86/release/cloud/samples/client $ ./aircon_controlee
Put "[host-ipaddress:port] [authprovider] [authcode]" for sign-up and sign-in and publish resources
Put "[host-ipaddress:port] [uid] [accessToken] 1" for sign-in and publish resources
  • Device Sign-up using OAuth 2 Auth Code

To register device, you need 'Auth Code' provided by OAuth 2 provider like Facebook, Google or Github. IoTivity Cloud project includes 'GitHub' account plugin. To get a 'Auth Code' from 'GitHub' you can make request to below URL.


https://github.com/login?return_to=%2Flogin%2Foauth%2Fauthorize%3Fclient_id%3Dea9c18f540323b0213d0%26redirect_uri%3Dhttp%253A%252F%252Fwww.example.com%252Foauth_callback%252F


Once you signed-in, you'll be redirected to other web page include 'Auth Code' in the redirected URL.


http://www.example.com/oauth_callback/?code=bf9beb5db17ea476fa46


The 'code' part in the URI is the 'Auth Code' from 'GitHub'.

We'll use this code to register and sign-in device.

Note. You should put Interface server address, credential to run sample.

~iotivity/out/linux/x86/release/cloud/samples/client $ ./aircon_controlee 10.1.1.110:5683 github 63987ad18106a87c6525
Auth response received code: 4
	accesstoken:	de42093f01fd35645bd6038139213c56a6fca3e6
        certificate:	[..CertInfo..]
	expiresin:	-1
	redirecturi:	coap+tcp://127.0.0.1:5683
	refreshtoken:	(null)
	sid:	2a6085d1-815d-4277-baba-4e4e4df91308
	tokentype:	bearer
	uid:	0cf89f61-d999-48cf-857f-73918a37531c
Auth response received code: 4
	expiresin:	-1
Registering resources to platform...
Publishing resources to cloud  result: 0 Waiting Publish default resource response from cloud
 result: 0 Waiting Publish user resource response from cloud
Publish resource response received, code: 4
PUT 1/0 to turn on/off air conditioner for observe testing, q to terminate
Publish resource response received, code: 4

You'll get access token and uid value from result of registration. The device should reuse those value for sign-in.

  • Device Sign-in and Resource publish

To sign-in, you need access token, uid.

~iotivity/out/linux/x86/release/cloud/samples/client $ ./aircon_controlee 10.1.1.110:5683 0cf89f61-d999-48cf-857f-73918a37531c de42093f01fd35645bd6038139213c56a6fca3e6 1
Auth response received code: 4
	expiresin:	-1
Registering resources to platform...
Publishing resources to cloud  result: 0 Waiting Publish default resource response from cloud
 result: 0 Waiting Publish user resource response from cloud
Publish resource response received, code: 4
PUT 1/0 to turn on/off air conditioner for observe testing, q to terminate
Publish resource response received, code: 4

Once the aircon_controlee has registered and signed-in, you can use aircon_controller to find and control.

  • Device Sign-in and Resource find

You need another authcode to run aircon_controller at first-time.

~iotivity/out/linux/x86/release/cloud/samples/client $ ./aircon_controller 10.1.1.110:5683 github 9d31d32e18c3e38bd559
Login/out response received code: 4
	accesstoken:	a0572063607baae269e5fdc336367d295f1efbdc
        certificate:	[..CertInfo..]
	expiresin:	-1
	redirecturi:	coap+tcp://127.0.0.1:5683
	refreshtoken:	(null)
	sid:	2a6085d1-815d-4277-baba-4e4e4df91308
	tokentype:	bearer
	uid:	0cf89f61-d999-48cf-857f-73918a37531c
Login/out response received code: 4
	expiresin:	-1
Finding airconditioner  result: 0
Device found: /di/1a78ae17-3dc0-48f8-a51e-b19574de198b/oic/d
DI: 1a78ae17-3dc0-48f8-a51e-b19574de198b
PUT 1/0 to turn on/off air conditioner, q to terminate
RT: oic.wk.d
RT: oic.d.airconditioner
Airconditioner found
Aircondition resource found: /di/a1d02b66-dbc4-44fd-8feb-93c565d7d4df/oic/d
RT: oic.wk.d
RT: oic.d.airconditioner
Aircondition resource found: /di/a1d02b66-dbc4-44fd-8feb-93c565d7d4df/oic/p
RT: oic.wk.p
Aircondition resource found: /di/a1d02b66-dbc4-44fd-8feb-93c565d7d4df/sec/aircon/0
....

You can put 0 / 1 to aircon_controller or aircon_controlee to trigger binary switch.

Cloud Architecture

  • Each gray box represents application process.
  • Cloud Interface process uses Device Server System module to handle devices.
  • Green boxes are external libraries.
  • Red boxes are internal modules where application can not access.
  • Orange boxes are exposed to application layer.
  • Mint boxes are framework classes wherer accessible by main class.
  • Purple boxes are internal modules of each application.
  • Some features like clustering and http support is not implemented yet.

Resource models on cloud

Here are exposed resources by Interface server. Clients uses these resources for authenticating, publishing, finding assets from cloud.


  • KeepAlive resource

In order to ensure that the connection between an OCF Device is maintained, when using CoAP serialization over TCP, an OCF Device that initiated the connection should send application layer KeepAlive messages.


  • Authentication resource

We'll update this part soon.


  • Resource directory resource

Resource directory resource is used for storing and finding resources.

IoTivity cloud implements OIC 1.1 RD specification.

We'll update this part soon.


  • Resource find

You can use default implementation to find resources.

Making your own devices

You can find couple of samples under cloud/samples/client folder to help you how to make your own cloud devices. Airconditioner samples are designed for using C++ API to create resource server and client. Thin_Light is C API based resource server. MessageQueue samples will guide you how to use MessageQueue feature to share data between clients on cloud. Group and invite sample is for supporting complex scenario like sharing devices between different accounts.

iotivity_cloud_-_programming_guide.txt · Last modified: 2017/09/05 11:27 by Kousthubha M N