To add new devices to openHES, follow these steps:

1. Obtain the driver information.
2. Create a configuration template.
3. Create a configuration register.
4. Assign the register to the configuration template.
5. Create a communication unit.
6. Create the device in openHES.
7. Create a bulk operation to schedule and manage data readings from devices.

Important

All requests in this documentation follow this endpoint structure:

/io.clbs.openhes.services.svcapi.ApiService/{endpoint}

Replace {endpoint} with the specific API action listed in each section.

Get Driver Information

Before configuring a device, you must identify what data is available for its device type. This is determined by the device driver.

• Driver manufacturers provide a list of devices supported by each driver.

List Drivers

To retrieve the driver identification, send a request to the ListDrivers endpoint.

Example request:

{
  "pageSize": 1000,
  "offset": 0
}

In the response, identify the driverType corresponding to your device.

Example response:

{
  "items": [
    {
      "spec": {
        "version": "v0.9.36",
        "driverType": "CYBROSLABS_GENERIC_DLMS_LN"
      }
    },
    {
      "spec": {
        "version": "v0.9.36",
        "driverType": "CYBROSLABS_GENERIC_DLMS_SN"
      }
    },
    {
      "spec": {
        "version": "v0.9.36",
        "driverType": "LANDISGYR_GENERIC_DLMS_SN"
      }
    }
  ]
}

Get Detailed Driver Information

Once you have the driverType, you can now request detailed information about what the driver can read from the device.

Send a request with the identified driverType to the GetDriver endpoint.

Example request:

GetDriver("CYBROSLABS_GENERIC_DLMS_SN")

The response provides data that is necessary for further configuration steps.

{
"spec": {
  "version": "v0.9.36",
  "listeningPort": 11000,
  "driverType": "CYBROSLABS_GENERIC_DLMS_SN",
  "maxConcurrentJobs": 500,
  "maxCascadeDepth": 100,
  "typicalMemUsage": 1024,
  "templates": {
    "communicationTemplates": [
      {
        "type": "COMMUNICATION_TYPE_TCPIP",
        "datalinks": [
          {
            "linkProtocol": "LINKPROTO_HDLC",
            "appProtocolRefs": [
              "APPPROTO_DLMS_SN"
            ],
            "attributes": [
              {
                "fieldId": "negotiate",
                "label": "Negotiate hdlc frame size.",
                "dataType": "BOOLEAN",
                "required": false
              }
            ]
          }
        ]
      }
    ],
    "appProtocols": [
      {
        "id": "dlms_sn",
        "protocol": "APPPROTO_DLMS_SN",
        "attributes": [
          {
            "fieldId": "acclevel",
            "label": "Access level. Supported options are: ...",
            "dataType": "INTEGER",
            "required": false,
            "defaultValue": {
              "integerValue": "32"
            }
          },
          {
            "fieldId": "physical",
            "dataType": "INTEGER",
            "required": false,
            "defaultValue": {
              "integerValue": "0"
            }
          },
          {
            "fieldId": "logical",
            "dataType": "INTEGER",
            "required": false,
            "defaultValue": {
              "integerValue": "1"
            }
          },
          {
            "fieldId": "password",
            "dataType": "TEXT",
            "required": false
          }
        ]
      }
    ],
    "actionAttributes": [
      {
        "type": "ACTION_TYPE_GET_REGISTER",
        "attributes": [
          {
            "fieldId": "obis",
            "dataType": "TEXT",
            "required": true
          }
        ]
      },
      {
        "type": "ACTION_TYPE_GET_PERIODICAL_PROFILE",
        "attributes": [
          {
            "fieldId": "obis",
            "dataType": "TEXT",
            "required": true
          },
          {
            "fieldId": "buffer",
            "dataType": "TEXT",
            "required": true
          }
        ]
      }
    ],
    "accessTemplates": []
  },
  "displayName": "cybros labs Generic DLMS/SN"
}
}

→ API OBJECT documentation (Get Driver Info)

Create Configuration Register

Configuration registers specify the exact data points to read from a device.

• Information about the register definition is in the GetDriver response under actionAttributes.

To create a register, send a request to the CreateDeviceConfigurationRegister endpoint.

Example request:

{
    "spec": {
      "driverType": "LANDISGYR_GENERIC_DLMS_SN",
      "registerType": "REGISTER",
      "attributes": {
        "obis": { "stringValue": "1-1:1.8.0.255" }
      },
    },
    "metadata": {
      "fields": {
        "field_01": {
          "stringValue": "Field 01"
        }
      },
      "managedFields": { },
      "name": "TEST_FAKE_REGISTER_01"
    }
  }

→ API OBJECT documentation (Create Config Register)

The response contains a unique register ID.

Example response:

"01958ef2-4724-71d5-9d0a-9c7178b1c687"

Create Configuration Template

Configuration templates contain information about communication protocols and attributes that are necessary for reading data from the device.

To create a template, send a request to the CreateDeviceConfigurationTemplate endpoint.

Example request:

{
  "spec": {
    "driverType": "LANDISGYR_GENERIC_DLMS_SN"
  },
  "metadata": {
    "name": "TEST_LG_650"
  }
}

→ API OBJECT documentation (Create Config Template)

• You can use the name to search for particular templates or as a display name in the user interface.

The response contains a unique template ID.

Example response:

"01958ede-87b2-7932-95e9-d608e1318eef"

Assign Register to Template

To avoid sending all register info every time you want to read data, you can assign registers to templates and then use the template ID with list of actions to read.

To assign a register to a template, send a request with the template ID (dctId) and register ID to the AddDeviceConfigurationRegisterToDeviceConfigurationTemplate endpoint.

Example request:

{
    "dctId": "01958ede-87b2-7932-95e9-d608e1318eef",
    "registerId": "01958ef2-4724-71d5-9d0a-9c7178b1c687"
}

→ API OBJECT documentation (Add Register to Template)

Create Communication Unit

Communication units enable connections between openHES and devices.

• Information about the communication unit definition is in the GetDriver response under communicationTemplates.
• Details must also be provided by the device installer.

To create a communication unit, send a request to the CreateCommunicationUnit endpoint.

→ API OBJECT documentation (Create Communication Unit)

{
  "spec": {
    "externalId": "TEST_COMMUNICATION_UNIT",
    "connectionInfo": {
      "tcpip": {
        "host": "10.77.1.160",
        "port": 20009,
        "timeout": "60s"
      },
      "linkProtocol": "LINKPROTO_HDLC"
    }
  },
  "metadata": {
    "name": "TEST_COMMUNICATION_UNIT"
  }
}

{
  "spec": {
    "externalId": "TEST_COMMUNICATION_UNIT",
    "connectionInfo": {
      "modemPool": {
        "number": "+420111222333",
        "poolId": "3",
        "modem": {
          "name": "name of modem",
          "tcpip": {
            "host": "10.72.0.45",
            "port": 20458,
            "timeout": "30s"
          }
        }
      },
      "linkProtocol": "LINKPROTO_HDLC",
      "attributes": {
        "access_level": { "integerValue": 32},
        "password":{ "stringValue": "000000"},
        "address" : {"integerValue": 1}
      }
    }
  },
  "metadata": {
    "name": "TEST_MODEM_COMMUNICATION_UNIT"
  }
}

{
  "spec": {
    "externalId": "TEST_COMMUNICATION_UNIT",
    "connectionInfo": {
        "serialOverIp": {
          "moxa" :
          {
              "host": "10.78.3.50",
              "dataPort": 20456,
              "commandPort": 20789,
              "timeout": "60s"
          }

        },
        "linkProtocol": "LINKPROTO_HDLC",
        "attributes": {
        "access_level": { "integerValue": 32},
        "password":{ "stringValue": "000000"},
        "address" : {"integerValue": 1}
      }
    }
  },
  "metadata": {
    "name": "TEST_MOXA_COMMUNICATION_UNIT"
  }
}

• You can use the name to search for particular communication units or as a display name in the user interface.
• If each device has its own communication unit, we recommend to use similar names.

The response contains a unique communication unit ID.

Example response:

"01958f03-af85-7b8e-8969-b0f9c12def6e"

Create Device

To register a new device in openHES and assign the communication unit for data exchange, send a request to the CreateDevice endpoint.

Example request:

{
  "spec": {
    "dctId": "01958ede-87b2-7932-95e9-d608e1318eef",
    "externalId": "ext-test.device.clbs.io-001",
    "attributes": {
      "physical": {
        "integerValue": "7001"
      },
      "acclevel": {
        "integerValue": "32"
      },
      "password": {
        "stringValue": "00000000"
      }
    },
    "communicationUnitLink": [
      {
        "communicationUnitId": "01958f03-af85-7b8e-8969-b0f9c12def6e",
        "appProtocol": "APPPROTO_DLMS_SN"
      }
    ],
    "timezone": "Europe/Prague"
  },
  "metadata": {
    "name": "test.device.clbs.io-001"
  }
}

→ API OBJECT documentation (Create Device)

• You can use the name to search for particular devices or as a display name in the user interface.
• If each device has its own communication unit, we recommend to use similar names.

The response contains a unique device ID.

Example response:

 "01958f30-9b30-752b-b917-533a55831c87"

Update Device Communication Units

If you want to assign additional communication units to previously created devices, send a request with the communication ID to the SetDeviceCommunicationUnits endpoint.

Example request:

{
  "deviceId": "01958f30-9b30-752b-b917-533a55831c87",
  "communicationUnits": [
    {
      "communicationUnitId": "01958f03-af85-7b8e-8969-b0f9c12def6e",
      "appProtocol": "APPPROTO_SCTM"
    },
    {
      "communicationUnitId": "91958f03-af85-7b8e-8969-b0f9c12def6e",
      "appProtocol": "APPPROTO_DLMS_LN"
    }
  ]
}

→ API OBJECT documentation (Update Communication Units)