资料介绍
软件简介
TinyFrame
TinyFrame is a simple library for building and parsing data frames to be sent over a serial interface (e.g. UART, telnet, socket). The code is written to build with --std=gnu99
and mostly compatible with --std=gnu89
.
The library provides a high level interface for passing messages between the two peers. Multi-message sessions, response listeners, checksums, timeouts are all handled by the library.
TinyFrame is suitable for a wide range of applications, including inter-microcontroller communication, as a protocol for FTDI-based PC applications or for messaging through UDP packets.
The library lets you register listeners (callback functions) to wait for (1) any frame, (2) a particular frame Type, or (3) a specific message ID. This high-level API is general enough to implement most communication patterns.
TinyFrame is re-entrant and supports creating multiple instances with the limitation that their structure (field sizes and checksum type) is the same. There is a support for adding multi-threaded access to a shared instance using a mutex.
TinyFrame also comes with (optional) helper functions for building and parsing message payloads, those are provided in the utils/
folder.
Ports
TinyFrame has been ported to mutiple languages:
- The reference C implementation is in this repo
- Python port - MightyPork/PonyFrame
- Rust port - cpsdqs/tinyframe-rs
- JavaScript port - cpsdqs/tinyframe-js
Please note most of the ports are experimental and may exhibit various bugs or missing features. Testers are welcome :)
Functional overview
The basic functionality of TinyFrame is explained here. For particlars, such as the API functions, it's recommended to read the doc comments in the header file.
Structure of a frame
Each frame consists of a header and a payload. Both parts can be protected by a checksum, ensuring a frame with a malformed header (e.g. with a corrupted length field) or a corrupted payload is rejected.
The frame header contains a frame ID and a message type. Frame ID is incremented with each new message. The highest bit of the ID field is fixed to 1 and 0 for the two peers, avoiding a conflict.
Frame ID can be re-used in a response to tie the two messages together. Values of the type field are user defined.
All fields in the frame have a configurable size. By changing a field in the config file, such as TF_LEN_BYTES
(1, 2 or 4), the library seamlessly switches between uint8_t
, uint16_t
and uint32_t
for all functions working with the field.
,-----+-----+-----+------+------------+- - - -+-------------,
| SOF | ID | LEN | TYPE | HEAD_CKSUM | DATA | DATA_CKSUM |
| 0-1 | 1-4 | 1-4 | 1-4 | 0-4 | ... | 0-4 | <- size (bytes)
'-----+-----+-----+------+------------+- - - -+-------------'
SOF ......... start of frame, usually 0x01 (optional, configurable)
ID ......... the frame ID (MSb is the peer bit)
LEN ......... number 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 .. data checksum (left out if LEN is 0)
Message listeners
TinyFrame is based on the concept of message listeners. A listener is a callback function waiting for a particular message Type or ID to be received.
There are 3 listener types, in the order of precedence:
- ID listeners - waiting for a response
- Type listeners - waiting for a message of the given Type field
- Generic listeners - fallback
ID listeners can be registered automatically when sending a message. All listeners can also be registered and removed manually.
ID listeners are used to receive the response to a request. When registerign an ID listener, it's possible to attach custom user data to it that will be made available to the listener callback. This data (void *
) can be any kind of application context variable.
ID listeners can be assigned a timeout. When a listener expires, before it's removed, the callback is fired with NULL payload data in order to let the user free()
any attached userdata. This happens only if the userdata is not NULL.
Listener callbacks return values of the TF_Result
enum:
-
TF_CLOSE
- message accepted, remove the listener -
TF_STAY
- message accepted, stay registered -
TF_RENEW
- sameasTF_STAY
, but the ID listener's timeout is renewed -
TF_NEXT
- message NOT accepted, keep the listener and pass the message to the next listener capable of handling it.
Data buffers, multi-part frames
TinyFrame uses two data buffers: a small transmit buffer and a larger receive buffer. The transmit buffer is used to prepare bytes to send, either all at once, or in a circular fashion if the buffer is not large enough. The buffer must only contain the entire frame header, so e.g. 32 bytes should be sufficient for short messages.
Using the *_Multipart()
sending functions, it's further possible to split the frame header and payload to multiple function calls, allowing the applciation to e.g. generate the payload on-the-fly.
In contrast to the transmit buffer, the receive buffer must be large enough to contain an entire frame. This is because the final checksum must be verified before the frame is handled.
If frames larger than the possible receive buffer size are required (e.g. in embedded systems with small RAM), it's recommended to implement a multi-message transport mechanism at a higher level and send the data in chunks.
Usage Hints
-
All TinyFrame functions, typedefs and macros start with the
TF_
prefix. - Both peers must include the library with the same config parameters
-
See
TF_Integration.example.c
andTF_Config.example.c
for reference how to configure and integrate the library. - DO NOT modify the library files, if possible. This makes it easy to upgrade.
-
Start by calling
TF_Init()
withTF_MASTER
orTF_SLAVE
as the argument. This creates a handle. UseTF_InitStatic()
to avoid the use of malloc(). -
If multiple instances are used, you can tag them using the
tf.userdata
/tf.usertag
field. -
Implement
TF_WriteImpl()
- declared at the bottom of the header file asextern
. This function is used byTF_Send()
and others to write bytes to your UART (or other physical layer). A frame can be sent in it's entirety, or in multiple parts, depending on its size. - Use TF_AcceptChar(tf, byte) to give read data to TF. TF_Accept(tf, bytes, count) will accept mulitple bytes.
-
If you wish to use timeouts, periodically call
TF_Tick()
. The calling 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) and can also time-out ID listeners. -
Bind Type or Generic listeners using
TF_AddTypeListener()
orTF_AddGenericListener()
. -
Send a message using
TF_Send()
,TF_Query()
,TF_SendSimple()
,TF_QuerySimple()
. Query functions take a listener callback (function pointer) that will be added as an ID listener and wait for a response. -
Use the
*_Multipart()
variant of the above sending functions for payloads generated in multiple function calls. The payload is sent afterwards by callingTF_Multipart_Payload()
and the frame is closed byTF_Multipart_Close()
. -
If custom checksum implementation is needed, select
TF_CKSUM_CUSTOM8
, 16 or 32 and implement the three checksum functions. -
To reply to a message (when your listener gets called), use
TF_Respond()
with the msg object you received, replacing thedata
pointer (andlen
) with a response. -
At any time you can manually reset the message parser using
TF_ResetParser()
. It can also be reset automatically after a timeout configured in the config file.
Gotchas to look out for
-
If any userdata is attached to an ID listener with a timeout, when the listener times out, it will be called with NULL
msg->data
to let the user free the userdata. Therefore it's needed to checkmsg->data
before proceeding to handle the message. - If a multi-part frame is being sent, the Tx part of the library is locked to prevent concurrent access. The frame must be fully sent and closed before attempting to send anything else.
-
If multiple threads are used, don't forget to implement the mutex callbacks to avoid concurrent access to the Tx functions. The default implementation is not entirely thread safe, as it can't rely on platform-specific resources like mutexes or atomic access. Set
TF_USE_MUTEX
to1
in the config file.
Examples
You'll find various examples in the demo/
folder. Each example has it's own Makefile, read it to see what options are available.
The demos are written for Linux, some using sockets and clone()
for background processing. They try to simulate real TinyFrame behavior in an embedded system with asynchronous Rx and Tx. If you can't run the demos, the source files are still good as examples.
- 简单实用短路分析方法 12次下载
- 短路分析最简单的方法 6次下载
- 最简单的pcb软件 5次下载
- 简单实用的pcb软件 0次下载
- 最简单的pcb设计软件 11次下载
- 简单pcb设计实例 15次下载
- 简单分析PCB孔无铜以及改善方法资料下载 11次下载
- 简单线路亦好声:一部功放的改制 16次下载
- 选择最简单易用的HyperLynx进行串扰仿真资料下载 19次下载
- 简单的二极管基准电压源电路 65次下载
- 基于C语言的LED呼吸灯简单源代码 16次下载
- python实现简单爬虫的资料说明 21次下载
- 单片机MQTT如何实现推送的简单使用 9次下载
- 简单的USB转RS232线驱动安装入口 16次下载
- 最简单的触摸屏接线方法 57次下载
- 简单认识变压器 273次阅读
- QT串口通信的简单使用 403次阅读
- 简单认识无源器件 207次阅读
- 一个简单的高压表电路分享 901次阅读
- Django的简单应用示例 706次阅读
- 一个简单的多音报警电路图分享 4007次阅读
- 测试IGBT的简单方法 1.3w次阅读
- 简单逆变器电路图 2.5w次阅读
- 四款简单光控灯电路图 8.2w次阅读
- 两例简单的电平转换电路分享 2.2w次阅读
- 最简单IO驱动的智慧 2248次阅读
- 简单PLD有哪些? 6588次阅读
- 简单时钟电路图 1.1w次阅读
- 简单的断开报警电路图 4223次阅读
- 简单的温度控制器电路 5182次阅读
下载排行
本周
- 1山景DSP芯片AP8248A2数据手册
- 1.06 MB | 532次下载 | 免费
- 2RK3399完整板原理图(支持平板,盒子VR)
- 3.28 MB | 339次下载 | 免费
- 3TC358743XBG评估板参考手册
- 1.36 MB | 330次下载 | 免费
- 4DFM软件使用教程
- 0.84 MB | 295次下载 | 免费
- 5元宇宙深度解析—未来的未来-风口还是泡沫
- 6.40 MB | 227次下载 | 免费
- 6迪文DGUS开发指南
- 31.67 MB | 194次下载 | 免费
- 7元宇宙底层硬件系列报告
- 13.42 MB | 182次下载 | 免费
- 8FP5207XR-G1中文应用手册
- 1.09 MB | 178次下载 | 免费
本月
- 1OrCAD10.5下载OrCAD10.5中文版软件
- 0.00 MB | 234315次下载 | 免费
- 2555集成电路应用800例(新编版)
- 0.00 MB | 33566次下载 | 免费
- 3接口电路图大全
- 未知 | 30323次下载 | 免费
- 4开关电源设计实例指南
- 未知 | 21549次下载 | 免费
- 5电气工程师手册免费下载(新编第二版pdf电子书)
- 0.00 MB | 15349次下载 | 免费
- 6数字电路基础pdf(下载)
- 未知 | 13750次下载 | 免费
- 7电子制作实例集锦 下载
- 未知 | 8113次下载 | 免费
- 8《LED驱动电路设计》 温德尔著
- 0.00 MB | 6656次下载 | 免费
总榜
- 1matlab软件下载入口
- 未知 | 935054次下载 | 免费
- 2protel99se软件下载(可英文版转中文版)
- 78.1 MB | 537798次下载 | 免费
- 3MATLAB 7.1 下载 (含软件介绍)
- 未知 | 420027次下载 | 免费
- 4OrCAD10.5下载OrCAD10.5中文版软件
- 0.00 MB | 234315次下载 | 免费
- 5Altium DXP2002下载入口
- 未知 | 233046次下载 | 免费
- 6电路仿真软件multisim 10.0免费下载
- 340992 | 191187次下载 | 免费
- 7十天学会AVR单片机与C语言视频教程 下载
- 158M | 183279次下载 | 免费
- 8proe5.0野火版下载(中文版免费下载)
- 未知 | 138040次下载 | 免费
评论
查看更多