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.

                The packet counter will be incremented on every packet which
                is received with a valid CRC and address.
                Unknown packets or packets with wrong payload lengths are
                ignored - but the sequence counter will still be incremented.

    @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 + 1         | UUID + new address     |
    | 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

    The shellmatta always uses the maximum buffersize of
    #SHELLMATTA_TRANPORT_PAYLOAD_MAXLENGTH.
    If the host has a smaller receive buffer this can be set using the 0x02
    packet.

    A host should use this packet to request the shellmatta buffersize.
    This can be changed in the future.


    @section shellmatta_transport_layer_addressing Addressing and Search

    The shellmatta comes with a primitive multidrop implementation to address
    and find multiple shellmatta transport layer enabled devices on a bus.

    Every command comes with a source and destination address.
    0 is the broadcast address an received everytime.
    1 is reserved for the MASTER/HOST. The Shellmatta will always send responses
    to this address - no matter what the source of the telegram was.

    The packet response is sent to the source from the request packet.

    To assign a new address to a shellmatta transport layer enabled device
    there is a possibility to search for devices on the bus.

    Every shellmatta which enables this feature requires a 16 byte UUID to be
    specified which is unique on the bus.
    The Host can then search for shellmatta nodes using a range of UUIDs
    using command 0x03.

    Every shellmatta instance within this range will respond.
    If more than one shellmatta is in the specified range this will lead to
    collisions on the bus. When the host detects collisions it shall repeat
    the search requests with different ranges until only one shellmatta
    responds.

    Once the host has found a single shellmatta in one range it can assign a
    unique address using command 0x04.

    The shellmatta can now be accessed using this address.


    @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

*/