Tiny Protocol

Table of Contents

• Introduction
• Tiny Protocol API
• Packet Structure
• User-defined callbacks
• Arduino related documentation

This is Tiny protocol implementation for microcontrollers (Arduino, Stellaris).

Introduction

This protocol is intended to be used in low-memory systems, like microcontrollers (Stellaris, AVR, Espressif, STM). It is also can be compiled for desktop Linux systems, and it is possible to build it for Windows.

Tiny Protocol API

Library API supports C-Style functions - the basic API, and C++ API, which provides high level easy to use classes. Please refer to documentation. Basically TinyProto library provides 3 different protocol implementations:

Tiny HDLC protocol API functions This is basis, which all other protocols implementations are built on top of. Hdlc api provides basic input/output operations, like FCS, escape sequencies, etc. There is no C++ wrappers for it.

Tiny light protocol API functions This is simple protocol, based on HDLC api. It simplifies sending and receiving messages on small controllers, and at the same time it has low memory consumption (800 bytes of flash). But, be careful since light version doesn't have any confirmation from remote side. At the same time light version checks for checksum, and validates received data.

Tiny Full Duplex API functions This is the heaviest protocol implementation in the library. For atmega controllers it requires 7KiB of flash, and at least 700 bytes of RAM to operate with 64-byte length frames. Unlike hd version, fd version of protocol is much faster, as it doesn't wait for confirmation before sending next frame (thanks to window, specified in HDLC specs). Fd version of protocol uses official HDLC frame format, and implements U-frames (SABM,UA), S-frames (RR,REJ), I-frames.

Packet Structure

HDLC frame format:

     8        any len    None/8/16/32     8
 |   7E   |    DATA     |    FCS     |   7E   |

Full duplex hdlc uses standard hdlc frame format:

     8     ADDR  CONTROL     any len    None/8/16/32     8
 |   7E   | FF | hdlc ctl | USER DATA  |    FCS     |   7E   |

• 7E is packet delimiter (commonly used on layer 2) as defined in HDLC/PPP framing. packet delimiter is used by the protocol to find first and last byte of the frame being transmitted.
• USER DATA of any length. This field contains user data with replaced 0x7D and 0x7E bytes by special sequenced as defined in HDLC/PPP framing. Length of data is now limited on buffer used to receive frames and/or 32767 bytes (Tiny Protocol using 16-bit field to store frame length).
• FCS is standard checksum. Depending on your selection, this is 8-bit, 16-bit or 32-bit field, or it can be absent at all. Refer to RFC1662 for examples. FCS field is also optional and can be disabled. But in this case transport errors are not detected.

User-defined callbacks

Tiny HDLC protocol API functions needs 3 callback functions, defined by a user (you may use any function names you need).

HDLC callbacks:

int write_func_cb(void *user_data, const void *data, int len);
int on_frame_read(void *user_data, void *data, int len);
int on_frame_send(void *user_data, void *data, int len);

• write_func_cb() is called by HDLC implementation every time, it needs to send bytes to TX channel
• on_frame_read() is called by HDLC implementation every time, new frame arrives and checksum is correct.
• on_frame_send() is called by HDLC implementation every time, new frame is sent to TX. HDLC protocol requires only write_func_cb() to be defined. Other callbacks are optional. As for RX processes, your application code is responsible for reading data from RX line, then all you need to do, is to pass received bytes to HDLC implementation for processing via hdlc_run_rx().

All higher level protocols (Tiny light protocol API functions, Tiny Full Duplex API functions) needs 4 callback functions, defined by a user: The list of callbacks:

int write_func_cb(void *user_data, const void *data, int len);  // LIGHT API Only
int read_func_cb(void *user_data, void *data, int len);         // LIGHT API Only
void on_frame_cb(void *udata, uint8_t *pdata, int size);        // FD API Only
void on_frame_send_cb(void *udata, const uint8_t *pdata, int size);  // FD API Only

Unlike HDLC implementation, higher level protocols use different approach. They control both TX and RX channels, for example, to transparently send ACK frames, etc. That's why higher level protocols need to read_func_cb to be defined:

• read_func_cb() is called by higher level protocol implementation every time, it needs to read bytes from RX channel.

Arduino related documentation

Arduino related API (C++)