Merge pull request #2121 from reubenmiller/docs-new-mqtt-spec-proposa…

…l-v1-format

docs(mqtt): use explicit v1 format to prevent conversion to legacy mqtt api

docs/src/contribute/design/mqtt-topic-design.md

@@ -20,13 +20,13 @@ Having a fixed **identifier** group in the topic structure makes it easier for o
 
 A client can subscribe to all measurements for the main device by subscribing to a single topic.
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt sub 'te/device/main///m/+'
 ```
 
 Alternatively, if a client wants to subscribe to all measurements regardless of the **identifier** then it can also can be done using a single subscription, as demonstrated by the following example:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt sub 'te/+/+/+/+/m/+'
 ```
 
@@ -123,7 +123,7 @@ graph LR
 
 The equipment, which is a conveyor belt called "belt01", is located in factory "factory01", in the "hallA" building, in the "packaging" area. The conveyor belt can be registered as a child-device by publishing the following message.
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/factory01/hallA/packaging/belt001' '{
   "@type": "child-device",
   "displayName": "belt001",
@@ -143,15 +143,15 @@ The registration message will associate the telemetry data or commands published
 
 For example, an event can be published to the `belt01` equipment using the following message.
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub 'te/factory01/hallA/packaging/belt001/e/running_status' '{
   "text": "Belt started"
 }'
 ```
 
 Since the topic schema encodes additional location information about the equipment, other MQTT clients can subscribe to telemetry data coming from all equipment located in the same area using a single MQTT subscription.
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub 'te/factory01/hallA/packaging/+/e/+'
 ```
 
@@ -160,15 +160,15 @@ When applying your own semantics to the **identifier**, you can leave any segmen
 
 For example, if it does not make sense to have the factory and building in the **identifier**, then they can be removed and the equipment can be registered using:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/packaging/belt001' '{
   "@type": "child-device"
 }'
 ```
 
 Publishing an event requires just leaving the last two segments of the **identifier** blank (whilst keeping the slashes `/` in place).
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub 'te/packaging/belt001///e/running_status' '{
   "text": "Belt started"
 }'

docs/src/references/mqtt-api.md

@@ -272,7 +272,7 @@ Here are a few examples of how various entities can be registered.
 
 #### Register a device
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/main' '{
   "@type": "device",
   "type": "Gateway"
@@ -281,7 +281,7 @@ tedge mqtt pub -r 'te/device/main' '{
 
 Or the device can be registered using an explicit id:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/main' '{
   "@type": "device",
   "@id": "tedge001",
@@ -291,7 +291,7 @@ tedge mqtt pub -r 'te/device/main' '{
 
 #### Register a service of the main device
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/main/service/nodered' '{
   "@type": "service",
   "displayName": "nodered",
@@ -304,7 +304,7 @@ The service is implicitly linked to the parent derived from the topic, `main` in
 But the parent can be explicitly provided as well with the `@parent` key,
 if the parent can not be derived from the topic directly:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/component_namespace/service/nodered/instance-1' '{
   "@type": "service",
   "@parent": "te/device/main",
@@ -315,7 +315,7 @@ tedge mqtt pub -r 'te/component_namespace/service/nodered/instance-1' '{
 
 #### Register a child device
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/child01' '{
   "@type": "child-device",
   "displayName": "child01",
@@ -329,7 +329,7 @@ If the `@parent` info is not provided, it is assumed to be an immediate child of
 
 Nested child devices are registered in a similar fashion as an immediate child device, however the registration message requires the additional `@parent` property to be set, indicating which parent the child device should be related to.
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/nested_child01' '{
   "@type": "child-device",
   "@parent": "te/device/child01",
@@ -343,7 +343,7 @@ Service registration for child devices also follow the same rules as the main de
 where the `@parent` device info is derived from the topic itself, by default.
 But, it is advised to declare it explicitly as follows:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/child01/service/nodered' '{
   "@type": "service",
   "@parent": "te/device/child01",
@@ -360,7 +360,7 @@ For example, a linux service runs on a device as it relies on physical hardware
 
 #### Register a service of a nested child device
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/nested_child01/service/nodered' '{
   "@type": "service",
   "@parent": "te/device/nested_child01",
@@ -440,57 +440,57 @@ so that it can process them.
 
 #### Publish to the main device
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/main///m/environment' '{
   "temperature": 23.4
 }'
 ```
 
 If the there is no measurement type, then the type can be left empty, but it must have the trailing slash `/` (so that the number of topic segments is the same).
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/main///m/' '{
   "temperature": 23.4
 }'
 ```
 
 #### Publish to a child device
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/child01///m/environment' '{
   "temperature": 23.4
 }'
 ```
 
 #### Publish to a service on the main device
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/main/service/nodered/m/environment' '{
   "temperature": 23.4
 }'
 ```
 
 Any MQTT client can subscribe to all measurements for all entities (devices and services) using the following MQTT topic:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt sub 'te/+/+/+/+/m/+'
 ```
 
 If you want to be more specific and only subscribe to the main device, then you can used fixed topic names rather than wildcards:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt sub 'te/device/main/+/+/m/+'
 ```
 
 Or to subscribe to a specific type of measurement published to an services on the main device, then use:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt sub 'te/device/main/service/+/m/memory'
 ```
 
 #### Publish to a service on a child device
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/child01/service/nodered/m/environment' '{
   "temperature": 23.4
 }'
@@ -503,7 +503,7 @@ which can be added/updated by publishing to `/meta` subtopics of those data type
 For example, the units associated with measurements in the `battery_reading` measurement type
 can be updated by publishing the following message:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r te/device/main///m/battery_reading/meta '{
   "units": {
     "temperature": "°C",
@@ -571,7 +571,7 @@ For example, the `restart` could mean either a device restart or a service resta
 
 Command to fetch the software list from the main device:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/main///cmd/software_list/123' '{
   "status": "init"
 }'
@@ -582,15 +582,15 @@ such as `validating`, `downloading`, `executing` etc.
 
 The `status` field can even be skipped, which implies `init` status as follows:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/main///cmd/software_list/123' '{}'
 ```
 
 #### Command to child device
 
 Command to update the firmware of a child device:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/child01///cmd/firmware_update/123' '{
   "status": "init",
   "attempt": 1,
@@ -605,7 +605,7 @@ tedge mqtt pub -r 'te/device/child01///cmd/firmware_update/123' '{
 
 Command to update the configuration of a service:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r 'te/device/main/service/collectd/cmd/config_update/123' '{
   "status": "init",
   "type": "collectd",
@@ -620,7 +620,7 @@ For commands as well, additional command specific metadata can be registered as
 
 For example, the supported configuration list of the main device can be declared as follows:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r te/device/main///cmd/config_snapshot '{
   "description": "Upload a configuration from the device",
   "supportedTypes": ["mosquitto", "tedge", "collectd"]
@@ -631,7 +631,7 @@ tedge mqtt pub -r te/device/main///cmd/config_snapshot '{
 
 Services can publish their health status as follows:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r te/device/main/service/tedge-agent/status/health '{
   "pid": 1234,
   "status": "up",
@@ -641,21 +641,21 @@ tedge mqtt pub -r te/device/main/service/tedge-agent/status/health '{
 
 Services are responsible for updating their own health status by publishing to the above topic on any status changes. However, other clients can request the service to update its status by sending a health check command as shown below:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r te/device/main/service/tedge-agent/cmd/health/check '{}'
 ```
 
 Services are also expected to react to device-wide health check commands as well (where service and `<service_id>` segments are left blank):
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r te/device/main///cmd/health/check '{}'
 ```
 
 On receipt of the above command, all services on that device should respond with their health status.
 
 The services are also expected to register an MQTT Last Will and Testament (LWT) message with the broker to publish a `down` status message in the event that the service stops or crashes unexpectedly. The Last Will and Testament message ensures that the down status is published even if the service is not operational. The following example details such a message:
 
-```sh te2mqtt
+```sh te2mqtt formats="v1"
 tedge mqtt pub -r te/device/main/service/tedge-agent/status/health '{
   "status": "down"
 }'