search

thin-edge / thin-edge.io

The open edge framework for lightweight IoT devices
https://thin-edge.io
Apache License 2.0
219 stars 54 forks source link

Missing mapper input topic filters #1749

Closed Bravo555 closed 6 months ago

Bravo555 commented 1 year ago

Is your documentation request related to a problem? Please describe.

I think most of the topics used by the tedge-mapper are missing from the relevant section in the documentation:

  • Incoming topics

    • tedge/measurements
    • tedge/measurements/ (for Cumulocity)

  • Outgoing topics

    • tedge/errors (for errors)
    • c8y/measurement/measurements/create (for Cumulocity)
    • az/messages/events/ (for Azure IoT Hub)

E.g. Cumulocity mapper defines more topics:

https://github.com/thin-edge/thin-edge.io/blob/6fcb0f69e6c373d0295935e9901d15cdca2872d7/crates/core/tedge_mapper/src/c8y/mapper.rs#L140-L163

https://github.com/thin-edge/thin-edge.io/blob/6fcb0f69e6c373d0295935e9901d15cdca2872d7/crates/core/tedge_mapper/src/c8y/mapper.rs#L44-L55

Describe the improvement you'd like

If in this section we want to have a complete list of all the topics used by all the mappers, then we should add these missing topics. If we want to have a list of common topics used by all the mappers (e.g. tedge/measurements), then we should create dedicated documents for other mappers, put topics relevant to these mappers there, and link to these documents in this section.

Additional context

This section of the document is more than 1 year old, and was probably not kept in sync with the code. Documentation about topics used by the mappers, seems to be both worthwhile, and technically feasible, to test. We could create documentation tests which run a MQTT broker and a mapper, and then register to which topics the mapper subscribed. We could then check if these topics are properly mentioned in the documentation. The tricky part is that mappers look like they can have some state, or some configuration determining to which topics they subscribe? Not sure, but this can be tricky to handle. Also while it's relatively easy to check which topics mappers subscribe (they should subscribe to common tedge/ topics after all), it may be trickier to test whether they publish on the correct topics?

reubenmiller commented 6 months ago

The section in question has been removed from the docs as it did not provide any user value.