User Tools

Site Tools


resource_container_-_programming_guide

The resource container is a component that can dynamically load resource definitions. The resource definitions are grouped together in resource bundles. A typical use case is to provide translations to external protocols and to make 3rd party devices or services available as OIC resource servers.


Use Cases

The main use case of the resource container is acting as a bridge to non-OIC ecosystems. The container runs on a bridge device and can be configured to load resource bundles, which map non-OIC devices. The container creates OIC resource server, that OIC clients can use to access the non-OIC resources.

The resource container is a component used by many different stakeholders. The main stakeholders are device manufacturers that provide a device bridge to other technologies, a bundle provider providing bundles that map other technologies to IoTivity or offer software-defined resources (e.g. algorithms, sensor fusioning), system integrator or end-user which configure the resource container and its bundles for a concrete environment. For an application developer the resource container is transparent and the developer has only to adhere to the OIC specified interfaces. A stakeholder overview is given in the following figure.


Features

  • Ordered List ItemDynamically load/unload protocol plugins or soft sensors organized in pluggable software components (so called bundles)
  • Make non-OIC resource into OIC resources
  • Load non-OIC resource on-demand
  • Multi-platform support (Linux, Tizen, Android)
  • Common configuration mechanism (structured configuration can be provided for bundles)
  • C++ and Java bundles
  • Code-isolation (component-orientation), enable the loading of multiple versions of a library (e.g. comparable to OSGi component container)
  • Provide templates for soft-sensors and protocol bridge resources
  • Provide dependency injection for inter-resource dependency (e.g. Resource A requires some properties of Resource B) – comparable to existing soft-sensor manager functionality

Architecture

The figure below illustrates the architecture of the resource container. It offers a container API that can be used to start the container. A common XML configuration file is used for all resource bundles. The configuration contains parameters specific to the bundle but also to every resource instance. A resource bundle contains an activator and bundle resources. A bundle resource can be the definition of a soft sensor(= logical sensor, virtual sensor) resource that contains an algorithm to derive new knowledge and offer it as a resource and protocol bridge resources which map other technologies to OIC resources. The bundles only contain the mapping logic, whereas the actual creation of OIC resource servers happens in the resource container. The bundle provider is agnostic of the base and resource encapsulation layer APIs of IoTivity and only needs to adhere to the bundle API.

The interaction flow for the activation of a bundle is shown in next figure.

The resource container comes with an extension for the Android platform that enables the usage of native bundles to be loaded within an Android application, as well as the loading of Android based bundles. The main difference between native bundles and Android bundles is the availability to access the Android APIs based on the application context. The design of the extension is illustrated in the figure below. The core is a wrapper layer provided as .aar library, offering the APIs to control the resource container which runs in the native code and the interface to the bundle APIs. The main advantage of using the resource container on Android is to only depend on the resource container libraries to define a resource on Android. For a bundle developer, there is no dependency to the IoTivity base libraries. Further, the bundles can be provided as standalone .jar files and an Android application running the container can load these bundles based on the configuration. Resource bundles based on .jar files are loaded by the application that starts the resource-container. Therefore, all bundles share a common application process and common security permissions.

API

The APIs of the resource container can be used to start the container configured with the path to an XML configuration file. The configuration file describes the available resource bundles and the resouce instance configuration.

A dynamic configuration API is provided to add/remove bundles and resources during runtime.

Sample applications

Linux

A sample application demonstrates the resource container. Example bundles and a configuration is provided. The configuration can be found in the examples folder and a snippet of the XML file is shown below. You can inspect the configuration to see how to configure bundles to be loaded by the resource container.

…
<bundle>
      <id>oic.bundle.hueSample</id>
      <path>libHueBundle.so</path>
      <activator>huesample</activator>
      <version>1.0.0</version>
      <resources>
          <resourceInfo>
              <name>light</name>
              <resourceType>oic.r.light</resourceType>
              <address>http://192.168.0.2/api/newdeveloper/lights/1</address>
          </resourceInfo>       
      </resources>
</bundle>
…

First run the ContainerSample:

~/[release-folder]/service/resource-container/ $ ./ContainerSample

The resource container starts. Follow the instructions and press [ENTER] to see the demonstration of how bundles get loaded, stopped, activated and the whole container gets stopped. After the container is started you can execute in parallel the ContainerClientSample, which executes the test requests against container provided resources. To execute the ContainerSampleClient run:

~/[release-folder]/service/resource-container/ $ ./ContainerSampleClient

Tizen

This sections covers the Tizen Sample Applications of Resource Container module.

Work Flow

This section describes the working flow of the ContainerClientApp and ContainerServerApp Tizen Applications.

ContainerServerApp show the functionalities provided by Resource Container module. ContainerClientApp is to discover the resource created by ContainerServerApp.

Build and import procedure

  • Import ContainerServerApp and ContainerClientApp applications from the given path : “service\resource-container\examples\tizen” to Tizen IDE.
  • To import projects in tizen IDE, Go to File → Import → Tizen → Tizen Native Projects.
  • Create a lib folder in ContainerClientApp and ContainerServerApp projects (if not present) and copy the required libraries (mentioned below) extracted from the generated RPM package
  • Required libraries for ContainerServerApp and ContainerClientApp are “liboc.so, liboctbstack.so, libuuid.so, liboc_logger.so, liboc_logger_core.so, libconnectivity_abstraction.so, librcs_client.so, librcs_common.so, librcs_container.so, librcs_server.so, libboost_date_time, libboost_system and libboost_thread”.
  • Additional libraries required for ContainerServerApp are : libHueBundle.so, libDISensorBundle.so and libBMISensorBundle.so. These libraries also should be added in the lib folder.
  • Specify the path of the unzipped boost libraries in ContainerServerApp and ContainerClientApp projects in the way given mentioned below. (Unzip the boost libraries if not done already)
  • Right click the project in IDE → Properties → expand C/C++ Build → Settings → Tool Settings → select includes option under C++ Compiler → add the path of the unzipped boost libraries in the include paths area → Apply → OK.
  • Clean and build ContainerServerApp and ContainerClientApp projects and launch the applications in Tizen 2.3 device.

Run the application

Running the ContainerServerApp provides two options on the home screen:

  1. Start container
  2. Stop container

On selecting the start container options, it trigeers the container to start with default bundle provided in the configuration file. Once the container has started successfully the remaining container option is displayed to test the resource container APIs. The following images show the homescreen of the application and screen for container APIs.

Note : In sample application we have the configuration file (.xml) with hue bundle.

The remaining container APIs can be tested now as the container has been successfully started. On selecting the first option i.e. List Bundles, it displayes the list of all bundles in the container.

On selecting the option for List Hue resources, it displayes all resources added to the Hue bundle. Since we have not added amy resources it displayes the resource bundle size as 0.

Using the Add HUE Bundle Resource option, light resources can be added to the HUE bundle. On selecting this option a new resource is created and added.

Using the Add HUE Bundle Resource option, light resources can be added to the HUE bundle. On selecting this option a new resource is created and added. The following logs will be displayed.

Hue Bundle is added and started by default on starting the container. Addition bundles can also be added to the container. These APIs can be tested using the add and start bundle options. ‘Add BMI bundle’ and ‘Start BMI bundle’ options in the applications add a BMISensorBundle to the already started resource container. On selecting the ‘Add BMI bundle’ option first and then ‘Start BMI bundle’ option, BMISensor bundle is added to the container.

We can verify the authenticity by checking the list of bundles of the container. This can be done using the first option ‘List Bundles’.

Here we can see the bundle list size has increased and BMISensor bundle has been added to the container. Now similarly to stop and remove a bundle from the container, stop bundle and remove bundle options can be used. The ‘Stop BMI Bundle’ and ‘Remove BMI Bundle’ options will stop and remove the BMISensor bundle if added to the container.

The container can be stopped using the stop container button on the top right hand corner of the screen. Selecting this button automatically removes all bundles added to the container and stops the container. If the container is not yet started then this button has no effect what so ever.

ContainerClientApp provides the feature to discover the resource created by ContainerServiceApp. Running the ContainerClientApp provides only one option to start the container client. On selecting the start container client option new menu is shown.

If Resources have been created by the ContainerServiceApp, is can be discovered by this application. If a light resource discovery is to be made, selet the ‘Start light resource Discovery’ option to begin the discovery request. If the a light resource is running in the same network it will get a callback.

Once the desired resource has been found, the discovery request can be terminated by selecting the ‘Stop Discovery’ option. Once the discovery has been canceled, we will get a list of all the resources discovered to select from for our use. Similarly discovery can be made for a soft sensor resource also.

Android

This sections covers the Android Sample Applications of Resource Container module.

Working Flow

This section describes the working flow of the RCSampleClientApp and RCSampleServerApp Android Applications.

This section describes the working flow of the RCSampleClientApp and RCSampleServerApp Android Applications. RCSampleServerApp show the functionalities provided by Resource Container module. RCSampleClientApp is to discover the resource created by RCSampleServerApp. AndroidBundle is a sample bundle for android with several bundle resources

Build and import procedure

  • Import RCSampleClientApp, RCSampleServerApp and AndroidBundle applications from the given path : “{Iotivity_root} /service/resource-container/examples/android” to Android studio.
  • To import projects in Android Studio, Go to File → Open.
  • Create ‘libs’ folder in app folder each of RCSampleClientApp and RCSampleServerApp projects (if not present) and copy the required libraries.
  • iotivity-base-{TARGET_ARCH}-{MODE}.aar located in {Iotivity_root} /android/android_api/base/build/outputs/aar
  • iotivity-{TARGET_ARCH}-service-{MODE}.aar located in {Iotivity_root} /service/resource-encapsulation/android/service/build/outputs/aar
  • copy the below libs to ‘libs’ folder in app folder of RCSampleServerApp and AndroidBundle
  • iotivity-{TARGET_ARCH}-resource-container-{MODE}.aar located in {Iotivity_root} /service/resource-container/android/resource-container /build/outputs/aar
  • iotivity-{TARGET_ARCH}-resource-container-{MODE}.aar located in {Iotivity_root} /service/resource-container/android/resource-container /build/outputs/aar
  • libBMISensorBundle.so
  • libDISensorBundle.so
  • From : {Iotivity_root}/out/android/{TARGET_ARCH}/{MODE}/ where TARGET_ARCH is a build option for scons of iotivity and where MODE is release or debug.
  • Clean and build example projects and launch the applications.

Android Bundle

  • Execute the gradle jar task
  • Run the dx tool (Android platform tool) on the .jar in order to transform the classes for the Dalvik VM: dx –dex bundle.jar
  • Copy the resulting .jar file into the libs folder of the RCSampleServerApp

Running applications

  • First Run the RCSampleServerApp, and press START CONTAINER.
  • LIST BUNDLES will show the list of the bundles that the Container started with.
  • Note : In sample application we have the configuration file (.xml) with one bundle. It will create a resource of type oic.sensor. To discover the resource press “DISCOVER ESOURCE” button on RCSampleClientApp. The following logs will be shown on the Client app.\
  • User can press the option 1 and 2 of each bundle in the list to “Add and Start bundle”. Registered bundle resources will be listed with option 3.
  • Press option 4 “Stop Bundle” to stop the Bundle. If user stops the bundle all the resources that are added to bundle will be removed. Press option 5 “Remove Bundle” to remove the bundle.
resource_container_-_programming_guide.txt · Last modified: 2016/05/16 07:15 by Markus Jung