Difference between revisions of "OM2M/one/DeveloperSDT"

Latest revision as of 09:12, 14 September 2017

Develop an Interworking Proxy Application Entity (IPE) with SDT

This chapter shows how to write an application similar to that described in Develop an IPE Plugin, but using the SDT format.

Introduction to SDT

SDT (Smart Device Template) is a device abstraction initially designed by the Home Gateway Initiative and introduced in oneM2M Release 2 (TS-0023: Home Appliances Information Model and Mapping).

In a nutshell, SDT defines a data structure composed of Device objects, made of optional or mandatory functional units (Modules) that are composed of readable and/or writable data points.

As an example, a Light device contains a mandatory module BinarySwitch that has one boolean datapoint powerState. Turning on the light consists in writing this datapoint: light.getBinarySwitch().setPowerState(true).

The Light device also contains optional modules for controlling the saturation or the color, for physical devices that do support these features.

The TS-0023 document also specifies how these data structures are mapped into the oneM2M resource tree, using the concept of flexContainers introduced in the release 2 of oneM2M TS-0001 (section 9.6.35).

Plugin Development

Basically, the first steps to create such an application are identical to the ones described in Add a new plug-in to OM2M, except for dependencies: you don’t need to import/require any org.eclipse.om2m... bundle, but need to integrate the org.eclipse.om2m.sdt and org.eclipse.om2m.sdt.home packages:

Import-Package: org.apache.commons.logging,
 org.eclipse.om2m.sdt,
 org.eclipse.om2m.sdt.datapoints,
 org.eclipse.om2m.sdt.events,
 org.eclipse.om2m.sdt.exceptions,
 org.eclipse.om2m.sdt.home,
 org.eclipse.om2m.sdt.home.actions,
 org.eclipse.om2m.sdt.home.devices,
 org.eclipse.om2m.sdt.home.driver,
 org.eclipse.om2m.sdt.home.modules,
 org.eclipse.om2m.sdt.home.types,
 org.osgi.framework

The Lamp object now becomes an extension of the Light device as defined in the Home Appliances document (TS-0023):

SDT Lamp

package org.eclipse.om2m.ipe.sample.sdt.model;

import java.util.List;

import org.eclipse.om2m.sdt.Domain;
import org.eclipse.om2m.sdt.datapoints.IntegerDataPoint;
import org.eclipse.om2m.sdt.exceptions.DataPointException;
import org.eclipse.om2m.sdt.home.devices.Light;
import org.eclipse.om2m.sdt.home.driver.Utils;
import org.eclipse.om2m.sdt.home.modules.ColourSaturation;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceRegistration;

public class Lamp extends Light {

	private List<ServiceRegistration> serviceRegistrations;

	public Lamp(String id, String serial, Domain domain, BundleContext ctxt) {
		super(id, serial, domain);

		// Module ColourSaturation
		addModule(new ColourSaturation("colourSaturation_" + id, domain, 
			new IntegerDataPoint("colourSaturation") {
				private Integer v = new Integer((int)(Math.random() * 100));
				@Override
				public void doSetValue(Integer val) throws DataPointException {
					v = val;
				}
				@Override
				public Integer doGetValue() throws DataPointException {
					return v;
				}
			})
		);

		// Module BinarySwitch
		addModule(new SampleBinarySwitch("binarySwitch_" + id, domain));

		// Module Colour
		addModule(new SampleColour("colour_" + id, domain));

		setDeviceModelName("Fake lamp as SDT Light");
		setDeviceName("SDT Light");
		setLocation("Kitchen");
		setDeviceManufacturer("OM2M");
// Register this object as an OSGi service.
		serviceRegistrations = Utils.register(this, ctxt);
	}

}

This application works in conjunction with the org.eclipse.om2m.ipe.sdt module.

34      ACTIVE      org.eclipse.om2m.ipe.sample.sdt_1.0.0.20170111-1455
35      ACTIVE      org.eclipse.om2m.ipe.sdt_1.0.0.20170111-1455

The principle is to create a SDT device (here a org.eclipse.om2m.sdt.home.devices.Light), register it as an OSGi service, and the IPE SDT module will discover it and create in the oneM2M resource tree a flexContainer device in the IPE_SDT Application Entity:

The properties of the device are attributes of the corresponding flexContainer (e.g. cntDef or propLocation). The device modules are flexContainer children, with their datapoints represented as attributes of the corresponding flexContainer. See for instance the Light device’s Color module in the tree:

IPE Activator

• The Activator class contains the implementation of the start() and stop() method used to activate and deactivate the IPE plugin.
• In the start() method, the Activator registers the IPE Controller service on the registry to make it available for the CORE plugin. Then, it starts tracking the CORE CSE service to use it once the CORE plugin is activated.
• In the Stop() method, the Activator can execute some process to make a clean before deactivation such as stopping threads, handle exceptions, etc. In our case, we stop the Monitor that has a set of thread that must be handled.

package org.eclipse.om2m.sample.ipe;
 
//import org.eclipse.om2m.core.service.CseService;
//import org.eclipse.om2m.interworking.service.InterworkingService;
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.ServiceReference;
import org.osgi.util.tracker.ServiceTracker;
 
public class Activator implements BundleActivator {
 
	private static BundleContext context;
 
	private Monitor monitor;
 
	static BundleContext getContext() {
		return context;
	}
 
	public void start(BundleContext bundleContext) throws Exception {
		Activator.context = bundleContext;
		System.out.println("Starting Sample Ipe");
		// No need to use the CSE service
		// new ServiceTracker<Object, Object>(bundleContext, 
		//	CseService.class.getName(), null){ ... }
 
 		// No need to register as InterworkingService
		// bundleContext.registerService(InterworkingService.class.getName(), 
		//	new Controller(), null);
 
	}
 
	public void stop(BundleContext bundleContext) throws Exception {
		Activator.context = null;
		System.out.println("Stopping Sample Ipe");
		If (monitor != null){
			monitor.stop();
			monitor = null;
		}
	}
 
}

IPE Monitor

• The Monitor class creates one sensor AE called "MY_SENSOR", and one actuator AE called "MY_ACTUATOR". It creates two containers for each applications: "DESCRIPTOR" container to store the description and "DATA" container to store the measurements. For each container the right oBIX XML payload is created as contentInstance.
• The Monitor starts two threads to listen to each application data as well. Once a new data is detected, the Monitor creates a new contentInstance including the measurement representation.
• Another method is available to stop the monitor and linked threads.

Resources are created in the oneM2M tree by the IPE SDT module.

IPE oBIX Util

• Convert the description and the measured data of the device to oBIX XML representation.

No need to use oBIX format, devices and their modules and data points are directly Java objects.

IPE Controller

• Execute received requests from OM2M to the specific technologies.

No need to receive explicit oneM2M requests.

IPE Util: RequestSender

• This class simplify the interaction with the CseService providing the response of specific requests directly. You can take inspiration of this class if you want to create your own request utility/factory.

No need to send explicit oneM2M requests. Reading / writing values from the device is just accessing the desired datapoint, e.g. reading the state on/off:

	public boolean getLampValue(String id) throws DataPointException, AccessException {
		return getLamp(id).getBinarySwitch().getPowerState();
	}

Or setting the light color:

	public void setColor(String id, int red, int green, int blue) throws DataPointException, AccessException {
		Light light = getLamp(id); // SDT Device org.eclipse.om2m.sdt.home.devices.Light
		Colour color = light.getColour(); // SDT Module org.eclipse.om2m.sdt.home.modules.Colour
		color.setRed(red);
		color.setGreen(green);
		color.setBlue(blue);
	}