Create a zone by specifying the devices that should be added to it and then retrieve it in order to use it.

Creating a Zone

To create a new zone:

1. Retrieve the Home Zone Admin service (com.prosyst.mbs.services.hdm.zones.HomeZoneAdmin). If you are accessing the Home Device Manager via the JSON Remote API use the functions from the HZAdmin group.
2. Put the following configuration properties of a zone in a Map (or in a Plain Object if you are using the  JSON Remote API ):
   • HomeZone.DEVICES - An array of the UID's of all devices, that you want to add to the zone. One device can participate in more than one zone.
   • HomeZone.PARENTS - If you want your zone to be a child of another zone, specify its UID here. A zone can also have several parents (in this case, specify an array of strings).
   • HomeZone.TYPE - Zones can be categorized (and referred to) by their types. The type field of a zone allows you to add one or several string labels to it by which you can refer to it.
   • HomeZone.NAME - A user-friendly name for the zone.
   • Any additional properties that can be assigned to the zone.
3. Call the addHomeZone method of the HomeZoneAdmin interface (or HZAdmin/addHomeZone if you are using the JSON Remote API ) and pass the configuration properties of the zone along with a zone UID (optional).

The method returns a new com.prosyst.mbs.services.hdm.zones.HomeZone object. If you pass as an argument the UID of an existing home zone the method will result in setting the configuration properties as attributes of the zone.

The following Java code snippet creates a zone and adds two Home Device objects stored in the mydevice and myotherdevice variables to it.

    //Retrieve the Zone Admin service

  ServiceReference zoneref = bc.getServiceReference(HomeZoneAdmin.class.getName());

  HomeZoneAdmin zoneadmin = (HomeZoneAdmin)bc.getService(zoneref);

    //Construct an array of the devices' UID-s.  

  String[] uids = new String[] { mydevice.getUID(), myotherdevice.getUID() };

    //Construct the zone properties map.    

  HashMap zonemap = new HashMap();

  zonemap.put(HomeZone.TYPE,"test");

  zonemap.put(HomeZone.DEVICES, uids);

    //Create the zone  

  zoneadmin.addHomeZone("myzone", zonemap);

The following JavaScript code snippet creates remotely a zone and adds two Home Device objects to it.

   //Construct an array of the devices' UID-s

  uids = [mydevice.UID, myotherdevice.UID]

    //Construct the zone properties object.    

  zonemap = new Object();

  zonemap.type ="test"

  zonemap.devices = uids;

    //Create the zone.    

  var xhr = new XMLHttpRequest();

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

  xhr.send('{"jsonrpc": "2.0", "method": "HZAdmin/addHomeZone", "params": ["myzone", '+JSON.stringify(zonemap)+'], "id": 1}')

Retrieving a Zone

To retrieve a zone:

1. Retrieve the Home Zone Admin service and do one of the following:
   • Invoke the getHomeZonemethod (or HZAccess/getHomeZone if you are using the JSON Remote API) and pass the unique UID of the zone.
   • Invoke the getHomeZones method (or HZAccess/getHomeZones if you are using the JSON Remote API) by passing a LDAP String filter as an input argument. The method returns an array of all zones that meet the filter criteria (invoking the same method with null as an argument returns all zones in the network).

The following Java code snippet retrieves all zones of type "test".

HomeZone[] myzones = zoneadmin.getHomeZones("("+HomeZone.TYPE+"=test)");

The following JavaScript code snippet retrieves remotely all zones of type "test".

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

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

  xhr.send('{"jsonrpc": "2.0", "method": "HZAccess/getHomeZones", "params": "(type=test)", "id": 1}')0

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

Grouping Zones

Zones can be grouped hierarchically and thus a parent-child relationship between them can be formed.

You can group several zones into one and thus provide some specific logic and functionality. For example, "small" home zones like "Light on the First Floor", "Lights in the Garage" and "Lights on the Second Floor" can be child zones of the "bigger" home zone - "Lights in the House".

• You can establish a parent-child relationship for a zone by setting the UID(s) of its parent zone(s) as a value of the HomeZone.PARENTS field when you create the zone. You can also invoke the addChildZone/removeChildZone methods of the parent HomeZone to add/remove a child home zone.
• To retrieve the members of a parent zone call the getChildZones method.
• All methods that can be invoked on a parent zone allow you to specify whether they should be executed only on the parent zone or they should also include all child zones.

System Zone

You always have one system zone (HomeZoneAdmin.SYSTEM_HOME_ZONE) which cannot be removed. It contains all devices that don't belong to any other zone. When a device is added to a zone, it is removed from the system zone.

Manipulating Devices in a Zone

The zone model allows you to easily launch common device actions directly from a zone. Depending on the requirements you have passed, the Home Device Manager will launch the execution on all devices or devices with certain functionality and capabilities.

Executing an Operation on a Device Class Object

Operations provide direct approach to initiating an action on the DCO of a device in accordance with the implemented device class interface. For convenience, you can start such actions over a whole zone.

To execute an operation on all Device Class Objects of a certain type, that belong to a certain zone:

1. Retrieve the zone.
2. Invoke the invokeDCOOperation method (or HZAccess/invokeDCOOperation ) by passing the following input arguments:
   • String deviceClass - The type of the Device Class Object.
   • String operationName - The name of the operation.
   • Object[] operationParams - An array of the arguments of the operation, or null if it doesn't have any.
   • boolean includeChildZones - A flag that indicates whether the operation should also be executed on the devices included in the child zones of the current zone.

The operation will be executed on all devices that are in the zone, either one by one or natively if their protocol supports it.

Changing a Property of a Device Class Object

To change the properties of all Device Class Objects of a certain type, that belong to a certain zone:

1. Retrieve the zone.
2. Invoke the setDCOProperty method (or HZAccess/setDCOProperty) by passing:
   • The type of the Device Class Object.
   • The name of the property.
   • The property's new value.
   • A boolean - false if you want to include devices from this zone only and true if you want to include devices from this zone and all of its children.

The property value of all devices that are in the zone will be changed either one by one or natively if their protocol supports it.

Subscribing to Zone Events

You can be notified when zones are added and removed or when new devices are added to or removed from them.

To receive events related to zones, implement an event handler and subscribe to the topics you are interested in.

You can configure the set of properties that are included in the events generated by zones. There are three possible options for configuring the event properties set:

• Minimal - Pass "true" as a value to the hdm.events.configuration.minimal system property and only the event name and value along with the zone UID, status, error code and message will be added to the received zone events.
• Full - Use "false" as a value to the hdm.events.configuration.minimal system property and all zone properties along with the additional ones will be added to the received events (see the description of the HDM Zone Events Properties Configuration with PID mbs.hdm.core.zone.events in "Configuration Properties" section in "Setup Guide").
• Custom - Use the HDM Zone Events Properties Configuration with PID mbs.hdm.core.zone.events (see the "Configuration Properties" section in "Setup Guide") to specify which properties you want to be included in the zone events you have subscribed to.

The events related to home zones are provided as constants of the com.prosyst.mbs.services.hdm.HomeZoneEventConstants interface.

• HomeZoneEventConstants.TOPIC_HOME_ZONE_ADDED - Fired when a new home zone is added to the HDM.
• HomeZoneEventConstants.TOPIC_HOME_ZONE_REMOVED - Indicates that a home zone is removed from the HDM.
• HomeZoneEventConstants.TOPIC_CHILD_ZONE_ADDED - Fired when a child home zone is added to another zone.
• HomeZoneEventConstants.TOPIC_CHILD_ZONE_REMOVED - Indicates that a child home zone is removed from its parent zone.
• HomeZoneEventConstants.TOPIC_HOME_ZONE_NAME_CHANGED - Fired when the name of a zone is changed.
• HomeZoneEventConstants.TOPIC_HOME_ZONE_TYPE_CHANGED - Denotes that the type of a home zone is changed.
• HomeZoneEventConstants.TOPIC_HOME_ZONE_INTERNAL_FLAG_CHANGED - Fired when the flag indicating whether the zone is internal is changed.
• HomeZoneEventConstants.TOPIC_HOME_ZONE_DEVICE_ADDED - Indicates that a new home device is added to the zone.
• HomeZoneEventConstants.TOPIC_HOME_ZONE_DEVICE_REMOVED - Fired when a home device is removed from a zone.

You can receive events by subscribing to specific event topics via OSGi Event Handler or via JSON-RPC or Web Socket.