lora_aprs_node_pico/buildmanual/lora-kiss-tnc-pico.tex

\documentclass[a4paper]{article}
\usepackage{graphicx}
\usepackage[table]{xcolor}
\usepackage{subcaption}
\usepackage{multirow}% http://ctan.org/pkg/multirow
\usepackage{hhline}% http://ctan.org/pkg/hhline
\usepackage{listings}
%\usepackage{amssymb}
%\usepackage{amsmath}

\makeatletter
\newcommand{\verbatimfont}[1]{\renewcommand{\verbatim@font}{\ttfamily#1}}
\makeatother

\begin{document}

\title{A LoRa KISS TNC for APRS}
\author{M.T. Konstapel}
\date{2022-05-18}
\maketitle

\begin{abstract}
The traditional FSK based 1200bd APRS used in conjunction with analogue FM transceivers is still going strong, but APRS over LoRa is gaining in popularity. Unfortunately, most existing modems are stand alone trackers and iGates. These are convenient as they do not need any external hardware, but integrating these modems in existing digipeater-setups is a challenge. That is why I decided to design a LoRa modem with a standardized KISS interface over USB. This modem can, for example, be connected to a computer running APRX on Linux (eg. an existing 2 meter APRS digipeater). Simply attach the modem with \textit{kissattach} to the Linux AX.25 stack and you now have a cross band APRS digipeater without any hassle.
\end{abstract}

\section{The design}

\begin{figure}[ht]
  \centering
  \includegraphics[width=\textwidth]{block-diagram-hardware.eps}
  \caption{block diagram of the modem}
  \label{fig:figure1}
\end{figure}

Figure \ref{fig:figure1} shows the block diagram of the modem. It is basically two blobs attached to each other. The controller is a Raspberry Pi Pico and the radio is a 433MHz Ra-02 module, which is a LoRa module based around an SX1278 chip. A couple of LEDs provide some status indication, like POWER ON, RX and TX. The I2C-interface as well as six GPIO-pins are available on two headers. These are not used by the default firmware, but could be utilized by altering this firmware yourself.

\section{The firmware}

\begin{figure}[ht]
  \centering
  \includegraphics[width=\textwidth]{block-diagram-software.eps}
  \caption{block diagram of firmware}
  \label{fig:figure2}
\end{figure}

\subsection{LoRa APRS}

A typical LoRa APRS frame is just a string of ASCII characters. And that's a bit of a problem as this is not quite what the original AX.25 standard\footnote{http://www.ax25.net/AX25.2.2-Jul\%2098-2.pdf} describes as a valid AX.25 frame. The firmware has to convert the APRS string to a proper AX.25 frame.

\subsection{AX.25 APRS}

The conversion, of course, goes both ways. From LoRa APRS to AX.25 and from AX.25 to LoRa APRS. Before converting from LoRa APRS to AX.25 some error checking is done as frames could be corrupted in transit.

\subsection{KISS}

Kiss\footnote{https://en.wikipedia.org/wiki/KISS\_(TNC)} is stupidly simple: send two bytes (0xC0 0x00), than just send the AX.25 frame and end with one byte: 0xC0. The AX.25 frame has to be escaped, because any 0xC0 value in it is seen as an end of frame.

\subsection{USB}

The KISS frames are send to the host over the USB interface. The host can simply attach the interface to the AX.25 stack via \textit{kissattach} or attach it directly to APRX via the APRX configuration file.

\section{Configuration}

The modem can be configured via a serial terminal program like \textit{minicom}. Exit from KISS mode with command \textit{kissparm -p ax0 -x} (assuming the modem is attached to ax0) and kill the kissattach process. Than start minicom (19200bd 8N1). When finished you can go back to KISS mode with command \textit{kiss 1} or you can power cycle the modem.

All commands that alter settings write to RAM. After a reboot, these settings are lost, unless the settings are saved to FLASH.

\begin{table}[ht!]
\centering
\begin{tabular}{|c|c|c|}
    \hline
    \multicolumn{3}{|c|}{\cellcolor{gray!40}\textbf{System commands}} \\
    \hline
    \cellcolor{gray!40}\textbf{command} & \cellcolor{gray!40}\textbf{parameter} & \cellcolor{gray!40}\textbf{description}\\
    \hline
    \multirow{2}{*}{read} & ram   & read settings from RAM\\
                          & flash & read settings from FLASH\\
    \hline
    save & - & Save RAM settings to FLASH \\
    \hline
    kiss & 1 & Switch to KISS mode\\
    \hline
    \multicolumn{3}{c}{} \\
    \hline
    \multicolumn{3}{|c|}{\cellcolor{gray!40}\textbf{LoRa commands}} \\
    \hline
    \cellcolor{gray!40}\textbf{command} & \cellcolor{gray!40}\textbf{parameter} & \cellcolor{gray!40}\textbf{description}\\
    \hline
    freq & Herz & Set lora frequency (limited between 420MHz and 450MHz)\\
    \hline
    spread & value & Set lora spreading factor (can be between 6 and 12)\\
    \hline
    pre & value & Set lora preamble (can be between 6 and 65535)\\
    \hline
    rate & value &  Set lora coding rate (can be between 5 and 8)\\
    \hline
    power & dBm &  Set lora tx power (can be between 2 and 17) \\
    \hline
    pa & 0/1 & Set PA on or off \\
    \hline
    band & value &  Set lora bandwidth (can be between 7800 and 500000) \\
    \hline
    restart & - &  Restart radio (do this after altering LoRa settings) \\
    \hline
    \multicolumn{3}{c}{} \\
    \hline
    \multicolumn{3}{|c|}{\cellcolor{gray!40}\textbf{Stand alone commands (not used in KISS mode)}} \\
    \hline
    \cellcolor{gray!40}\textbf{command} & \cellcolor{gray!40}\textbf{parameter} & \cellcolor{gray!40}\textbf{description}\\
    \hline
    mycall & CALL-x & Set call and ssid of modem \\
    \hline
    servercall & CALL-x & Set call and ssid of server \\
    \hline
    path 1 & PATH & Set first path or leave blank \\
    \hline
    path 2 & PATH & Set second path or leave blank \\
    \hline
    dest & ID & Set destination \\
    \hline
\end{tabular}
\caption{request packet}
\label{bms-protocol-request}
\end{table}

\clearpage

\section{Practical notes}

\subsection{Build the pcb}

Building the printed circuit board is straight forward. The design files are made with KiCad 5.1.8 and scaled PDF files of the printed circuit board are available. The pcb has two layers and can be made by yourself or ordered from a pcb manufacturer. When etched yourself, there are no plated through vias. All ground connections, as well as some other connections, should be soldered on both sides of the pcb.

\clearpage
\appendix
\section{Full schematic}

\begin{figure}[ht]
  \centering
  \includegraphics[width=15cm, angle=90]{lora_kiss_tnc_pico_rev2.eps}
  \caption{full schematic of the modem}
    \label{fig:figure3}
\end{figure}

\clearpage
\section{Component placement}

\begin{figure}[ht]
  \centering
  \includegraphics[width=\textwidth]{lora_kiss_tnc_pico_rev2-pcb-layout}
  \caption{component placement}
  \label{fig:figure4}
\end{figure}

\clearpage
\section{Component placement 3D view}

\begin{figure}[ht]
  \centering
  \includegraphics[width=\textwidth]{lora_kiss_tnc_pico_rev2_3d-view.png}
  \caption{3d view}
  \label{fig:figure5}
\end{figure}

\clearpage

\section{Bill of material}

\begin{figure}[ht]
  \centering
  \includegraphics[width=\textwidth]{lora_kiss_tnc_pico_rev2_bom.eps}
  \caption{bill of material}
  \label{fig:figure6}
\end{figure}
\clearpage

\section{Open source hardware and software}
All the design files are available on my website: https://www.meezenest.nl/mees

This document is published under the Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.

\begin{figure}[ht!]
  \begin{subfigure}[b]{0.5\textwidth}
    \includegraphics[width=\textwidth]{oshw-logo-outline.eps}
    \label{fig:7}
  \end{subfigure}
  %
  \begin{subfigure}[b]{0.5\textwidth}
    \includegraphics[width=\textwidth]{gpl-v3-logo.eps}
    \label{fig:8}
  \end{subfigure}
  \label{fig:fully-build}
\end{figure}

\begin{figure}[ht]
  \centering
  \includegraphics[width=\textwidth]{by-sa.eps}
  \label{fig:figure6}
\end{figure}

\end{document}