The Simulator Protocol Adapter is a protocol adapter designed for test purposes, that allows you to register dummy devices.

Protocol Information

The Home Device Manager (HDM) provides an abstraction layer (a common interface) for controlling home devices using different communication protocols. It allows you to manage home networks of devices through a specified protocol adapter.The HDM Simulator allows the simulation of real home network devices functionality by exporting the information for them and eventually importing the devices as simulated ones using the Simulator adapter. Other purposes include providing a way to add / remove / manage sample devices with simulated behaviour of some common device classes such as BinarySwitch, BinarySensor, TemperatureActuator etc. This can be achieved by using the HomeDeviceManager API for management of Simulator protocol adapter devices or via the HDM WebAdmin Console plugin. To be able to manage a Simulated network via the Home Device Manager you need to select the protocol adapter registered under the name Simulator.

Supported Operations

The Simulator Protocol Adapter supports two types of device administration operations:

• add
• remove

Protocol Properties

The supported adapter properties for each simulated protocol adapter are provided by importing an XML of configurable type HDMDeviceClassSimulation. The device classes can be overwritten by re-importing an XML file containing the adapter properties 'config' node. Every simulated protocol can have various simulations. If a required property is missing, the device will not be added. In the case when protocol adapter properties are not provided, all properties for a device will be automatically considered as user properties.

The Adapter Properties are custom, while the supported metadata properties are as follows:

• description
• enum
• min
• max
• access
• step
• resolution - can be mandatory or optional

For an example on defining protocol properties see Adding Adapter Properties Definitions section.

Device Classes

The Simulator Protocol Adapter implements the following HDM device classes:

• WindSensor
• Volume
• WindowActuator
• MotionSensor
• MultiLevelSensor
• MultiLevelSwitch
• TemperatureActuator
• StandBy
• DoorActuator
• Key
• Blinds
• BinarySwitch
• BinarySensor
• Playback
• BatteryLevel
• Simulate

Using the Simulator

The Simulator creates simulated devices in the HDM upon importing of their configurations in the ConfigTree, as described in the Simulator demo. You can inspect these devices in the HDM as described here and execute operations on them and their child devices as described in Operations on Parent Devices and Operations on Child Devices in the  Simulator demo.

To simulate a network of devices with the Simulator you need to:

• Add an XML file through a HDMDeviceSimulator configurable. When exporting the XML file, it should be done under Devices configurable.
• Define the properties of the simulated Protocol Adapter. This step is optional since the protocol adapter may not support adapter properties or may move them into a specific Configuration device class.
• Define which Device Classes will be supported by the simulated Protocol Adapter.
• Define each Device Class supported by the simulated Protocol Adapter. Add the properties needed and the operations (including additional metadata). This step is optional but otherwise the operations will have no simulation functionality and the setters will have the default behaviour.
• Define the Home Devices (with their structure and properties) that will be created for the simulated Protocol Adapter. All home device functionalities are represented as device class objects. There are two ways of simulating home devices: using ConfigTree via WebConsole or using the HDM API.
  • In order to import home device configurations in the ConfigTree via the Web Console:
    • First export the configuration of real HDM devices for a given protocol. The export is handled via the Devices type of configurable.
    • Afterwards this configuration must be imported in the HDM Simulator adapter, with an HDMDeviceSimulator configurable.
    • The same applies for the Controller devices which must be exported from real protocols and imported later on.
    • The import of the devices must be merged with existing devices in the HDM Simulator. In order to do this, the devices listed in the new configuration need to be deleted first and then to be re-created. Removing an imported simulated device manually will not do the full job. In order to fully remove a simulated device, it is necessary to import an empty XML file for the simulated Protocol Adapter. Have in mind that importing an empty XML file will remove the devices only for the specific simulated Protocol Adapter. An example of how a device class with an empty "simulate" node looks like is available:

      <config name="Volume">

         <property key="name" value="com.prosyst.mbs.services.hdm.deviceclasses.Volume" type="string"/>
         <config name="simulate"/>

      </config>

Adding Adapter Properties Definitions

To introduce a simulated Protocol Adapter you should specify the properties of this Protocol Adapter in a configurable of type HDMDeviceClassSimulation. Importing an XML with the adapter properties definitions is not required in order a specific home protocol adapter simulation to be supported, since the simulated protocol can have no supported properties. When an XML with home devices for a specific protocol adapter is added and there are no protocol adapter properties imported as an XML file, the import process will not fail but the adapter properties of the devices will be considered as user/side properties. In any other case all adapter properties, including both generic and device class specific need to be described in the definitions node. The general adapter properties are always defined with a config property with key 'general'.

In order to illustrate the definition of adapter properties in a XML file, an example is provided. In the code snippet below the serialNumber property and the 'device.classes' node of the protocol adapter "X" are defined.

The root 'config' node has an attribute "name" with value HDMDeviceClassSimulation. It has one 'config' child node with attribute "name" with value - the name of the simulated protocol adapter - in this case "X". This node has one child 'config' node with attribute "properties" which contains the names of all the simulated adapter properties. The child 'config' node definitions contains the metadata description of the included adapter properties (value, type and key) and it shows the name of the property, which in the example is serialNumber. In the definitions node all adapter properties must be described, both the general and the device class properties.

Device class properties should be always described under a device.classes type node. device.classes should contain definitions with device class specific properties. The device.classes node should firstly have a child 'config' node - "name"(user-friendly one), "BinarySwitch" in the case bellow. Each 'device.classes' config node contains a config node with the full name of the device class. The next config node starts the representation of the simulated properties. The device class simulated properties node contains one 'properties' config property which contains all device class specific properties for this device class, as seen in the example. These nodes are optional as shown. If included, the "property" child node must have the "type", "value" and "key" of the property. Of course there are various combinations that could be included as definitions - see next section.

The following code snippet defines the serialNumber property and the 'device.classes' node of the protocol adapter "X" and "Y" respectively.

<config name="HDMDeviceClassSimulation">

  <config name="X">                         <!-- optional -->

    <config name="properties">              <!-- optional -->

      <property value="serialNumber,level"  type="string[]"  key="general"/>     <!-- optional -->

      <config name="definitions">           <!-- optional -->

       <config name="serialNumber">         <!-- optional -->

        <config name="metadata">            <!-- optional -->

          <property value="R"  type="string"  key="access"/>                         <!-- optional-->

          <property value="mandatory"  type="string"  key="resolution"/>

        </config>

      </config>

    </config>

  </config>

  <config name="Y">

    <config name="device.classes">

             <!-- optional -->

      <config name="BinarySwitch">

             <!-- optional -->

        <property value="com.prosyst.mbs.services.hdm.deviceclasses.BinarySwitch"  type="string"  key="name"/>

        <config name="simulate">

             <!-- optional -->

          <config name="turnOn">                                                             <!-- optional -->

            <config name="property">

              <property value="state"  type="string"  key="name"/>                           <!-- optional -->

              <property value="1"  type="string"  key="value"/>

            </config>

          </config>

          <config name="turnOff">

            <config name="property">

              <property value="state"  type="string"  key="name"/>

              <property value="0"  type="string"  key="value"/>

            </config>

          </config>

        </config>

      </config>

    </config >

  </config>

</config>

Adding Device Class Definitions

Adding definitions for the simulated device classes, that are used by the simulated devices is important, since that way, they are marked that are supported by the simulated protocol adapter.

In this type of XML description, the actual semantics of the schema is very important because it illustrates the simulation steps that occur. Every 'config' node, represents a simulation 'step' and has a specific place for its exact function. To make things more clear every property or operation simulation is basically consisted of steps and each step represents another property/operation that is being invoked by one simulated operation. One must know that plenty of combinations are supported by the Simulator. A simulated operation may including: invoking two and more properties/operations within a main property, an operation/property invoked by another property, various types of expressions and arguments in all combinations that have a certain logic. Keep in mind that when more than one property is included in the simulation logic, it is better to index each of them with a suffix e.g. property1; property2; etc.

In order to illustrate the definitions of simulated device classes, a simple example is provided. A description of the simulation 'config' node follows.

The root 'config' node has an attribute "name" with value HDMDeviceClassSimulation. It has one 'config' child node with attribute "name" with value - the name of the simulated protocol adapter - in this case "X". This node has one child 'config' node with attribute 'device.classes'. The simulated device class is defined in a child 'config' node with attribute "name", with value - a user-friendly name of the simulated device class - in this case BinariSwitch. The next node contains the actual full name of the simulated device class. The device class can have different simulation behaviour depending on the type of the device class. Each protocol adapter can define its own, specific simulation for each device class.

The functionalities are defined in a 'config' node named "simulate". Simulations are not recursive in the Home Device Manager. These simulations are valid only for the concrete device class. Under the "simulate" 'config' node there is a list with all additional properties. Every property is defined primarily by its name, followed by a child 'config' node stating it is a property. The next child 'config' node defines the simulation steps that will occur and their logic is found in the list right above the example. As seen, at the bottom of the example there is a simulated operation - readPowerSequence, which is configured by a 'config' node with its specific name, followed by a child node, on the next level, stating that it is an "operation". The next property 'config' node actually shows that this operation is invoking another operation with the name sequenceStatistics. This operation is defined with arguments, so all necessary properties are noted under the args 'config' node.

In general, when the DeviceClassObject property value is set, the property will always receive this exact value that comes from the setter. If any other simulation logic does exist, it is executed additionally. That way both of the simulations will be executed. The device class can have different simulation behaviour depending on its type. Each protocol adapter can define its own, specific simulation for each necessary device class. Another thing to have in mind is that when simulating an operation with arguments everything necessary is defined under a 'config' node named args, as said before.

Below is the example configuration of the BinariSwitch device class. It supports the following property simulation steps:

• when the property "turnOn" is changed, the property "state" is assigned the value "1"
• when the property "turnOff" is performed, the property "state" is assigned the value "0"
• when the property "toggle" is performed, the property "state" is assigned the value of the property "state ^ 1"
• when the operation "readPowerSequence" is performed, it invokes another operation with the name "sequenceStatistics" which is defined with arguments

  <config name="HDMDeviceClassSimulation">

    <config name="X">                       <!-- optional -->

      <config name="device.classes">        <!-- optional -->

      <config name="BinarySwitch">          <!-- optional -->

        <property value="com.prosyst.mbs.services.hdm.deviceclasses.BinarySwitch" type="string" key="name"/>

        <config name="simulate">            <!-- optional -->

          <config name="turnOn">            <!-- optional-->

            <config name="property">        <!-- optional-->

              <property value="state"  type="string"  key="name"/>

              <property value="1"  type="string"  key="value"/>

            </config>

          </config>

          <config name="turnOff">

            <config name="property">

              <property value="state"  type="string"  key="name"/>

              <property value="0"  type="string"  key="value"/>

            </config>

          </config>

          <config name="toggle">

            <config name="property">

              <property value="state"  type="string"  key="name"/>

              <property value="state ^ 1"  type="string"  key="value"/>

             </config>

            </config>

          </config>

          <config name="readPowerSequence">

            <config name="operation">

              <property value="sequenceStatistics"  type="string"  key="name"/>

              <config name="args">

                <property value="3"  type="string"  key="1"/>

                <property value="4"  type="string"  key="2"/>

              </config>

            </config>

          </config >

        </config>

      </config>

    </config>

  </config>

Specifying Additional Device Classes Supported by the Simulated Protocol Adapter

If any custom device class property or operation simulation is skipped, or in order to mark that a device class is supported by the simulated protocol adapter, the imported definitions for the device classes need to be empty. This is a type of special case when the imported device class definitions lack simulation.

Additional Device Classes that are supported by the Simulated Protocol Adapter are specified in a configurable of type HDMDeviceClassSimulation. In such a configurable are included all Device Classes that are not predefined by the Simulated Protocol Adapter and there is no definition for their properties and operations in a separate configurable. The root 'config' node has an attribute "name" with value HDMDeviceClassSimulation. It has one 'config' child node with attribute "name" with value - the name of the simulated protocol adapter - in this case "X".

This node has one child 'config' node with attribute "device.classes". Each device class is specified in a child 'config' node with attribute "name" and value - the name of the device class. As a property to this child node is given the full name (with package name) of the simulated device class.

Definitions for the simulated device classes used by the simulated devices for the simulated protocol adapter have to be added in order to mark that they are supported by it. It is not necessary to provide simulation logic for the supported device classes so you can use empty simulations as in the example below.

The following code snippet defines that the simulated protocol adapter "X" will support the device class Color.

<config name="HDMDeviceClassSimulation">

  <config name="X">

    <config name="device.classes">

      <config name="Color">

        <property key="name" value="demo.hdm.dc.Color" type="string"/>

      </config>

    </config>

  </config>

</config>

Defining Home Devices to be Created for the Simulated Protocol Adapter

To introduce simulated device classes you need to import their configurations in the ConfigTree. Each device configuration is imported as a configurable of type HDMDeviceSimulator. It contains the definitions of the simulated "X" protocol devices.

The configurable starts with a root 'config' node and attribute “name” with value “Devices”. The root has child 'config' node “X”. In this node are described all simulated HomeDevices as child 'config' nodes. Each root device is described in a child node with name starting with "HomeDevice" of the 'config' node "X". The device predefined properties like "name", "vendor", "UID", type etc. are described as 'config' properties of the device 'config' node with key - the name of the property. The device additional properties (both user and adapter), e.g. "path" and "model" are contained as 'config' properties of the "Properties" 'config' node.

The device class descriptions are contained in the child 'config' node "DeviceClasses" of the device 'config' node. As a child 'config' node you can find all properties associated with the specific listed device class. Bellow this node is situated the "name", "key", "value" and "type" of the property. The DeviceClassObject "value" property has very little limitations in simulations and may include arithmetic operations on other values, on properties or a constant itself. The root and child device 'config' node have the exact same structure and basically look alike in the XML schema. The list of child devices are organized the same way and the only difference from the name of the parent device in its corresponding "child" number e.g. :1, :2 etc.

After the listing of properties, the list of operations is found. The example for operations can be found for the second device in the XML snippet, grouped under the 'config' node with name "spine". Each operation is specified, primarily by its name, in a separate 'config' node. There is a "child" node "metadata" and bellow it are to be found the properties of the operation, which include "key", "value" and "type".

<config name="Devices">

  <config name="X">

    <config name="HomeDevice_hdm:X:SIEMENS-SN278I36TE-68A40E0118B7">

      <property key="UID" value="hdm:X:SIEMENS-SN278I36TE-68A40E0118B7" type="string"/>

      <property key="name" value="Dishwasher SIEMENS SN278I36TE" type="string"/>

      <property key="vendor" value="BOSCH" type="string"/>

      <property key="type" value="Dishwasher" type="string"/>

      <config name="Properties">

        <property key="path" value="/ship" type="string"/>

        <property key="model" value="SN278I36TE" type="string"/>

      </config>

      <config name="DeviceClasses">

        <config name="com.prosyst.mbs.services.ship.hdm.deviceclasses.PairingControl">

          <config name="operations">

            <config name="pair">

              <config name="metadata">

                <property key="description" value="Pairs the device." type="string"/>

              </config>

            </config>

            <config name="unpair">

              <config name="metadata">

                <property key="description" value="Unpairs the device." type="string"/>

              </config>

            </config>

          </config>

        </config>

      </config>

    </config>

   <config name="spine">

    <config name="HomeDevice_hdm:spine:d:_i:20219_BOSCH-DUMMY06E06-68A40E004D2F">

      <property key="UID" value="hdm:spine:d:_i:20219_BOSCH-DUMMY06E06-68A40E004D2F" type="string"/>

      <property key="vendor" value="BOSCH" type="string"/>

      <property key="name" value="Dishwasher" type="string"/>

      <property key="type" value="Dishwasher" type="string"/>

      <config name="Properties">

        <property key="firmware.version" value="1.4.6" type="string"/>

        <property key="hdmuid.deviceLinks" value="hdm:ship:BOSCH-DUMMY06E06-68A40E004D2F" type="string"/>

        <property key="deviceCode" value="DUMMY06E06" type="string"/>

      </config>

      <config name="HomeDevice_hdm:spine:d:_i:20219_BOSCH-DUMMY06E06-68A40E004D2F::1">

        <property key="UID" value="hdm:spine:d:_i:20219_BOSCH-DUMMY06E06-68A40E004D2F::1" type="string"/>

        <property key="vendor" value="BOSCH" type="string"/>

        <property key="type" value="Dishwasher" type="string"/>

        <property key="status" value="2" type="int"/>

        <config name="DeviceClasses">

          <config name="com.prosyst.mbs.services.spine.hdm.deviceclasses.whitegoods.Dishwasher">

            <property key="polling interval" value="0" type="long"/>

            <config name="Properties">

              <config name="powerSequenceAlternatives">

                <property key="value" value="[{powerSequences:[{state{state:2,sequenceId:0,activeSlotNumber:-1,sequenceRemoteControllable:true},description:null,

                                            startTime:1467396836880,stoppable:false,valueSource:2}],alternativeId:1}]" type="string"/>

                <config name="metadata">

                  <property key="access" value="RE" type="string"/>

                  <property key="description" value="Property name for power sequence &quot;alternatives&quot; group." type="string"/>

                </config>

              </config>

              <config name="sequenceId">

                <property key="value" value="-1" type="long"/>

                <config name="metadata">

                  <property key="access" value="RWE" type="string"/>

                  <property key="description" value="Property name for the chosen sequence on the appliance. The value is applicable only when the appliance has a selected sequence.

                Additionally this property is also used for configuring an appliance schedule - setting start or end time, configuration of the power time slots." type="string"/>

                </config>

              </config>

              <config name="stoppable">

                <property key="value" value="false" type="boolean"/>

                <config name="metadata">

                  <property key="access" value="RE" type="string"/>

                  <property key="description" value="Property name for indication if the chosen power sequence can be stopped/canceled." type="string"/>

                </config>

              </config>

            </config>

            <config name="operationss">

              <config name="readPowerSequence">

                <config name="metadata">

                  <property key="description" value="Requests all the information of one specific power sequence the power sequences server offers." type="string"/>

                  <property key="IN1" value="The ID of the sequence information to read." type="string"/>

                  <property key="OUT" value="the information of the requested power sequence." type="string"/>

                </config>

              </config>

              <config name="readPowerSequenceState">

                <config name="metadata">

                  <property key="description" value="Requests the current state of one specific power sequence the power sequences server offers." type="string"/>

                  <property key="IN1" value="The ID of the sequence state to read." type="string"/>

                  <property key="OUT" value="The current state of the requested power sequence." type="string"/>

                </config>

              </config>

              <config name="start">

                <config name="metadata">

                  <property key="description" value="Starts or resumes the selected power sequence on the appliance." type="string"/>

                </config>

              </config>

              <config name="stop">

                <config name="metadata">

                  <property key="description" value="Cancels the selected power sequence on the appliance." type="string"/>

                </config>

              </config>

            </config>

          </config>

        </config>

      </config>

    </config>

  </config>

Home devices can be added manually via the HDM API or the WebAdmin Console. In this case, it is required to include a 'simulated.protocol' adapter property. If this property is not included, the default value will be set to "Simulator" which means that the simulated protocol adapter will be the "Simulator" protocol adapter. Adapter properties that are going to be included in the "properties" 'config' node should support the simulated protocol or they will be considered as device user properties. If "required" properties exist, meaning that they are imported through an XML file and not manually, they must be incorporated in the 'config' node with specific properties. This is relevant for both, general properties and device class ones. When adding parent-child devices, have in mind that a combination of manual and configurable adding will not work. The devices exported via the configurable Devices can be directly imported in the HDMDeviceSimulator configurable, as they share the same structure, and that way they will be added as simulated devices. Some properties e.g. 'status' , will be ignored. It is not required to import only exported XML files for the Devices configurable. As a matter of fact every XML that matches the structure of the configurable can be imported into the Simulator.

Limitations:

There are some limitations that need to be taken under consideration while working with the HDM Simulator:

• Ternary expressions work only with numeric operands. For example:

  java.lang.IllegalArgumentException: Error while trying to calculate the expression 'muted'.

  Unexpected value was received: true

• DeviceClassObject properties are not supported in String expressions. The HDM Simulator has to distinguish the references to other "DeviceClass" properties in expressions of type String. The HDM Simulator is using the text as String instead of Get value of the specified DeviceClassObject property.
• By default, it is not possible to use a new DeviceClassObject property value in DeviceClassObject property simulation expressions. When the DeviceClassObject property is set, the property value will be changed with the new value. Optionally, if a property simulation exists - additional logic can be performed.
• When invoking a property simulation without any value, a NullPointerException will occur.
• When invoke or set a DeviceClassObject property or operation that internally invokes the simulation of an operation, some operation arguments may be skipped. They will be considered as null and an IllegalArgumentException will be thrown.
• The DeviceClassObject simulation for several DeviceClassObject properties or operations are executed in an undefined order.
• Create map, array and bean DeviceClassObject property values are not supported.
• There is no simulation of DeviceClass property bean, array or null property value.
• The HDM Simulator does not support all valid DeviceClass property names. If the DeviceClass property name contains "$" or "_" some errors might occur.
• The HDM Simulator does not support conditional execution of DeviceClassObject simulations. When a condition in terms of the Simulator is evaluated as true or false, then a sequence of simulations can be executed.
• Exception simulations are not supported.
• Not all math functionalities are supported. The same goes for any random value.
• Internal properties are not supported.
• The following expression operator are not supported: "++", "--", ">>>" .
• NetworkController is not supported.