====== General mode of operation ======
original source(([[http://en.blitzortung.org/Compendium/Documentations/Documentation_2014-05-11_Red_PCB_10.4_PCB_12.3_PCB_13.1_PCB_14.1.pdf|Documentation System RED]], chapter 5.5))

FIXME Mark the sections for RED/BLUE only.

FIXME If there are BLUE only sections, add them.

The following sections describes the technical background of the hard- and software. You don’t have
to understand all of them, but you should try to read the important parts.


===== About the firmware =====

The firmware is bare metal microcontroller software. That means, no operating system like Linux
or an embedded real-time-operating-system (RTOS) is used as a base. This saves space and gives
full control over all peripherals. The firmware has been built with the GNU Tools ARM Embedded
toolchain. There are some 3rd party libraries included, which are listed in the About section of the
web-interface.

Several peripherals are configured to use DMA access: The ADCs which stores all their samples
in RAM all the time (up to 150MBit/s), the DAC for playing sounds, GPS USART for receiving the
position data and debug USART for sending messages. Those transfers are handled by two DMA
controllers without interaction of the CPU.

Other functions are realized with interrupts (IRQ). The two most important interrupts are the
1PPS timer capture and the ADC watchdog. The 1PPS-IRQ has the highest priority, which means that
a 1PPS impulse from the GPS, immediately will stop the current routine and enters the 1PPS-IRQ
function. The ADC-IRQ has "only" the second highest priority. There are a lot of other interrupt
sources, where the timing is not so important.

The firmware uses some of the hardware timers for measurements and/or interrupts. The most
important one is again the 1PPS timer, which runs at 84MHz. That means, the timing of the 1PPS
signal can be measured with an accuracy up to 12ns - theoretically.

===== Flash and settings =====

The flash not only contains the firmware, but also user settings which can be changed through the
web-interface. If no settings are present in the flash, then default ones are used.

By design, flash has several limitations. You don’t have to care about them, as the firmware
already does this. One limitation is, that the whole flash area is divided into sectors. Before writing
on a position which already contains data, the whole sector has to be deleted and rewritten. Most
sectors in the STM32F407 CPU have a size of 128kB. Thus, a simple change of a small entry in the
flash needs a full rewrite which is not so easily possible due to lack of RAM. Additionally, the flash
tolerates "only" 10000 erase cycles. This is far enough, even when rewriting flash several times a day.

However, the controller downloads new configuration settings, proposed by the server, several
times per hour. Due to reasons mentioned above, those settings won’t be stored in flash memory. In
the current firmware, all flash operations must be done by the user himself.

===== Start-up Sequence =====

After a reset or power-on, the controller initializes itself and peripherals, like CPU-Clocks, LCD,
Real-Time-Clock, I/Os, Amplifiers and USARTs. The configuration is loaded from flash too. The
LEDs and LCD light up and there should be two beeps: A first start-beep and a second beep for a
successful initialization of an amplifier. While this boot-sequence takes less than 3 seconds, some
additionally initialization will run in the background.

The GPS-module has to lock position and 1PPS signal, which can take several minutes after a
cold start. Additionally, the controller checks for valid communication with the GPS and, if needed,
initializes the GPS with the defined baud-rate.

The assignment of a network IP address by your DHCP server can also take some seconds. As
soon as the controller has a IP-address assigned, a HTTP-request to the Blitzortung.org-servers will
be sent. The response contains information like computing server address or station id.

After all these processes have been finished successfully, the controller starts sending data.

===== Real-Time-Clock =====

The MCU has an integrated real-time-clock (RTC). It’s only used for internal functions to be independent
from GPS time. The time settings stays even when the controller has been resetted. The RTC is
adjusted automatically by GPS or remote configuration. It supports UTC time only.

===== Watchdogs =====

If the controller hangs due to a software bug or due to external impact, an integrated independent
hardware watchdog will reset the CPU. The watchdog can only be disabled by pressing the blue
button during start-up. It’s not possible to save that to flash.

Both microcontrollers, the STM32F4 on the controller board and the ATMega8 on the amplifier
have brown out watchdogs enabled. If there’s an undervoltage, a internal reset will be triggered. The
brown out watchdogs cannot be disabled.

With all those watchdogs enabled, the system should always be accessible.

===== Server connections =====

The controller uses two ways to communicate with different servers:

  - For each signal, the controller sends a UDP packet with the needed data to at least one computing server. The main information included in such a packet is the time-stamp of the trigger. The signal data itself is included in binary format. The protocol is flexible and data which didn’t change since the last packet doesn’t need to be transmitted again. That could be sampling settings or gain levels. This saves traffic and processing time on client and server side. However, traffic can get high when receiving a lot of signals, i.e. due to high thunderstorm activities or due to interference. We cannot give a concrete value, but we’ve already seen stations with 300MB/day. There are some mechanism implemented to reduce traffic and we are already thinking about further improvements here.
  - A HTTP connection is used for bi-directional communication. On the one hand, the controller sends information about itself, like status of GPS, amplifier, CPU or signal statistics to a control server. On the other hand, it gets information from the control server. For example, the controller gets its station-id, which computing server to use and whether a new firmware is available. The server can also change gain, threshold, sampling settings and a lot of other values.\\The control connection has a also fall-back mechanism included: If a HTTP-connection to the control server cannot be established, it tries to connect to other servers, until it gets valid information. The servers have no direct access to the controller, but the controller up- and downloads the information from time to time. The overall traffic could be some megabytes per day.

Both different connection methods make the system very flexible and reliable. UDP for sendning
the signals reduces overhead a lot and fits perfectly our needs. We measured a packet loss much lower
than 1% even on long distant connections.

===== Detecting signals =====

The previous sections gave a look into the technical background. The following list summarizes that
and gives a short overview what happens when a signal on a single channel gets received:

  - Electromagnetic fields induce a small current in the antenna coil.
  - The signal is amplified and filtered several times on the amplifier board. Gain settings have already been set before through the on board controller (ATMega8).
  - The signal is transmitted through the cable to the controller board. The reference voltage is 0V ± 1.5V.
  - On the controller board, the signal is shifted 1.5V up.
  - The shifted signal lies on the input of an A/D-converter integrated in the MCU. It samples the voltage with about 500,000 times per second (minimum) and stores this value in a register.
  - The DMA controller reads the register values of all three ADCs at once, and saves them one after another in memory. This memory block has a size of several kilobytes.
  - A watchdog compares the ADC-register value with a threshold. If the threshold is reached, a interrupt is generated.
  - The interrupt functions checks the 1PPS timer value and reads the needed ADC-samples from the memory block. This is the first time, where the CPU is needed.
  - Depending on settings, the recorded signals are checked and filtered.
  - The values of the triggered channel and the other channels as well as other information are send within a UDP packet to the computing server.