Documentation on mapping child device MEA to an explicit ID without prefixing main device ID

[d-timotijevic]

Is your documentation request related to a problem? Please describe. I've encountered a challenge with the current method of mapping child device measurements to an external ID in thin edge mapper, as illustrated in the provided example. The problem arises when the system prefixes the <main-device-id>:device to the child ID in the thin edge mapping of the payload. This convention can be restrictive and doesn't seem to allow for mapping measurements to an explicit, predefined ID without this prefixing behavior. I'm not sure if an alternative mapping strategy is possible within the current framework, which leads to my documentation request.

Describe the improvement you'd like I'm seeking an improvement in the documentation that addresses whether it's possible to map a child device measurement to an explicit ID, bypassing the default behavior of prefixing <main-device-id>:device to the child ID in the payload mapping. If such a capability exists or can be implemented, a detailed example illustrating how to achieve this would be nice. This example should demonstrate how to map a child device measurement to an explicit child device ID directly, without automatically including the main device ID as a prefix.

Additional context Screenshot from the documentation here

[didier-wenzek]

This is indeed a documentation issue.

There is a hint to solve your issue here:

• the child device must be explicitly registered using a registration message
• and this message must provide an explicit "@id"
• as explained in this comment

=> The documentation is not clear and will be improved.

[reubenmiller]

@d-timotijevic @didier-wenzek, on the same page referenced in the ticket, there is a section about registering a child device with an explicit id, and the last sentence says that the @id value will be used in the external id.

https://thin-edge.github.io/thin-edge.io/references/mappers/c8y-mapper/#child-device-with-explicit-id

[reubenmiller]

If you're using Cumulocity IoT, then you will have to be careful that child id's don't conflict, as the child device managed object MUST be owned by the agent, otherwise you won't be able to publish data to the child device managed object in Cumulocity IoT.

[d-timotijevic]

This is indeed a documentation issue.

There is a hint to solve your issue here:

• the child device must be explicitly registered using a registration message
• and this message must provide an explicit "@id"
• as explained in this comment

=> The documentation is not clear and will be improved.

Thanks you for the reply, a couple of questions:

• Do I understand it correctly that what is specified in the @id field is to be used as the external ID of type c8y_Serial in C8Y?
• What is the difference between child01 in the topic name and @id in the payload when registering an entity?
• Can @id be used in the payload of measurements sent to te/device/child01///m/ to direct it to a specific external ID? If not, how does thin-edge determine whether there should be a main device prefix before the child01?

[d-timotijevic]

@d-timotijevic @didier-wenzek, on the same page referenced in the ticket, there is a section about registering a child device with an explicit id, and the last sentence says that the @id value will be used in the external id.

https://thin-edge.github.io/thin-edge.io/references/mappers/c8y-mapper/#child-device-with-explicit-id

Yes, noticed that one. A little unclear which of the child01 references are to be used as a external ID, the one in the topic name or the one specified in @id field of the payload. Another thing is that the documented topic name and mapping seems to be incorrect when looking into it, the following example

tedge mqtt pub -r 'te/device/child0001//' '{
  "@type": "child-device",
  "@id": "child0001",
  "name": "child0001",
  "type": "SmartHomeHub"
}'

yields this mapping:

c8y/s/us 101,child0001,child0001,SmartHomeHub

[reubenmiller]

child0001

Ah yes you're right, we're missing the device name in the mapping output (as per the Cumulocity IoT Docs)

[reubenmiller]

This is indeed a documentation issue. There is a hint to solve your issue here:

• the child device must be explicitly registered using a registration message
• and this message must provide an explicit "@id"
• as explained in this comment

=> The documentation is not clear and will be improved.

Thanks you for the reply, a couple of questions:

• Do I understand it correctly that what is specified in the @id field is to be used as the external ID of type c8y_Serial in C8Y?

Yes the @id field is the external identity with the type c8y_Serial in Cumulocity IoT.

• What is the difference between child01 in the topic name and @id in the payload when registering an entity?

The topic name is a local address for the data to be published. Since the local MQTT broker does not have to be unique across multiple thin-edge.io instances, it allows users to decouple the topic name from the cloud identity. The registration message is used to establish the relationship between the topic name and the external id. The default naming convention is described here, and for most cases it is ok, however you can use your own topic structure by controlling the @id values in the registration messages. You can set the <device_id> in the topic name to match the @id value provided in the registration message if you would prefer, but again you must ensure that you won't have any naming conflicts between thin-edge.io instances.

• Can @id be used in the payload of measurements sent to te/device/child01///m/ to direct it to a specific external ID? If not, how does thin-edge determine whether there should be a main device prefix before the child01?

No, the @id can only be specified in the registration messages, as you are also declaring to all the listeners on the MQTT broker, the meta information about your device. The mappers will then use the entity registration messages when performing the mapping.

[didier-wenzek]

• Do I understand it correctly that what is specified in the @id field is to be used as the external ID of type c8y_Serial in C8Y?

Yes, this is correct

• What is the difference between child01 in the topic name and @id in the payload when registering an entity?

The @id is identifier of the device in the cloud and should be unique for the a tenant. device/child01// in the identifier of the child device on a main thin-edge device. Note that the identifier is device/child01// and not child01.

Can @id be used in the payload of measurements sent to te/device/child01///m/ to direct it to a specific external ID? If not, how does thin-edge determine whether there should be a mainhttps://thin-edge.github.io/thin-edge.io/references/mappers/c8y-mapper/#child-device-with-explicit-id device prefix before the child01?

No @id cannot be used with measurements. The relationship between device/child01// and external id which is not the default must be established using a registration message.

[reubenmiller]

The docs have been updated, and can be viewed from the "next" version. https://thin-edge.github.io/thin-edge.io/next/references/mappers/c8y-mapper/#child-device-with-explicit-id