shellmatta/doc/shellmatta_transport_layer.dox

/**

    @page shellmatta_transport_layer Shellmatta Transport Layer

    To be able to use the shellmatta directly on an unsecured interface like
    raw UART a simple connectionless transport layer has been implemented.

    The transport layer is optional and can be removed during compile time as
    well as deactivated during runtime.

    To enable it during compile time add the define ``SHELLMATTA_TRANSPORT``.


    The transport layer intends to be used in machine to machine interfaces.

    @warning    As the transport layer is connectionless there is no way to
                determine wether a packet is received properly.
                To check if all packets have been received by the shellmatta
                the sequence counters included in any packet can be used.

    @section shellmatta_transport_layer_sequence Basic sequence

    @startuml
        loop until command is sent
            Host -> Shellmatta: send packet
            Shellmatta -> Shellmatta: validate packet
        end

        loop until response is sent
            Shellmatta -> Host: send return packet
            Host -> Host: validate packet
        end
    @enduml


    @section shellmatta_transport_layer_protocol Protocol


    | Offset | Length        | Description                                 |
    |--------|---------------|---------------------------------------------|
    |    0   |     1         | Start of header (\\SOH)                     |
    |    1   |     1         | Protocol version                            |
    |    2   |     1         | Packet type                                 |
    |    3   |     1         | Payload Length                              |
    |    4   |     1         | Source                                      |
    |    5   |     1         | Destination                                 |
    |    6   |     1         | Sequence counter host to shellmatta         |
    |    7   |     1         | Sequence counter shellmatta to host         |
    |    8   | L1 = 0 .. 255 | Payload                                     |
    |8 + L1  |     4         | CRC32 of header + payload without CRC32     |


    @subsection shellmatta_transport_layer_protocol_packet_Types Packet types

    The type codes are divided into request and respond codes using the MSB.
    The MSB indicates a response.

    | type | Description                    | Payload length |  Payload               |
    |------|--------------------------------|----------------|------------------------|
    | 0x00 | Plain Data                     | 0 .. 255       | User data              |
    | 0x01 | Request Sequence counters      | 0              | -                      |
    | 0x81 | Respond Sequence counters      | 0              | -                      |
    | 0x02 | Request and set max buffersize | 1              | Hosts buffersize       |
    | 0x82 | Respond max buffersize         | 1              | Shellmattas buffersize |
    | 0x03 | Search device by unique ID     | 32             | UUID Range 2x 16 byte  |
    | 0x83 | Respond to search              | 16             | UUID of Shellmatta     |
    | 0x04 | Set address                    | 16             | UUID of Shellmatta     |
    | 0x84 | Respond to set address         | 16             | UUID of Shellmatta     |


    @section shellmatta_transport_layer_sequence_counters Sequence counters

    The sequence counters are included in the header of every packet to enable
    the host to check for any dropped packets.
    This is a quite nasty workaround as the host has no chance to determine
    which packet has been dropped - but better than nothing.

    If no response is received from the shellmatta the sequence counters can be
    requested explicitly.

    The sequence counter host to shellmatta will increment on every successfully
    received packet.

    The sequence counter shellmatta to host will increment on every packet the
    shellmatta sends to the host.


    @section shellmatta_transport_layer_buffersize Buffer sizes

    @todo Not implemented yet


    @section shellmatta_transport_layer_addressing Addressing and Search

    @todo Not implemented yet


    @section shellmatta_transport_layer_crc CRC calculation

    The shellmatta transport layer uses the CRC32 algorithm to secure the
    transmission (0x04c11db7).

    By default the shellmatta crc implementation uses a lookup table to
    calculate the crc in a performant way.

    This uses quite a lot of read only memory on the device. If the memory
    consumption is an Issue you can switch to a slower implementation without
    the lookup table. This will increase CPU load quite a bit, but saves nearly
    1K of read only memory.

    To enable the lookup table less CRC just define
    ``SHELLMATTA_TRANSPORT_CRC_NO_LOOKUP`` during compilation.


    @section shellmatta_transport_layer_control Controlling the transport layer

    @todo Not implemented yet

*/