This is Tiny protocol implementation for microcontrollers (Arduino, Stellaris).
Introduction
This protocol is intended to be used in low-memory systems, like microcontrollers (Stellaris, Arduino). It is also can be compiled for desktop Linux systems, and it is possible to build it for Windows.
Tiny Protocol API
Linux API supports C-Style functions, while Arduino API supports both C-Style and C++ classes. Usage C++ Arduino classes makes easy use of the protocol for Arduino projects. Please refer to documentation.
Packet Structure
Full packet format:
8 16 any len None/8/16/32 8
| 7E | UID | 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.
- UID mean unique identifier of the frame (in network byte order). For Half Duplex Tiny Protocol (Tiny Half Duplex API functions) it is widely used in acknowledge frames. This field is optional, you may omit UID parameter in Tiny simple API functions and Tiny advanced API functions functions. Tiny light protocol API functions do not use UID field in the frames.
- 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_sent(void *user_data, const 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_sent() 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 Half Duplex API functions) needs 4 callback functions, defined by a user: read_func_cb() is added. The list of callbacks:
int write_func_cb(void *user_data, const void *data, int len);
int read_func_cb(void *user_data, void *data, int len);
int on_frame_read(void *user_data, void *data, int len);
int on_frame_sent(void *user_data, const void *data, int len);
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++)