Document how to define measurement units

Signed-off-by: Didier Wenzek <[email protected]>

Author: didier-wenzek

docs/src/references/mappers/c8y-mapper.md

@@ -378,6 +378,82 @@ c8y/measurement/measurements/create
 
 </div>
 
+### Measurement units
+
+The Cumulocity mapper uses the measurement meta topics to attach units to measurement values.
+
+The metadata for a measurement topic:
+
+```mermaid
+graph LR
+  te --/--- entity_id["&lt;entity id&gt;"] --/--- m --/--- measurement_type["&lt;measurement type&gt;"]
+```
+
+are to be published to the associated meta topic:
+
+```mermaid
+graph LR
+  te --/--- entity_id["&lt;entity id&gt;"] --/--- m --/--- measurement_type["&lt;measurement type&gt;"]  --/--- meta
+```
+
+The idea is to describe in a single metadata message all the units of the measurements published under the measurement topic.
+This message uses the same shape as the measurements and is published as retained on the meta topic of the measurement topic.
+
+```shell
+tedge mqtt pub -r 'te/device/main///m//meta' '{
+    "Climate":{
+        "Temperature": {"unit": "°C"},
+        "Humidity": {"unit": "%RH"}
+    },
+    "Acceleration":{
+        "X-Axis": {"unit": "m/s²"},
+        "Y-Axis": {"unit": "m/s²"},
+        "Z-Axis": {"unit": "m/s²"}
+    }
+}'
+```
+
+The measurements published to the topic for measurements of the same type:
+
+```shell
+tedge mqtt pub 'te/device/main///m/' '{
+    "Climate":{
+        "Temperature":23.4,
+        "Humidity":95.0
+    },
+    "Acceleration":{
+        "X-Axis":0.002,
+        "Y-Axis":0.015,
+        "Z-Axis":5.0
+    }
+}'
+```
+
+are then forwarded to C8Y with their units.
+
+```json
+{
+  "type": "ThinEdgeMeasurement",
+  "Climate": {
+    "Temperature": {"value":23.4,"unit":"°C"},
+    "Humidity":{"value":95,"unit":"%RH"}
+  },
+  "Acceleration": {
+    "X-Axis": {"value":0.002,"unit":"m/s²"},
+    "Y-Axis": {"value":0.015,"unit":"m/s²"},
+    "Z-Axis": {"value":5,"unit":"m/s²"}
+  },
+  "time":"2025-09-03T10:05:47.226Z"
+}
+```
+
+- A message received on `te/device/main///m/<type>` uses the units defined on `te/device/main///m/<type>/meta`, if any.
+- If the unit for a measurement is unknown, the measurement value is simply sent with no unit.
+- Other metadata such as the precision or the min and max values can be attached to a measurement.
+  However, these are ignored by the Cumulocity mapper.
+- `"Temperature"`, `"Climate": { "Temperature" }` and `"Engine": { "Temperature" }` can be given different units.
+- Units and all measurement metadata can be cleared by publishing an empty retained message on `te/device/main///m/<type>/meta`.
+
 ### Events
 
 <div class="code-indent-left">

docs/src/references/mqtt-api.md

@@ -506,15 +506,41 @@ can be updated by publishing the following message:
 
 ```sh te2mqtt formats=v1
 tedge mqtt pub -r te/device/main///m/battery_reading/meta '{
-  "units": {
-    "temperature": "°C",
-    "voltage": "V",
-    "current": "A"
-  }
+  "temperature": { "unit": "°C", "precision": "±0.1°C" },
+  "voltage": { "unit": "V", "min": 0, "max": 20 },
+  "current": { "unit": "A" }
 }'
 ```
 
-The metadata fields supported by each data type will be defined in detail later.
+These free-form metadata fields are used to interpret the values published on the associated topic.
+
+Continuing the example with the following measurement:
+
+```sh te2mqtt formats=v1
+tedge mqtt pub te/device/main///m/battery_reading '{
+  "temperature": 25,
+  "voltage": 20,
+  "current": 5,
+  "ttl": 1
+}'
+```
+
+The metadata for *battery_reading* are used by the Cumulocity mapper, to attach units to these values:
+
+```json
+{
+  "temperature": {"temperature":{"value":25.0,"unit":"°C"}},
+  "voltage":{"voltage":{"value":20.0,"unit":"V"}},
+  "current":{"current":{"value":5.0,"unit":"A"}},
+  "ttl":{"ttl":{"value":1.0}},
+  "time":"2025-09-05T13:47:23.818993647Z",
+  "type":"battery_reading"
+}
+```
+
+Note that:
+- Metadata can be missing. The Cumulocity mapper doesn't mandate units and publishes the *ttl* value even if no units is known.
+- Extra metadata can be added. The Cumulocity mapper only uses the units and ignores all other metadata fields.
 
 ## Twin metadata