User Tools

Site Tools


scene_manager

Scene Manager - Programmer's Guide

Scene Manager is implemented to help users create a “Scene” with multiple discovered resources in a network. Using scenes means that users can easily change the resources to a configured representation by executing the single scene, rather than updating all the resources individually. Scene Manager is developed on top of the Resource Encapsulation of the IoTivity primitive service to provide users an easier way to develop a scene application as shown below.


USE CASES

The main use of a “Scene” is to restore a set of resources to certain states which the user configured before in a very convenient way, such as a single touch of a icon on their own phones. For example, one scene for a smart home scenario is an “AWAY home” mode. User can build the scene which makes all lights at home turned off and an entrance door locked beforehand. After that, when the user leaves home, he can change the devices to be set to “AWAY home” by executing the mode by his smart phone or smart watch even from outside of home.

There are two difference locations to store a scene: a local device and a remote device like a hub at home or a cloud server. One may want to store and use it privately like in a personal smart phone OR register it to a central-device like a hub and use it. Different from the first approach, in the second, any authorized user can discover a scene registered by other users at the hub and execute it. Below, an example of the second approach is provided:


FEATURES

In this section, several features of Scene Manager are provided as follows:

  • One can create a SceneCollection resource having a set of scenes to update multiple resources of (a) homogeneous/heterogeneous resource type(s)
  • By means of CoAP request(i.e. POST), one can create a SceneCollection and add a SceneMember to the SceneCollection at other remote OIC server
  • One can make a SceneCollection resource discoverable in a network so that other authenticated OIC client can send a request to execute a scene provided by the resource
  • Compatible to Scene-related resource models and behaviors in OIC Core Spec.

RESOURCE MODEL

A scene above is provided in a form of OIC resource. Regarding the resource, there are 3 OIC resources for a scene: SceneList, SceneCollection, and SceneMember resources. And these resources are standardized in ‘OIC Core Framework’ specification so any authorized OIC client can easily discover the resources and create/update/execute a scene by sending CoAP request. Please refer to the OIC specification document if you need futher information for the resources.

SceneCollection resource and SceneMember resource above are two of OIC resources and standardized in OIC Core specification. More detailed information is provided in the next section and the specification document.

SceneList resource

SceneList resource is an overloaded collection resource which has several SceneCollection resources as child resources. Any authorized OIC client can discover the SceneList resource with its resource type, “oic.wk.scenelist” and be aware of which SceneCollection resources are there.

SceneCollection resource

SceneCollection resource is also an overloaded collection resource which has several SceneMember resources as child resources. SceneCollection resource shows a list of scenes as a property(i.e. sceneValues) and OIC client can execute one of the scenes by sending POST request to a certain property(i.e. lastScene). The request to execute will be propagated to all SceneMember resources associated with the SceneCollection resource.

SceneMember resource

SceneMember resource contains a link information of other resource (e.g., light resources) to be updated by a scene execution. And it also does an mapping information between a scene and what needs to happen according to that scene on the an indicated resource. When its SceneCollection resource receives an execution request of a certain scene, each SceneMember resource looks up the mapping information and sends a POST request to update the indicated resource’s property.

Descriptive relationship of the resources

This section provides an illustrated example for the resources. It assumes that there are two ordinary OIC resources: Vacuum and Window. And SceneCollection resource under SceneList resource supports “off” and “CleaningHome” scenes and each SceneMember resource stores a link to each resource and mapping information for these scenes.


ARCHITECTURE


API USAGES C++

There are two role players to create a scene. The first player is one who creates a scene in own local device. In this case, users can create SceneList, SceneCollection, and SceneMember resource by calling Scene Manager APIs and their their properties are directly updated when one of the APIs is called. Additionally, user can receive its responses for API calls instantly with a return value or exception event.

The other player is one who asks a remote OIC server to create a scene. In contrast with the first case, all requests including creating a new SceneCollection resource are done by sending a CoAP request. That is, users can know an result of a request after receiving a response packet from a remote OIC server, which should be delivered by calling a callback function registered before. Additionally, in this case, user may want to just execute a scene created by other users.

To cover the above two use cases, Scene Manager provides two sets of classes: we calls the classes for local operation and remote operation, respectively.

Class diagram for local operation

For local operation, Scene Manager provides 4 interface classes: SceneList, SceneCollection, Scene, and SceneAction classes. The releationship between these classes are described as follows:

Each class’s major characteristics are briefly introduced below:

  1. SceneList class
    1. Provides an API to create a new SceneCollection instance
    2. SceneList class have a number of SceneCollection instances created before
    3. SceneList class runs as a singleton in a process
  2. SceneCollection class
    1. Provides an API to create a Scene instance
    2. SceneCollection class have a number of Scene instances created before
  3. Scene class
    1. Each Scene instance has a human-readable name unique in the associated SceneCollection instance like “Away home” or “Movie Time”
    2. Provides an API to create a SceneAction instance which corresponds a unit of action composing a scene
    3. Scene class have a number of SceneAction instances created before
  4. SceneAction class
    1. User should specify a unit of action individually when the associated scene is executed.
    2. SceneAction instance needs 3 parameters in creation: a target resource (e.g. light), a property key(e.g. power), and its value(e.g. FALSE)

API usages for local operation

This section is going to describe how to use APIs to create a simple scene. It is assumed that one have two light devices in a living room and wants to create “AllOn” and “AllOff” scene with the lights. And the lights are already discovered in a network by using DiscoveryManager provided in Resource Encapsulation service.

  • Preliminary, discover desired resources in a network by using DiscoverManager
const std::vector<std::string> resourceTypes{"core.light"};
RCSDiscoveryManager::getInstance()-> discoverResourceByTypes(RCSAddress::multicast(), relativetUri,
                                                            resourceTypes, &onResourceDiscovered);

Once DiscoverManager found a resource with “core.light” resource type, it calls onResourceDiscovered function and passes a RCSRemoteResourceObject instance indicating the found light resource.

  • Add a new SceneCollection instance
SceneCollection::Ptr g_sceneCollectionPtr;
SceneCollectionPtr = SceneList::getInstance()->addNewSceneCollection();
SceneCollectionPtr->setName(“Lights in a living room”)

After 2 light resource are found in a network, what we do first is to create a SceneCollection instance. As described, the API to create is provided by SceneList instance. Additionally, user can set a name to the SceneCollection instance if wants.

  • Add a new Scene instance
Scene::Ptr g_scene_on, g_scene_off;
g_scene_on = sceneCollectionPtr->addNewScene(“AllOn”);
g_scene_off = sceneCollectionPtr->addNewScene(“AllOff”);

A SceneCollection instance can have multiple Scene instances and each scene should have a unique name in the SceneCollection instance, like “AllOn” and “AllOff”. An API to create a new Scene instance is provided by the upper instance, SceneCollection instance.

  • Add a new SceneAction instance
// lightResource_1, lightResource_2 in RCSRemoteResourceObject instance
 
g_scene_on->addNewSceneAction(lightResource_1, “power”, TRUE);
g_scene_on->addNewSceneAction(lightResource_2, “power”, TRUE);
 
g_scene_off->addNewSceneAction(lightResource_1, “power”, FALSE);
g_scene_off->addNewSceneAction(lightResource_2, “power”, FALSE);

After creating the Scene instance, we have to specify a unit of action once the scene is executed. To specify the action, we put (1) one of discovered light resources, (2) property key, (3) property value of the resource. In this example, for a “AllOn” scene, we make all light resources’ power property changed to TRUE. For a “AllOff” scene, we can make them to “FALSE”. The API to add a SceneAction is provided by a Scene instance.

  • Execute a Scene
g_scene_on->execute(onExecute);
g_scene_off->execute(onExecute);

Finally, after specifying a Scene instance by adding multiple SceneAction instances, user can just call an *execute* API of a Scene instance. As a parameter of the API, user has to specify a callback function (e.g., onExecute) to receive a result of the execution.

Class diagram for remote operation

As described in the beginning of this section, the remote operation in Scene Manager is to register new Scene-related resources at a remote device and just executing a scene already registered by others at the remote device

For remote operation as same as local operation, Scene Manager provides 4 interface classes: RemoteSceneList, RemoteSceneCollection, RemoteScene, and RemoteSceneAction classes. The releationship between these classes are described as follows:

As compared to the class digram of local operation, the above supported APIs are very similar to each other’s one except a need of callback function. That is because some requests should be transmitted to the remote device by CoAP request so those results for the requests can be passed in an asynchronous way, i.e. calling a callback function. Each class’s major characteristics are briefly introduced below:

  1. RemoteSceneList class
    1. Corresponding instance to a SceneList resource at a remote device
    2. Provides an API to create and get a RemoteSceneCollection instance
    3. With RemoteSceneList instance, user can create a new SceneCollection resource at the remote device and get a new RemoteSceneCollection instance corresponding to the SceneCollection resource. (by addNewSceneCollection API)
    4. With RemoteSceneList instance, user can access one of existing SceneCollection resources at the remote device and get a RemoteSceneCollection instance corresponding to the SceneCollection resource. (by getSceneCollections API)
    5. RemoteSceneList instance have a number of RemoteSceneCollection instances of which SceneCollection resources are registered at the remote device.
  2. RemoteSceneCollection class
    1. Provides an API to create and get a RemoteScene instance
    2. RemoteSceneCollection instance have a number of RemoteScene instances created before or already registered at the remote device
  3. RemoteScene class
    1. Each RemoteScene instance has a human-readable name unique in the associcated RemoteSceneCollection instance like “Away home” or “Movie Time”
    2. Provides an API to create a RemoteSceneAction instance which corresponds a unit of action composing a scene
    3. RemoteScene class have a number of RemoteSceneAction instances created before or already registered at the remote device
  4. RemoteSceneAction class
    1. User should specify a unit of action individually when the associated scene is executed.
    2. RemoteSceneAction instance needs 3 parameters in creation: a target resource (e.g. light), a property key(e.g. power), and its value(e.g. FALSE)

API usages for remote operation

This section is going to describe how to use APIs to create a new scene at a remote device. In addition to a new scene, user can utilize an existing scene from the remote device but the explanation for it will be not mentioned in this section due to its straight-forward usage.

For both scenarios, user has to find a SceneList resource in a network. After a SceneList resource is found, user can attach a new scene to the resource or utilize an existing scene from the resource. As mentioned in Section 12.3.1, a resource type of a SceneList resource is dedicated to “oic.wk.scenelist”.

  • Preliminary, discover desired resources in a network by using DiscoverManager
const std::vector<std::string> resourceTypes {"oic.wk.scenelist"};
RCSDiscoveryManager::getInstance()-> discoverResourceByTypes(RCSAddress::multicast(), relativetUri,
                                                            resourceTypes, &onResourceDiscovered);

Once DiscoverManager found a resource with “oic.wk.scenelist” resource type, it calls onResourceDiscovered function and passes a RCSRemoteResourceObject instance indicating the found SceneList resource.

  • Create a RemoteSceneList instance
RemoteSceneList::createInstance(g_foundSceneListResource,onRemoteSceneListCreated);

After calling the above API, user can have a RemoteSceneList instance by the registered callback function, i.e. onRemoteSceneListCreated.

  • Create a new RemoteSceneCollection instance
g_remoteSceneListObj->addNewSceneCollection(onRemoteSceneCollectionCreated);

Note that g_remoteSceneListObj is a pointer of the RemoteSceneList instance. With this, user calls an addnewSceneCollection API to create a new RemoteSceneCollection instance. The desired instance is also passed by a callback function, i.e. onRemoteSceneCollectionCreated.

  • Create a new RemoteScene instance
g_remoteSceneColObj->addNewScene("Going Out", onRemoteSceneCreated);

Note that g_remoteSceneColObj is a pointer of the RemoteSceneCollection instance. With this, user calls an addNewScene API with a name, ”Going Out”, to create a new RemoteScene instance. The desired instance is also passed by a callback function, i.e. onRemoteSceneCreated.

  • Create a new RemoteSceneAction instance
g_remoteSceneObj->addNewSceneAction(g_foundMemberResource, "power", "off", onRemoteSceneActionCreated);

Note that g_remoteSceneObj is a pointer of the RemoteScene instance. With this, user calls an addNewSceneAction API with a targer resource object, property key, value, and a callback function to create a new RemoteSceneAction instance. The desired instance is also passed by a callback function, i.e. onRemoteSceneActionCreated.

  • Execute a RemoteScene instance
g_remoteSceneObj->execute(onRemoteSceneExecute);

As same as local operation, after specifying a RemoteScene instance, user can just call an *execute* API of a RemoteScene instance. As a parameter of the API, user has to specify a callback function (i.e. onRemoteSceneExecute) to receive a result of the execution.


SAMPLE APPLICATION

How To Build With Scons

~/iotivity$ scons TARGET_OS=linux RELEASE=0 SECURED=0 

Scene server and resource servers (local operation)

This section introduces how to run sample applications for scene operation, especially in local operation. There are three sample applications: 2 for resource servers (i.e. light and fan) and the rest for scene resource server. With the sample, we suppose that there is “Home” SceneList and is going to create a “Living Room” SceneCollection. And in “Living Room”, we are going to create two scenes: “Going Out” and “TV mode”. The “Going Out” scene makes a light and fan change power property to “off” and speed property to zero, respectively. And the “TV mode” scene makes a light and fan change power property to “on” and speed property to 20, respectively.

Preliminary, run light and fan resource server applications as follows:

~/iotivity/service/scene-manager/sampleapp/linux $ ./lightserver
Resource URI : /a/light
		Resource Type Name : core.light
		Resource Interface : oic.if.baseline
		Resource creation is successful with resource handle : 0x80f0320
 
 
~/iotivity/service/scene-manager/sampleapp/linux $ ./fanserver
Resource URI : /a/fan
Resource Type Name : core.fan
		Resource Interface : oic.if.baseline
		Resource creation is successful with resource handle : 0x9c5d338

Now, run a scene server application as follows:

~/iotivity/service/scene-manager/sampleapp/linux $ ./sceneserver
Wait 2 seconds until discovered.
onResourceDiscovered callback
		Resource URI : /a/light
		Resource Host : coap://[fe80::52b7:c3ff:feab:f569]:55353
onResourceDiscovered callback
		Resource URI : /a/fan
		Resource Host : coap://[fe80::52b7:c3ff:feab:f569]:44685
========================================================
1. Create a SceneList                       
2. Quit                       
========================================================

Once running the application, it automatically tries to discover light and fan resources in a network. After few seconds, you can find two resources discovered on your screen like above. If you can see the log on your screen like above, it confirms that all preliminary steps are done successfully.

First step is to create SceneList. In the above, there are two options. If you select “1” option, you can create a “Home” SceneList.

========================================================
1. Create a SceneList                       
2. Quit                       
========================================================
1	(user put the option)
		Home(SceneList)

Press Enter to Continue.....

Second step is to create a new SceneCollection and register it to the SceneList. Suppose that we want to create a “Living Room” SceneCollection. To do so, if you select “1” option among the below options, you can create a “Living Room” SceneCollection at “Home” SceneList .

========================================================
1. Create a SceneCollection                       
2. Quit                       
========================================================
1	(user put the option)
		Home(SceneList)
		   |_ _ _ Living Room(SceneCollection)
Press Enter to Continue.....

As you can see in your screen, “Living Room” SceneCollection is successfully attached at “Home” SceneList. If you confirm this, please press enter key. Now, you can see two options, as well. If you select “1” option, you can create two Scenes, “Going Out” and “TV mode”.

========================================================
1. Create a Scene                       
2. Quit                       
========================================================
1 (user put the option)
	Home(SceneList)
		   |_ _ _ Living Room(SceneCollection)
			      |_ _ _ Going Out(Scene)
			      |_ _ _ TV mode(Scene)
 
Press Enter to Continue.....

As you can see in your screen, the two Scenes are successfully created and attached to “Living Room” SceneCollection.

As of now, each Scene has no SceneAction. So you have to specify SceneActions which tell how light and fan resource should be changed. If you select “1” option among 2 options, you can specify the Scenes more detailed by creating SceneActions.

========================================================
1. Create a SceneAction                       
2. Quit                       
========================================================
1 (user put the option)
	Home(SceneList)
		   |_ _ _ Living Room(SceneCollection)
			      |_ _ _ Going Out(Scene)
			      |		|_ _ _ /a/light:power - "off"
			      |		|_ _ _ /a/fan:speed - "0"
			      |_ _ _ TV mode(Scene)
			       		|_ _ _ /a/light:power - "on"
			       		|_ _ _ /a/fan:speed - "20"
 
Press Enter to Continue.....

All required steps to create a scene are done now. You just execute one of the two Scenes. Let us assume that you select to execute “Going Out” scene.

========================================================
1. Execute Scene1                       
2. Execute Scene2                       
3. Quit                       
========================================================
1 (user put the option)

Then, you can find that running light and fan resources receive POST requests to update properties properly as follows:

~/iotivity/service/scene-manager/sampleapp/linux $ ./lightserver
0: 
In entity handler wrapper: 
 
	In Server CPP entity handler:
		requestFlag : Request
			requestType : POST
				power: off
 
 
~/iotivity/service/scene-manager/sampleapp/linux $ ./fanserver
 
0: 
In entity handler wrapper: 
 
	In Server CPP entity handler:
		requestFlag : Request
			requestType : POST
				speed: 0

Scene client manages a scene at remote scene server (Remote operation)

This section introduces how to run sample applications for scene operation, especially in remote operation. In addition to 2 resource server applications and scene server application, a scene client application is required more. The scene client application can execute an existing Scene already created in the remote scene server. Or it can create a new SceneCollection and Scene on a remote scene server. Firstly, the former will be explained as follows.

Let us assume that we already formed “Home” SceneList as explained in the previous section. That is, at a scene server, there are two scenes like “Going Out” and “TV mode”.

First, run a sceneclient application. Then it automatically discovers a SceneList resource in a network, which is the one we created at the sceneserver application. Then, we need to create RemoteSceneList instance with the discovered SceneList resource. Please choose “1” option in below.

~/iotivity/service/scene-manager/sampleapp/linux $ ./sceneclient
Wait 2 seconds until discovered.
onResourceDiscovered callback
		Resource URI : /SceneListResURI
		Resource Host : coap://[fe80::52b7:c3ff:feab:f569]:38060
========================================================
1. Create a RemoteSceneList 
2. Quit                 
========================================================
1 (user put the option)

Then, we need to see existing SceneCollection resources. Please choose “2” option in below.

========================================================               
1. Create a RemoteSceneCollection    
2. Show existing RemoteSceneCollection 
3. Quit                            
========================================================               
2 (user put the option)
	(SceneList)
		   |_ _ _ 8c308940-6792-4ecd-b4e8-e1df505668c2 (SceneCollection)
			   |_ _ _ Going Out (Scene)
			      		|_ _ _ /a/sceneMember/1 : speed - "0"
			      		|_ _ _ /a/sceneMember/0 : power - "off"
			   |_ _ _ TV mode (Scene)
			      		|_ _ _ /a/sceneMember/1 : speed - "20"
			      		|_ _ _ /a/sceneMember/0 : power - "on"

As you may notice, the shown SceneCollection and Scenes are what you created before in the previous section with a scene server application. With these, we just execute one of Scenes. Please choose “1” to execute “Going Out” Scene in below.

========================================================
1. Execute a first RemoteScene  
2. Quit                     
========================================================
1 (user put the option)

Then, you can find that running light and fan resources receive POST requests to update properties properly as follows:

~/iotivity/service/scene-manager/sampleapp/linux $ ./lightserver
0: 
In entity handler wrapper: 
 
	In Server CPP entity handler:
		requestFlag : Request
			requestType : POST
				power: off
 
~/iotivity/service/scene-manager/sampleapp/linux $ ./fanserver
0: 
In entity handler wrapper: 
 
	In Server CPP entity handler:
		requestFlag : Request
			requestType : POST
				speed: 0

Now, the following will explain the later use cases where a scene client creates a new SceneCollection resource at a remote scene server. For that please run scene server, 2 resource servers applications, first. And at the server, you have to create a SceneList resource, at least. Finally then run a scene client application. When the client is executed, you can see that the 2 resources and SceneList resource are discovered as follows. And please choose “1” option to create RemoteSceneList instance.

~/iotivity/service/scene-manager/sampleapp/linux $ ./sceneclient
Wait 2 seconds until discovered.
onResourceDiscovered callback
		Resource URI : /SceneListResURI
		Resource Host : coap://[fe80::52b7:c3ff:feab:f569]:58754
onResourceDiscovered callback
		Resource URI : /a/light
		Resource Host : coap://[fe80::52b7:c3ff:feab:f569]:54733
onResourceDiscovered callback
		Resource URI : /a/fan
		Resource Host : coap://[fe80::52b7:c3ff:feab:f569]:38909
========================================================
1. Create a RemoteSceneList 
2. Quit                 
========================================================
1 (user put the option)

Now, please choose “1” option in below to create a new RemoteSceneCollection instance.

========================================================               
1. Create a RemoteSceneCollection    
2. Show existing RemoteSceneCollection 
3. Quit                            
========================================================               
1 (user put the option)
	(SceneList)
		   |_ _ _ a08830f9-a1ea-4427-a8fb-278cf46093e4 (SceneCollection)

With the RemoteSceneCollection instance, you can create an RemoteScene(i.e. “Night mode”) and several RemoteSceneAction instances (for light and fan servers). This processes are very similar to those explained for usages of scene server application above. So please see the above Section 12.5 if you have any question.

	(SceneList)
		   |_ _ _ a08830f9-a1ea-4427-a8fb-278cf46093e4 (SceneCollection)
			   |_ _ _ Night mode (Scene)
			      		|_ _ _ /a/sceneMember/1 : speed - "50"
			      		|_ _ _ /a/sceneMember/0 : power - "on"
========================================================
1. Execute RemoteScene          
2. Quit                     
========================================================
1 (user put the option)

After that, please choose “1” option to execute the created scene. Then you can find that running light and fan resources receive POST requests to update properties properly as follows:

~/iotivity/service/scene-manager/sampleapp/linux $ ./lightserver
0: 
In entity handler wrapper: 
 
	In Server CPP entity handler:
		requestFlag : Request
			requestType : POST
				power: on
 
~/iotivity/service/scene-manager/sampleapp/linux $ ./fanserver
0: 
In entity handler wrapper: 
 
	In Server CPP entity handler:
		requestFlag : Request
			requestType : POST
				speed: 50

scene_manager.txt · Last modified: 2017/04/24 09:48 by Jihun Ha