How to define a new command and retrieve an existing one.

Defining Commands

To create a new command:

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 createCommand method of the HomeAutomationAdmin interface (or HAM/createCommand) by passing the type of the command you want to create. For a list of all the different types of commands, see Commands.
3. Configure its properties and call the save method to the updated object (or by passing it to the JSON Remote API the properties are passed as arguments to the HAM/createCommand function, so this step is not applicable).

The following Java code snippet creates a new command of type Log Command and configures it. Additionally, it saves the ID of the command in the mylogcommandID variable.

  HomeAutomationAdmin hamAdmin = (HomeAutomationAdmin) service;
    //The type of the command that we want to create and its properties
  String type = LogCommand.TYPE;
    //create a command
  Object mycommand = hamAdmin.createCommand(type);
  LogCommand mylogcommand = (LogCommand)mycommand;
    //configure its properties
  mylogcommand.setMessage("Message");
  mylogcommand.setPrintOnConsole(true);
  mylogcommand.setPrintOnLog(false);
    //apply changes
  mylogcommand.save();
    //save its id for later use
  String mylogcommandID = mylogcommand.getId();    

The following JavaScript code snippet creates a new command of type Log Command and configures it. Additionally, it saves the ID of the command in the mylogcommandID variable.

    //The type of the command that we want to create and its properties
  type = "LogCommand"
  props = new Object()
  props.message = "Message"
  props.print_on_console=true
  props.print_on_log=false
    //create a command 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/createCommand", "params": ["'+type+'", '+
        JSON.stringify(props)+'], "id": 1}')
   //save its id for later use
  mylogcommandID = JSON.parse(xhr.responseText).result

Editing Commands

To edit a command:

1. Retrieve it by using the getAllCommands and getCommand methods (or HAM/getCommands / HAM/getCommand if you are using the JSON Remote API).
2. Configure its properties.
3. Apply your changes by calling the save method (or by passing the updated object to the HAM/updateCommand function if you are using the JSON Remote API).

The following Java code example retrieves the command, created in the previous example and changes one of its properties.

    //retrieve the command
  HomeAutomationAdmin hamAdmin = (HomeAutomationAdmin) service;
  Object mycommand = hamAdmin.getCommand(LogCommand.TYPE, mylogcommandID);
  LogCommand mylogcommand = (LogCommand)mycommand;
    //change property
  mylogcommand.setMessage("Different Message");
    //apply changes
  mylogcommand.save();

The following JavaScript code example retrieves the command, created in the previous example and changes one of its properties.

    //retrieve the command
  var xhr = new XMLHttpRequest();
  xhr.open("POST", "/remote/json-rpc", false);
  xhr.setRequestHeader("Content-Type","application/json")
  xhr.send('{"jsonrpc": "2.0", "method": "HAM/getCommand", "params": ["LogCommand", "'+
         mylogcommandID+'" ], "id": 1}')
  mylogcommand=JSON.parse(xhr.responseText).result
    //change property
  mylogcommand.message = "Another Message"
    //apply changes
  xhr.open("POST", "/remote/json-rpc", false);
  xhr.setRequestHeader("Content-Type","application/json")
  xhr.send('{"jsonrpc": "2.0", "method": "HAM/updateCommand", "params": ["LogCommand", "'+
          mylogcommandID+'", '+JSON.stringify(mylogcommand)+' ], "id": 1}')

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

Explicitly Starting a Command

To explicitly start a command:

1. Retrieve the command by using the getAllCommands and getCommand methods (or HAM/getCommands / HAM/getCommand if you are using the JSON Remote API).
2. Call the start method of the Command interface (or HAM/runCommand if you are using the JSON Remote API).

Receiving Events

You can be 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 (*).

Command Status Events

Status events fired by commands are under the StatusReporter.TOPIC_STATUS topic.

Command status events are disabled by default. You can enable them by populating the ham.status.event system property, either with comma-separated list of the command types you want to listen to, or with a wildcard (*) to listen to events by all command types.

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