Implementing Device Logic

You can implement your device logic on any programming language you want. You need to know about the following:

• How to communicate with device. Often it works via modbus, CAN etc. This part is out of scope of this documentation.
• How to communicate with MQTT broker. You can use any MQTT library you want.
• How to use Enapter Device MQTT API. This part is described below.

Device MQTT API

Device MQTT API is completely described here. The key points are:

• MQTT topic for telemetry — v1/from/<hardware_id>/<channel_id>/v1/telemetry.
• MQTT topic for properties — v1/from/<hardware_id>/<channel_id>/v1/properties.
• Telemetry and properties message payload is a JSON object with timestamp and attributes.
• MQTT topic for command requests — v1/to/<hardware_id>/<channel_id>/v1/command/requests.
• Command request message payload is a JSON object with request id, command name, and optional command arguments.
• MQTT topic for command responses — v1/from/<hardware_id>/<channel_id>/v1/command/responses.
• Command response message payload is a JSON object with request id, execution state, and optional payload result.

Python example

Here is a simple example of Enapter Device MQTT API usage on Python using paho-mqtt library.

This example is as simple as possible. It does not handle the following:

• Reconnecting to MQTT broker.
• Connecting to the gateway using mDNS.
• Communicating with real device.

To run the example, do the following:

• Create the virtualenv: virtualenv my_device_src.
• Go to virtualenv: cd my_device_src.
• Activate it: source bin/activate.
• Install paho-mqtt library: pip install paho-mqtt.
• Copy previosly saved server-ca.crt, client.crt, client.key into my_device_src folder.
• Copy the following example into script.py.

import paho.mqtt.client as mqtt
import json
import time

mqtt_host = "mqtt.enapter.com"
mqtt_port = 1883
hardware_id = "SD595D4EF54C643B7988AADDBF12A2E30"
channel_id = "s"

command_req_topic = f"v1/to/{hardware_id}/{channel_id}/v1/command/requests"
command_resp_topic = f"v1/from/{hardware_id}/{channel_id}/v1/command/responses"
properties_topic = f"v1/from/{hardware_id}/{channel_id}/v1/properties"

def on_connect(client, userdata, flags, reason_code, properties):
    client.subscribe(command_req_topic)

def on_message(client, userdata, msg):
    if msg.topic == command_req_topic:
        req = json.loads(msg.payload)
        print('received command request:', req)
        resp = {
            "id": req["id"],
            "state": "completed",
            "payload": {
                "new_power": 4700
            }
        }
        client.publish(command_resp_topic, json.dumps(resp))

mqttc = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2)
mqttc.tls_set(
    ca_certs='./server-ca.crt',
    certfile='./client.crt',
    keyfile='./client.key'
)
mqttc.on_connect = on_connect
mqttc.on_message = on_message

mqttc.connect(mqtt_host, mqtt_port, 60)

mqttc.loop_start()

while True:
    props = {
        "timestamp": int(time.time()),
        "vendor": "Enapter",
        "fw_ver": "7.5.0"
    }
    mqttc.publish(properties_topic, json.dumps(props))
    print('sent properties:', props)
    time.sleep(30)

mqttc.loop_stop()