diff --git a/M17_spec.pdf b/M17_spec.pdf index 4a6aa34..e3bf418 100644 Binary files a/M17_spec.pdf and b/M17_spec.pdf differ diff --git a/M17_spec.tex b/M17_spec.tex index ae9d268..17e0cc3 100644 --- a/M17_spec.tex +++ b/M17_spec.tex @@ -11,16 +11,16 @@ \usepackage{float} \usepackage{tikz} \usetikzlibrary{shapes.geometric, arrows.meta} -\tikzstyle{textonly} = [rectangle, -minimum width=1cm, +\tikzstyle{textonly} = [rectangle, +minimum width=1cm, minimum height=1cm, -text centered, +text centered, draw=white] \tikzstyle{whrectround} = [rectangle, rounded corners, -minimum width=1cm, -minimum height=1cm, -text centered, -text width=2cm, +minimum width=1cm, +minimum height=1cm, +text centered, +text width=2cm, draw=black] \usepackage{amstext} \usepackage{array,calc} @@ -34,21 +34,21 @@ draw=black] \definecolor{codepurple}{rgb}{0.58,0,0.82} \definecolor{backcolour}{rgb}{0.95,0.95,0.92} \lstdefinestyle{codestyle}{ - backgroundcolor=\color{backcolour}, + backgroundcolor=\color{backcolour}, commentstyle=\color{codegreen}, keywordstyle=\color{magenta}, numberstyle=\tiny\color{codegray}, stringstyle=\color{codepurple}, basicstyle=\ttfamily\footnotesize, - breakatwhitespace=false, - breaklines=true, - captionpos=b, - keepspaces=true, - numbers=left, - numbersep=5pt, - showspaces=false, + breakatwhitespace=false, + breaklines=true, + captionpos=b, + keepspaces=true, + numbers=left, + numbersep=5pt, + showspaces=false, showstringspaces=false, - showtabs=false, + showtabs=false, tabsize=2 } \lstset{style=codestyle} @@ -230,7 +230,7 @@ is sent first. For example, the four dibits contained in the byte \texttt{0xB4} \node (rrc) [whrectround, right of=up, xshift=1cm] {RRC Filter}; \node (fm) [whrectround, right of=rrc, xshift=1cm] {Frequency Modulation}; \node (out) [textonly, right of=fm, xshift=1cm] {4FSK Output}; - + \draw [-latex](in) -- (sym); \draw [-latex](sym) -- (up); \draw [-latex](up) -- (rrc); @@ -323,7 +323,7 @@ CSMA may be used to minimize collisions on a shared radio frequency by having th \node (rrc) [whrectround, below of=up] {rrc filter}; \node (fm) [whrectround, below of=rrc] {frequency modulation}; \node (fsk) [whrectround, below of=fm] {4FSK RF}; - + \draw [-latex](payload) -- (rand); \draw [-latex](rand) -- (sync); \draw [-latex](sync) -- (cd); @@ -386,7 +386,7 @@ utilized will be indicated for each frame type. \node (cont) [whrectround] {Data Link Layer Contents}; \node (ecc) [whrectround, right of=cont, xshift=2.5cm] {ECC/FEC Encode}; \node (payload) [whrectround, right of=ecc, xshift=2.5cm] {Payload}; - + \draw [-latex](cont) -- node [midway, above] {Type 1 bits} (ecc); \draw [-latex](ecc) -- node [midway, above] {Type 4 bits} (payload); \end{tikzpicture} @@ -399,7 +399,7 @@ utilized will be indicated for each frame type. \node (payload) [whrectround] {Payload}; \node (ecc) [whrectround, right of=payload, xshift=2.5cm] {ECC/FEC Decode}; \node (cont) [whrectround, right of=ecc, xshift=2.5cm] {Data Link Layer Contents}; - + \draw [-latex](payload) -- node [midway, above] {Type 4 bits} (ecc); \draw [-latex](ecc) -- node [midway, above] {Type 1 bits} (cont); \end{tikzpicture} @@ -1540,7 +1540,7 @@ M17 uses 48-bit (6-byte) addresses. Callsigns and special purpose addresses are \texttt{0xF46109000000 - 0xFFFFFFFFFFFE} & Reserved & \texttt{12,777,376,710,655} & for application use \\ \hline \texttt{0xFFFFFFFFFFFF} & Broadcast & \texttt{1} & Valid only for destination \\ - \hline[2pt] + \hline[2pt] \end{tblr} \caption{M17 Addresses} \end{table} @@ -1584,10 +1584,10 @@ The final address encoded into the 6-byte LSF/LICH field would be \texttt{0$\tim \section{Encoding Reserved Addresses} -Reserved addresses can be encoded by prepending an 8 character callsign with a hash character, \texttt{\#}. The hash -indicates that \texttt{$40^9$} is added to the encoded value of the eight character subfield. Thus, a lone hash +Reserved addresses can be encoded by prepending an 8 character callsign with a hash character, \texttt{\#}. The hash +indicates that \texttt{$40^9$} is added to the encoded value of the eight character subfield. Thus, a lone hash symbol encodes to \texttt{0$\times$EE6B28000000}, -while \texttt{\#A} is \texttt{0$\times$EE6B28000001} and so on. +while \texttt{\#A} is \texttt{0$\times$EE6B28000001} and so on. Using this scheme, the last hash encodable special address, a hash followed by eight dots, is \texttt{0$\times$F46108FFFFFF}. @@ -1603,60 +1603,46 @@ be documented here. Developers can register the hash address(es) by submitting a \pagebreak -\section{C++ Encoder Example} +\section{Encoder Example} -\begin{lstlisting}[language=C++] -#include -#include -#include +\begin{lstlisting}[language=C,numbers=none] +#include +#include +#include -const std::string m17chars(" ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-/."); - -// Input callsign is assumed to be in uppercase -void Encode(const std::string& callsign, uint8_t* pUChar) +void Encode(const char *callsign, uint8_t *pUChar) { - assert(NULL != pUChar); + uint64_t address = 0; // the calculate address in host byte order - std::string cs(callsign); - cs.resize(9, ' '); // truncate or fill to 9 characters - - uint64_t address = 0; - - if (0 == cs.compare("ALL ")) + if (pUChar && callsign && *callsign) // quick check the input { - address = 0xffffffffffffu; // handle the broadcast - } - else - { - bool isReserved = false; - // is this a reserved callsign? - if ('#' == cs.at(0)) + const char *p = callsign; + + // find the last char + while (*p++ && (p-callsign < 9)) ; + + // process each char from the end to the beginning + for (p--; p>=callsign; p--) { - isReserved = true; - cs.erase(0, 1); + unsigned val = 0; // the default value of the character + if ('A' <= *p && *p <= 'Z') val = *p - 'A' + 1; + else if ('0' <= *p && *p <= '9') val = *p - '0' + 27; + else if ('-' == *p) val = 37; + else if ('/' == *p) val = 38; + else if ('.' == *p) val = 39; + else if ('a' <= *p && *p <= 'z') val = *p - 'a' + 1; + + if (p == callsign && '#' == *p) // is this a hashed address? + address += 0xee6b28000000ull; + else + address = 40u * address + val; // increment and add } - // calculate the address, in host byte order - for (int i = cs.size() - 1; i >= 0; i--) - { - auto pos = m17chars.find(cs.at(i)); - if (pos == std::string::npos) - { - pos = 0; // not in the M17 character set, use a space - } - address *= 40; - address += pos; - } - - if (isReserved) - { - // offset the address if there was a leading '#' - address += 0xee6b28000000u; - } + if (0x4ce1ull == address) // is this "ALL"? + address = 0xffffffffffffull; } - // store the address in network byte order - for (int i = 5; i >= 0; i--) + for (int i=5; i>=0; i--) // put it in network byte order { pUChar[i] = address & 0xffu; address /= 0x100u; @@ -1666,49 +1652,49 @@ void Encode(const std::string& callsign, uint8_t* pUChar) \pagebreak -\section{C++ Decoder Example} +\section{Decoder Example} -\begin{lstlisting}[language=C++] -#include -#include -#include +\begin{lstlisting}[language=C,numbers=none] +#include +#include +#include -std::string Decode(const uint8_t* pUChar) +char *Decode(const uint8_t* pUChar) { - assert(NULL != pUChar); + static char cs[10]; + strcpy(cs, " "); + + if (NULL == pUChar) + return cs; + + const char *m17chars = " ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789-/."; // calculate the address in host byte order uint64_t address = 0; for (int i=0; i<6; i++) address = address * 0x100u + pUChar[i]; - // is this the broadcast address? - if (address == 0xffffffffffffu) + if (address == 0xffffffffffffu) // is this the broadcast address? + return "ALL "; + + if (address >= 0xf4610a000000u) // is it in the decodable range? + return cs; + + unsigned i = 0; // start decoding + + if (address > 0xee6b27ffffffu) // is this a reserved address? { - return std::string("ALL "); + cs[i++] = '#'; + address -= 0xee6b28000000u; } - std::string callsign; - - // is it in the decodable range? - if (address < 0xf4610a000000u) + while (address) // get the characters { - // is this a reserved address - if (address > 0xee6b27ffffffu) - { - callsign.assign("#"); - address -= 0xee6b28000000u; - } - - while (address) - { - callsign.append(1, m17chars[address % 40u]); - address /= 40u; - } + cs[i++] = m17chars[address % 40u]; + address /= 40u; } - callsign.resize(9, ' '); // fill to 9 characters - return callsign; + return cs; } \end{lstlisting} @@ -1866,7 +1852,7 @@ This is equivalent to 0xC75 in hexadecimal notation. Both the generating matrix \begin{align} G = [I_{12}|P] = \left[ \begin{array}{cr} - I_{12} \begin{matrix} + I_{12} \begin{matrix} 1&1&0&0&0&1&1&1&0&1&0&1 \\ 0&1&1&0&0&0&1&1&1&0&1&1 \\ 1&1&1&1&0&1&1&0&1&0&0&0 \\ @@ -1928,7 +1914,7 @@ Sample MATLAB/Octave code snippet for generating $G$ and $H$ matrices is shown b \begin{lstlisting}[language=Matlab] P = hex2poly('0xC75'); [H,G] = cyclgen(23, P); - + G_P = G(1:12, 1:11); I_K = eye(12); G = [I_K G_P P.']; @@ -1985,7 +1971,7 @@ The linearized representations are: P1 = [1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1, 1, 0, 1, 1] - + P2 = [1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0] \end{verbatim} @@ -2006,9 +1992,9 @@ The linearized representation is: \chapter{Interleaving} -For interleaving a Quadratic Permutation Polynomial (QPP) is used. The polynomial +For interleaving a Quadratic Permutation Polynomial (QPP) is used. The polynomial -$\pi(x)=(45x+92x^2)\mod 368$ +$\pi(x)=(45x+92x^2)\mod 368$ is used for a 368 bit interleaving pattern QPP. @@ -2186,9 +2172,9 @@ The reason for this is that it allows for easier synchronization. This is equiva static constexpr uint16_t MASK = 0x1FF; static constexpr uint8_t TAP_1 = 8; // Bit 9 static constexpr uint8_t TAP_2 = 4; // Bit 5 - + uint16_t state = 1; - + public: bool generate() { @@ -2320,7 +2306,7 @@ Short for ``Keep it simple, stupid''. A simplified TNC protocol designed to move \subsection{type indicator} -A one byte code at the beginning of a KISS frame which indicates the TNC \textbf{port} and KISS \textbf{command}. +A one byte code at the beginning of a KISS frame which indicates the TNC \textbf{port} and KISS \textbf{command}. \subsection{port} @@ -2643,7 +2629,7 @@ dev -\textgreater{} rrc -\textgreater{} bin -\textgreater{} aud \section{To-Do} -File formats for packet and voice + data streams. +File formats for packet and voice + data streams. \section{References} @@ -2661,18 +2647,18 @@ Raised Cosine} %\label{label_fdl} \begin{center} - + Version 1.3, 3 November 2008 - - + + Copyright \copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. - + \bigskip - + \texttt{} - + \bigskip - + Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. \end{center} @@ -2786,7 +2772,7 @@ A section ``\textbf{Entitled XYZ}'' means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as ``\textbf{Acknowledgements}'', -``\textbf{Dedications}'', ``\textbf{Endorsements}'', or ``\textbf{History}''.) +``\textbf{Dedications}'', ``\textbf{Endorsements}'', or ``\textbf{History}''.) To ``\textbf{Preserve the Title}'' of such a section when you modify the Document means that it remains a section ``Entitled XYZ'' according to this definition. @@ -2876,43 +2862,43 @@ and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version: \begin{itemize} - \item[A.] + \item[A.] Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. - + \item[B.] List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. - + \item[C.] State on the Title page the name of the publisher of the Modified Version, as the publisher. - + \item[D.] Preserve all the copyright notices of the Document. - + \item[E.] Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. - + \item[F.] Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. - + \item[G.] Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice. - + \item[H.] Include an unaltered copy of this License. - + \item[I.] Preserve the section Entitled ``History'', Preserve its Title, and add to it an item stating at least the title, year, new authors, and @@ -2921,7 +2907,7 @@ of it. In addition, you must do these things in the Modified Version: stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. - + \item[J.] Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise @@ -2930,26 +2916,26 @@ of it. In addition, you must do these things in the Modified Version: You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. - + \item[K.] For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. - + \item[L.] Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. - + \item[M.] Delete any section Entitled ``Endorsements''. Such a section may not be included in the Modified Version. - + \item[N.] Do not retitle any existing section to be Entitled ``Endorsements'' or to conflict in title with any Invariant Section. - + \item[O.] Preserve any Warranty Disclaimers. \end{itemize} @@ -3220,15 +3206,15 @@ to permit their use in free software. \begin{center} {\parindent 0in - + Copyright \copyright\ 1989, 1991 Free Software Foundation, Inc. - + \bigskip - + 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA - + \bigskip - + Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. } @@ -3293,11 +3279,11 @@ modification follow. %\renewcommand{\theenumi}{\alpha{enumi}} \begin{enumerate} - + \addtocounter{enumi}{-1} - - \item - + + \item + This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The ``Program'', below, refers to @@ -3307,45 +3293,45 @@ modification follow. modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term ``modification''.) Each licensee is addressed as ``you''. - + Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does. - + \item You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. - + You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. - + \item - + You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: - + \begin{enumerate} - - \item - + + \item + You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. - + \item - + You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License. - + \item If the modified program normally reads commands interactively when run, you must cause it, when started running for such @@ -3357,10 +3343,10 @@ modification follow. License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.) - + \end{enumerate} - - + + These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in @@ -3370,50 +3356,50 @@ modification follow. on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. - + Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. - + In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. - + \item You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following: - + \begin{enumerate} - + \item - + Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, - + \item - + Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, - + \item - + Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.) - + \end{enumerate} - - + + The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any @@ -3424,13 +3410,13 @@ modification follow. form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. - + If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code. - + \item You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt @@ -3439,7 +3425,7 @@ modification follow. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. - + \item You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or @@ -3449,7 +3435,7 @@ modification follow. Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it. - + \item Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the @@ -3458,7 +3444,7 @@ modification follow. restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. - + \item If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), @@ -3472,12 +3458,12 @@ modification follow. all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. - + If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. - + It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the @@ -3488,10 +3474,10 @@ modification follow. system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. - + This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. - + \item If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the @@ -3500,13 +3486,13 @@ modification follow. those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. - + \item The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. - + Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and ``any later version'', you have the option of following the terms and conditions @@ -3514,7 +3500,7 @@ modification follow. Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. - + \item If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author @@ -3523,13 +3509,13 @@ modification follow. make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. - + \begin{center} {\Large\sc No Warranty } \end{center} - + \item {\sc Because the program is licensed free of charge, there is no warranty for the program, to the extent permitted by applicable law. Except when @@ -3540,7 +3526,7 @@ modification follow. to the quality and performance of the program is with you. Should the program prove defective, you assume the cost of all necessary servicing, repair or correction.} - + \item {\sc In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who may modify and/or @@ -3551,7 +3537,7 @@ modification follow. you or third parties or a failure of the program to operate with any other programs), even if such holder or other party has been advised of the possibility of such damages.} - + \end{enumerate} @@ -3577,17 +3563,17 @@ the exclusion of warranty; and each file should have at least the \begin{quote} one line to give the program's name and a brief idea of what it does. \\ Copyright (C) yyyy name of author \\ - + This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. - + This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. - + You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. @@ -3619,7 +3605,7 @@ necessary. Here is a sample; alter the names: \begin{quote} Yoyodyne, Inc., hereby disclaims all copyright interest in the program \\ `Gnomovision' (which makes passes at compilers) written by James Hacker. \\ - + signature of Ty Coon, 1 April 1989 \\ Ty Coon, President of Vice \end{quote}