> For the complete documentation index, see [llms.txt](https://docs.yudash.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yudash.com/pf/ct/payload/json.md). # JSON Generator The **YuDash JSON Template Engine** creates custom JSON payloads for MQTT, HTTP and other server/API integrations. Unlike predefined payload formats, the JSON Template Engine does not impose a fixed JSON structure. The user defines a reference JSON template, and the data logger dynamically inserts live sensor values, timestamps and device metadata into that structure at runtime. This makes the engine suitable for integrating with APIs that require their own field names, nested objects, arrays, parameter metadata, timestamps, device identifiers or other application-specific content. The generated output remains valid JSON and can closely match the schema expected by the receiving application. {% hint style="info" %} **Payload Format:** Select `JSON_FORMAT_19` in the Payload Formatter to use the **JSON Template Engine**. {% endhint %} ### How the JSON Template Engine Works The engine starts with a **reference JSON template**. The template may contain normal static JSON together with special YuDash references. At runtime, the data logger processes the complete JSON structure and replaces these references with current values. ```mermaid flowchart LR A["Reference JSON
Template"] --> B["JSON Template Engine"] C["Static JSON"] --> B D["$ Live Variables"] --> B E["@ Device Metadata"] --> B F["@YUTS Timestamp"] --> B B --> G["Generated JSON Payload"] ``` Objects and arrays remain actual JSON structures. Numerical sensor values are inserted as JSON numbers rather than being converted into quoted text. ### Template Syntax The JSON Template Engine uses a small set of conventions. | Template content | Example | Behaviour | | ------------------- | ----------------------- | --------------------------------------------- | | **Static value** | `"unit": "mA"` | Sent exactly as entered | | **Live variable** | `"value": "$analog_1"` | Replaced with the current value of `analog_1` | | **Device metadata** | `"station_id": "@YSID"` | Replaced with a YuDash device/system value | | **Timestamp** | `"date_time": "@YUTS"` | Replaced with the configured timestamp | The **JSON keys are defined entirely by the application**. They do not need to match the internal YuDash variable names. For example: ```json "bod": "$analog_1" ``` means: > Use the current value of the YuDash variable `analog_1`, but publish it under the JSON key `bod`. ### Example 1 — Simple Key-Value Mapping A basic template can directly map YuDash variables to the field names required by the receiving application. #### Template ```json { "bod": "$analog_1", "cod": "$analog_2", "tss": "$analog_3", "ph": "$analog_4" } ```
#### Generated Payload ```json { "bod": 5.9965, "cod": 6.99675, "tss": 7.997, "ph": 8.99725 } ``` The `$` prefix identifies a **live YuDash variable**. At runtime, each reference is replaced by the current value of that variable. The test output confirms this substitution.
### Live Variables — `$` A JSON string value beginning with `$` is treated as a reference to a current YuDash datapoint. For example: ```json { "temperature": "$temperature", "humidity": "$humidity" } ``` If the current values are `28.4` and `67.2`, the generated payload becomes: ```json { "temperature": 28.4, "humidity": 67.2 } ``` The engine preserves the runtime data type where supported. Numerical datapoints are inserted as JSON numbers, while strings and Boolean values can retain their corresponding JSON types. > The referenced variable must exist in the current YuDash datapoint set. The name should match the configured sensor, calculated or other generated variable. *** ### Example 2 — Nested JSON with Metadata The JSON Template Engine can combine sensor values with device metadata, timestamps and nested JSON objects. #### Template ```json { "station_id": "@YSID", "device_id": "yu10005054", "date_time": "@YUTS", "sensor_data": { "analog_1": "$analog_1", "analog_2": "$analog_2", "analog_3": "$analog_3", "analog_4": "$analog_4" } } ```
#### Generated Payload ```json { "date_time": "2026-10-18 13:29:46", "device_id": "yu10005054", "sensor_data": { "analog_1": 5.9965, "analog_2": 6.99675, "analog_3": 7.99625, "analog_4": 8.99725 }, "station_id": "station001" } ``` Here: * `device_id` is a **static value** * $analog\_1 to $analog\_4 are **live variables** * `@YSID` inserts the configured **Station ID** * `@YUTS` inserts the generated **timestamp** The resulting nested structure is created directly by the engine. payload *** ### Device Metadata — `@` YuDash provides system-generated values that can be inserted into the template using `@` references. For example: ```json { "station_id": "@YSID", "firmware": "@YFWV", "timestamp": "@YUTS", "temperature": "$temperature" } ``` Unlike `$` variables, these values describe the **device or runtime environment** rather than a measured process variable. Device metadata can also be added to predefined payload formats through the **Device Headers** settings. The JSON Template Engine provides additional flexibility by allowing these values to be positioned directly within a custom JSON hierarchy. *** ### Timestamp — `@YUTS` `@YUTS` inserts the timestamp generated by the Payload Formatter. The required representation is defined using the **Timestamp Encoder**. For example: ``` #YY-#MM-#DD#SP#HH:#NN:#SS ``` generates: ``` 2026-10-18 14:02:50 ``` Therefore: ``` { "observed_at": "@YUTS" } ``` becomes: ``` { "observed_at": "2026-10-18 14:02:50" } ``` `@YUTS` may be used at multiple locations within the same JSON template. *** ### Example 3 — Array-Based API Payload Many APIs expect measurements as an **array of parameter objects** rather than as a simple key-value object. The JSON Template Engine can generate this structure directly. #### Template ```json { "station_id": "@YSID", "device_id": "yu10005054", "date_time": "@YUTS", "sensor_data": [ { "observed_at": "@YUTS", "parameter_key": "Analog_1", "value": "$analog_1", "unit": "mA" }, { "observed_at": "@YUTS", "parameter_key": "Analog_2", "value": "$analog_2", "unit": "mA" }, { "observed_at": "@YUTS", "parameter_key": "Analog_3", "value": "$analog_3", "unit": "mA" }, { "observed_at": "@YUTS", "parameter_key": "Analog_4", "value": "$analog_4", "unit": "mA" } ] } ```
#### Generated Payload ```json { "date_time": "2026-10-18 14:02:50", "device_id": "yu10005054", "sensor_data": [ { "observed_at": "2026-10-18 14:02:50", "parameter_key": "Analog_1", "unit": "mA", "value": 5.9965 }, { "observed_at": "2026-10-18 14:02:50", "parameter_key": "Analog_2", "unit": "mA", "value": 6.99675 }, { "observed_at": "2026-10-18 14:02:50", "parameter_key": "Analog_3", "unit": "mA", "value": 7.99625 }, { "observed_at": "2026-10-18 14:02:50", "parameter_key": "Analog_4", "unit": "mA", "value": 8.996562 } ], "station_id": "station001" } ``` This example combines **arrays, nested objects, repeated timestamps, live variables, static parameter metadata and device metadata** in a single payload. payload This makes the engine particularly useful when integrating YuDash devices directly with APIs that mandate their own telemetry schema. *** ### Timestamp Encoder Reference The Timestamp Encoder controls the representation inserted by `@YUTS`. | Token | Meaning | Example | | ----- | -------------------- | ------------ | | `#YY` | Four-digit year | `2026` | | `#MM` | Month | `10` | | `#DD` | Day | `18` | | `#HH` | Hour | `14` | | `#NN` | Minute | `02` | | `#SS` | Second | `50` | | `#DT` | Date as `YYYY_MM_DD` | `2026_10_18` | | `#TD` | Time as `HH_MM_SS` | `14_02_50` | | `#SP` | Space | | | `#NL` | New line | line break | Normal non-space characters may be used as separators. For example: ``` #YY/#MM/#DD#SP#HH:#NN:#SS ``` produces: ``` 2026/10/18 14:02:50 ``` while: ``` #YY-#MM-#DDT#HH:#NN:#SS ``` produces: ``` 2026-10-18T14:02:50 ``` > Literal spaces in the encoder are ignored. Use `#SP` whenever an actual space is required in the generated timestamp. Timestamp timezone selection is configured separately in the Payload timestamp settings. *** ## Device Metadata Reference The following device/system values can currently be resolved by the JSON Template Engine: | Code | Runtime value | | ------- | --------------------------------------- | | `@YSID` | Station ID | | `@YDNO` | Device serial number | | `@YFWV` | Firmware version | | `@YMC1` | MAC address without separators | | `@YMC2` | Device MAC-address representation | | `@EIPA` | Ethernet IP address | | `@MBSL` | Modbus Slave ID represented as text | | `@MBSI` | Modbus Slave ID represented as a number | | `@FGDB` | Cellular signal-strength value | | `@YUTS` | Generated payload timestamp | These references may be combined with static content and `$` live variables. For example: ``` { "serial_no": "@YDNO", "station_id": "@YSID", "firmware": "@YFWV", "timestamp": "@YUTS", "flow": "$flow_rate" } ``` *** ### Advanced — Variable Groups The JSON Template Engine also supports insertion of a **YuDash variable group** into a JSON object. A template entry whose key begins with: ``` YU_VARGROUP ``` can reference a configured variable-group number. During payload generation, the datapoints belonging to that group are dynamically inserted into the corresponding JSON object. This can be useful where a larger collection of variables needs to be transmitted without explicitly listing every $variable in the template. > For fixed third-party API schemas, explicit $variable mappings are generally easier to read and maintain. Variable-group insertion is intended for more advanced or dynamic applications. I would keep this section short until we have a clean worked UI example. *** ### Engine Behaviour The JSON Template Engine recursively processes both **JSON objects and JSON arrays**. Static values remain unchanged, while recognised `$` and `@` references are resolved at runtime. This allows static application metadata and dynamic YuDash data to coexist anywhere inside the same payload. If a referenced datapoint is in an error state, the engine can substitute the configured payload error value instead of a normal datapoint. The JSON Template Engine defines the **payload structure**. MQTT broker settings, HTTP endpoint configuration, transmission interval and network connectivity are configured independently. *** ### When to Use the JSON Template Engine Use a **predefined JSON payload**, such as the standard key-value format, when the receiving system accepts a straightforward payload. Use the **JSON Template Engine** when the destination API requires a specific structure, for example: ```json { "station": "...", "timestamp": "...", "measurements": [ { "parameter": "...", "value": 0, "unit": "..." } ] } ``` The engine allows this structure to be generated **directly at the edge**, reducing or eliminating the need for an intermediate payload-conversion service.