User Tools

Site Tools


resource_container

Resource container

The main purpose of the resource container is to:

  • Provide a framework of integration non-OIC protocols into the OIC ecosystem.
  • Dynamic loading of plug-ins (resource bundles). One resource bundle can contain multiple resource types. A bundle is activated by the container and then the bundle registers its resource at the resource container re-using the features of other resource encapsulation layer components.
  • It provides a common resource template and configuration mechanism for resource bundles. It deals with OIC specific communication features, and provides common functionalities in a generic way.
  • Provides features to activate and deactivate resource instance(s) dynamically on demand.

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.

Stakeholder

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.

Basic interaction flow

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

Android extension

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.

Resource bundle APIs and project templates

The IoTivity resource container dynamically loads resource definitions from external libraries. The library consists of multiple bundle resource classes which can represent either a software defined sensor or a protocol bridge resource. A protocol bridge resources maps the interaction between OIC-based communication and arbitrary protocols. Third-parties can use this mechanism to integrate their technologies in the OIC eco-system. A so-called bundle combines multiple resource type definitions. A bundle has to provide a bundle activator, which is responsible to create resource instances and to register the resource instances at the resource container. The container offers an API to retrieve the bundle and resource configuration and to register/unregister resources.

The resource container supports C++ and Java libraries. According APIs and project templates ease the development of bundles. The resource container can also be used on the Android platform, but in the current version only bundles of C++ native libraries can be loaded.

C++ Bundle APIs and Project Template

A C++ bundle is a shared object library (.so) which is dynamically loaded by the resource container. To create a C++ bundle the header files located in the resource-container/bundle-api folder have to be included by a bundle developer. A sample C++ template project is provided in resource-container/examples/HueSampleBundle. To create a bundle the header files of the bundle API need to be included. A bundle has then to provide a bundle activator and its resource definitions. A protocol bridge bundle shall further provide a connector.

Bundle configuration: The common format for the XML configuration of a bundle is given below.

<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>

The root element of the configuration is the container element which contains an arbitrary number of bundle elements specifying the configuration of bundles. For configuration of the bundle an id, path, activator ,version and resources need to be configured. The identifier should be a string uniquely identifying the bundle. A hierarchical naming scheme like a domain name is desirable but an arbitraty string can be chosen. The path references the local path of the bundle location relative to the executing application. The activator holds bundle specific information of the activation code that needs to be triggered if a bundle is started. For C++ bundles, this is a name prefix of a static activation function, for Java it is a class name.

The resources element encapsulates all resource specific information. A resource element covers here the configuration of a single resource instance. The bundle contains resource type specific classes that map the interaction for a specific protocol or soft sensor. The resource element provides all instance specific configuration. A bundle can contain multiple resources, and each resource is described with the resourceInfo element. Mandatory elements of the resource configuration are name and resourceType and resourceUri. In addition to the mandatory fields, arbitrary technology specific information for the resource can be included in the configuration file. A soft sensor resource could further provide resource configuration for inputs. In this case the resource container can take care to acquire the according data from the according input resources. Output attributes can either be listed in the configuration or programmatically inside the soft sensor implementation.

<resources>
  <resourceInfo>
    <name>DiscomfortIndexSensor1</name>
    <resourceType>oic.r.sensor</resourceType>
    <outputs>
      <output>
        <name>discomfortIndex</name>
        <type>int</type>
      </output>
      <output>
        <name>humidity</name>
        <type>double</type>
      </output>
    </outputs>
  </resourceInfo>  
</resources>

Project template

A project template to create a C++ resource bundle is given in “resource-container/examples/HueSampleBundle” A resource bundle has to define an activator, a connector and resource classes.

A resource bundle should implement the BundleActivator interface to define an activator. The following external functions also need to be defined, and trigger the creation and the execution of the activator. The prefix of the external functions should be the same as the activator described in the bundle configuration file.

extern "C" void huesample_externalActivateBundle(ResourceContainerBundleAPI *resourceContainer, std::string bundleId)
{
    bundle = new HueSampleBundleActivator();
    bundle->activateBundle(resourceContainer, bundleId);
}
 
extern "C" void huesample_externalDeactivateBundle()
{
    bundle->deactivateBundle();
    delete bundle;
}
 
extern "C" void huesample_externalCreateResource(resourceInfo resourceInfo)
{
    bundle->createResource(resourceInfo);
}
 
extern "C" void huesample_externalDestroyResource(BundleResource::Ptr pBundleResource)
{
    bundle->destroyResource(pBundleResource);
}

To define resource classes, the resource bundle should implement ProtocolBridgeResource and SoftSensorResource interface to define resources for each protocol bridge and soft sensor bundle.

Build instructions

To build the bundle API and a C++ resource bundle, include the header files of the bundle-api into a new project and provide the resource container library. Scons can be used to create a resource library. The Sconscript of the resourceContainer shows how to build a resource bundle.

Java bundle APIs and project template

A Java bundle offers the capability to reuse existing Java-based communication libraries and integrate your protocols. The Java bundle mechanism can also be used in an Android environment. A Java bundle developer only needs to take care about the mapping between the OIC resource representation and the integrated technology. The required interfaces to create a Java bundle can be found in the resource-container/bundle-java-api directory. The API consists of a set of interfaces and abstract classes. Most important is the BaseActivator class, which has to be extended by a bundle provider. It offers the methods for retrieving configuration parameters and for resource registration. The second important abstract class is the BundleResource. A developer has to extend this class for concrete resource types and implement the mapping for reads and writes on the resource attributes.

Project Template

A Java example project template is provided in the folder examples/HueJavaSampleBundle/hue. To create a new Java bundle, copy this folder and modify the Maven pom.xml. Source files can be put in an arbitrary package.

Build instructions

For building the Java Bundle APIs and the bundle projects the Maven build system is used.

Note (using Maven behind firewall or proxy): 
If you are behind a firewall or proxy it might be required to ease the security settings. Provide the following parameters to your Maven commands if external dependencies are downloaded.
-Dmaven.wagon.http.ssl.insecure=true
-Dmaven.wagon.http.ssl.allowall=true
-Dmaven.wagon.http.ssl.ignore.validity.dates=true

Bundle API

First step is to build the Java Bundle API.

resource-container/bundle-java-api> mvn compile
resource-container/bundle-java-api> mvn install

This compiles the bundle api and installs it in the local maven repository. All bundle projects can use the library then. A project can include declare a dependency on the Java bundle API. An example pom.xml can be found in the resource-container/examples/HueJavaSampleBundle folder.

Java resource bundle

To build a Java bundle all dependencies need to be included. In order to package all dependencies the assembly plugin is used.

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.

Working 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.txt · Last modified: 2016/03/25 05:55 by Markus Jung