The Developer Service – Part 2

Before adding a new device, I’ll explain the message’s structure.
In PulseStation every message goes through the “Core’s service”.
A message is a simple string separated by “|”.

The structure of the message before going in the service core :

[type of command] | [service from] | [service to] | [command] | [paramaters 1] | [parameters 2] | [parameters x]

  • type of command : 0 – Command / 1 – Action / 9 – Answer
  • service from : The service who issued the command
  • service to : The service who treats the command
  • command : The code of the command
  • parameters 1..x : Parameters of the command

When the message arrives in the core’s service we add some extra info.

[message] | [date] | [hash code]

The hash code can be used to send an answer to a specific message. In that way we can determine if a message is successfully treated or not.

You can find a lot of examples in the log of the Core’s service.

Now that we know how to interpret a message, it can be easier to implement a new functionality.

Everything goes into the file “service.php” and “service-implementation.php”.

In the file “service.php”, we can add the commands and in the file “service-implementation.php” we can implement the functionality itself.

service.php

I use different “switch cases”, the first one calls a specific function depending the “type of command”.
The command of type “0”(Command) is used to interact with the service itself.
The command of type “1”(Action) is used to interact with the devices of the service.

In our case, we want to add a new device, so we are using the type “1”, so we go in the function “decodeAction”.
In that function, you also have a “switch case” but now based on the command itself.

Here we want to add a new device, so we will reuse the command “ADD” but with a different parameter (eg: myobject).

The message should look like this : 1|HUB|myservice|ADD|myobject

To implement it, just add another “case” with the parameter value.
You can add a function that will be implemented in the “service-implementation.php”

You also see other commands predefined :

  • CHECKPERIODIC : Used if you defined the parameter “check-periodic-time” in config.ini
  • UPDATEPROPERTY : You MUST implement this command. This command is implemented in each service. For info, the Imperihome’s service uses this command to interact with the services.
  • DELETE : Used to delete a device

You can override this function if you want to add some extra functionnalities.

service-implementation.php

Now we can implement the functions defined in the file service.php

To easily develop a new service, I have implemented some useful functions in the file utils.php, here are the most used :

  • getNextId() : Return the next available id for a device – Use it when you wan to add a new device
  • read() : Return an array with all the objects of your service
  • sendCommandToHub($message) : Send a message to the core service
  • save($allObjects) : Save the array in parameter
  • addServiceLog($text) : Add the specified text to the service’s log
  • getDevice($deviceId) : Get a specified device based on his id
  • findValueByProperty($device, $valueid) : Return a specific value for the device passed in parameter and his value id
  • replaceDeviceAndSave($device) : Replace a specified device and save the result
  • removeDeviceAndSave($device) : Remove a specified device and save the result

Here is how you have to define your new object

function addMyObject($message){
        // Get the current list of devices
	$allObjects = read();
        // Add a new object
	$allObjects[] = newMyObject();
        // Save the result
	save($allObjects);
        // Send a response to tell that the device is added
	sendCommandToHub("9|".$message['hash']."|1|".$message['toService']."|HUB|1|NEW_DEVICE_ADDED");
}

The object itself is defined like this I just put the different possibilities :

function newMyObject(){
	$object = array();
        //Mandatory infos
	$object['id'] = getNextId();	
	$object['type'] = 'Developer Service';
	$object['manufacturer'] = 'You';
	$object['product'] = 'Developer Service';
	$object['time'] = time();

        //List of the properties 
	$object['values'] = array();

	$value = array();
	$value['id'] = '1';
        //Depending the type, the display in the application'll be different.
        //It can be : string / bool / list / scene / button
	$value['type'] = 'string';
       //Used a dot separated name
	$value['property'] = 'developer.property.one';
	$value['units'] = '';
        //true or false if you want let the user modify or not this property
	$value['readonly'] = 'false';
        //The default value of the property
	$value['value'] = 'My Value';
        //Add the value to the list
	$object['values'][] = $value;
	
        
	$value['id'] = '2';
        //Depending the type, the display in the application'll be different.
        //It can be : string / bool / list / scene
	$value['type'] = 'list';
       //Used a dot separated name
	$value['property'] = 'developer.property.one';
	$value['units'] = '';
        //true or false if you want let the user modify or not this property
	$value['readonly'] = 'false';
        //The default value of the property
	$value['value'] = 'My Value 2';
        //Use the same value for the label and the key
        $value['list'] = array(array("label" =>'My Value', "value" => "My Value"), array("label" =>'My Value 2', "value" => "My Value 2"));
        //Add the value to the list
	$object['values'][] = $value;
	return $object;
}

structure.json
Now you want to have the capability to call your new device.
Edit the file “structure.json” and edit the property “add” to be like this :

"add" : [
		 {
				"type" : "Developer Test",
				"message" : "1|HUB|[service]|ADD|object"
		 },
		{
				"type" : "Developer Test2",
				"message" : "1|HUB|[service]|ADD|myobject"
		 }
	]

Refresh PulseStation and go to your service, you’ll see a second option to call your second object.

Blockly
You have nothing more to do !
Normally you should see a new menu with the blocks available for your devices.

A part 3 will follow with more advanced possibilities.