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 typestruct rt_link_service*
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 typestruct rt_link_service*
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