frames.adoc

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 using name property.

<?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 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, 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> - Message payload.

• <id> - Numeric message ID.

• <size> - Remaining size (length).

• <sync> - Synchronization bytes.

• <checksum> - Checksum.

• <value> - Extra value, usually to be assigned to one of the <interface> fields.

• <custom> - Any other custom layer, not defined by CommsDSL.

If there is any other property 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 as well as their own specific set of properties.

Use properties table for future references.

common.adoc payload.adoc id.adoc size.adoc sync.adoc checksum.adoc value.adoc custom.adoc