-
Notifications
You must be signed in to change notification settings - Fork 1
/
protocol.tex
142 lines (107 loc) · 5.85 KB
/
protocol.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
\documentclass[border=10pt,png]{article}
\usepackage{bytefield}
\usepackage{color}
\begin{document}
\section{Introduction}
\textcolor{red}{WARNING! This spec is still in BETA and is subject to change.}
\subsection{Big Ideas}
Each piece of data is assigned an ID
\subsection{General Notes}
All multi-byte words are defined to be in network ordering (RFC 1700, big endian).
\section{Packet Layer}
The packet layer structures data provided by the underlying link layer into an organized packet. Currently, there is only one implementation of this layer.
\subsection{In-band Signaling over UART Serial Terminal}
This provides embedding telemetry data in a UART serial terminal stream. It is assumed that no ASCII control characters will be transmitted on the same stream as they will be used to delimit telemetry data.
While not required by the spec, the telemetry transmitter may preface each telemetry frame with ANSI commands to prevent serial terminals from displaying the telemetry (gibberish) contents. ANSI conceal and invisible may be used.
To prevent terminals from interpreting the telemetry data as ANSI commands, anytime an ANSI escape character (\texttt{0x1b}) appears in the data stream, a null character (\texttt{0x00}) should be added directly afterwards. This should be handled by the packet layer only - the byte will be stuffed at this layer at the transmitter and destuffed at the corresponding layer at the receiver. The data length should not include stuffed bytes.
\begin{bytefield}{32}
\bitheader{0, 15, 16, 31} \\
\bitbox{16}{Start of Frame \\ \tiny{0x05 0x39}}
& \bitbox{16}{Data Length \\ \tiny{(2 bytes, number of bytes in the data)}} \\
\wordbox[lrt]{1}{Data \\ \tiny{payload of bytes equal to length above}} \\
\skippedwords \\
\wordbox[lrb]{1}{} \\
\bitbox{16}{CRC (unimplemented)}
\end{bytefield}
\section{Telemetry Protocol Layer}
Each telemetry packet is structured as follows:
\begin{bytefield}{16}
\bitheader{0, 7, 8, 15} \\
\bitbox{8}{Opcode}
& \bitbox{8}{Sequence \#} \\
\wordbox[lrt]{1}{Payload \\ \tiny{length dependent on payload opcode}} \\
\skippedwords \\
\wordbox[lrb]{1}{}
\end{bytefield}
The sequence number is incremeneted by 1 per transmitted packet (rolling over at the maximum of 255) and should start at zero. This is used to detect network errors like dropped packets. No ARQ protocol is currently specified.
\subsection{Payload format for opcode 0x81: Data Definition}
This is sent to the telemetry client to configure the display. This should be the first telemetry packet sent and must be comprehensive (all data IDs are sent, populated with all immutable fields). After initial configuration, this packet may be transmitted (in either direction) to update mutable fields.
\begin{bytefield}{16}
\bitheader{0, 7, 8, 15} \\
\wordbox[lrt]{1}{Data headers} \\
\skippedwords \\
\wordbox[lrb]{1}{} \\
\bitbox{8}{0x00 \\ \tiny{terminator ``record''}} \\
\end{bytefield}
Each data header is defined as:
\begin{bytefield}{16}
\bitheader{0, 7, 8, 15} \\
\bitbox{8}{Data ID}
\bitbox{8}{Data type} \\
\wordbox[lrt]{1}{KV records} \\
\skippedwords \\
\wordbox[lrb]{1}{} \\
\bitbox{8}{0x00 \\ \tiny{terminator ``record''}} \\
\end{bytefield}
Data IDs may not exceed 127 (allowing varints to be used in future implementations, as necessary). The Data ID of 0 is reserved as a terminator.
Each KV record is defined as:
\begin{bytefield}{16}
\bitheader{0, 7, 8, 15} \\
\bitbox{8}{Record ID} \\
\wordbox[lrt]{1}{Record value} \\
\skippedwords \\
\wordbox[lrb]{1}{} \\
\end{bytefield}
Record IDs may not exceed 127 (allowing varints to be used in future implementations, as necessary). The Record ID of 0 is reserved as a terminator. \\
Record ID meanings are different for each data type. The length and format of the record value is dependent on the record meaning. \\
Record IDs 1-63 (0x01-0x3f) are reserved for common global records definitions. IDs from 64 onwards are free to be defined per data type.
\subsubsection{Global Records IDs}
Record values are immutable (can't be updated after the initial header is sent), unless otherwise noted.
0x00: reserved (terminator) \\
0x01: internal name, as a null-terminated string, default to data ID \\
0x02: display (user-friendly) name, as a null-terminated string, default to internal name \\
0x03: units, as a null-terminated string, default "" \\
0x08: freeze on/off, one byte as a boolean flag (nonzero is TRUE), if TRUE prevents the value from being updated on the client, default is 0, mutable \\
\subsection{Data format for opcode 0x01: Data}
Data is usually sent from server to the client. However, a packet from the client to the server means to set the corresponding data object.
\begin{bytefield}{16}
\bitheader{0, 7, 8, 15} \\
\wordbox[lrt]{1}{Data records} \\
\skippedwords \\
\wordbox[lrb]{1}{} \\
\bitbox{8}{0x00 \\ \tiny{terminator ``record''}} \\
\end{bytefield}
Each data record is defined as:
\begin{bytefield}{16}
\bitheader{0, 7, 8, 15} \\
\bitbox{8}{Data ID} \\
\wordbox[lrt]{1}{Data value} \\
\skippedwords \\
\wordbox[lrb]{1}{} \\
\end{bytefield}
The data value length and format is dependent on the data type, which is defined by the data ID in the header.
\section{Data Types}
\subsection{Numeric: Data type 1}
\subsubsection{KV Records}
Record ID 0x40, uint8: data sub-type: 0x01 indicates unsigned integer, 0x02 indicates signed integer, 0x03 indicates floating-point \\
Record ID 0x41, uint8: data length (in bytes) \\
Record ID 0x42, uint8: range limits (in data type, obviously must be transmitted after sub-type and length) \\
\subsubsection{Data format}
Raw data in network order.
\subsection{Numeric Array: Data type 2}
\subsubsection{KV Records}
This includes all the records in the numeric type (for element type), along with: \\
Record ID 0x50, uint32: array count (in number of elements)
\subsubsection{Data format}
Raw data in network order.
\end{document}