Technical reference¶

The following sections describes some technical details of the software.

Communication¶

The controller uses two ways to communicate with different servers. HTTP(S) for general configuration and control (BORC - Blitzortung Remote Control) and UDP for the signal data. Both different connection methods make the system very flexible and reliable. UDP for sending 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.

graph LR

A{Controller} 
A <-->|HTTP| B[BORC Control Server 1];
A --->|UDP| D[iBOD Computing Server];
D -->|UDP| F[BOD Computing Server 3];
D -->|UDP| G[BOD Computing Server 4];
A <-.->|HTTP| C[BORC Control Server 2];
A -.->|UDP| E["BOD Computing Server (Backup)"];

BORC Control connection (HTTP/HTTPS)¶

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.

Since firmware 10 this connection will be encrypted by default.

Signal packets (UDP)¶

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 (see Data structure).

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.

UDP Fragmentation and MTU size¶

The size of each UDP packet depends on the signal form, its encoding, compression and number of channels. Sometimes the UDP data packet exceeds 1500 bytes which is the maximum packet size for ethernet frames. Such a packet will be sent fragmented. Such big fragmented UDP packets often get lost on the way to our servers, i.e. on the home router, the internet provider or on some router in the data center.

This problem is solved for most users by using a lower MTU of 1480. This also affects other traffic (TCP, HTTP), but this shouldn't be noticeable at all. Using smaller packet sizes just only for signals packets is currently not possible.

Encryption and privacy¶

Starting with Firmware 10 the whole traffic between stations and servers can be encrypted. We are using best practice methods keeping your data secret from others. The control connection uses TLS 1.2 with ECDHE key exchange and AES-GCM encryption (TLS-ECDHE-RSA-WITH-AES-128-GCM-SHA256/-AES-256-GCM-SHA384 or TLS-RSA-WITH-AES-128-GCM-SHA256/-AES-256-GCM-SHA384). The public CA certificate can be downloaded here. The TLS buffer size is just around 6kB instead of standard 32kB like in browser (which would be almost all free RAM).

For encryption of the signal packets a unique key will be sent over the control connection. This key will be replaced by a new one after some hours. These keys are only known by our servers. The key is used to encrypt every signal packet with AES-GCM algorithm.

Encryption uses some CPU resources and a few extra kilobytes of RAM. The theoretical max. number of signals per second will drop by ~10-20%. For performance reasons you can disable encryption for HTTP and/or UDP completely.

Signal detection and processing¶

The following list summarizes that and gives a short overview what happens when a signal on a single channel gets received:

1. Electromagnetic fields induce a small current in the antenna coil.
2. The signal is amplified and filtered on the pre amplifier board.
3. The signal is transmitted through the cable to the controller board.
4. The signal is amplified and filtered several times in the amplifier
5. The 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.
6. 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.
7. A watchdog compares the ADC-register value with a threshold. If the threshold is reached, an interrupt is generated.
8. 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.
9. Depending on settings, the recorded signals are checked and filtered.
10. 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.

Firmware implementation¶

The firmware is bare metal micro controller 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.

Start-up Sequence¶

After a reset or power-on, the controller initializes itself and peripherals, like CPU clocks, real time clock, I/Os, amplifiers and USARTs. The configuration is loaded from flash. 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 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.

GPS¶

The main purpose of the GPS is the 1PPS signal which gives all worldwide station the same absolute time base. The 1PPS-line is directly connected to an I/O pin of the MCU. It is also connected to an ADC input pin to check the quality of the 1PPS-pulse in case of an error.

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.

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.

For fast code execution STM32F4 can use flash prefetch. Unfortunately this may creates some noise spikes in the signals:

Prefetch is off on the two left signals and on the right ones. The far right signal has much more spikes until trigger, where the CPU enters the interrupt routine.

Backup registers¶

These registers keep their values upon reset. Smoothed GPS position is saved there. After a software reboot this saves some time as no check for stable position is needed.

Backup RAM¶

The content of the backup RAM survives upon reset. Its currently only used for debugging.

Hardware 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.

The STM32F4 on the controller board has brown out watchdogs enabled (the ATMega8 on RED amplifiers too). 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.

Timers¶

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.

* LSI: low speed internal clock, which is not very accurate. RTC adjusted by GPS.

1PPS capture¶

The 1PPS timer value will is captured and set to 0 on each 1PPS pulse. The accuracy of the 1PPS pulse is far enough for our needs. The timing difference between different GPS modules has been tested and the difference is just a few nanoseconds. The length of the antenna cable has more effects:

blue: u-blox, yellow: MT3333 (BLUE), purple: MT3339 (RED) with external (left) and internal (right) antenna

DMA¶

Several peripherals are configured to use DMA access:

• ADCs: which stores all their samples in RAM all the time (up to 150MBit/s)
• DAC: for playing buzzer sounds
• GPS USART: receiving the position data
• Debug USART: Sending debug messages.
• Signal Test: Injecting test signals into on board amplifiers via DAC

IRQ¶

Interrupts are used by a lot of different peripherals, mainly:

• 1PPS timer capture
• 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.

ADC¶

The MCU has three A/D converters. Each of them can sample several input channels (0-17). The sampling rate can be adjusted by an external timer or by the ADC itself. Both modes are implemented in the firmware. The three ADCs can run simultaneously with different inputs or they run interleaved to sample the same input channel very fast. This can be used sampling 1PPS signal (timing check) or input voltage (check for power supply quality).

Italic means that there is a non analogue part connected to the corresponding pin.

DAC¶

Digital analogue converters for outputting signal waves.

• DAC1 is used for signal test injection (BLUE only).
• DAC2 is used for buzzer.

USARTs¶

* RED only

SPI¶

I2C¶

• I2C1 is used for AS3935 (RED only)

RNG - Random number generator¶

The random number generator is used for generating entropy for encryption.

USB¶

USB can be used as virtual COM port or in DFU mode.