> For the complete documentation index, see [llms.txt](https://alex-robenko.gitbook.io/commsdsl-specification/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alex-robenko.gitbook.io/commsdsl-specification/frames.md).

# Frames

Every communication protocol must ensure that the message is successfully delivered over the I/O link to the other side. The serialised message payload must be wrapped in some kind of transport information prior to being sent and unwrapped on the other side when received. The **CommsDSL** allows specification of such transport wraping using **\<frame>** XML node.

```
<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <frame ...>
        ...
    </frame>
</schema>
```

## Name

Every frame definition must specify its [name](/commsdsl-specification/names.md) using **name** [property](/commsdsl-specification/properties.md).

```
<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <frame name="ProtocolFrame">
        ...
    </frame>
</schema>
```

## Description

It is possible to provide a description of the frame about what it is and how it is expected to be used. This description is only for documentation purposes and may find it's way into the generated code as a comment for the generated class. The [property](/commsdsl-specification/properties.md) is **description**.

```
<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <frame name="ProtocolFrame">
        <description>
            Some long
            multiline
            description
        </description>
        ...
    </frame>
</schema>
```

## Layers

The protocol framing is defined using so called "layers", which are additional abstraction on top of [fields](/commsdsl-specification/fields.md), where every such layer has a specific purpose. For example:

```
<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <fields>
        <enum name="MsgId" type="uint8" semanticType="messageId">
            <validValue name="Msg1" val=0x1" />
            <validValue name="Msg2" val=0x2" />
        </enum>
    </fields>

    <frame name="ProtocolFrame">
        <id name="Id" field="MsgId" />
        <payload name="Data" />
    </frame>
</schema>
```

The example above defines simple protocol framing where 1 byte of numeric message ID precedes the message payload.

```
ID (1 byte) | PAYLOAD
```

Available layers are:

* [\<payload>](/commsdsl-specification/frames/payload.md) - Message payload.
* [\<id>](/commsdsl-specification/frames/id.md) - Numeric message ID.
* [\<size>](/commsdsl-specification/frames/size.md) - Remaining size (length).
* [\<sync>](/commsdsl-specification/frames/sync.md) - Synchronization bytes.
* [\<checksum>](/commsdsl-specification/frames/checksum.md) - Checksum.
* [\<value>](/commsdsl-specification/frames/value.md) - Extra value, usually to be assigned to one of the

  [\<interface>](/commsdsl-specification/interfaces.md) fields.
* [\<custom>](/commsdsl-specification/frames/custom.md) - Any other custom layer, not defined by **CommsDSL**.&#x20;

If there is any other [property](/commsdsl-specification/properties.md) defined as XML child of the **\<frame>**, then all the layers must be wrapped in **\<layers>** XML element for separation.

```
<?xml version="1.0" encoding="UTF-8"?>
<schema ...>
    <frame>
        <name value="ProtocolFrame" />
        <layers>
            <id name="Id" field="MsgId" />
            <payload name="Data" />
        </layers>
    </frame>
</schema>
```

All these layers have [common](/commsdsl-specification/frames/common.md) as well as their own specific set of properties.

Use [properties table](/commsdsl-specification/appendix/frame.md) for future references.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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://alex-robenko.gitbook.io/commsdsl-specification/frames.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.