appendices.tex

\begin{appendices}
\addtocontents{toc}{\protect\setcounter{tocdepth}{0}}

\chapter{Source Code Repositories}
\label{apx:source-repos}

All source code and documentation for the \acrfull{ahabus} platform and, its flight software \acrfull{fcore} and the ground segment software are made available and grouped under the AHABus GitHub organisation, at https://github.com/ahabus. Below is a list of the different repositories:

\begin{description}
\item[\acrshort{fcore}] main flight software, based on FreeRTOS.\\https://github.com/ahabus/fcore

\item[Dl-Fldigi] Fork of Dl-Fldigi able to export raw RTTY binary streams.\\https://github.com/ahabus/dl-fldigi

\item[radio-parser] A simple packet parser that decodes incoming \acrshort{ahabus} frame streams and displays packet contents.\\https://github.com/AHABus/radio-parser

\item[PacketRadio] AHABus Radio Protocol encoder/decoder reference implementation.\\https://github.com/AHABus/packet-radio

\item[Arduino-Payload] Example implementation of a \acrshort{ahabus} payload for Arduino-compatible micro-controllers.\\https://github.com/AHABus/arduino-payload
\end{description}

\chapter{Test Data Repositories}
\label{apx:test-data-repos}

The data collected during the testing phase is made available under the AHABus GitHub organisation. Below is a list of the different repositories:

\begin{description}
\item[Raw Data] https://github.com/ahabus/test-rawdata

\item[Data Processing Scripts] https://github.com/ahabus/test-processing
\end{description}

\chapter{AHABus Packet Radio Protocol Specification}\label{apx:protocol-radio}

\begin{verbatim}
author:     Amy Parent <amy@amyparrent.com>
version:    3
date:       2017-02-15
\end{verbatim}

This document describes the protocol used by the AHABus platform (or any
other compliant bus) to transfer telemetry data from an airborne
platform (typically, a High-Altitude Balloon payload) to a ground
station over a radio link.

\section{Protocol Overview}\label{protocol-overview}

The protocol is designed with low-bandwidth, low-power radio links in
mind, to stay within the legal limits for airborne transmission in the
UK {[}1{]}: 70cm wavelength band transmissions at a power no higher than
10~mW.

The model used by low-cost High Altitude Balloon missions (one way,
two-point non multiplexed RTTY link), there is no real network to speak
of. For this reason, the OSI layers model {[}2{]} is hardly applicable
to the AHABus protocol.

None the less, the protocol follows a layer model, described here in
increasing levels of abstraction: the application-level packets are
encapsulated in frames, which provide order and error correction. Frames
themselves are sent over the RTTY radio link, which uses Frequency-Shift
Keying to convert a digital stream of bits to an analogue radio signal.

\section{Requirements}\label{requirements}

The AHABus Packet Protocol's main goal is to support telemetry
transmission from an AHABus-based High Altitude Balloon mission to a
ground station. The following requirements all come from this main goal:

\begin{itemize}
\item
  provide a system to transmit multiple payload's data on a same link
\item
  provide stable transmissions on a low-power link
\item
  provide some level of transmission error correction
\item
  provide means to track the payload's GNSS location over time
\end{itemize}

\section{Layers Specification}\label{layers-specification}

The three main layers of the AHABus Radio Protocol are meant to be as
independent from each other as possible. The rationale behind that is
that one layer could be swapped for a different implementation without
impacting the design of the other layers.

On every layer above the data-link layer, any multi-octet field must be
transmitted in network byte order (little-endian). Integers must be
transmitted in two's-complement binary format, floating point values in
IEEE754 single precision. Values sent as fixed-point have their
fractional and integer bit width specified when required.

\subsection{Radio Link}\label{radio-link}

The lowest-level layer of the AHABus Radio Protocol is the radio link.
Its only role is to provide a raw binary stream between the payload and
the ground station, without consideration for the transmitted data's
structure.

Because of the restrictions imposed on airborne radio transmission
equipment in the United Kingdom {[}1{]}, the chosen physical link is:

\begin{verbatim}
frequency:      434MHz band
power:          < 10mW
Modulation:     FSK/AFSK
 
Encoding:       RTTY (8bit-bytes, No parity bit, 2 stop bits)
Rate:           50-300bauds
\end{verbatim}

These are guidelines only, and can be swapped for other types of
modulation and encoding where it is legal to do so, and as long as the
chosen encoding can provide a binary stream.

\subsection{Frame Layer}\label{fec-layer}

The FEC layer provides transfer reliability to the {[}over{]} layers.
Any data generated by upper layers is split into frames at the FEC
layer. Each frame is composed of a frame sync marker, a header, the
binary data and a Forward Error Correction code.

The header contains the frame's AHABus protocol version and a sequence
number which allows a partial frame stream to be re-constructed on the
ground in the case a frame is lost in transmission.

The last 32 octets of each frame make up the frame's Reed-Solomon
(255,223) {[}3{]} FEC code, used to correct data corruptions on
reception of each frame. The code is computed using the complete frame,
sync marker and header included.

A frame should start to be decoded when the incoming byte in the streams
goes from \texttt{0xAA} to \texttt{0x5A}. There can be any number of
sync bytes (\texttt{0xAA}). The frame marker (\texttt{0x5A}) is part of
the frame's 256 bytes, but is not counted when computing the
Reed-Solomon error-correction code for the frame.

\textbf{AHABus Frame Structure}

\begin{verbatim}
struct radio_frame {
    00: u8          start_marker = 0x5A
    01: u8          protocol_version
    02: u16         sequence_number
    04: b8[220]     data
    e0: b8[32]      fec_code
}
\end{verbatim}

\subsection{Packet Layer}\label{application-layer}

The application layer provides the support for the high-level AHABus
operations: packets encapsulate both each instruments' data samples, but
also ancillary data that is required to support a High-Altitude Balloon
mission. Packets also allow multiple instruments' data to be sent over a
shared connection.

Each packet is composed of a primary and second header, and a body of
variable length.

\begin{itemize}
\item
  The primary header contains data required for the packet decoder to
  parse and dispatch the packet's data correctly:

  \begin{itemize}
  \item
    AHABus protocol version,
  \item
    Payload ID of the instruments who's data is carried in the packet,
  \item
    Packet's length in bytes, including the header.
  \end{itemize}
\item
  The secondary header contains ancillary data required for the support
  of the mission:

  \begin{itemize}
  \item
    AHABus platform's latitude in decimal format at the time the packet
    was encoded as a 32-bit signed integer, multiplied by 10000,
  \item
    AHABus platform's longitude in decimal format at the time the packet
    was encoded as a 32-bit signed integer, multiplied by 10000,
  \item
    AHABus platform's altitude in metres at the time the packet was
    encoded, in 16-bit unsigned integer format.
  \end{itemize}
\end{itemize}

Packets transmitted over AHABus frame streams should be aligned on frame
boundaries. Each packet should start on a new frame, and the end of a
packet should be the last data in a frame.

\textbf{AHABus Packet Structure}

\begin{verbatim}
struct radio_packet {
    00: u8          protocol_version
    01: u8          instrument_id
    04: u16         length
    06: i32         latitude
    08: i32         longitude
    0a: u16         altitude
    0c: b8[length]  data
}
\end{verbatim}

\section{Related Documents}\label{related-documents}

\begin{itemize}
\item
  \href{https://github.com/AHABus/src/software/payload-bus.md}{AHABus
  Payload Bus Protocol Specification}
\end{itemize}

\section{References}\label{references}

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
  Ofcom (2014). IR 2030 -
  \href{https://www.ofcom.org.uk/__data/assets/pdf_file/0028/84970/ir_2030-june2014.pdf}{UK
  Interface Requirements 2030 Licence Exempt Short Range Devices}.
  London
\item
  Stallings, W. (1987). Handbook of computer- communications standards.
  Macmillan. isbn: 002948071X.
\item
  UKHAS (2010). \href{http://ukhas.org.uk/code:rs8encode}{Reed-Solomon
  Encoder (255,223)}.
\end{enumerate}

\chapter{AHABus Payload Bus Protocol}\label{apx:protocol-bus}

\begin{verbatim}
author:     Amy Parent <amy@amyparrent.com>
version:    3
date:       2017-02-15
\end{verbatim}

This document describes the protocol used by the AHABus platform (or any
other compliant bus) to communicate and fetch data from payload
instruments hosted on an FCORE data bus.

\section{Protocol Overview}\label{protocol-overview}

The AHABus protocol (AHAP) is designed to provide an asymmetric
communication platform between a High-Altitude Balloon mission's
instruments and the main flight computer (FCORE).

AHAP relies on the two-wire (Phillips I2C) protocol to establish a
connection between the main computer and each payload. Communications
are controlled solely by the main computer: a payload can only send or
receive data when it has been addressed.

Because the AHABus platform relies on low-bandwidth data, data rate caps
can be enforced on each payload. These caps are defined on a per-mission
basis. If a payload returns more data than it is allowed to the computer
will stop addressing it.

FCORE (the software component of the AHABus flight computer) will
address each payload in turn over a certain period of time. By default,
each payload has the same data rate restrictions. If priorities are
given to payloads, higher priority payloads will be allowed higher data
caps than their low-priority counterparts.

AHAP is a virtual remote memory access protocol. After opening a
communication line with a payload, the computer requests the data at
certain virtual memory addresses (defined in further sections) to obtain
payload data and metadata relating to it. There are no requirement that
those addresses map to physical addresses on each instrument's
controller -- just that the instrument return the expected pieces of
data or metadata.

\section{Virtual Registers}\label{virtual-registers}

Payloads that implement AHAP should provided specific information in
certain virtual registers, mapped at the following addresses:

\begin{longtable}[]{@{}lll@{}}
Address & Name &\tabularnewline
\midrule
\endhead
\texttt{\$00{[}1{]}} & Tx Flag & \texttt{0x01} when the bus controller
is addressing\tabularnewline
\texttt{\$01{[}2{]}} & Data Length & Number of bytes of available
data\tabularnewline
\texttt{\$10{[}-{]}} & Data & Start of data made available to the
bus\tabularnewline
\end{longtable}

\section{Communications format}\label{communications-format}

AHABus uses the I2C protocol to denote whether an address is being read,
or written to. Communication is always initiated by the Bus Controller.

To accommodate low-budget, low-power devices which may present small I2C
transmission buffers, the AHABus protocol does not allow transmission of
more than 32 bytes at once. If a payload must send more than 32 bytes of
data, the controller will read its data sequentially, in chunks of 32
bytes starting at address \texttt{\$10}.

\section{Synopsis}\label{synopsis}

In typical operations, a bus controller/payload interaction follows
these steps:

\begin{enumerate}
\def\labelenumi{\arabic{enumi}.}
\item
  The bus controller addresses the payload's address and writes
  \texttt{0xff} in the Tx Flag register. At this point, the payload must
  not change the contents of any of its public registers.
\item
  The bus controller requests the contents of the of Data Length
  register by writing its address on the bus, then reading two bytes. If
  no data is available (Data Length = \texttt{0x0000}), the controller
  goes to step 4.
\item
  The bus controller requests the data by writing the address of the
  data area, and reads \texttt{Data\ Length} bytes.
\item
  The bus controller writes \texttt{0x0} in the payload's Tx Flag
  register. The connection is considered close after this point.
\end{enumerate}

In the event where any of the connection's communication would fail, the
bus controller skips any further steps and attempts to close the
connection.

\section{Related Documents}\label{related-documents}

\begin{itemize}
\item
  \href{https://github.com/AHABus/src/software/packet-radio.md}{AHABus
  Packet Radio Protocol Specification}
\end{itemize}


\end{appendices}