You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This page describes `rtxlink`: a communication protocol implemented by
4
-
OpenRTX and used to accomplish the following functions:
3
+
This page describes `rtxlink`, the communication protocol used by the OpenRTX firmware to accomplish the following functions:
5
4
6
-
- Get radio info
7
-
- Reboot radio
8
-
- Full flash backup/restore
9
-
- Download file
10
-
- Upload file
11
-
- Set RTX params
5
+
- Retrieval of radio info
6
+
- Reboot of the device
7
+
- Backup and restore of the nonvolatile memory
8
+
- File download and upload
9
+
- Change of some RTX parameters
12
10
13
-
Additionally, the protocol has the following characteristics:
11
+
## Physical Layer
14
12
15
-
- SLIP is used for framing and encloses the whole protocol
16
-
- The protocol is Byte-oriented
17
-
- protocol is composed of getters and setters
18
-
- variables to get and set are encoded into opcodes
19
-
- plain ymodem is used for file transfer
20
-
21
-
The protocol stack is as follows:
22
-
23
-
| Application | CAT, FMP, XMODEM |
24
-
|:-----------:|:-----------------:|
25
-
| Framing | SLIP |
26
-
| Physical | UART, VCOM |
27
-
28
-
## Physical Layer - UART, VCOM
29
-
30
-
This protocol is designed to be executed on a serial link, which depending on the platform support might be a physical (UART) link or a Virtual COM over USB. Buffering is tolerated by the protocol. The baud rate is 115200.
13
+
The physical layer of the rtxlink protocol is a serial communication, which may either be based on a physical link (UART) or a Virtual COM over USB.
14
+
In case a physical link is used, its configuration is 8 data bits, no parity and either EIA hardware flow control, or CLOCAL mode (3-wire null-modem).
15
+
The default baud rate is 115200 bit per second but the change to a different datarate can be requested by the client device. The support for datarates
16
+
other than the default one is not mandatory, although an rtxlink host must support at least 115200 bit per second. The protocol tolerates buffering and
17
+
fragmentation of the transmitted data.
31
18
32
19
## Data Link Layer
33
20
34
-
The data link layer of RTXLink is composed of frames with a variable length encoded using the SLIP protocol. Each SLIP frame must begin with an END character; incoming frames not beginning with and END character are accepted anyway, even if not strictly conformant to the specification.
35
-
36
-
### SLIP framing
37
-
38
-
The framing is performed using the [Serial Line Internet Protocol (SLIP)](https://en.wikipedia.org/wiki/Serial_Line_Internet_Protocol).
39
-
The following are the standard value Bytes employed by the SLIP protocol.
40
-
41
-
| Hex value | Dec Value | Oct Value | Abbreviation | Description |
- Appending a special "END" Byte to it, to distinguish datagram boundaries in the Byte stream,
51
-
- If the END Byte occurs in the data to be sent, the two Byte sequence ESC, ESC_END is sent instead,
52
-
- If the ESC Byte occurs in the data, the two Byte sequence ESC, ESC_ESC is sent.
53
-
- Variants of the protocol may begin, as well as end, packets with END.
54
-
55
-
SLIP requires a serial port configuration of 8 data bits, no parity, and either EIA hardware flow control, or CLOCAL mode (3-wire null-modem) UART operation settings.
56
-
57
-
SLIP can extend the frame length up to the double of the original length, this needs to be taken into account when sizing buffers during the protocol implementation.
21
+
The data link layer of the rtxlink protocol consists of variable-length frames encoded using the [Serial Line Internet Protocol (SLIP)](https://en.wikipedia.org/wiki/Serial_Line_Internet_Protocol).
22
+
Each SLIP frame must begin with an END character: incoming frames not beginning with and END character are accepted anyway, even if not strictly conformant to the specification. SLIP can extend
23
+
the frame length up to the double of the original length, this needs to be taken into account when sizing buffers during the protocol implementation.
58
24
59
-
### Frame format
25
+
The frames format is the following:
60
26
61
27
| 0 | 1 | ... | N-1 | N |
62
28
|:---:|:-------:|:----:|:----:|:---:|
63
29
| END | ProtoID | Data | CRC8 | END |
64
30
65
-
Following the leading END marker, the first byte of each frame is a protocol identifier describing the frame content, while the last byte of the frame contains the CRC-8 of the protocol ID and data fields. The polynomial used for the CRC is 0xA6, ensuring a minimum hamming distance of 2 for data blocks composed by more than 2048 bytes.
31
+
After the star of frame marker, the first byte of each frame is a protocol identifier describing the frame content. The last byte of the frame, following the content and preceding the frame end
32
+
marker contains the CRC-8 of the protocol identifier and data fields. The CRC is computed using the polynomial 0xA6 and ensures a minimum hamming distance of two for data blocks composed by more
33
+
than 2048 bytes.
66
34
67
35
The recognized protocol IDs are the following:
68
36
@@ -75,61 +43,54 @@ The recognized protocol IDs are the following:
75
43
76
44
## Application Layer
77
45
78
-
The application layer is composed of two different protocols: a Computer Aided Transceiver (CAT) protocol to control the operation of the radio and a File Management Protocol (FMP) to request file transfers and memory backup and restore. The actual transfer of files and backup images is performed using the XMODEM protocol.
46
+
The application layer of rtxlink consists of two command different protocols: the Computer Aided Transceiver (CAT) protocol and the File Management Protocol (FMP).
79
47
80
48
### Computer Aided Transceiver (CAT)
81
49
82
-
Byte encodings are little-endian.
83
-
84
-
CAT commands are Byte-aligned and encoded in key-value pairs to achieve both simplicity of the protocol and ease of parsing.
85
-
86
-
The CAT command identifies resources through 2 Byte IDs, and allows the host (main agent of the transmission) to get values associated with each ID or set a new value to a corresponding ID.
87
-
88
-
The first byte of a CAT command and response packet is the packet OpCode.
50
+
The CAT protocol is based on a request/response command structure. Commands are byte-aligned and encoded in key-value pairs to achieve both simplicity of the protocol and ease of parsing. All the
51
+
commands and their arguments are encoded in little-endian format. The first byte of each CAT command or response packet is the packet opcode.
89
52
90
53
#### Get Requests
91
54
92
-
A get request asks the secondary entity on the RTXLink bus for a value associated with a specific ID. The request is composed by 3 bytes: the first byte is the command OpCode, followed by two symbol identifier bytes.
55
+
A get request is used by the rtxlink client to request the value of given entity. The command frame has a fixed length of three bytes, with the opcode set to 0x47 (ASCII character 'D'). Following
56
+
the opcode there are two bytes containing the resource ID. In response to a get request the host sends either a data response frame or, in case of failures, an ack frame reporting an error code.
93
57
94
58
| 0 | 1 | 2 |
95
59
|:---:|:--:|:--:|
96
60
| CMD | ID | ID |
97
61
98
-
In response to a get request the radio sends either a data response packet or, in case of failures, an ack packet with the ERROR flag set 1.
99
-
100
62
#### Set Requests
101
63
102
-
Set requests allow to change a specific value associated with a certain ID.
103
-
Set requests are composed by one command byte, 2 Bytes of symbol ID and N bytes of data.
64
+
A set request is used by the rtxlink client to change the value of an entity. The command frame has a variable length with a minimum size of four bytes and the opcode is 0x53 (ASCII character 'S').
65
+
Following the opcode there are two bytes containing the resource ID and N bytes of data. In response to a set request the host sends an ack frame with a status code.
104
66
105
67
| 0 | 1 | 2 | 3 | ... | N |
106
68
|:---:|:--:|:--:|:-:|:---:|:-:|
107
69
| CMD | ID | ID | V | ... | V |
108
70
109
-
The radio replies to a set request with an ack response packet with either the OK or ERROR flag set.
110
-
111
71
#### Peek Requests
112
72
113
-
Peek requests allow to read the content of a the radio internal memory at a given address. Peek requests are composed by one command byte, one byte of data length and four bytes of address.
73
+
A peek request allow the client to read the content of the host internal memory at a given address. The command frame has a fixed length of six bytes, with the opcode set to 0x50 (ASCII character 'P').
74
+
After the command opcode, there is one byte of data length and four bytes of address. The host replies to a peek request with a data response packet or, in case of failures, an ack frame reporting an
75
+
error code.
114
76
115
77
| 0 | 1 | 2 | 3 | 4 | 5 |
116
78
|:---:|:---:|:----:|:----:|:----:|:----:|
117
79
| CMD | LEN | ADDR | ADDR | ADDR | ADDR |
118
80
119
-
The radio replies to a peek request with a data response packet or, in case of errors, with an ack response packet with the ERROR flag set.
120
-
121
81
#### Data response
122
82
123
-
A data response packet starts with a response type byte set to 0x44 (ASCII character 'D') followed by N bytes of data.
83
+
A data response frame has the opcode set to 0x44 (ASCII character 'D') followed by N bytes of data. Data response frames are sent in reply to get or peek requests.
124
84
125
85
| 0 | 1 | ... | N |
126
86
|:----:|:-:|:---:|:-:|
127
87
| 0x44 | V | ... | V |
128
88
129
89
#### ACK response
130
90
131
-
An ack response packet is constituted of two bytes: the first byte (response type) is always set to 0x41 (ASCII character 'A') while the second one carries a status code. A status code equal to zero means that the previous command has been successfully executed. In case of an error the status code field contains a POSIX error code describing the fault or 0xFF to signal a generic, unspecified error.
132
-
The absolute minimum requirement is to have the status field set either to 0x00 or 0xFF.
91
+
An ack response frame has a fixed length of two bytes: the first byte (opcode) is always set to 0x41 (ASCII character 'A'), the second one carries a status code. A status code zero means that the previous
92
+
command has been successfully executed. Othewise, in case an error occurred, the status code field contains a POSIX error code describing the fault or 0xFF to signal a generic, unspecified error. The host
93
+
must at least use the values 0x00 and 0xFF for the status field.
133
94
134
95
| 0 | 1 |
135
96
|:----:|:------:|
@@ -140,31 +101,48 @@ The absolute minimum requirement is to have the status field set either to 0x00
| Request | Get | 0x47 'G' | ID | 3 | Gets the N Byte word corresponding to the specified ID. |
143
-
| Response | Data | 0x44 'D' | Value | Variable | The N Byte word which was requested. |
104
+
| Response | Data | 0x44 'D' | Value | Variable | The N Byte word which was requested. |
144
105
| Request | Set | 0x53 'S' | ID, Value | Variable | Sets a N Byte word to the specified ID. |
145
-
| Response | Ack | 0x41 'A' | Status | 1 | Status of the previous Set command, success or error. |
106
+
| Response | Ack | 0x41 'A' | Status | 1 | Status of the previous Set command, success or error. |
146
107
| Request | Peek | 0x50 'P' | Address | 5 | Gets the 32bit word corresponding to the specified 32-bit address. |
147
-
| Response | Data | 0x44 'D' | Value | 5 | The 32bit word which was requested. |
108
+
| Response | Data | 0x44 'D' | Value | 5 | The 32bit word which was requested. |
148
109
149
-
#### Identifiers
110
+
#### Get/set resource IDs
150
111
151
-
OpenRTX CAT uses symbolic values to identify controllable features of the radio, the tables below summarizes the features and the respective sizes, semantics and permissions.
112
+
The tables below summarizes the CAT resource identifiers with their respective size, semantic and permissions.
152
113
153
114
| Permissions | Symbol |
154
115
|:---------------|:-------|
155
116
| Read Only | R |
156
-
| Read and Write | RW |
157
-
| Write Only | W |
117
+
| Read and Write | RW |
118
+
| Write Only | W |
158
119
159
120
| Symbol | ID | Type (Length) | Permissions | Description |
0 commit comments