This document describes how to create, edit and receive events about changes in specific conditions.

Defining Conditions

To create a new condition:

1. Get the Home Automation Admin service (com.prosyst.mbs.services.ham.HomeAutomationAdmin) from the OSGi framework. If you are accessing the Home Automation Manager via the JSON Remote API use the functions from the HAM group.
2. Call the createCondition method (or HAM/createCondition) by passing the type of the condition you want to create. For a list of all the different types of conditions, see Conditions.
3. Configure its properties and call the save method to apply your changes (if you are using the JSON Remote API  the properties are passed as arguments to the HAM/createCondition function, so this step is not applicable).

The following Java code example creates a new condition of type Event Condition and configures it. Additionally the ID of the condition in the myeventconditionID variable is saved.

  HomeAutomationAdmin hamAdmin = (HomeAutomationAdmin) service;

   //The type of the condition that we want to create and its properties (in this case one property)

  String type = EventCondition.TYPE;

  String topic = "org/osgi/framework/BundleEvent/STARTED";

   //create a condition

  Object mycondition = hamAdmin.createCondition(type);

  EventCondition myeventcondition = (EventCondition)mycondition;

   //configure its properties

  myeventcondition.setTopic(topic);

    //apply changes

  myeventcondition.save();

    //save its id for later use

  String myeventconditionID = myeventcondition.getId();

The following JavaScript code example creates a new condition of type Event Condition and configures it. Additionally the ID of the condition in the myeventconditionID variable is saved.

//The type of the condition that we want to create and its properties (in this case one property)

type = "EventCondition"

topic = "org/osgi/framework/BundleEvent/STARTED"

  //create a condition and configure its properties

var xhr = new XMLHttpRequest();

xhr.open("POST", "/remote/json-rpc", false);

xhr.setRequestHeader("Content-Type","application/json")

xhr.send('{"jsonrpc": "2.0", "method": "HAM/createCondition", "params": ["'+type+'", {topic:"'+ topic+'"}], "id": 1}')

  //save its id for later use

myeventconditionID = JSON.parse(xhr.responseText).result

Editing Conditions

To edit a condition:

1. Retrieve it by using the getAllConditions and getCondition methods (or HAM/getConditions / HAM/getCondition if you are using the JSON Remote API).
2. Modify its properties.
3. Apply your changes by calling the save method to the updated object (or by passing it to the HAM/updateCondition function if you are using the JSON Remote API).

The following Java code examples retrieve the condition, created in the previous example and change one of its properties.

  //retrieve the condition

HomeAutomationAdmin hamAdmin = (HomeAutomationAdmin) service;

Object mycondition = hamAdmin.getCondition(EventCondition.TYPE, myeventconditionID);

EventCondition myeventcondition = (EventCondition)mycondition;

  //change property

String topic = "org/osgi/framework/BundleEvent/STOPPED";

  //apply changes

myeventcondition.save();

  //retrieve the condition

var xhr = new XMLHttpRequest();

xhr.open("POST", "/remote/json-rpc", false);

xhr.setRequestHeader("Content-Type","application/json") xhr.send('{"jsonrpc": "2.0", "method": "HAM/getCondition", "params": ["EventCondition", "'+ myeventconditionID+'" ], "id": 1}')

myeventcondition=JSON.parse(xhr.responseText).result)

  //change property

myeventcondition.topic = "org/osgi/framework/BundleEvent/STOPPED";

  //apply changes

xhr.open("POST", "/remote/json-rpc", false);

xhr.setRequestHeader("Content-Type","application/json")

xhr.send('{"jsonrpc": "2.0", "method": "HAM/updateCondition", "params": ["EventCondition", "'+ myeventconditionID+'", '+JSON.stringify(myeventcondition)+' ], "id": 1}')

If you are using the JSON API you can retrieve some of the condition's properties, without retrieving the whole JSON object by calling the getConditionSimple and getAllConditionsSimple functions and passing an array of the properties you need.

Explicitly Triggering a Condition

The Home Automation Manager allows you to test the behavior of your automation components, which are based on a specific condition. You can trigger a condition manually by calling its trigger method (or HAM/triggerCondition).

Receiving Events

Get notified when new commands and condition types are added and when commands finish their execution.

Available Command/Condition Types

The topics of the events related to changes in the set of command and condition types are:

• HomeAutomationAdmin.TOPIC_TYPE_ADDED for newly-added command and condition types.
• HomeAutomationAdmin.TOPIC_TYPE_REMOVED for removed command and condition types.

To subscribe to both topics, use the HomeAutomationAdmin.TOPIC_PREFIX prefix followed by a wildcard (*).

You can receive events by subscribing to those topics via OSGi Event Handler, or remotely via JSON-RPC or Web Socket.