# Message Format

### Tag-Length-Value (TLV) Encoding

#### About TLV Encoding

All messages exchanged between the host and the device are formatted using the tag-length-value **Distinguished Encoding Rules** (DER) defined in ***ITU-T X.680 | ISO/IEC 8824-1*** and ***ITU-T X.690 | ISO/IEC 8825-1***. A subset of these standards is also used in ***EMV Integrated Circuit Card Specifications for Payment Systems 4.3, Part IV, Annex B Rules for BER-TLV Data Objects***, so the latter can serve as a useful point of reference.

Summarizing those specifications, each TLV data object follows these basic rules:

* The DER standard designates the least significant bit of a byte as **bit 1**, and the most significant bit of a byte as **bit 8**. This is different from the remainder of the MMS standard, which indexes bit numbers starting at 0 to be consistent with each bit position number representing that bit’s power of 2.
* The **Tag** or **Identifier** portion of a TLV data object identifies the TLV data object. DER assigns the tag portion as follows:
  * Bits 8 and 7 specify whether the TLV data object is universal, application-defined, context-specific, or private. Most messages in this standard contain **context-specific** tags (bits 8 and 7 = **10**), meaning different messages reuse the same tags, and the tags represent sequentially numbered parameters passed in any message.
  * Bit 6 specifies whether the tag is **primitive** (bit 6 = **0**), meaning it contains its values directly, or **constructed** (bit 6 = **1**), meaning the TLV data object contains more TLV data objects.
  * Bits 5 to 1 specify a unique tag number, with 11111 reserved to mean the tag is not a single byte long. In that multi-byte case:
    * Bits 7 to 1 of subsequent bytes with bit 8 set to 1 are also part of the tag identifier with the most significant of the whole tag number in bit 7.
    * Bits 7 to 1 of the final byte with bit 8 set to 0 are also part of the tag identifier.
* The **Length** portion is the total length of the Data portion that follows it. Lengths can be either short form or long form:
  * Short form: one byte long in the range 0x00 to 0x7F.
  * Long form: multiple bytes long, starting with one byte 0x80 or greater, where the lower 7 bits specify how many subsequent bytes are used to indicate the length. Example: length 8201C3 — 0x82 indicates two subsequent bytes (0x01C3) giving the total length of the data block (451 bytes).
  * DER stipulates all TLV objects should be encoded using the smallest length required to fit the data.
* The **Value** or **Data** portion is the actual payload of the TLV data object.

This document provides message definitions in hexadecimal format; when the host constructs or interprets a message, if no additional encode/decode filtering or translation is in place at the platform layer, it should expect each hexadecimal value shown in this document to be represented as binary bytes in the message stream, not as string literals. For example, FF is a single byte with all bits set to 1, not the two-byte string literal "FF."

#### TLV Example

Below is an example of a TLV-encoded request and response for **Command 0xDF01 - Echo**, wrapped in the standard message format.

Host sends the device the binary byte stream:

```
AA0081040101DF018407DF018103010203
```

Breakdown:

* AA00 = Standard Start of Message / API Framework Version (not TLV)
* 81, 04, 0101DF01
  * Tag 81 = Request Message Parameter 1, **Message Information**
  * Length 04
  * Value 01 01 DF 01
    * 01 = Request from host to device
    * 01 = Message reference number
    * DF01 = **Command 0xDF01 - Echo**
* 84, 07, DF018103010203
  * Tag 84 = Request Message Parameter 4, **Request Payload**
  * Length 07
  * Value DF01 81 03 01 02 03
    * DF01 = Payload format is for Request **Command 0xDF01 - Echo** (not TLV)
    * Tag 81 = Payload Parameter 1, **Value to Echo**
    * Length 03
    * Value 01 02 03 = Value to Echo

Device responds with the binary byte stream:

```
AA0081048201DF018204000000008407DF018103010203
```

Breakdown:

* AA00 = Standard Start of Message / API Framework Version (not TLV)
* 81, 04, 8201DF01
  * Tag 81 = Response Message Parameter 1, **Message Information**
  * Length 04
  * Value 82 01 DF 01
    * 82 = Response from device to host
    * 01 = Message reference number
    * DF01 = **Command 0xDF01 - Echo**
* 82, 04, 00000000
  * Tag 82 = Response Message Parameter 2, **Response Status** (one byte Operation Status Summary, three bytes Operation Status Detail)
  * Length 04
  * Value 00 00 00 00 = OK / Done, General / All Good / Requested operation was successful
* 84, 07, DF018103010203
  * Tag 84 = Response Message Parameter 4 for **Response Payload**
  * Length 07
  * Value DF01 81 03 01 02 03
    * DF01 = Payload format is for Response **Command 0xDF01 - Echo** (not TLV)
    * Tag 81 = Payload Parameter 1, **Value to Echo**
    * Length 03
    * Value 01 02 03 = Value to Echo

## See Also

* [**Command 0xDF01 - Echo**](https://magtek.gitbook.io/magtek-pilot-gitbooks/internal-documentation/index/6.0-commands/6.9-command-group-0xdfnn-diagnostics-and-utilities/6.9.1-command-0xdf01-echo)
* [**Value to Echo**](https://magtek.gitbook.io/magtek-pilot-gitbooks/internal-documentation/index/6.0-commands/6.9-command-group-0xdfnn-diagnostics-and-utilities/6.9.1-command-0xdf01-echo)

## How to Read TLV Tables

Tables that show TLV data objects use slashes in front of the **Tag** identifier to indicate that object’s relative level of nesting/containment within other TLV data objects in the same table. These levels are relative and not absolute: a given TLV object may be nested within other TLV objects at any level.

Example of slash notation:

* Earth contains
  * /North America, which contains
    * //United States, which contains
      * ///California

In TLV tables, a Length of **var** means the length is variable and must be calculated based on nested objects.

See Table 10 below for an example.

#### Table 10 - TLV Table Example

<table><thead><tr><th width="80.33331298828125">Tag</th><th width="72">Len</th><th>Value / Description</th><th width="70">Typ</th><th width="87">Req</th><th width="121.00006103515625">Default</th></tr></thead><tbody><tr><td>A1</td><td>var</td><td>TLV data object <strong>A1</strong> contains four directly nested TLV data objects: 81, 82, A3, and 84 (A1/81, A1/82, A1/A3, and A1/84). A1/82 is optional (Req = <strong>O</strong>), so the length of A1 will vary depending on whether or not A1/82 is included (Len = <strong>var</strong>).</td><td>T</td><td>R</td><td></td></tr><tr><td>/81</td><td>01</td><td>TLV data object A1/81 contains one byte and is required. It has no default value because it must be explicitly included.</td><td>B</td><td>R</td><td></td></tr><tr><td>/82</td><td>03</td><td>TLV data object A1/82 contains three bytes but is optional. If not included, the device assumes the default value 0x4D6F6D.</td><td>B</td><td>O</td><td>0x4D6F6D</td></tr><tr><td>/A3</td><td>08</td><td>TLV data object A1/A3 contains two TLV data objects: 81 and 82 (A1/A3/81 and A1/A3/82). Its length is the combined length of its two nested objects.</td><td>T</td><td>R</td><td></td></tr><tr><td>//81</td><td>03</td><td>TLV data object A1/A3/81 contains three bytes and is required.</td><td>B</td><td>R</td><td></td></tr><tr><td>//82</td><td>01</td><td>TLV data object A1/A3/82 contains one byte and is required.</td><td>B</td><td>R</td><td></td></tr><tr><td>/84</td><td>03</td><td>TLV data object A1/84 contains three bytes that represent distinct values stored directly inside A1/84 instead of separate nested TLVs.</td><td>B</td><td>R</td><td></td></tr><tr><td>//null</td><td>(1)</td><td>Raw byte inside 84 (no TLV). Tag shown as <strong>/null</strong>, length in parentheses.</td><td>B</td><td>R</td><td></td></tr><tr><td>//null</td><td>(1)</td><td>Another raw byte inside 84.</td><td>B</td><td>R</td><td></td></tr><tr><td>//null</td><td>(1)</td><td>Another raw byte inside 84.</td><td>B</td><td>R</td><td></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.magtek.com/hardware/card-readers/mms-dyna-devices/emv-common-kernel/dynaflex-ii-go/documents/programmers-manuals/programmers-manuals-commands/messages-requests-responses-notifications-and-files/message-format.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.