You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
117 lines
4.3 KiB
117 lines
4.3 KiB
# TinyFrame
|
|
|
|
TinyFrame is a simple library for building and parsing frames to be sent
|
|
over a serial interface (e.g. UART, telnet etc.). The code is written
|
|
in `--std=gnu89`.
|
|
|
|
Frames are protected by a checksum (~XOR, CRC16 or CRC32) and contain
|
|
a unique ID field, which can be used for chaining messages. The highest value
|
|
of the ID is different for each peer (TF_MASTER or TF_SLAVE) to avoid collisions.
|
|
|
|
All fields in the frame have configurable size (see the top of the header file).
|
|
By just changing a value, like `TF_LEN_BYTES`, the library seamlessly switches
|
|
from `uint8_t` to `uint16_t` or `uint32_t` to support longer payloads.
|
|
|
|
The library lets you bind listeners waiting for any frame, a particular frame Type,
|
|
or a specific message ID. This lets you easily implement asynchronous
|
|
communication.
|
|
|
|
## Frame structure
|
|
|
|
```
|
|
,-----+----+-----+------+------------+- - - -+------------,
|
|
| SOF | ID | LEN | TYPE | HEAD_CKSUM | DATA | PLD_CKSUM |
|
|
| 1 | ? | ? | ? | ? | ... | ? | <- size (bytes)
|
|
'-----+----+-----+------+------------+- - - -+------------'
|
|
|
|
SOF ......... start of frame, 0x01
|
|
ID ......... the frame ID (MSb is the peer bit)
|
|
LEN ......... nr of data bytes in the frame
|
|
TYPE ........ message type (used to run Type Listeners, pick any values you like)
|
|
HEAD_CKSUM .. header checksum
|
|
DATA ........ LEN bytes of data
|
|
DATA_CKSUM .. checksum, implemented as XOR of all preceding bytes in the message
|
|
```
|
|
|
|
## Usage Hints
|
|
|
|
- Both peers must include the library with the same parameters (config in the header file)
|
|
- Start by calling `TF_Init()` with MASTER or SLAVE as the argument
|
|
- Implement `TF_WriteImpl()` - declared at the bottom of the header file as `extern`.
|
|
This function is used by `TF_Send()` to write bytes to your UART (or other physical layer).
|
|
Presently, always a full frame is sent to this function.
|
|
- If you wish to use `TF_PARSER_TIMEOUT_TICKS`, periodically call `TF_Tick()`. The period
|
|
determines the length of 1 tick. This is used to time-out the parser in case it gets stuck
|
|
in a bad state (such as receiving a partial frame).
|
|
- Bind Type or Generic listeners using `TF_AddTypeListener()` or `TF_AddGenericListener()`.
|
|
- Send a message using `TF_Send()` or the other Send functions.
|
|
If you provide a listener callback (function pointer) to the function,
|
|
the listener will be added as an ID listener and wait for a response.
|
|
- To reply to a message (when your listener gets called), use `TF_Respond()`
|
|
with the same frame_id as in the received message.
|
|
- Remove the ID listener using `TF_RemoveIdListener()` when it's no longer
|
|
needed. (Same for other listener types.) The slot count is limited.
|
|
- If the listener function returns `false`, some other listener will get
|
|
a chance to handle it
|
|
- Manually reset the parser using `TF_ResetParser()`
|
|
|
|
### The concept of listeners
|
|
|
|
Listeners are callback functions that are called by TinyFrame when a message which
|
|
they can handle is received.
|
|
|
|
There are 3 listener types:
|
|
|
|
- ID listeners
|
|
- Type listeners
|
|
- Generic listeners
|
|
|
|
They handle the message in this order, and if they decide not to handle it, they can return `false`
|
|
and let it be handled by some other listener, or discarded.
|
|
|
|
### Implementing "synchronous query"
|
|
|
|
Sometimes it's necessary to send a message and wait for a response to arrive.
|
|
|
|
One (not too pretty) way to do this is using a global variable - pseudocode:
|
|
|
|
```c
|
|
#define MSG_PING 42
|
|
|
|
static volatile bool got_response = false;
|
|
|
|
/** ID listener */
|
|
static bool onResponse(TF_ID frame_id, TF_TYPE type, const uint8_t *data, TF_LEN len)
|
|
{
|
|
// ... Do something ...
|
|
// (eg. copy data to a global variable)
|
|
|
|
got_response = true;
|
|
return true;
|
|
}
|
|
|
|
bool syncQuery(void)
|
|
{
|
|
TF_ID id;
|
|
// Send our request, and bind an ID listener
|
|
got_response = false;
|
|
TF_Send0(MSG_PING, onResponse, &id); // Send0 sends zero bytes of data, just TYPE
|
|
|
|
// the ID is now in `id` so we can remove the listener after a timeout
|
|
|
|
// Wait for the response
|
|
bool suc = true;
|
|
while (!got_response) {
|
|
//delay()
|
|
if (/*timeout*/) {
|
|
TF_RemoveIdListener(id); // free the listener slot
|
|
return false;
|
|
}
|
|
}
|
|
|
|
// ... Do something with the received data? ...
|
|
// (can be passed from the listener using a global variable)
|
|
|
|
return true;
|
|
}
|
|
```
|
|
|