RT-Link
RT-Link is an open link layer transmission protocol. It is designed to achieve stable, secure and efficient point-to-point data transmission between devices, and has a simple interface and is easy to use.
Directory structure:
Features:
Stability : RT-Link has a series of capabilities such as data retransmission, frame sequence number check, and state synchronization to ensure stable transmission;
Security : Supports CRC verification and uses Ethernet verification protocol;
Efficient : The protocol header is very concise, only 4 bytes, and every bit has practical significance;
Open : It has a unified operation API and supports multiple underlying hardware interfaces, such as UART, SPI, and USB.
Easy to use : The API is simple and can easily integrate RT-Link into existing applications, with good portability and compatibility.
The overall framework of RT-Link is as follows:
The top layer is the service layer , which supports multiple services running on one device at the same time, and the bottom layer uses the same data communication port;
The second layer is the rt-link transport layer , which implements the core functions of rt-link and is used to ensure the reliability and stability of data transmission functions;
The third layer is the rt-link_hw port docking layer , which is used to connect to the underlying data transmission port;
The lowest layer is the transmission port layer of the device , which is the communication port that actually transmits data, such as UART, SPI, Network, etc.
There can be multiple services in rt-link. For upper layer applications, each service represents a transmission channel, and there can be no association between services. Each service has an independent structure object. For ease of understanding, only the service structure object and related parameter definitions are listed here. Other contents can be rt-link.h
viewed in the header file. The relevant attributes are as follows:
timeout_tx blocking/non-blocking send
rt-link provides two data transmission modes: blocking transmission and non-blocking transmission . timeout_tx can be configured using RT_WAITING_FOREVER
(blocking) or (non-blocking) during initialization .RT_WAITING_NO
In blocking mode, if you need to configure a certain timeout, you can also configure a specific timeout for timeout_tx. The unit of this value is tick (system clock). In order to prevent a service from occupying the data transmission channel for a long time, there will be a maximum timeout in rt-link. Therefore, in blocking transmission mode, the smaller timeout will be used as the final transmission timeout.
send_cb data sending callback
In non-blocking mode, send_cb will send a callback notification after the sending is completed, regardless of whether the sending result is "successful" or "failed". The specific sending result can be viewed in the err error code in the structure object.
It should be noted that after calling the send interface in non-blocking mode , the data address space to be sent will be temporarily used by rt-link. The service application should not release or modify the data in this space until it receives the notification from send_cb and then operates the data address space.
recv_cb data receiving callback
The service receives data by registering a callback. The data space for receiving data is dynamically requested by rt-link. The service application gets the data space address and size in the callback interface. The subsequent use and release of this space needs to be managed by the service application .
flag Transmission quality flag
In rt-link, you can configure the data transmission quality of the service channel. There are two main configurable items: RT_LINK_FLAG_ACK
and RT_LINK_FLAG_CRC
.
When the ACK function is enabled, the data sent by the service channel will have an ACK response to confirm that the other end has successfully received it, and the retransmission function will also be enabled .
If you disable the ACK function, the ACK response and timeout retransmission functions will also be disabled. Enabling or disabling only affects this service channel.
When the CRC function is enabled, the sender will calculate the CRC before sending data and fill it at the end of a data frame. After receiving the data, the receiver will calculate and verify the other parts except CRC.
Disabling the ACK and CRC functions can improve transmission efficiency to a certain extent, but the corresponding data transmission quality needs to be guaranteed by the actual data transmission channel.
service type flag
Each service object has an independent service channel identifier, and the service type is defined in rt_link_service_e
. During initialization, you need to rt_link_service_e
select a type from and configure it to the service structure object.
state Connection status
state marks the connection status of the service channel, which is divided into the following three connection states:
type | significance | illustrate |
RT_LINK_INIT | initialization | The status of the service when it is initialized |
RT_LINK_DISCONN | Disconnection | The peer's detached state indicates that the peer's service is offline. |
RT_LINK_CONNECT | Connection successful | The status after the peer is attached, indicating that the peer service is online |
err error code
In the service structure object, err marks the error type of the last operation. In the current version, it mainly refers to errors that occur during data transmission. The meanings of the error codes used are as follows:
type | illustrate |
RT_LINK_EOK | success |
RT_LINK_ERR | Common error, usually due to interface parameter problems |
RT_LINK_ETIMEOUT | Data sending timeout |
RT_LINK_ENOMEM | Insufficient memory, the sent data is too long or the memory space is insufficient |
RT_LINK_EIO | The underlying IO error, the underlying port sending failed |
Here we take studio as an example, find Components -> Tools -> RT-Link on the configuration page, select Enable and configure, as shown below.
Configure the CRC calculation method. The software CRC function is already included in RT-Link. The hardware CRC needs to be connected to the relevant interface according to different platforms.
Save the settings and you can add RT-Link to the current project. The DEBUG option can be enabled according to debugging needs and is disabled by default.
Find the rt-link_hw software package in the software package , software package -> iot -> rt-link_hw. For a detailed introduction to the software package, see README;
UART is selected here, and you need to configure the device name and the hardware interface used. If you need to add other ports, you can view the introduction of the underlying link docking interface ;
One more thing, don't forget to open the hardware interface you want to use, here I use UART2;
The upper-layer application interface list is shown below, and these interfaces will be introduced in the subsections.
The default is automatic initialization. You can decide whether to enable automatic initialization based on the specific application. If you need to disable automatic initialization, you can rtlink.h
comment out the macro definition inRT_LINK_AUTO_INIT
Return Value | describe |
RT_EOK | Initialization successful |
-RT_ENOMEM | Insufficient memory, space application failed |
-RT_ERROR | Initialization failed |
When RT-Link is not needed, you can execute rt_link_deinit()
to release system resources.
Return Value | describe |
RT_EOK | Deinitialization successful |
parameter | describe |
service | The service object to be registered, parameter type |
Return Value | -- |
RT_EOK | Successful registration |
-RT_EINVAL | Parameter error |
struct rt_link_service
The meaning of each member variable in the structure has been explained in the [Introduction to the service concept](#Introduction to the service concept) section .
Example:
parameter | describe |
service | The service object to be removed, parameter type |
Return Value | -- |
RT_EOK | Removed successfully |
-RT_EINVAL | Parameter error |
parameter | describe |
service | service structure object |
data | Data sent |
size | The length of the data |
Return Value | -- |
0 | Send failed |
size | The length of the data sent |
The underlying link docking interface is defined in rtlink_port.h
and needs to be implemented when docking the underlying transmission port.
It is mainly used to initialize the resources of the underlying port. It will be called when RT-Link is initialized and deinitialized. This part needs to be implemented by yourself during porting. For UART, SPI, etc., the relevant interfaces provided by the device framework can be used in RT-Thread.
This function will be called by the core logic of RT-Link to send data through the actual underlying port. For simple interfaces such as UART , data can be sent directly without affecting the operation of the system. For more complex communication interfaces such as SPI, USB , etc., the sending logic can be implemented through mechanisms such as events and mailboxes.
parameter | describe |
data | Data sent |
length | The length of the data |
Return Value | -- |
0 | Send failed |
length | The length of the data sent |
The function of the reconnection interface is that when rt_link_port_send() fails to send, rt-link will call this interface to try to reconnect the underlying link, and call rt_link_port_send() again to try to send data. For example, if the underlying data link uses a TCP network, if the TCP connection is abnormally disconnected, TCP reconnection can be performed in this interface.
When the underlying interface receives data, this function can be directly called to send data to RT-Link and provide the received data to the upper layer service. This function can be directly called in an interrupt.
parameter | describe |
data | Data written |
length | The length of the data |
Return Value | -- |
0 | Write failed |
> 0 | The actual length of the data written |
Last updated