Extending the initial/reusable connection examples

[egekorkan]

We should extend the document at https://github.com/w3c/wot/blob/main/planning/ThingDescription/td-next-work-items/usability-and-design.md#examples-of-message-flow

• Simplest one Thing one Consumer: @egekorkan
• Broker-based: @egekorkan
• WS and OAuth2 Credentials: @relu91
• Proxy: @lu-zero

[egekorkan]

Here are my diagrams for the first two:

• A simple HTTP request-response with no reuse of initial connection

sequenceDiagram
    participant Thing
    participant Consumer
    activate Consumer
    Consumer->>Thing: readproperty Temperature (e.g. HTTP GET request)
    activate Thing
    Thing->>Thing: get sensor reading
    Thing->>Consumer: send Temperature property value (e.g. HTTP response)
    deactivate Thing
    activate Consumer
    Consumer->>Consumer: use property value
    deactivate Consumer
    deactivate Consumer
    

Loading

• Observing a property with MQTT where the initial broker connection is reused. Here, the first connect messages are the initial connection that is reused

sequenceDiagram
    participant Thing
    participant Broker
    participant Consumer
    activate Broker
    Thing->>Broker: Connect to broker
    activate Thing
    Consumer->>Broker: Connect to broker
    activate Consumer
    Thing->>Thing: get sensor reading
    activate Thing
    Thing->>Broker: publish updated temperature value to mytemp topic
    Broker->>Thing: puback
    deactivate Thing
    Consumer->>Broker: subscribe to mytemp topic (observeproperty)
    Thing->>Thing: get sensor reading
    activate Thing
    Thing->>Broker: publish updated temperature value to mytemp topic
    Broker->>Thing: puback
    deactivate Thing
    Broker->>Consumer: send Temperature property value
    activate Consumer
    Consumer->>Consumer: use property value
    deactivate Consumer
    activate Thing
    Thing->>Broker: publish updated temperature value to mytemp topic
    Broker->>Thing: puback
    deactivate Thing
    Broker->>Consumer: send Temperature property value
    activate Consumer
    Consumer->>Consumer: use property value
    deactivate Consumer
    deactivate Consumer
    deactivate Thing
    deactivate Broker

Loading

Let me know if this style is fine for all. Then I can make a PR where we discuss further.

[lu-zero]

This is the initial draft regarding a Proxy, mermaid sadly does not have a good way to color the different interactions so I ended up rewriting in drawio.

[egekorkan]

Notes from the call:

• Having the same WoT operations in all protocols would be better for comparison
• Mermaid has limitations, which are highlighted in the comment above:
  - Cannot show an active connection (mqtt broker connection is active in subsequent messages)
  • Cannot add style, e.g. color, to the diagram.
• @egekorkan and @relu91 will use the drawio to sketch the connections

[egekorkan]

I have updated my comment above to use activation feature of mermaid. In the end, leaving colours aside, mermaid is pretty good. However, I could not arrange things like I wanted. Thinking that these kind of diagrams can go into the spec to explain the feature, it is better to have more flexibility and higher quality figures. So going with Draw.io is better, even though the initial work will be slightly higher.

[egekorkan]

Below are the draw.io version of my diagrams above. After agreement, I will put it into the work items readme.

---

[egekorkan]

• @mahdanoura : The connection in HTTP is also reused (the port is kept open)

• @ashimura : What data is used needs to be explained

• @relu91 : Interaction pattern is different between the two cases. In HTTP case, you can/should close the connection once you are done reading the value. Keeping the connection is an optimization. In MQTT, the runtime knows not to close the connection, it is not an optimization.

• We can put a time component (e.g. 5 mins) where the connection is closed between two HTTP requests but is not closed between two MQTT messages. Some code snippets can highlight this further.

• We should explain that the Thing has its own HTTP server but in the MQTT case, they are separate entities.

• A lifecycle diagram of the connection would be useful. In MQTT, the broker connection is closed if the device is not online anymore.

• In some cases, it would be useful to indicate how long the connection can be kept.

[TallTed]

Note that accessibility strongly advises that color not be the only differentiator in diagrams like these, due to color blindness and other visual limitations that readers may have. Variably dashed lines, shape differences, patterned fills, etc., are strongly preferred.

Color contrasts are also important. The usual problem is with colored text overlaid on color blocks; here, it's with color blocks over color blocks. I expect the "dark" lines will be fine when compared to the "light" fills, but in these diagrams, it's currently equally (if not more) important that the various light fills appear differently enough from each other that they can be discerned.

[relu91]

Here it is the OAuth version:

I tried to depict an usual flow based on OAuth. Out there, there are many flavors, different flows, and OpenID among them but I've tried to factorize the most common interactions between the parties.

@TallTed I'm currently using the same visual language just because it will be easier to refactor all the diagrams when we settle the discussion, I hope they are still understandable. I'm sorry it causes any trouble.

[relu91]

Websocket:

[egekorkan]

Talking with @mjkoster , Node RED has taken some decisions to enable this. For example, all MQTT connections are handled by hidden node(s) that the other nodes refer to. @egekorkan will do a short demo in the TD call this week.

[egekorkan]

Discussion in the Call of 24 July:

• We can pick a color palette recommended by W3C that ensures color contrast. This can be applied to all diagrams in the specification.
• We will not change the line style since they have a meaning in sequence charts.
• The linked PR will be updated by @egekorkan , @relu91 and @lu-zero