Project (2022-03 Plugfest): TDs for Commercial Devices

[mmccool]

I have the following commercial systems in my lab and want to write TDs for them and make them available on the VLAN for testing:

• Victron Energy OctoGX (Solar Power system monitor) connected to Victron Energy 30/100 MPPT Charger - MQTT (also MODBUS/TCP)
• Goal Zero Yeti 1500X (Lithium battery 1.5kWh + AGM 9kWH, (solar charger), inverter... etc) - HTTP
• Shelley Door/Window 2 - HTTP, CoAP (CoIoT), MQTT - Gen1
• Home Assistant/Weatherflow Tempest - MQTT (gateway from proprietary UDP protocol), support MQTT Discovery

To do:

• Get VLAN set up
• Write TDs

[relu91]

I've been working on MQTT protocol binding template lately and I'm now starting to work on practical examples. I thought that using a real device would test the expressivity of the ontology. So I tried to describe Shelly Gas sensor following the documentation linked about. I'm posting some thoughts here. This is the final TD (expand if needed):

Gas sensor MQTT TD

{
  "@context": "https://www.w3.org/2019/wot/td/v1",
  "title": "Shelly Gas",
  "id": "urn:dev:test",
  "description": "Shelly Gas is a sensor that can measure combustible gas concentration and issue an alarm in the event of a gas leak. Shelly Gas operates on AC voltage.",
  "securityDefinitions": {
    "nosec_sc": {
      "scheme": "nosec"
    }
  },
  "security": "nosec_sc",
  "properties": {
    "status": {
      "title": "Sensor status",
      "observable": true,
      "enum": [
        "unknown",
        "warmup",
        "normal",
        "fault"
      ],
      "type": "string",
      "forms": [
        {
          "href": "mqtt://broker.com/",
          "mqtt:filter": "shellies/shellygas-<deviceid>/sensor/operation",
          "op": "observeproperty"
        }
      ]
    },
    "concentration": {
      "title": "Gas concentration",
      "observable": true,
      "readOnly": false,
      "minimum": -1,
      "maximum": 65535,
      "type": "integer",
      "forms": [
        {
          "href": "mqtt://broker.com",
          "mqtt:filter": "shellies/shellygas-<deviceid>/sensor/concentration",
          "op": "observeproperty"
        }
      ]
    },
    "gasAlarm": {
      "title": "Gas Alarm",
      "observable": true,
      "enum": [
        "unknown",
        "none",
        "mild",
        "heavy",
        "test"
      ],
      "type": "string",
      "forms": [
        {
          "href": "mqtt://broker.com",
          "mqtt:filter": "shellies/shellygas-<deviceid>/sensor/gas",
          "op": "observeproperty"
        }
      ]
    },
    "valve": {
      "title": "Valve",
      "observable": true,
      "enum": [
        "unknown",
        "closed",
        "opened",
        "not_connected",
        "failure",
        "closing",
        "opening",
        "checking"
      ],
      "type": "string",
      "forms": [
        {
          "href": "mqtt://broker.com/",
          "mqtt:filter": "shellies/shellygas-<deviceid>/valve/0/state",
          "op": "observeproperty"
        }
      ]
    }
  },
  "actions": {
    "mute": {
      "title": "Mute",
      "forms": [
        {
          "href": "mqtt://broker.com/",
          "mqtt:topic": "shellies/shellygas-<deviceid>/sensor/mute",
        }
      ]
    },
    "unmute": {
      "title": "Unmute",
      "forms": [
        {
          "href": "mqtt://broker.com/",
          "mqtt:topic": "shellies/shellygas-<deviceid>/sensor/unmute",
        }
      ]
    },
    "changeValveStatus": {
      "title": "Change Valve Status",
      "input": {
          "type": "string",
          "enum": ["open", "close"]
      },
      "forms": [
        {
          "href": "mqtt://broker.com/",
          "mqtt:topic": "shellies/shellygas-<deviceid>/valve/0/command",
        }
      ]
    }
  },
}

Some discussion points:

• The TD above uses the new terms from my WIP MQTT ontology. You can notice that now I have a term for Topics and for Topic filter. This is because the actual MQTT documentation describes these two terms as different entities. Any input on this decision is welcomed, we'll probably discuss more on the wot-binding-templates repository.
• Gas sensor has a self-test command that should be described with the new "async action" semantics. If you take a look at the documentation they define an endpoint for starting the self-test and another endpoint to listen about the level of competition. Although I can still describe the two endpoints with an Action and a Property, I decided not to because this is a good example of "async actions" in the wild. Morever, I couldn't describe the self test command using the current queryaction operations. Cause for this case we would need something like observeaction given that is not clear if the messages published by the device are retained or not.
• As stated above is not clear if the messages are retained, therefore all the properties are only observable but not readable. I think we have an issue on TD about the fact that is hard to express observe only properties, but I couldn't find it. This might be a practical example that we can use to discuss that.
• Notice that the default mqtt:controlPacket for observeproperty is SUBSCRIBE that's why I didn't express it in every form.
• TD designers might choose to model changeValveStatus with two actions (open and close), I decided to stick closer to the actual documentation.

I'll now try to model also the door sensor and might we can compare it with your solution.

[mmccool]

Discussion:

• Separate broker link, useful for Node-RED? Need to link to discussion
• What about modelling message from the broker, e.g. last will?
• This is a new ontology, but PR is in progress, will publish link here when ready
• URL vs filters: consistent with Architecture assertion? Also applies to modbus. Also different HTTP methods.
• Access to various other devices above: VLAN in progress