diff --git a/README.md b/README.md index 3b4669b..8651588 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,36 @@ # TinyFrame -Minimalist library for building and parsing data frames for serial comm + +TinyFrame is a simple library for building and parsing frames +(packets) to be sent over a serial interface (like UART). It's implemented +to be compatible with C89 and platform agnostic. + +Frames are protected by a checksum and contain a "unique" ID, +which can be used for chaining messages. Each peer uses a different +value for the first bit of all IDs it generates (the "master flag" +or "peer_bit") to ensure there are no clashes. Typically the master +(PC, main microcontroller) will use "1" and the surrogate (WiFi module, +USB-serial connected gadget, display driver...) uses "0". + +The library lets you bind listeners waiting for any frame, or a +particular ID. This allows for easy implementation of async communication. + +## Frame structure + +The frame makeup is inspired by that of SBMP (my other, more complicated +and advanced UART protocol library). + +``` + + +SOF ... start of frame, 0x01 +ID ... (master_flag | 7-bit counter) - the frame ID +NOB ... nr of payload bytes in the frame (1..256) +PAYLOAD ... NOB bytes of data, can contain any byte values 1..256 +CKSUM ... checksum, implemented as XOR of all preceding bytes in the message +``` + +The frame ID (in SBMP called "session ID") can be used to chain multiple related +messages and maintain the context this way. For example, a response may copy +the frame ID of the request frame, which then triggers a callback bound by the +requesting peer. Such behavior is application specific and is thus left to the +upper layers of the protocol. diff --git a/TinyFrame.c b/TinyFrame.c new file mode 100644 index 0000000..10df105 --- /dev/null +++ b/TinyFrame.c @@ -0,0 +1,252 @@ +#include "TinyFrame.h" +#include + +/* Note: payload length determines the Rx buffer size. Max 256 */ +#define TF_MAX_PAYLOAD 256 +#define TF_MAX_CALLBACKS 16 +#define TF_SOF_BYTE 0x01 + + +enum TFState { + TFState_SOF = 0, //!< Wait for SOF + TFState_ID, //!< Wait for ID + TFState_NOB, //!< Wait for Number Of Bytes + TFState_PAYLOAD, //!< Receive payload + TFState_CKSUM //!< Wait for Checksum +}; + + +/** + * Frame parser internal state + */ +static struct TinyFrameStruct { + /* Own state */ + bool peer_bit; //!< Own peer bit (unqiue to avoid msg ID clash) + unsigned int next_id; //!< Next frame / frame chain ID + + /* Parser state */ + enum TFState state; + unsigned int id; //!< Incoming packet ID + unsigned int nob; //!< Payload length + unsigned char pldbuf[TF_MAX_PAYLOAD+1]; //!< Payload byte buffer + unsigned int rxi; //!< Receive counter (for payload or other fields) + unsigned int cksum; //!< Continually updated checksum + + /* Callbacks */ + int cb_ids[TF_MAX_CALLBACKS]; //!< Callback frame IDs, -1 = all + TinyFrameListener cb_funcs[TF_MAX_CALLBACKS]; //!< Callback funcs, 0 = free slot +} tf; + + +/** + * Initialize the TinyFrame engine. + * This can also be used to completely reset it (removing all listeners etc) + * + * @param peer_bit - peer bit to use for self + */ +void TF_Init(bool peer_bit) +{ + memset(&tf, 0, sizeof(struct TinyFrameStruct)); + + tf.peer_bit = peer_bit; +} + + +/** + * Reset the frame parser state machine. + */ +void TF_ResetParser(void) +{ + tf.state = TFState_SOF; + tf.cksum = 0; +} + + +/** + * Register a receive callback. + * + * @param frame_id - ID of the frame to receive + * @param cb - callback func + * @return Callback slot index (for removing). TF_ERROR (-1) on failure + */ +int TF_AddListener(int frame_id, TinyFrameListener cb) +{ + int i; + + for (i = 0; i < TF_MAX_CALLBACKS; i++) { + if (tf.cb_funcs[i] == NULL) { + tf.cb_funcs[i] = cb; + tf.cb_ids[i] = frame_id; + return i; + } + } + + return TF_ERROR; +} + + +/** + * Remove a rx callback function by the index received when registering it + * + * @param index - index in the callbacks table + */ +void TF_RemoveListener(int index) +{ + tf.cb_funcs[index] = NULL; +} + + +/** + * Remove a callback by the function pointer + * + * @param cb - callback function to remove + */ +void TF_RemoveListenerFn(TinyFrameListener cb) +{ + int i; + + for (i = 0; i < TF_MAX_CALLBACKS; i++) { + if (tf.cb_funcs[i] == cb) { + tf.cb_funcs[i] = NULL; + // no break, it can be here multiple times + } + } + + return; +} + + +/** + * Accept incoming bytes & parse frames + * + * @param buffer - byte buffer to process + * @param count - nr of bytes in the buffer + */ +void TF_Accept(const unsigned char *buffer, unsigned int count) +{ + unsigned int i; + + for (i = 0; i < count; i++) { + TF_AcceptChar(buffer[i]); + } +} + + +/** + * Process a single received character + * + * @param c - rx character + */ +void TF_AcceptChar(unsigned char c) +{ + int i; + bool rv; + + switch (tf.state) + { + case TFState_SOF: + if (c == TF_SOF_BYTE) { + tf.cksum = 0; + tf.state = TFState_ID; + } + break; + + case TFState_ID: + tf.id = c; + tf.state = TFState_NOB; + break; + + case TFState_NOB: + tf.nob = c + 1; // using 0..255 as 1..256 + tf.state = TFState_PAYLOAD; + tf.rxi = 0; + break; + + case TFState_PAYLOAD: + tf.pldbuf[tf.rxi++] = c; + if (tf.rxi == tf.nob) { + tf.state = TFState_CKSUM; + } + break; + + case TFState_CKSUM: + tf.state = TFState_SOF; + + if (tf.cksum == (unsigned int)c) { + // Add 0 at the end of the data in the buffer (useful if it was a string) + tf.pldbuf[tf.rxi] = '\0'; + + // Fire listeners + for (i = 0; i < TF_MAX_CALLBACKS; i++) { + // Fire if used & matches + if (tf.cb_funcs[i] && (tf.cb_ids[i] == -1 || tf.cb_ids[i] == tf.id)) { + rv = tf.cb_funcs[i](tf.id, tf.pldbuf, tf.nob); + + // Unbind + if (rv) tf.cb_funcs[i] = NULL; + } + } + } else { + // Fail, return to base state + tf.state = TFState_SOF; + } + break; + } + + // Update the checksum + tf.cksum ^= c; +} + + +/** + * Compose a frame + * + * @param outbuff - buffer to store the result in + * @param msgid - message ID is stored here, if not NULL + * @param payload - data buffer + * @param len - payload size in bytes, 0 to use strlen + * @param explicit_id - ID to use, -1 to chose next free + * @return nr of bytes in outbuff used by the frame, -1 on failure + */ +int TF_Compose(unsigned char *outbuff, unsigned int *msgid, + const unsigned char *payload, unsigned int payload_len, + int explicit_id +) { + unsigned int i; + unsigned int id; + int xor; + + // sanitize len + if (payload_len > TF_MAX_PAYLOAD) return TF_ERROR; + if (payload_len == 0) payload_len = strlen(payload); + + // Gen ID + if (explicit_id == TF_NEXT_ID) { + id = tf.next_id++; + if (tf.peer_bit) { + id |= 0x80; + } + + if (tf.next_id > 0x7F) { + tf.next_id = 0; + } + } else { + id = explicit_id; + } + + outbuff[0] = TF_SOF_BYTE; + outbuff[1] = id & 0xFF; + outbuff[2] = (payload_len - 1) & 0xFF; // use 0..255 as 1..256 + memcpy(outbuff+3, payload, payload_len); + + xor = 0; + for (i = 0; i < payload_len + 3; i++) { + xor ^= outbuff[i]; + } + + outbuff[payload_len + 3] = xor; + + if (msgid != NULL) *msgid = id; + + return payload_len + 4; +} diff --git a/TinyFrame.h b/TinyFrame.h new file mode 100644 index 0000000..73d1e4c --- /dev/null +++ b/TinyFrame.h @@ -0,0 +1,48 @@ +//--------------------------------------------------------------------------- + +#ifndef TinyFrameH +#define TinyFrameH +//--------------------------------------------------------------------------- + +#include +#include + +/** + * TinyFrame receive callback trype. + * + * @param frame_id - ID of the received byte (if response, same as the request) + * @param buff - byte buffer with the payload + * @param len - number of bytes in the buffer + * @return return true, if the callback should be removed. + */ +typedef bool (*TinyFrameListener)( + unsigned int frame_id, + const unsigned char *buff, + unsigned int len +); + +// Forward declarations (comments in .c) + +void TF_ResetParser(void); +void TF_Init(bool peer_bit); + +void TF_Accept(const unsigned char *buffer, unsigned int count); +void TF_AcceptChar(unsigned char c); + +#define TF_ANY_ID -1 +int TF_AddListener(int frame_id, TinyFrameListener cb); // returns slot index +void TF_RemoveListener(int index); +void TF_RemoveListenerFn(TinyFrameListener cb); + +// returns "frame_id" + +#define TF_NEXT_ID -1 +#define TF_ERROR -1 + +// returns nr of bytes in the output buffer used, or TF_ERROR +int TF_Compose(unsigned char *outbuff, unsigned int *msgid, + const unsigned char *payload, unsigned int payload_len, + int explicit_id +); + +#endif diff --git a/test.c b/test.c new file mode 100644 index 0000000..201485f --- /dev/null +++ b/test.c @@ -0,0 +1,36 @@ +#include +#include +#include "TinyFrame.h" + +#define BUFLEN 200 + +bool listen(unsigned int frame_id, const unsigned char *buff, unsigned int len) +{ + printf("\033[33mrx frame %s, len %d, id %d\033[0m\n", buff, len, frame_id); + + return false; // Do not unbind +} + +void main() +{ + TF_Init(1); + + int msgid; + unsigned char buff[BUFLEN]; + + TF_AddListener(TF_ANY_ID, listen); + + int len = TF_Compose(buff, &msgid, "Hello TinyFrame", 0, TF_NEXT_ID); + printf("Used = %d, id=%d\n",len, msgid); + for(int i=0;i