docs: publish the mqtt service docs and extend details on the different options by reubenmiller · Pull Request #4144 · thin-edge/thin-edge.io

reubenmiller · 2026-04-23T18:47:36Z

Proposed changes

Publish the previously unlisted Cumulocity MQTT Service page, and include the two different options (e.g. dual bridge connections, or using a single connection).

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

Checklist

I have read the CONTRIBUTING doc
I have signed the CLA (in all commits with git commit -s. You can activate automatic signing by running just prepare-dev once)
I ran just format as mentioned in CODING_GUIDELINES
I used just check 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

…nt options Signed-off-by: reubenmiller <reuben.d.miller@gmail.com>

codecov · 2026-04-23T18:56:40Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

albinsuresh · 2026-04-24T06:03:37Z

+and a second bridge is set up specifically to connect to the MQTT service endpoint.
+This uses the community package [`tedge-mapper-c8y-mqttservice`](https://github.com/thin-edge/tedge-mapper-c8y-mqttservice).
+
+1. Make sure the device is already connected to Cumulocity. If not, follow the [connection guide](./connect.md).


The connection itself isn't really necessary, right? Only the c8y.url config needs to be set, no?

That is more to prove that the device is already connected and functioning correctly with the given certificates.

albinsuresh · 2026-04-24T06:27:36Z

+   ```sh
+   sudo systemctl start tedge-mapper-c8y-mqttservice
+   ```
+


Should we add a WARN/CAUTION here, advising the user to never publish a SmartREST message over this connection, as it can put the bridge connection in a permanent infinite loop.

Would it though?

Which bridge will be stuck in a loop? Why?

The MQTT service bridge would be stuck in the infinite loop as follows(for the logs of the tedge-mapper-c8y-mqttservice service):

Apr 24 11:28:07 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:28:07.583248332Z INFO MQTT: Connection established Apr 24 11:28:08 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:28:08.343202171Z INFO MQTT bridge: [cloud] Received CONNACK (Connection Acknowledged): ConnAck { session_present: false, code: Success } Apr 24 11:28:08 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:28:08.343285773Z INFO MQTT bridge: [cloud] MQTT bridge connected to cloud broker Apr 24 11:28:08 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:28:08.34330484Z INFO MQTT bridge: [cloud] Bridge connection subscribing to [] <----- I published the message to s/us topic here Apr 24 11:29:54 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:29:54.682898358Z WARN MQTT bridge: [cloud] Connection error: MqttState(ConnectionAborted) Apr 24 11:29:54 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:29:54.683103276Z ERROR MQTT bridge: [cloud] MQTT bridge failed to connect to cloud broker: Mqtt state: Connection closed by peer abruptly Apr 24 11:29:54 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:29:54.6831947Z INFO MQTT bridge: [cloud] Waiting 3.424393831s until attempting reconnection to broker Apr 24 11:29:58 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:29:58.109170648Z INFO MQTT bridge: [cloud] Attempting to connect to broker Apr 24 11:29:58 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:29:58.735043371Z INFO MQTT bridge: [cloud] Received CONNACK (Connection Acknowledged): ConnAck { session_present: false, code: Success } Apr 24 11:29:58 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:29:58.735076616Z INFO MQTT bridge: [cloud] MQTT bridge connected to cloud broker Apr 24 11:29:58 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:29:58.735103855Z INFO MQTT bridge: [cloud] Bridge connection subscribing to [] Apr 24 11:29:58 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:29:58.73620737Z WARN MQTT bridge: [cloud] Ignoring already known pkid=1 Apr 24 11:29:58 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:29:58.936942781Z WARN MQTT bridge: [cloud] Connection error: MqttState(ConnectionAborted) Apr 24 11:29:58 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:29:58.937146792Z ERROR MQTT bridge: [cloud] MQTT bridge failed to connect to cloud broker: Mqtt state: Connection closed by peer abruptly Apr 24 11:29:58 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:29:58.937198685Z INFO MQTT bridge: [cloud] Waiting 5.243963079s until attempting reconnection to broker Apr 24 11:30:04 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:30:04.183089951Z INFO MQTT bridge: [cloud] Attempting to connect to broker Apr 24 11:30:04 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:30:04.696777396Z INFO MQTT bridge: [cloud] Received CONNACK (Connection Acknowledged): ConnAck { session_present: false, code: Success } Apr 24 11:30:04 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:30:04.696885513Z INFO MQTT bridge: [cloud] MQTT bridge connected to cloud broker Apr 24 11:30:04 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:30:04.696929374Z INFO MQTT bridge: [cloud] Bridge connection subscribing to [] Apr 24 11:30:04 57e6f37c9cf3 tedge-mapper[939]: 2026-04-24T11:30:04.698330978Z WARN MQTT bridge: [cloud] Ignoring already known pkid=1

@albinsuresh Can you just confirm what message you actually published.

Ah by "infinite loop" you're talking about that the mqtt client is being disconnected because it publishing to a forbidden topic...not that we have a message loop.

Added a warning 2f041a7

Though we should probably add a feature in the MQTT Service mapper which will reject/discard those messages if a specific setting is enabled, so that we can prevent user-pain here.

albinsuresh · 2026-04-24T06:32:19Z

+Use [go-c8y-cli](https://github.com/reubenmiller/go-c8y-cli) to enable the required tenant feature, or you can use the Cumulocity Administration application:
+
+```sh
+c8y features enable --key mqtt-service.smartrest


It'd be good to provide the alternative curl command using the REST API for the same as well, for those not using go-c8y-cli.

Curl becomes even more confusing for users as you need to talk about authorization etc. I'd stick to go-c8y-cli, or people can use the features UI

go-c8y-cli is with no doubts the perfect companion to thin-edge in a Cumulocity context. It make sense to encourage our users to use it.

albinsuresh · 2026-04-24T06:41:28Z

+
+1. Make sure the device is already connected to Cumulocity. If not, follow the [connection guide](./connect.md).
+
+1. Install the `tedge-mapper-c8y-mqttservice` community package


How about adding one step prior to this one, with the instruction to setup the community repo as well? Even though the Set Me Up button is there at the top of the community repo, I'm not quite sure if people would always notice it. Also wondering if we should add these installation instructions to the README of the community plugin as well.

the docs could benefit from that, but I'd leave that off the README in the repo, as if you click on the link to the package, it will redirect you so the cloudsmith page showing the package and the "setup me up" button.

Resolved in b669a4b

albinsuresh · 2026-04-24T06:46:58Z

+To display the full set of topic mapping rules for the Cumulocity bridge, run:
+
+```sh
+tedge bridge inspect c8y


That command would be different based on how we connected, right? It could be tedge bridge inspect c8y-mqttservice as well, if Option 1 was followed.

Opps, that should read tedge bridge inspect c8y-mqttservice

Actually it needs both depending on which option the user used...

There are now tabs which present the commands based on each option. Resolved in b669a4b

albinsuresh · 2026-04-24T06:49:39Z

+   Once installed, the package reads the existing %%te%% Cumulocity configuration (e.g. `c8y.url` and device
+   certificate) and automatically configures the second bridge to connect to the same tenant.


For those users that have not already connected to the core MQTT endpoint, or not even planning to, would it make sense to capture setting the url in the mapper.toml as a standalone step?

That is highlighted in the next step

But maybe a word saying "if it already configured" somewhere in the sentence would help clarify it

Resolved in b669a4b

didier-wenzek · 2026-04-24T07:47:00Z

+endpoint, which restricts devices to a predefined set of topics and data formats (e.g. SmartREST and JSON over MQTT).
 The [Cumulocity MQTT service](https://cumulocity.com/docs/device-integration/mqtt-service) on the other hand,
 is the next-gen MQTT endpoint offered by Cumulocity,
 which allows devices to publish and receive data using user-defined custom topic and payload formats as well.


I would add a note here telling that the MQTT service will soon provide the two aspects (legacy API + extensible endpoints). This would make clearer the table below - with 3 variants.

Added a sentence about it the future of having 1 endpoint capable of both free-form and SmartREST based topics. b669a4b

didier-wenzek · 2026-04-24T07:51:08Z

-|----|----|-----------|------|
-|Core MQTT|8883|Allows devices to send messages directly into Cumulocity, provided that the device implements the pre-defined topic schema and payload formats of Core MQTT|[General Availability](https://cumulocity.com/docs/2024/glossary/g/#ga)|
-|MQTT Service|9883|Allows devices to send and receive arbitrary payloads on any MQTT topic|[Public Preview](https://cumulocity.com/docs/2024/glossary/p/#public-preview) (subject to change)|
+For more information about the two MQTT interfaces offered by Cumulocity, see the following table.


The with or without SmartREST support should not come as a surprise reading the table.
So beyond the number of options, we need to say first a word about SmartREST support.

Suggested change

For more information about the two MQTT interfaces offered by Cumulocity, see the following table.

For more information about the three MQTT interfaces offered by Cumulocity, see the following table.

Added a sentence about it, and I just avoided being explicit how many options are available. b669a4b

didier-wenzek · 2026-04-24T08:00:53Z

+   ```

-1. Provide the topics to subscribe to (e.g: topic to receive sensor config updates)
+   You can set multiple topics by using comma separated values.


Another way is to use tedge config add

$sudo tedge config add c8y.mqtt_service.topics hello/c8y

In addition, the difference of the examples above and below tedge config set c8y.mqtt_service.topics is the only using " or not. Both are using comma-separated values. I agree to replace one example with tedge config add.

Added an additional example of using add in b669a4b

And I accidentally introduced a duplicate section...but I've removed the csv info and replaced it with the add command, a1439fe

…different options Signed-off-by: reubenmiller <reuben.d.miller@gmail.com>

…on the different options Signed-off-by: reubenmiller <reuben.d.miller@gmail.com>

…etails on the different options Signed-off-by: reubenmiller <reuben.d.miller@gmail.com>

docs: publish the mqtt service docs and extend details on the differe…

067759a

…nt options Signed-off-by: reubenmiller <reuben.d.miller@gmail.com>

reubenmiller requested a review from didier-wenzek as a code owner April 23, 2026 18:47

reubenmiller requested a deployment to Test Pull Request April 23, 2026 18:47 — with GitHub Actions Waiting

reubenmiller added documentation Improvements or additions to documentation theme:c8y Theme: Cumulocity related topics labels Apr 23, 2026

albinsuresh reviewed Apr 24, 2026

View reviewed changes

didier-wenzek reviewed Apr 24, 2026

View reviewed changes

fixup! docs: publish the mqtt service docs and extend details on the …

b669a4b

…different options Signed-off-by: reubenmiller <reuben.d.miller@gmail.com>

reubenmiller requested a deployment to Test Pull Request April 24, 2026 14:22 — with GitHub Actions Waiting

fixup! fixup! docs: publish the mqtt service docs and extend details …

a1439fe

…on the different options Signed-off-by: reubenmiller <reuben.d.miller@gmail.com>

reubenmiller requested a deployment to Test Pull Request April 24, 2026 14:27 — with GitHub Actions Waiting

fixup! fixup! fixup! docs: publish the mqtt service docs and extend d…

2f041a7

…etails on the different options Signed-off-by: reubenmiller <reuben.d.miller@gmail.com>

reubenmiller requested a deployment to Test Pull Request April 24, 2026 14:35 — with GitHub Actions Waiting


		1. Make sure the device is already connected to Cumulocity. If not, follow the [connection guide](./connect.md).

		1. Install the `tedge-mapper-c8y-mqttservice` community package

		Once installed, the package reads the existing %%te%% Cumulocity configuration (e.g. `c8y.url` and device
		certificate) and automatically configures the second bridge to connect to the same tenant.

	For more information about the two MQTT interfaces offered by Cumulocity, see the following table.
	For more information about the three MQTT interfaces offered by Cumulocity, see the following table.

Conversation

reubenmiller commented Apr 23, 2026

Proposed changes

Types of changes

Paste Link to the issue

Checklist

Further comments

Uh oh!

codecov Bot commented Apr 23, 2026

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

reubenmiller Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

reubenmiller Apr 24, 2026 •

edited

Loading