README.rst 7.97 KB
Newer Older
1 2 3
Getting Started
---------------

George Nash's avatar
George Nash committed
4 5 6
IoTivity-Constrained is a lightweight implementation of the
`Open Connectivity Foundation <https://openconnectivity.org/>`_ (OCF) standards
for the Internet of Things (IoT).
7

George Nash's avatar
George Nash committed
8 9 10
It was designed to build secure and interoperable IoT applications in full
compliance with the
`OCF specifications <https://openconnectivity.org/developer/specifications>`_
Kishen Maloor's avatar
Kishen Maloor committed
11
with a limited footprint not exceeding the needs of the specifications. The
George Nash's avatar
George Nash committed
12 13
stack architecture lends itself to be ported rapidly to any chosen hardware/OS
environment.
Kishen Maloor's avatar
Kishen Maloor committed
14

George Nash's avatar
George Nash committed
15 16
IoT applications may be built for a wide variety of rich and resource-constrained
devices across the IoT landscape. As a general guideline, it should be feasible
Kishen Maloor's avatar
Kishen Maloor committed
17
to deploy applications on class 2 constrained devices (>256KB Flash, >64KB RAM),
George Nash's avatar
George Nash committed
18
or better.
Kishen Maloor's avatar
Kishen Maloor committed
19

George Nash's avatar
George Nash committed
20 21
The project is open-source, and its code is distributed under the
commercial-friendly Apache v2 license.
22 23 24 25 26 27

Contents
--------

- `IoTivity-Constrained Architecture`_
- `Project directory structure`_
Kishen Maloor's avatar
Kishen Maloor committed
28
- `Setup source tree`_
29 30 31 32 33 34 35 36 37 38 39
- `Building sample applications on Linux`_
- `Framework configuration`_

IoTivity-Constrained Architecture
---------------------------------

.. image:: IoTivityConstrained-Arch.png
   :scale: 100%
   :alt: IoTivity-Constrained Architecture
   :align: center

Kishen Maloor's avatar
Kishen Maloor committed
40 41 42 43 44 45
IoTivity-Constrained's design presents the following features:

- **OS agnostic core**: This cross-platform core (written in pure C)
  encompasses the APIs, OCF resource model, protocol, security features,
  memory management and event loop. The core interacts
  with lower level platform-specific functionality via a very limited
Kishen Maloor's avatar
Kishen Maloor committed
46
  collection of abstract interfaces. Such a decoupling of the common
Kishen Maloor's avatar
Kishen Maloor committed
47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
  OCF standards related functionality from adaptations to any OS/target
  facilitates greater ease of long-term maintenance and evolution of
  the stack through successive releases of the OCF specifications.

- **Platform abstraction**: These are a collection of abstract interfaces
  with a small set of hooks to platform-specific features. These interfaces
  are defined in generic terms and elicit a specific contract from
  implementations. The core calls into these interfaces to interact with
  the underlying OS/platform. The simplicity and boundedness of these
  interface definitions allow them to be rapidly implemented on any chosen
  OS/target. Such an implementation then constitutes a "port". A number of ports
  (adaptations) currently exist for immediate use, and the project will
  continue to expand this set.

- **Support for static OR dynamic allocation of internal structures**:
  On environments with a C library that supports heap allocation functions,
  the stack can be configured at build-time to use dynamic memory allocation
Kishen Maloor's avatar
Kishen Maloor committed
64
  to operate without any pre-configured set of memory constraints.
Kishen Maloor's avatar
Kishen Maloor committed
65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80

  Alternatively, the stack may be configured to statically allocate all
  internal structures by setting a number of build-time parameters that
  constrain the number of serviceable connections and requests,
  payload sizes, memory pool sizes, timeouts etc.  These
  collectively characterize an acceptable workload for an application.

- **Lightweight design and low complexity**: This is achieved through
  the implementation of functionally cohesive modules, and weak coupling
  between stack layers.

- **Simple C APIs**: The APIs are defined so as to closely align to OCF
  specification constructs aiding greater ease of understanding. Application
  code utilizing these APIs are largely cross-platform as a consequence
  of the design, and can be quickly migrated over to a any other target
  environment.
81 82 83 84 85

Project directory structure
---------------------------

api/*
Kishen Maloor's avatar
Kishen Maloor committed
86 87
  contains the implementations of client/server APIs, the resource model,
  utility and helper functions to encode/decode
88
  to/from OCF’s data model, module for encoding and interpreting type 4
George Nash's avatar
George Nash committed
89 90
  UUIDs, base64 strings, OCF endpoints, and handlers for the discovery, platform
  and device resources.
91 92 93 94 95

messaging/coap/*
  contains a tailored CoAP implementation.

security/*
Kishen Maloor's avatar
Kishen Maloor committed
96
  contains resource handlers that implement the OCF security model.
97 98 99 100 101

utils/*
  contains a few primitive building blocks used internally by the core
  framework.

Kishen Maloor's avatar
Kishen Maloor committed
102 103 104
onboarding_tool/*
  contains the sample onboarding tool (OBT).

105 106 107 108
deps/*
  contains external project dependencies.

deps/tinycbor/*
Kishen Maloor's avatar
Kishen Maloor committed
109 110 111 112
  contains the tinyCBOR sources.

deps/mbedtls/*
  contains the mbedTLS sources.
113

Kishen Maloor's avatar
Kishen Maloor committed
114 115
patches/*
  contains patches for deps/mbedTLS and need to be applied once.
116 117

include/*
Kishen Maloor's avatar
Kishen Maloor committed
118
  contains all common headers.
119 120 121 122 123 124 125 126 127 128

include/oc_api.h
  contains client/server APIs.

include/oc_rep.h
  contains helper functions to encode/decode to/from OCF’s
  data model.

include/oc_helpers.h
  contains utility functions for allocating strings and
Kishen Maloor's avatar
Kishen Maloor committed
129 130
  arrays either dynamically from the heap or from pre-allocated
  memory pools.
131

Kishen Maloor's avatar
Kishen Maloor committed
132 133 134
include/oc_obt.h
  contains the collection of APIs for security onboarding
  and provisioning.
135

Kishen Maloor's avatar
Kishen Maloor committed
136 137
port/\*.h
  collectively represents the platform abstraction.
138

Kishen Maloor's avatar
Kishen Maloor committed
139 140
port/<OS>/*
  contains adaptations for each OS.
141 142 143 144

apps/*
  contains sample OCF applications.

145 146 147
service/*
  contains OCF services

Kishen Maloor's avatar
Kishen Maloor committed
148
Setup source tree
149 150
-----------------

Kishen Maloor's avatar
Kishen Maloor committed
151
Grab source and dependencies using:
152

Kishen Maloor's avatar
Kishen Maloor committed
153
``git clone --recursive https://github.com/iotivity/iotivity-constrained.git``
154

Kishen Maloor's avatar
Kishen Maloor committed
155 156
Building sample applications on Linux
-------------------------------------
157

George Nash's avatar
George Nash committed
158 159 160
The entire build is specified in ``port/linux/Makefile``. The output of the
build consists of all static and dynamic libraries, and sample application
binaries which are stored under ``port/linux``.
161

Kishen Maloor's avatar
Kishen Maloor committed
162
Run ``make`` for a release mode build without debug output.
163

George Nash's avatar
George Nash committed
164 165
Add ``SECURE=0`` to exclude the OCF security layer and mbedTLS. The security
layer is built by default.
166

Kishen Maloor's avatar
Kishen Maloor committed
167
Add ``DEBUG=1`` for a debug mode build with verbose debug output.
168

George Nash's avatar
George Nash committed
169 170 171 172 173
Add ``TCP=1`` to include support for TCP endpoints and CoAP over TCP (RFC 8323).

Add ``IPV4=1`` to include IPv4 support in the build. Excluding ``IPV4=1``
produces an IPv6-only build.

174 175 176
Add ``CLOUD=1`` to include OCF Cloud in the build. TCP and IPv4
are included too.

177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207
Building sample applications on Windows
---------------------------------------

A Visual Studio project file can be found in
``port/windows/vs2015/IoTivity-Constrained.sln``. Open the solution file in
Visual Studio 2015 or newer. If the version of Visual Studio is newer a prompt
should pop up asking if you would like to upgrade the visual studio project
files. Agree to upgrade the files.

Select the version of the samples you would like to build. Debug/Release,
x86/x64. From the ``build`` menu select ``Build Solution``.

The samples can be run from Visual Studio by right clicking on the
``SimpleServer`` or ``SimpleClient`` project from the Solution Explorer and
select ``Debug`` > ``Start new instance``. Or the binaries can be run from the
output folder ``port/windows/vs2015/{Debug|Release}/{Win32|x64}/``.

The build options are hard coded into the visual studio project. The project
defaults to using: dynamic memory allocation, OCF security layer is enabled and
built, and IPv4 support is included in the build.

To change the build options the properties page for each project must be modified
Right click on the project select ``Properties`` find 
``C/C++`` > ``Preprocessor`` > ``Preprocessor Definitions`` find the macro
associated with the feature you wish to enable or disable. For example to
disable the OCF security layer find and delete ``OC_SECURITY`` from the 
``Preprocessor Definitions``. The ``Preprocessor Definitions`` must match for
all projects for them to build and run. Due to the difficulty keeping all the
projects matching it is recommended to avoid modifying the
``Preprocessor Definitions`` unless necessary.

George Nash's avatar
George Nash committed
208
Note: The Linux, Windows, and native Android ports are the only adaptation layers
Kishen Maloor's avatar
Kishen Maloor committed
209
that are actively maintained as of this writing.
210 211 212 213

Framework configuration
-----------------------

214
Build-time configuration options for an application are set in ``oc_config.h``.
George Nash's avatar
George Nash committed
215
This needs to be present in one of the include paths.
Kishen Maloor's avatar
Kishen Maloor committed
216

George Nash's avatar
George Nash committed
217
Pre-populated (sample) configurations for the sample applications for all
218
targets are present in ``port/<OS>/oc_config.h``.