Domain Model

[cstoidner]

Proposed changes

Documentation of the thin-edge domain-model.

That PR is a replacement for discontinued PR #1195.

• Scope of discontinued PR child-device requirements #1195 was too vague / wide
• That PR contains all latest domain-model contents from discontinued PR child-device requirements #1195,
  but exclusively focuses on domain-model

Last unresolved domain-model comments from discontinued PR #1195 are listed below as TODOs. All those TODOs shall be considered/resolved in that PR; for each an individual comment shall be opened.

1. Synopsis: "This syntax is used in several places in this document, but sounds really weird."
   Link: child-device requirements #1195 (comment)

2. Synopsis: "simplify this by removing "sensors, actuators or domain applications."
   Link: child-device requirements #1195 (comment)

3. Synopsis: "Why do we use 'external' here? (external child-device)"
   Link: child-device requirements #1195 (comment)

4. Synopsis: "I am a bit irretated by introducing "metric" here."
   Link: child-device requirements #1195 (comment)

5. Synopsis: "This device model is focused on OT devices, while thin-edge will run elsewhere. I find this confusing."
   Link: child-device requirements #1195 (comment)

6. Synopsis: "The source of a metric it not necessarily a device - it can be a process."
   Link: child-device requirements #1195 (comment)

7. Synopsis: "Having "Command" under "telemetry" heading feels a bit strange to me."
   Link: child-device requirements #1195 (comment)

8. Synopsis: "we should explain somewhere in more details our approach (device-twin) here,
   e.g. that commands do a device state change and then update the device twin afterwards]"
   Link: child-device requirements #1195 (comment)

9. Synopsis: "this section (data concept) is not domain-model related."
   Link: child-device requirements #1195 (comment)

10. Synopsis: "better term for plugin"
    Link: child-device requirements #1195 (comment)

11. Synopsis: "It would be good to explain that DM is conceptually based on the doamin model terms above."
    Link: child-device requirements #1195 (comment)

12. Synopsis: "I think we are missing a section for the "Inventory data" which is neither measurement nor metrics."
    Link: child-device requirements #1195 (comment)

13. Synopsis: Improvement for definition of 'device twin'
    Link: child-device requirements #1195 (comment)

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Improvement (general improvements like code refactoring that doesn't explicitly fix a bug or add any new functionality)
• Documentation Update (if none of the other choices apply)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Paste Link to the issue

#1260

Checklist

• I have read the CONTRIBUTING doc
• I have signed the CLA (in all commits with git commit -s)
• I ran cargo fmt as mentioned in CODING_GUIDELINES
• I used cargo clippy as mentioned in CODING_GUIDELINES
• I have added tests that prove my fix is effective or that my feature works
• I have added necessary documentation (if appropriate)

Further comments

[cstoidner]

TODO (5)

Synopsis: "This device model is focused on OT devices, while thin-edge will run elsewhere. I find this confusing."
Link: #1195 (comment)

With the latest structure changes focused on OT devices is gone.

[...] connecting to other devices which may or may not have thin-edge running but need device managment e.g. Sony use case

Also that "gateway case" is covered now.

[cstoidner]

TODO (1)

Synopsis: "This syntax is used in several places in this document, but sounds really weird."
Link: #1195 (comment)

Entire document was changed according to the suggestion (see https://github.com/cstoidner/thin-edge.io/commit/0a9449d1f76ff94e2131937fe4584cff218b3fc4).

[cstoidner]

TODO (2)

Synopsis: "simplify this by removing "sensors, actuators or domain applications."
Link: #1195 (comment)

Suggestion applied, see https://github.com/cstoidner/thin-edge.io/commit/cfe5163bc6a396d6643412ee6dff39050fb67955

[cstoidner]

TODO (3)

Synopsis: "Why do we use 'external' here? (external child-device)"
Link: #1195 (comment)

The term "external child-device" is used, since beside those also processes or containers on the main-device can be handled as "logical child-devices". I added now an according hint, see https://github.com/cstoidner/thin-edge.io/commit/da26172f73e0f8109f3c53e09bc2d406ca550463

[didier-wenzek]

Can you please:

• clean the commit history inherited from child-device requirements #1195
• sign you commit with commit -s
• read and follow the CONTRIBUTING.md guide

[cstoidner]

Can you please:

* clean the commit history inherited from #1195

* sign you commit with `commit -s`

* read and follow the CONTRIBUTING.md guide

Done.

[cstoidner]

TODO (6)

Synopsis: "The source of a metric it not necessarily a device - it can be a process."
Link: #1195 (comment)

[...] collectd is a source of measurement that is not represented as a child device.

I see. I adopted the definition of metric now, see https://github.com/cstoidner/thin-edge.io/commit/e5e47a334d2db1aa939cbd02c2fcb9ddf5d8087f

More details about that shall be later considered in the data model.

[cstoidner]

TODO (7)

Synopsis: "Having "Command" under "telemetry" heading feels a bit strange to me."
Link: #1195 (comment)

New response in old PR:

"I see the term command is really missleading here.
[...]
Instead I prefer to name it setpoint."

See #1195 (comment)

Replaced now command with setpoint, see 719912e

[cstoidner]

TODO(12)

Synopsis: "I think we are missing a section for the "Inventory data" which is neither measurement nor metrics."
Link: #1195 (comment)

I added the inventory, see e9c186a

@reubenmiller , please have a look.

[cstoidner]

TODO (13)

Synopsis: Improvement for definition of 'device twin'
Link: #1195 (comment)

Also insprired by your suggestion I decoupled the concept 'telemtry data' from state now.
See https://github.com/cstoidner/thin-edge.io/commit/e4c57206351183fc906717cae3ba2a3fea0dcb93

[cstoidner]

TODO (4)

Synopsis: "I am a bit irretated by introducing "metric" here."
Link: #1195 (comment)

[...] The more I investigate about metrics and measurements I came now also to the clue, that metric is not the right thing here. [...]
[...] So I am about to remove "metrics" from the model and adapt the definition of measurements. [...]

I removed now the concept "metric", but added "sample" underneath the measurements. See c6bbf0c

[cstoidner]

TODO (11)

Synopsis: "It would be good to explain that DM is conceptually based on the doamin model terms above."
Link: #1195 (comment)

[...] This include software, configuration and log management. The management uses above terms (commands, measurements) to interact with the IoT Cloud.

Software, configuration and log management do not really base on commands or measurements. So I see nothing to add.

I assume your comment is a result of that missleading term of commands. Fortunately that was removed now (see #1554 (comment) above). Sorry for that.

[cstoidner]

TODO (9)

Synopsis: "this section (data concept) is not domain-model related."
Link: #1195 (comment)

Document was restructured and that entire section "thin-edge data concept" was removed now.

[cstoidner]

[cstoidner]

TODO (10)

Synopsis: "better term for plugin"
Link: #1195 (comment)

New suggestion in old PR:

"[...] what do you think about the term add-on, using for components like c8y-config-plugin, or similar 3rd party or customer specific components?
[...]"

See #1195 (comment)

Still to be aligned about a suitable term.

[cstoidner]

TODO (8)

Synopsis: "we should explain somewhere in more details our approach (device-twin) here,
e.g. that commands do a device state change and then update the device twin afterwards]"
Link: #1195 (comment)

[...]
That's why it must be introduced, and even better explained.

Proposal:
thin-edge has been designed with the assumption [...]

Suggested explanation for "device twin" is adopted now.

[...] we should explain somewhere in more details our approach [...]

More details can be added into a specific document.

[reubenmiller]

LGTM.

[didier-wenzek]

I'm okay to have this merged - as long as the commits are squashed.

However, I find this text really too dry with a long list of definitions with little context and definitions. Hope this will be improved in the future.

[didier-wenzek]

Nothing of that section has been currently implemented.

[cstoidner]

Thats true. Same for the new telemetry item setpoint and telemetry details units and samples; and finally new device management functionality firmware management.

For all those development work need to be planned.