You are here

Getting Started

Introduction

This guide provides instructions and resources to help developers set up the development environment, build the IoTivity stack and build sample applications on Ubuntu for a Linux target. Developers should also read the IoTivity Programmer's Guide before starting development to better understand IoTivity architecture and use cases.

Tools and libraries

The following tools and libraries are necessary to build IoTivity code for Linux. The commands and instructions provided in this section are specifically for Ubuntu LTS 12.04.

Open the terminal window and use the following instructions to install all the necessary tools and libraries to build an IoTivity project.

Ubuntu LTS 12.04

Ubuntu LTS version 12.04 is the supported OS for building the IoTivity stack. Instructions may be different for other versions of Ubuntu and Linux.

Git

Git is a source code management software, and is necessary to gain access to the IoTivity source code.

Use the following command to download and install git:

$ sudo apt-get install git-core

scons

Scons is used to build IoTivity:

$ sudo apt-get install scons

ssh

Secure Shell is required to connect to the git repository to check out the IoTivity source code. Secure Shell is typically part of the base operating system and should be included. If for any reason it is not available, it can be installed by running the following command in your terminal window:

$ sudo apt-get install ssh

G++ version 4.6.1

G++ is required to build the IoTivity stack. Download and install G++ by running the following command in your terminal window:

$ sudo apt-get install build-essential g++

Additional libraries

IoTivity and boost depend on several additional libraries that have to be available. Please install the following libs:

$ sudo apt-get install libboost-dev libboost-program-options-dev libboost-thread-dev uuid-dev libssl-dev libtool libglib2.0-dev libcap-dev libcurl4-openssl-dev autotools-dev autoconf

Boost version 1.55

Boost C++ library is necessary to build the IoTivity stack. To download and install Boost libraries:

Step 1:

download boost_1_55_0.tar.gz

Step 2:

Run the following command in your terminal window:

$ tar xzvf boost_1_55_0.tar.gz

Step 3:

Navigate to the boost directory.

$ cd boost_1_55_0/

Step 4

Please make sure to remove previous version of boost before following this step. Run the following command in the terminal window to add libraries:

$ ./bootstrap.sh --with-libraries=system,filesystem,date_time,thread,regex,log,iostreams,program_options --prefix=/usr/local

Run following in terminal to get the required libraries, main one is icu for boost::regex support

$ sudo apt-get update 
$ sudo apt-get install python-dev autotools-dev libicu-dev build-essential libbz2-dev

Step 5:

Run the following command to install:

$ sudo ./b2 install

If you have /usr/local/lib not setup, you can add it to your LD LIBRARY PATH

$ sudo sh -c 'echo '/usr/local/lib' >> /etc/ld.so.conf.d/local.conf'

Reset the ldconfig:

$ sudo ldconfig

Doxygen

Doxygen is a documentation generation tool used to generate API documentation for the IoTivity project. Download and install Doxygen by running the following command in your terminal window:

$ sudo apt-get install doxygen

Source code

There are 2 methods to get the source code.

  1. Downloading most stable source from here.
  2. Getting source directly from gerrit.

Gerrit is a web-based code review tool built on top of the git version control system. Gerrit's main features are side-by-side difference viewing and inline commenting, which streamline code review. Gerrit allows authorized contributors to submit changes to the git repository after reviews are done. Contributors can have code reviewed with little effort, and get their changes quickly through the system.

The following five steps describe how to check out the source code on the development machine.

Note: skip Step 1 to use existing ssh keys.

Step 1:

Create ssh keys.

  1. On the terminal, type the following (replace "your name <your_email_address>" with your name and email address):
    $ ssh-keygen -t rsa -C "your name"
    For example John Doe with an email address john.doe@example.com would type:
    $ ssh-keygen -t rsa -C "John Doe john.doe@example.com"
  2. After pressing the Enter key at several [LS6] prompts, an ssh key-pair will be created at ~/.ssh/id_rsa.pub.

Step 2:

Upload and register an ssh public key.

  1. Log in to IoTivity Gerrit.
  2. Click on Settings on the top right side as shown here:
    IoTivity Gerrit Settings
  3. Click on SSH Public Keys and add key.
  4. Open ~/.ssh/id_rsa.pub, copy the content, and paste the content in the "Add SSH Public Key" window.
  5. Click Add.

Step 3:

Setting up ssh.

  1. Open ~/.ssh/config in a text editor.
  2. Add the following line:
    Host iotivity gerrit.iotivity.org 
      Hostname gerrit.iotivity.org 
      IdentityFile ~/.ssh/id_rsa 
      User [Insert_your_username_here]
      Port 29418
  3. To connect behind the proxy, add the following line after IdentityFile ~/.ssh/id_rsa with the appropriate proxy address and port:
    ProxyCommand nc -X5 -x <proxy-address>:<port> %h %p

Step 4:

Verify your ssh connection.

  1. Execute the following command in the terminal window:
    $ ssh gerrit.iotivity.org
  2. Upon successful connection, the following message should appear indicating proper ssh and configuration connection.
    **** Welcome to Gerrit Code Review ****
  3. If the connection is not established, check for the proxy and use the proxy settings described in Step 3.

Step 5:

Cloning the project source.

To build the IoTivity resource stack:

  1. Using your terminal window, browse to the directory where code will be checked out.
  2. Execute the following command in the terminal window to clone the iotivity repository:
    $ git clone iotivity:iotivity 
    or
    git clone ssh://gerrit.iotivity.org/iotivity

This command clones the repository in your current working directory.

Build the IoTivity project for Linux

To build the whole project, including the core, C SDK, C++ SDK and samples:

  1. Navigate to the root of the iotivity directory using the terminal window.
  2. Execute the scons build command from the iotivity directory in the terminal window:
    $ scons 

This command builds all the components of the IoTivity project. If the build is successful then you will not see any error in terminal window. 

Running the samples

To run the C++ samples, make sure they are built first (see "Build the C++ samples").

  1. Navigate to iotivity/resource/examples/release/ folder using terminal window.
  2. Run the following command in the terminal:
    $ ./simpleserver

    You should see an output like this in the terminal:

    The usage of simpleserver should be as follows,
    Usage : simpleserver < secure resource and observer >
    Default - Non-secure resource and notify all observers
    1 - Non-secure resource and notify list of observers
    2 - Secure resource and notify all observers
    3 - Secure resource and notify list of observers

     

  3. Open another terminal and navigate to iotivity/resource/examples/release/ folder
  4. Run the following command in the terminal:
    $ ./simpleclient

    You should see the following output in the terminal:

    Finding Resource... 
    DISCOVERED Resource:
    	URI of the resource: /a/light
    	Host address of the resource: coap://192.168.1.3:50703
    	List of resource types: 
    		core.light
    		core.brightlight
    	List of resource interfaces: 
    		oc.mi.def
    		oc.mi.ll
    Getting Light Representation...
    GET request was successful
    Resource URI: /a/light
    	state: 0
    	power: 0
    	name: John's light
    Putting light representation...
    PUT request was successful
    	state: 1
    	power: 15
    	name: John's light
    Posting light representation...
    POST request was successful
    	Uri of the created resource: /a/light1
    Posting light representation...
    POST request was successful
    	state: 1
    	power: 55
    	name: John's light
    Observe is used.
     
    OBSERVE RESULT:
    	SequenceNumber: 0
    	state: 1
    	power: 55
    	name: John's light
    OBSERVE RESULT:
    	SequenceNumber: 5
    	state: 1
    	power: 65
    	name: John's light

    The simpleserver terminal will also be updated to show the following output in the server:

    Usage : simpleserver < secure resource and observer >
        Default - Non-secure resource and notify all observers
        1 - Non-secure resource and notify list of observers
        2 - Secure resource and notify all observers
        3 - Secure resource and notify list of observers
     
    0: 
    In entity handler wrapper: 
     
    	In Server CPP entity handler:
    		requestFlag : Request
    			requestType : GET
    0: 
    In entity handler wrapper: 
     
    	In Server CPP entity handler:
    		requestFlag : Request
    			requestType : PUT
    				state: 1
    				power: 15
    0: 
    In entity handler wrapper: 
     
    	In Server CPP entity handler:
    		requestFlag : Request
    			requestType : POST
    0: 
    In entity handler wrapper: 
     
    	In Server CPP entity handler:
    		requestFlag : Request
    			requestType : POST
    				state: 1
    				power: 55
    0: 
    In entity handler wrapper: 
     
    	In Server CPP entity handler:
    		requestFlag : Request
    			requestType : GET
    		requestFlag : Observer
     
    Power updated to : 65
    Notifying observers with resource handle: 0xb1d820
    0: 
    In entity handler wrapper: 
     
    	In Server CPP entity handler:
    		requestFlag : Request
    			requestType : GET
     
    Power updated to : 75
    Notifying observers with resource handle: 0xb1d820
    0: 
    In entity handler wrapper: 
     
    	In Server CPP entity handler:
    		requestFlag : Request
    			requestType : GET
     
    Power updated to : 85
    Notifying observers with resource handle: 0xb1d820
    0: 
    In entity handler wrapper: 
     
    	In Server CPP entity handler:
    		requestFlag : Request
    			requestType : GET

     

Build the API reference documentation

To build the API reference documentation:

  1. Navigate to iotivity/resource/docs folder using the terminal window.
  2. Run the following command:
    $ doxygen

    This command builds the API reference documentation in the output directory.

    The output directory for this command is iotivity/docs/html/index.html.