Cheryl He / telemetry-master

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

telemetry-master/docs/protocol.tex@0:fc22cf8cc478, 2015-05-05 (annotated)

Committer:
cheryl_he
Date:
Tue May 05 00:43:17 2015 +0000
Revision:
0:fc22cf8cc478
telemetry setup

Who changed what in which revision?

UserRevisionLine numberNew contents of line
cheryl_he 0:fc22cf8cc478 1 \documentclass[border=10pt,png]{article}
cheryl_he 0:fc22cf8cc478 2 \usepackage{bytefield}
cheryl_he 0:fc22cf8cc478 3 \usepackage{color}
cheryl_he 0:fc22cf8cc478 4
cheryl_he 0:fc22cf8cc478 5 \begin{document}
cheryl_he 0:fc22cf8cc478 6
cheryl_he 0:fc22cf8cc478 7 \section{Introduction}
cheryl_he 0:fc22cf8cc478 8
cheryl_he 0:fc22cf8cc478 9 \textcolor{red}{WARNING! This spec is still in BETA and is subject to change.}
cheryl_he 0:fc22cf8cc478 10
cheryl_he 0:fc22cf8cc478 11
cheryl_he 0:fc22cf8cc478 12 \subsection{Big Ideas}
cheryl_he 0:fc22cf8cc478 13 Each piece of data is assigned an ID
cheryl_he 0:fc22cf8cc478 14
cheryl_he 0:fc22cf8cc478 15 \subsection{General Notes}
cheryl_he 0:fc22cf8cc478 16 All multi-byte words are defined to be in network ordering (RFC 1700, big endian).
cheryl_he 0:fc22cf8cc478 17
cheryl_he 0:fc22cf8cc478 18 \section{Packet Layer}
cheryl_he 0:fc22cf8cc478 19 The packet layer structures data provided by the underlying link layer into an organized packet. Currently, there is only one implementation of this layer.
cheryl_he 0:fc22cf8cc478 20
cheryl_he 0:fc22cf8cc478 21 \subsection{In-band Signaling over UART Serial Terminal}
cheryl_he 0:fc22cf8cc478 22 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.
cheryl_he 0:fc22cf8cc478 23
cheryl_he 0:fc22cf8cc478 24 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.
cheryl_he 0:fc22cf8cc478 25
cheryl_he 0:fc22cf8cc478 26 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.
cheryl_he 0:fc22cf8cc478 27
cheryl_he 0:fc22cf8cc478 28 \begin{bytefield}{32}
cheryl_he 0:fc22cf8cc478 29 \bitheader{0, 15, 16, 31} \\
cheryl_he 0:fc22cf8cc478 30 \bitbox{16}{Start of Frame \\ \tiny{0x05 0x39}}
cheryl_he 0:fc22cf8cc478 31 & \bitbox{16}{Data Length \\ \tiny{(2 bytes, number of bytes in the data)}} \\
cheryl_he 0:fc22cf8cc478 32 \wordbox[lrt]{1}{Data \\ \tiny{payload of bytes equal to length above}} \\
cheryl_he 0:fc22cf8cc478 33 \skippedwords \\
cheryl_he 0:fc22cf8cc478 34 \wordbox[lrb]{1}{} \\
cheryl_he 0:fc22cf8cc478 35 \bitbox{16}{CRC (unimplemented)}
cheryl_he 0:fc22cf8cc478 36 \end{bytefield}
cheryl_he 0:fc22cf8cc478 37
cheryl_he 0:fc22cf8cc478 38 \section{Telemetry Protocol Layer}
cheryl_he 0:fc22cf8cc478 39
cheryl_he 0:fc22cf8cc478 40 Each telemetry packet is structured as follows:
cheryl_he 0:fc22cf8cc478 41
cheryl_he 0:fc22cf8cc478 42 \begin{bytefield}{16}
cheryl_he 0:fc22cf8cc478 43 \bitheader{0, 7, 8, 15} \\
cheryl_he 0:fc22cf8cc478 44 \bitbox{8}{Opcode}
cheryl_he 0:fc22cf8cc478 45 & \bitbox{8}{Sequence \#} \\
cheryl_he 0:fc22cf8cc478 46 \wordbox[lrt]{1}{Payload \\ \tiny{length dependent on payload opcode}} \\
cheryl_he 0:fc22cf8cc478 47 \skippedwords \\
cheryl_he 0:fc22cf8cc478 48 \wordbox[lrb]{1}{}
cheryl_he 0:fc22cf8cc478 49 \end{bytefield}
cheryl_he 0:fc22cf8cc478 50
cheryl_he 0:fc22cf8cc478 51 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.
cheryl_he 0:fc22cf8cc478 52
cheryl_he 0:fc22cf8cc478 53 \subsection{Payload format for opcode 0x81: Data Definition}
cheryl_he 0:fc22cf8cc478 54 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.
cheryl_he 0:fc22cf8cc478 55
cheryl_he 0:fc22cf8cc478 56 \begin{bytefield}{16}
cheryl_he 0:fc22cf8cc478 57 \bitheader{0, 7, 8, 15} \\
cheryl_he 0:fc22cf8cc478 58 \wordbox[lrt]{1}{Data headers} \\
cheryl_he 0:fc22cf8cc478 59 \skippedwords \\
cheryl_he 0:fc22cf8cc478 60 \wordbox[lrb]{1}{} \\
cheryl_he 0:fc22cf8cc478 61 \bitbox{8}{0x00 \\ \tiny{terminator ``record''}} \\
cheryl_he 0:fc22cf8cc478 62 \end{bytefield}
cheryl_he 0:fc22cf8cc478 63
cheryl_he 0:fc22cf8cc478 64 Each data header is defined as:
cheryl_he 0:fc22cf8cc478 65
cheryl_he 0:fc22cf8cc478 66 \begin{bytefield}{16}
cheryl_he 0:fc22cf8cc478 67 \bitheader{0, 7, 8, 15} \\
cheryl_he 0:fc22cf8cc478 68 \bitbox{8}{Data ID}
cheryl_he 0:fc22cf8cc478 69 \bitbox{8}{Data type} \\
cheryl_he 0:fc22cf8cc478 70 \wordbox[lrt]{1}{KV records} \\
cheryl_he 0:fc22cf8cc478 71 \skippedwords \\
cheryl_he 0:fc22cf8cc478 72 \wordbox[lrb]{1}{} \\
cheryl_he 0:fc22cf8cc478 73 \bitbox{8}{0x00 \\ \tiny{terminator ``record''}} \\
cheryl_he 0:fc22cf8cc478 74 \end{bytefield}
cheryl_he 0:fc22cf8cc478 75
cheryl_he 0:fc22cf8cc478 76 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.
cheryl_he 0:fc22cf8cc478 77
cheryl_he 0:fc22cf8cc478 78 Each KV record is defined as:
cheryl_he 0:fc22cf8cc478 79
cheryl_he 0:fc22cf8cc478 80 \begin{bytefield}{16}
cheryl_he 0:fc22cf8cc478 81 \bitheader{0, 7, 8, 15} \\
cheryl_he 0:fc22cf8cc478 82 \bitbox{8}{Record ID} \\
cheryl_he 0:fc22cf8cc478 83 \wordbox[lrt]{1}{Record value} \\
cheryl_he 0:fc22cf8cc478 84 \skippedwords \\
cheryl_he 0:fc22cf8cc478 85 \wordbox[lrb]{1}{} \\
cheryl_he 0:fc22cf8cc478 86 \end{bytefield}
cheryl_he 0:fc22cf8cc478 87
cheryl_he 0:fc22cf8cc478 88 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. \\
cheryl_he 0:fc22cf8cc478 89 Record ID meanings are different for each data type. The length and format of the record value is dependent on the record meaning. \\
cheryl_he 0:fc22cf8cc478 90 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.
cheryl_he 0:fc22cf8cc478 91
cheryl_he 0:fc22cf8cc478 92 \subsubsection{Global Records IDs}
cheryl_he 0:fc22cf8cc478 93 Record values are immutable (can't be updated after the initial header is sent), unless otherwise noted.
cheryl_he 0:fc22cf8cc478 94
cheryl_he 0:fc22cf8cc478 95 0x00: reserved (terminator) \\
cheryl_he 0:fc22cf8cc478 96 0x01: internal name, as a null-terminated string, default to data ID \\
cheryl_he 0:fc22cf8cc478 97 0x02: display (user-friendly) name, as a null-terminated string, default to internal name \\
cheryl_he 0:fc22cf8cc478 98 0x03: units, as a null-terminated string, default "" \\
cheryl_he 0:fc22cf8cc478 99
cheryl_he 0:fc22cf8cc478 100 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 \\
cheryl_he 0:fc22cf8cc478 101
cheryl_he 0:fc22cf8cc478 102 \subsection{Data format for opcode 0x01: Data}
cheryl_he 0:fc22cf8cc478 103 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.
cheryl_he 0:fc22cf8cc478 104
cheryl_he 0:fc22cf8cc478 105 \begin{bytefield}{16}
cheryl_he 0:fc22cf8cc478 106 \bitheader{0, 7, 8, 15} \\
cheryl_he 0:fc22cf8cc478 107 \wordbox[lrt]{1}{Data records} \\
cheryl_he 0:fc22cf8cc478 108 \skippedwords \\
cheryl_he 0:fc22cf8cc478 109 \wordbox[lrb]{1}{} \\
cheryl_he 0:fc22cf8cc478 110 \bitbox{8}{0x00 \\ \tiny{terminator ``record''}} \\
cheryl_he 0:fc22cf8cc478 111 \end{bytefield}
cheryl_he 0:fc22cf8cc478 112
cheryl_he 0:fc22cf8cc478 113 Each data record is defined as:
cheryl_he 0:fc22cf8cc478 114
cheryl_he 0:fc22cf8cc478 115 \begin{bytefield}{16}
cheryl_he 0:fc22cf8cc478 116 \bitheader{0, 7, 8, 15} \\
cheryl_he 0:fc22cf8cc478 117 \bitbox{8}{Data ID} \\
cheryl_he 0:fc22cf8cc478 118 \wordbox[lrt]{1}{Data value} \\
cheryl_he 0:fc22cf8cc478 119 \skippedwords \\
cheryl_he 0:fc22cf8cc478 120 \wordbox[lrb]{1}{} \\
cheryl_he 0:fc22cf8cc478 121 \end{bytefield}
cheryl_he 0:fc22cf8cc478 122
cheryl_he 0:fc22cf8cc478 123 The data value length and format is dependent on the data type, which is defined by the data ID in the header.
cheryl_he 0:fc22cf8cc478 124
cheryl_he 0:fc22cf8cc478 125 \section{Data Types}
cheryl_he 0:fc22cf8cc478 126
cheryl_he 0:fc22cf8cc478 127 \subsection{Numeric: Data type 1}
cheryl_he 0:fc22cf8cc478 128 \subsubsection{KV Records}
cheryl_he 0:fc22cf8cc478 129 Record ID 0x40, uint8: data sub-type: 0x01 indicates unsigned integer, 0x02 indicates signed integer, 0x03 indicates floating-point \\
cheryl_he 0:fc22cf8cc478 130 Record ID 0x41, uint8: data length (in bytes) \\
cheryl_he 0:fc22cf8cc478 131 Record ID 0x42, uint8: range limits (in data type, obviously must be transmitted after sub-type and length) \\
cheryl_he 0:fc22cf8cc478 132 \subsubsection{Data format}
cheryl_he 0:fc22cf8cc478 133 Raw data in network order.
cheryl_he 0:fc22cf8cc478 134
cheryl_he 0:fc22cf8cc478 135 \subsection{Numeric Array: Data type 2}
cheryl_he 0:fc22cf8cc478 136 \subsubsection{KV Records}
cheryl_he 0:fc22cf8cc478 137 This includes all the records in the numeric type (for element type), along with: \\
cheryl_he 0:fc22cf8cc478 138 Record ID 0x50, uint32: array count (in number of elements)
cheryl_he 0:fc22cf8cc478 139 \subsubsection{Data format}
cheryl_he 0:fc22cf8cc478 140 Raw data in network order.
cheryl_he 0:fc22cf8cc478 141
cheryl_he 0:fc22cf8cc478 142 \end{document}