Skip to content

Telemetry

Homegear Cloudconnect can send telemetry to Sensaru Cloud. For this to work, follow the following configuration steps in Homegear:

Global configuration

There is only one required global configuration step for Homegear: Create a category with the English name telemetry: homegear -e rc 'print_v($hg->createCategory(["en" => "Telemetry"]));'

That's it.

Configure variables to be sent to Sensaru Cloud

By default, no variable updates are sent to Sensaru Cloud. To send variable updates to Sensaru Cloud, the following needs to be done:

  1. Assign a role to the variable. Please note that the role must be supported by Sensaru Cloud. This does not apply to all roles in Homegear.
  2. Assign the category telemetry to the variable.

That's it.

Assign tags to a variable

Homegear uses roles to encode what a variable is, i. e. a setpoint temperature, a power meter value or the state of a light. Tags are used to encode what a variable is used for**. For example "this is a power meter for the heat pump". Tags should be used whenever there are multiple devices with the same role and a further differentiation is required.

The equivalent to a tag in Sensaru Cloud is a category in Homegear. So assign a tag to a variable first create a category for the tag:

~$ homegear -e rc 'print_v($hg->createCategory(["en" => "Heat pump"]));'
(Integer64) 12

Then assign this category to a variable (peer ID 5, channel 1, variable VALUE):

homegear -e rc '$hg->addVariableToCategory(5, 1, "VALUE", 12);'

The English name of the category is used as the tag. The name is stripped of all non-ASCII characters, all characters are converted to lower case and space is replaced with a dash. So Heat pump becomes the tag heat-pump. Please note, that the tag is displayed with the device in Sensaru Cloud - not the data point.

Alternatively, you can assign the tag directly to the device in Homegear as well.

homegear -e rc '$hg->addDeviceToCategory(5, 12);'

Assign a section to a variable

In addition to the tag, you can also assign a section the device should be listed under to a variable. For follow the steps to assign tags to a variable but prefix the category name with Section, e. g. Section primary facilities (without any special characters except for the space character). As for tags, the section is also assigned to the device in Sensaru Cloud (not the variable). Multiple sections are allowed per device.

Set a different location ID

Sometimes it is necessary to specify a location ID that differs from the location ID encoded in the Homegear Cloudconnect certificate. I. e. an economic unit might be required to send events for the associated buildings or administration units. It is possible to specify the location ID on the variable level. There is one restriction: The location ID must be the same or hierarchically lower than the location ID specified in the Homegear Cloudconnect certificate. For example if the location ID encoded in the certificate is 1234.1, the location ID of the variable can be 1234.1.2 or 1234.1.42. It cannot be 4321, 1234.2 or 1234.2.2.

Lets say the location ID specified in the Homegear Cloudconnect certificate is 1234 which encoded for an economic unit.

To set a different location ID for a variable, first create a building part:

~$ homegear -e rc 'print_v($hg->createBuildingPart(["en" => "Apartment 1"], ["au" => "1234.1.2"]));'
(Integer64) 5

The location ID is specified using the metadata struct and setting au there. 1234.1.2 encodes for an administration unit, e. g. an apartment.

The same can be done for buildings. Caution: Currently buildings are also set using building parts:

~$ homegear -e rc 'print_v($hg->createBuildingPart(["en" => "Building 1"], ["au" => "1234.1"]));'
(Integer64) 6

These building parts now can be assigned to variables:

homegear -e rc '$hg->addVariableToBuildingPart(5, 1, "VALUE", 6);'

This variable now creates telemetry for the building 1234.1 instead of the economic unit 1234.

Assign an equipment ID to the device

An equipment ID (e. g. the German AKS code) can be assigned to the device using the device's metadata. For example for peer with ID 5:

homegear -e rc '$hg->setValue(5, -1, "equipmentId", "123456");'

Device hierarchies / setting the parent device

A parent device and the "direction" (is the parent an input or output relative to the device) can be set. The property parent has the form <edge client location ID>_<peer ID>. parentDirection can be 0 for input/substraction ("this device is an input for the parent device/is located before the parent device", for a meter this device's value will be subtracted from the parent device's sum value) or 1 for output/addition ("this device is located after the parent device", for a meter this device's value will be added to the parent device's sum value).

homegear -e rc '$hg->setValue(5, -1, "parent", "60:18301_4");'
homegear -e rc '$hg->setValue(5, -1, "parentDirection", 0);'

Change the service message variable priority

Sometimes it might be required to change the priority of a service message variable (i. e. warning, error or critical). To do this, assign one of these categories to the service variable:

  • priority-info

  • priority-warning

  • priority-error
  • priority-critical

If the category doesn't exist, create it first:

~$ homegear -e rc 'print_v($hg->createCategory(["en" => "Priority error"]));'
(Integer64) 24

As with the other categories in this chapter, the English name of the category is used as the identifier. The name is stripped of all non-ASCII characters, all characters are converted to lower case and space is replaced with a dash. So Priority error becomes the tag priority-error.

Now assign this category to the variable:

homegear -e rc '$hg->addCategoryToVariable(5, 1, "ALARM", 24);'

Adding a device's web administration URL

Sensaru Cloud can proxy device's web administration interfaces. For this homegear-cloudconnect needs to be configured accordingly (see chapter network tunnels). After it has been configured, you can set the metadata property uiClientInfo on the device to the client index used in the homegear-cloudconnect configuration and to the URL path to open on the target device:

homegear -e rc '$hg->setValue(5, -1, "uiClientInfo", ["index" => 4, "path" => "/index.html"]);'