User Tools

Site Tools


soft_sensor_manager_for_linux

Soft Sensor Manager

The following sections provide interaction details for SoftSensorManager (SSM) and how it helps in receiving data from various sensors. The intent of this information is to help developers understand how to use the SDK APIs and how the SSM works to support the APIs.

The first part, the SDK API, describes how an application can use the SSM. We provide an Ubuntu*-based sample application that includes the functionality of registering and unregistering query statements to get sensor data.

The next part, SSM Architecture and Components, describes how the main operations of the SDK API operate in the SSM. In this part, the architecture of SSM is presented and the components in the architecture are described in detail.

In the third part, SSM Query Statement, a query language called CQL is explained with several examples. The query language is the language used in SSM for applications to get sensor data.

Finally, the Soft Sensor part explains how developers can implement a soft sensor and deploy it in the SSM. An example of SoftSensor, the DiscomfortIndexSensor (DISoftSensor), is provided.

Terminology


Physical Sensor App

A Physical Sensor App is a software application deployed in an open hardware device, such as an Arduino* board where the device has hardware sensors such as temperature, humidity, or gyro sensors.

This application gets physical sensor data from the hardware board and sends the sensor data to other devices using the IoTivity Base framework.

Soft Sensor (= Logical Sensor, Virtual Sensor)

A Soft Sensor is a software module that presents user-defined sensor data.

The soft sensor:

  1. Collects sensor data from the physical and/or other soft sensors,
  2. Manipulates the collected sensor data by aggregating and fusing it based on its own composition algorithms, and
  3. Provides the manipulated data to applications.

Soft Sensor Manager (SSM)

The Soft Sensor Manager is a software service that receives query statements about physical and logical sensors from applications, executes the queries, and returns results to the application through the Iotivity Base.

A more detailed description of the Soft Sensor Manager and its relevant components is provided later in this document.

SDK API


The SDK API is the application facet of SSM. It includes SSMClient and ISSMClientListener as shown in Figure 1.

Figure 1. SoftSensorManager SDK APIs and Application

SSMInterface

This class provides APIs for applications to send sensor data requests to SSM, and to receive the requested sensor data from it. Requests are in a query statement.

For an example, if we have a soft sensor providing an indoor discomfort index, called DiscomfortIndexSensor (DISoftSensor), the DISoftSensor provides different index levels as follows:

  • ALL_FEEL_COMFORT
  • BEGIN_TO_FEEL_UNCOMFORTABLE
  • HALF_OF_YOU_FEEL_UNCOMFORTABLE
  • ALL_FEEL_UNCOMFORT

So, we can make a query statement for a request to SSM:

subscribe DISoftSensor if DISoftSensor.level = BEGIN_TO_FEEL_UNCOMFORTABLE

Which means, the application wants SSM to send DISoftSensor data when the condition, DISoftSensor.level = BEGIN_TO_FEEL_UNCOMFORTABLE, is satisfied. Therefore, there can be a time difference between the time the application sends the request and the time the application receives the return because the SSM sends back the return to the application only if the condition is satisfied.

In the client, there are two main operations:

  • registerQuery()
  • unregisterQuery()

The first operation, registerQuery(), is to register the query statement to the SSM. After a successful response message for the registration, the SSM sends the event to the client when the query is satisfied as previously explained.

The second operation, unregisterQuery (), is to unregister the previously registered query to SSM. The SSM will not send any further message after successful unregistration.

The query statement is described in detail later.

ISSMClientListener and Application

This is an interface class for the application which has sent a query statement to get the return from the SSM asynchronously.

The precondition for the callback listening is as follows:

  • The Application should implement the pure virtual function.
        class SSMTestApp: public IQueryEngineEvent
        {
        private:
          SSMClient m_SSMClient;
     
        public:
     
          SSMTestApp();
     
          void onQueryEngineEvent(int cqid, IDataReader *pResult);
     
          . . .
        }
     
  • The Application should send the pointer of the Application when it calls the registerQuery(), so that the SSMClient can get the callback pointer.
        void SSMTestApp::registerQuery()
        {
          .
          rtn = m_SSMClient.registerQuery(std::string(l_queryString), this, l_qid);
          .
        }
     
        SSMReturn::SSMReturn SSMInterface::registerQuery(std::string queryString, IQueryEngineEvent *listener, std::string &cqid)
        {
          .
          .
     
          m_appListener = listener;
          .
          .
        }
     

Once the SSMInterface receives the return from SSM, it calls m_appListener→ onQueryEngineEvent () so that the Application can get the callback from the SSMInterface.

The onQueryEngineEvent() has two parameters, std::string modelName and IModelData *ppModelData. The model in this context means the soft sensor, so the model data means the output data of the soft sensor which was requested. Since the ouput data of the softe sensor can be more than one, it is encapsulated with classes called IDataReader and IModelData. That is, the onQueryEngineEvent() provides a reference of IModelData, which provides getModelData() with which soft sensor output data (i.e. ModelData) can be accessed as property name and property value.

IDataReader

Operation Name Parameter/Return Function
getAffectedModels P std::vector<std::string> *pAffectedModels
- [OUT] affected ContextModel list
Get affected ContextModels. The CQL can specify multiple ContextModels for retrieving data.
R SSMRESULT
getModelDataCount P1 std::string modelName
- affected ContextModel name
Get affected data count. There are multiple data can exist from given condition.
P2 int *pDataCount
- [OUT] affected dataId count
R SSMRESULT
getModelData P std::string modelName
- affected ContextModel name
Get actual Context Model data

IModelData

Operation Name Parameter/Return Function
getDataId P Get affected DataId. ContextModel has plenty of data so returned data is matched from given condition
R Int
getPropertyCount P ContextModel has at least one property that contains data property is described from its specification.
R Int
getPropertyName P int propertyIndex
-Index of property to read
Retrieve propertyName
R std::string
getPropertyValue P int propertyIndex
- index of property to read
Retrieve propertyValue
R std::string
getPropertyValueByName P std::string propertyName
- property name to search value
Retrieve propertyValue using given name
R std::string

SSM Architecture and Components


Context Diagram

The SSM service operates in the Iotivity Base messaging environment as shown in Figure 2.

Figure 2. SSM Context Diagram

There are two different types of interactions with SSM:

  • Interactions between the Application and the SSM
  • Interactions between the SSM and the physical sensors

For the first interaction, the SSM provides the SSM SDK API described in the previous section which hides the details of the Iotivity Base and provides a simple operation set in C++.

The second interaction is implemented within a resource model where a physical sensor is registered as a Resource in the Base and the SSM observes the resource by using the APIs provided by the Base.

SSM Architecture

The SSM service between applications and physical sensors consist of three main components: SSMInterface, QueryProcessor, and SensorManager, as shown in Figure 3. Figure 3. SSM Architecture

SSMInterface is an interface to the application (SSMClient) where it can receive requests from it and send response to it via callback. The SSMInterface includes two main components: SSM Resource Sever and SSM Core Manager. The SSM Resource Server is a wrapping class to communicate with SSMClient, and the SSM Core Manager is an interface class communicating with the Query Processor component.

QueryProcessor is a processing engine to get query statements, parse the statements, extract conditions and register conditions from the statements. It also monitors the registered conditions whether they are satisfied or not. Once satisfied, it sends the notification to the SSM Core Manager. It includes two main components, Query Engine and Propagation Engine. The Query Engine component is responsible for parsing the query statements and extracting conditions. The Propagation Engine component gets the conditions and registers them in the database (DB). It also registers the triggers to the database, so that the DB initiates the callback when a conditions are satisfied.

Sensor Manager is a component to maintain the registered Soft Sensors and collect physical sensor data required by the Soft Sensors. A Soft Sensor needs to be deployed in the share library form (*.so) with a manifest file (*.xml) describing the structure of the sensor to register Soft Sensors. Soft Sensor and its deployment is described in the fourth section. To collect physical sensors, there is a SensorResourceFinder class that finds specific resources, and registers an Observer into the resources found. It allows the physical sensor to send its sensor data when there is a change in the state or data.

SSM Query Statement


In query statements, a target model called ContextModel provides data for applications. In a device, there are three different types of context models; Device, SoftSensor, and PhysicalSensor.

The Device Context Model corresponds to the device the SSM deployed and provides three properties: UDN, Name, and Type. The UDN contains a 128bit length unique key value, the Name represents device's own name like 'My Phone', and the Type is the device's attribute (such as Mobile, TV, and PC).

Every Context Model includes dataId with which applications can access the Context Model data directly. For example, if the Device Context Model contains five data, you can access 4th device information like Device.dataId = 4

Soft sensors and physical sensors generally have their own structures and the Context Models of the sensors are generated with manifest files (*.xml) that are packaged together with the sensors.

Context Query Language (CQL)

The grammar of the CQL is as shown here:

[Command]

There are two commands provided: Subscribe and Get.

The Subscribe keyword is used for an asynchronous query request that is affective till cancel the registered query statements. That is, the result can be delivered to clients several times whenever conditions are met. The Get keyword is similar to Subscribe, but the result data is delivered only once.

One of main differences between the Subscribe and the Get command is number of callback calls and the inclusion of cached data. The result of Subscribe contains cached data at the execution time and new data after execution untill the query statement is unregistered. The Get command returns the most recent data only one time.

[ContextModel]

It is the part that application developer describes what Context Model data to retrieve for running result of CQL. The application developer can use comma (',') to retrieve multiple Context Models.

The Context Model can be defined refer to CQL's [Condition] part description. For example, if [Condition] part is described as 'Device.EPG.CurrentInfo.value != “null”' then [ContextModel] can hold Device, Device.EPG, Device.CurrentInfo Context Models.

If [Condition] part is described to combine conditions as 'Device.EPG.value != “null” and Device.EPG.CurrentInfo.value != “null”' using 'and' keyword, the [ContextModel] part can hold Device, Device.EPG Context Models because these two things are the only intersection of the two conditions.

[Condition]

It is used for application developers to search and trigger data using conditions. The [Condition] grammar is as shown below: The [property] part represents output properties of the [ContextModel]. Basically, every Context Model has 'dataId'(i.e.property). The [ContextModel] part must be declared with its parent [ContextModel] names. The [comparator] field can hold six operators like = (==), !=, >, >=, <, <=. The [value] field is set value for comparison. The following [value] types are possible: integer, float, double, text, Boolean and text, Boolean must be capsulated using double quotes.

Ex:) Device.LiftUpSmartPhone.status = “true” or Device.type = “Mobile”

Examples of CQL Statements

subscribe Device if Device.type == "Mobile"

When the Mobile Device appears on the network, inform us of device information to satisfy this condition.

subscribe Device if Device.type == "TV" and Device.NumberOfPeopleWatchingTV.number > 2

When conditions are that the type of Device is “TV” and the value of the NumberOfPeopleWatchingTV is greater than 2, it appears to satisfy this condition. Inform us of Device information to satisfy this condition.

subscribe if Device.LiftUpSmartPhone.value == "true" and Device.NumberOfPeopleWatchingTV.number > 0

For peripheral devices, when conditions are that the Device's value of LiftUpSmartPhone is “true” and the Device's number of NumberOfPeopleWatchingTV is greater than 0, if the Device appears to satisfy conditions inform us of Device information. (Device is common [ContextModel] of [Condition])

Get Device if Device.BatteryStatus.percentage > 50

If Battery's percentage is greater than 50, inform us of Device information.

Get Device if Device.PhoneTodaySchedule.title = "study" and Device.UserAtHome.value = "true"

For peripheral devices, If the Device's title of the PhoneTodaySchedule is “study” and the Device's value of UserAtHome is “true”, inform us of Device information to satisfy this condition.

Get Device. PhoneGPS[2]

Inform us of PhoneGPS information that dataId is 2. (Always the lowest [ContextModel] only have Index. “Get” Query containing index doesn't use to if-clause (a conditional sentence))

Subscribe Device if Device.CallStatus.callername = "lee" and Device.type = "TV"

When callername is “lee” and type is “TV”, inform us of Device's information.

Subscribe Device.TVZipcode if Device.TVZipcode.value != "null" and Device.dataId = 3

If TVZipcode's value is not “null” and Device's dataId is 3, inform us of TVZipcode's information.

Get Device.BatteryStatus[1]

Inform us of BatteryStatus information that dataId is 1. (If the appropriate data don't exist, do nothing.)

Get Device.UserAtHome if Device.UserAtHome.value = "true"

If UserAtHome's value is “true”, inform us of UserAtHome's information (If the appropriate data don't exist, do nothing.)

Subscribe Device if Device.LiftUpSmartPhone.value = "true" and Device.PhoneGPS.latitude != 20

If Phone's status is “LiftUp” and PhoneGPS's latitude is not 20, inform us of Device's information.

Subscribe Device if Device.BatteryStatus.percentage >= 50 and Device.LiftUpSmartPhone.value = "true"

If BatteryStatus's percentage is greater than or equal to 50 and Phone's status is “LiftUp”, inform us of Device's information.

Soft Sensor


Soft sensor, also called Virtual sensor or Logical sensor, is a software component which gets physical sensor data and generates a higher abstraction level of sensing data by data aggregation and fusion. This part shows how to develop a soft sensor, deploy in the SSM, and use the deployed soft sensor.

Development

SSM loads a share library, (*.so) as an soft sensor unit. A soft sensor should be developed and deployed as an share library which includes the entry operation, defined in the Interface, ICtxEvent.

Soft Sensor Definition: a soft sensor consists of three main elements; input data, output data, and execution logic. To be deployed in SSM the three elements can be implemented as follows:

Input data: the required data by the target soft sensor and it is generally the sensor data from physical sensors. For example, DiscomfortIndexSensor requires temperature sensors and humidity sensors as inputs. Output data: the result of data fusion by the target soft sensor. The unit of the output data should be different from the types of soft sensors.

In SSM, the main properties of Soft Sensor, name, input, output, should be described in a manifest file (i.e. HighContextDictionary.xml).

Here is an example of DiscomfortIndexSensor:

For the root_name, it is referred in the query statement from applications. It is also used for SSM to load the share library (*.so). It should be the same as the name of the share library file.

<softsensors>
 
  <softsensor>
    <name>DiscomfortIndexSensor</name>
    <attributes>
      <attribute>
        <name>version</name>
        <type>string</type>
        <value>1.0</value>
      </attribute>
      <attribute>
        <name>lifetime</name>
        <type>int</type>
        <value>60</value>
      </attribute>
    </attributes>
    <outputs>
      <output>
        <name>timestamp</name>
        <type>string</type>
      </output>
      <output>
        <name>temperature</name>
        <type>string</type>
      </output>
      <output>
        <name>humidity</name>
        <type>string</type>
      </output>
      <output>
        <name>discomfortIndex</name>
        <type>int</type>
      </output>
    </outputs>
    <inputs>
      <input>Thing_TempHumSensor</input>
      <input>Thing_TempHumSensor1</input>
    </inputs>
  </softsensor>
 
</softsensors>

The physical sensors required by the target soft sensor can be specified in this tag for inputs. Moreover, it can be not only physical sensors but also soft sensors.

Execution Logic: with the input data, Soft sensor generates the output, based on its own algorithm. It should be developed as a software code, in SSM, a class as shown in the DiscomfortIndexSensor example.

Soft sensor calls should implement the ICtxEvent interface which provides the OnCtxEvent() operation, as a pure virtual operation. In SSM, the operation is called by CContextExecutor class right after the class loads the soft sensor's .so file, and when the SSM receives sensor data from physical sensors.

The OnCtxEvent operation requires two input parameters, eventType, contextDataList as follows:

  • eventType: It is the time point the onCtxEvent() called by SSM and includes three types, SPF_START, SPF_UPDATE, and SPF_END, where SPF_START is the time when the soft sensor library is loaded, and currently SSM only uses this option.
  • contextDataList: it is the input value the soft sensor required and it is provided as an attribute map (key,string) of the sensor data from the physical sensors specified in the input tag in the manifest file. That is, SSM, CContextExecutor generates the attribute map of the input data and delegates to the soft sensor when it calls the OnCtxEvent().
        class ICtxEvent
        {
        public:
          virtual void OnCtxEvent( enum CTX_EVENT_TYPE, std::vector) = 0 ;
          virtual ~ICtxEvent(){};
        };
     
        class DiscomfortIndexSensor: public ICtxEvent
        {
        private:
     
          int RunLogic(std::vector< ContextData > &contextDataList);
     
        public:
          DiscomfortIndexSensor();
     
          void OnCtxEvent(enum CTX_EVENT_TYPE eventType,
                std::vector< ContextData > contextDataList);
          .
          .
        };
     
soft_sensor_manager_for_linux.txt · Last modified: 2016/06/23 09:24 by Phil Coval