> 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.md).

# Payload

A **payload** is the structured data generated by the YuDash device before it is transmitted to a server or written to a file.

The core payload contains the acquired **sensor data**. Depending on the application, optional metadata such as a **timestamp, device header, and device status** can also be included before the final JSON or TXT payload is generated.

```mermaid
flowchart LR
    A["Sensor Data"] --> B["Payload Encoder"]
    C["Timestamp"] --> B
    D["Device Header"] --> B
    E["Device Status"] --> B

    B --> F["JSON / TXT Payload"]
```

### Payload Configuration

Payload settings are configured from:

**Cloud Settings → Payload → Open Payload Wizard**

The **Payload Formatter Wizard** controls how acquired sensor data is encoded before it is transmitted or stored.

<figure><img src="https://1858257737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FToww5EM1cml3ouN6fvnJ%2Fuploads%2FF8F3c77Nd5OJK0Oj8uYC%2F01_payload_open_wizard_full_highlight.png?alt=media&amp;token=cc547e62-3504-4fa7-9244-c92e595b59fc" alt=""><figcaption></figcaption></figure>

#### Payload Format

The **Payload Format** selects the encoder used to generate the final payload. YuDash provides simple predefined JSON formats as well as configurable JSON and text generators.

Use **Format & Keys** to select the required format.

<table><thead><tr><th width="207">Payload Format</th><th>Use</th></tr></thead><tbody><tr><td><strong>JSON_FORMAT_10</strong></td><td>Standard key-value JSON payload. Recommended starting format for most MQTT and HTTP integrations.</td></tr><tr><td><strong>JSON_FORMAT_11 .. 18</strong></td><td>Other predefined JSON structures for specific integration requirements and existing deployments.</td></tr><tr><td><strong>JSON_FORMAT_19</strong></td><td>Configurable JSON generator for creating custom JSON payload structures.</td></tr><tr><td><strong>TXT20</strong></td><td>Configurable text generator for text, CSV-style, FTP and data-logging formats.</td></tr></tbody></table>

<figure><img src="https://1858257737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FToww5EM1cml3ouN6fvnJ%2Fuploads%2FsmfxHSGrmY8tMa8HQpJc%2F02_payload_format_keys.png?alt=media&amp;token=a5187b46-d9c0-4679-9c9d-7684ec73b4b1" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
**For most new JSON integrations, start with JSON10.** Use JSON19 when the receiving system requires a custom JSON structure.
{% endhint %}

## JSON Payload

JSON payloads provide a structured format for sending acquired variables to MQTT brokers, HTTP/HTTPS APIs and other applications that accept JSON data.

For most integrations, **JSON\_FORMAT\_10** is the recommended starting point. Alternative predefined structures are available where required, while **JSON\_FORMAT\_19** provides a configurable JSON generator for custom payloads.

#### JSON\_FORMAT\_10 — Standard Key-Value Payload

JSON10 sends each YuDash variable directly as a JSON key-value pair.

```
{
  "volt1_in": 237.67,
  "freq_in": 49.98,
  "kwhr_in": 1792.17
}
```

This simple structure works well for most MQTT and HTTP integrations where the receiving server can directly use the YuDash variable names.

***

#### JSON11 — Two-Level Payload

JSON11 creates a two-level JSON structure, with each variable name used as the main key.

```
{
  "volt1_in": {
    "value": 244.4
  },
  "freq_in": {
    "value": 50
  },
  "kwhr_in": {
    "value": 1792.17
  }
}
```

The secondary key, such as `value`, is configurable.

#### Other Predefined JSON Formats

Additional predefined JSON formats are available for **specific platforms, legacy integrations and application-specific data structures**.

### JSON\_FORMAT\_19 — JSON Template Engine

`JSON_FORMAT_19` enables the [**YuDash JSON Template Engine**](/pf/ct/payload/json.md), a generic payload engine for creating custom JSON structures to match application-specific APIs and server schemas.

Use the [**JSON Generator**](/pf/ct/payload.md) page for template syntax, live variables, device metadata, timestamps, nested objects and arrays./

### Time Stamp

A timestamp can be added to the generated payload when the receiving application requires the time associated with the data.

Enable **Send TimeStamp**, then configure:

* **Time Stamp Key** — the JSON key used for the timestamp, for example `ts`, `timestamp` or `time`
* **Time Stamp Format** — the required timestamp representation

The timestamp is inserted into the generated JSON along with the sensor data.

<figure><img src="https://1858257737-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FToww5EM1cml3ouN6fvnJ%2Fuploads%2F0yQgxJZKt6tJxi68jbxq%2F04_payload_timestamp_settings.png?alt=media&amp;token=5626e5ea-b951-43ad-a167-3a862990d5a6" alt=""><figcaption></figcaption></figure>

#### UTC Timestamp Formats

| Format                                    | Sample Time Stamp      |
| ----------------------------------------- | ---------------------- |
| **TS\_50 — UTC Seconds**                  | `1675630526`           |
| **TS\_51 — UTC MilliSeconds**             | `1675630526000`        |
| **TS\_52 — UTC YYYY-MM-DDTHH:MM:SS**      | `2023-02-05T20:55:26Z` |
| **TS\_53 — UTC YYYY-MM-DD HH:MM:SS**      | `2023-02-05 20:55:26`  |
| **TS\_54 — UTC YYYY\_MM\_DD\_HH\_MM\_SS** | `2023_02_05_20_55_26`  |
| **TS\_55 — UTC YYYY-MM-DDTHH:MM:00**      | `2023-02-05 20:55:00`  |
| **TS\_56 — UTC DD-MM-YYYY HH:MM:SS**      | `05-02-2023 20:55:26`  |

For **TS\_55**, seconds are set to `00`.

#### Local Time Timestamp Formats

| Format     | Representation                     |
| ---------- | ---------------------------------- |
| **TS\_60** | LocalTime Seconds                  |
| **TS\_61** | LocalTime MilliSeconds             |
| **TS\_62** | LocalTime YYYY-MM-DDTHH:MM:SS      |
| **TS\_63** | LocalTime YYYY-MM-DD HH:MM:SS      |
| **TS\_64** | LocalTime YYYY\_MM\_DD\_HH\_MM\_SS |
| **TS\_65** | LocalTime YYYY-MM-DDTHH:MM:00      |
| **TS\_66** | LocalTime DD-MM-YYYY HH:MM:SS      |

#### Example

With `JSON_FORMAT_10` and a timestamp key configured as `timestamp`:

```
{
  "volt1_in": 247.55,
  "freq_in": 49.94,
  "kwhr_in": 1792.17,
  "timestamp": "1675630887"
}
```

The **timestamp key is configurable**; common choices include `timestamp`, `ts` and `time`.

### Device Headers

**Device Headers** add identification or other metadata to the JSON payload in addition to the acquired sensor data.

A header consists of a **Key** and a **Value**. The value can either be a fixed value entered by the user or a dynamic YuDash metadata reference.

#### Fixed Key-Value Headers

Use a fixed value when the information remains constant for the installation.

For example:

| Header Key   | Header Value |
| ------------ | ------------ |
| `device_id`  | `YU10005054` |
| `station_id` | `STATION001` |

With `JSON_FORMAT_10`, these headers are added alongside the measured variables:

```
{
  "temperature": 28.4,
  "humidity": 67.2,
  "device_id": "YU10005054",
  "station_id": "STATION001"
}
```

Fixed headers are useful for application-specific identifiers such as a site name, station code or customer-defined device ID.

***

#### Dynamic Device Metadata

Instead of entering a fixed value, the Header Value can use a supported **`@` metadata reference**. YuDash resolves the reference when the payload is generated, allowing information such as the device serial number, station ID or firmware version to be included automatically.

For example:

| Header Key   | Header Value |
| ------------ | ------------ |
| `station_id` | `@YSID`      |
| `serial_no`  | `@YDNO`      |
| `firmware`   | `@YFWV`      |

The transmitted JSON then contains the actual runtime values rather than the `@` references.

#### Available Metadata References

| Reference | 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 as text           |
| `@MBSI`   | Modbus Slave ID as a number       |
| `@FGDB`   | Cellular signal-strength value    |
| `@YUTS`   | Generated payload timestamp       |

These metadata references are resolved by the YuDash payload engine at runtime.

> **Fixed values** are transmitted exactly as configured. **`@` metadata values** are resolved dynamically each time the payload is generated.