Add support for powering off the radiosonde. Improve documentation.

NOTES.md

@@ -1,16 +0,0 @@
-* TODO: Add support for power-off via button and possibility disable power-off button
-
-* TODO: create RTTY / FSK encoder for Si5351
-* TODO: create RTTY / FSK encoder for Si4032
-* TODO: create CW / OOK encoder -- the same one should work for both Si5351 and Si4032
-
-* TODO: Add relevant information about RS41 hardware
-* TODO: Add relevant links to other sources of information, e.g.:
-  * http://happysat.nl/RS-41/RS41.html
-  * https://github.com/darksidelemm/RS41HUP - 4FSK + 2FSK
-  * https://github.com/darksidelemm/RS41FOX - RS41-FOX - RS41 Amateur Radio Direction Finding (Foxhunting) Beacon
-  * https://github.com/bazjo/RS41_Hardware
-  * https://github.com/bazjo/RS41_Decoding
-  * https://destevez.net/2018/06/flashing-a-vaisala-rs41-radiosonde/
-  * https://destevez.net/2017/11/tracking-an-rs41-sgp-radiosonde-and-reporting-to-aprs/
-  * http://www.om3bc.com/docs/rs41/rs41_en.html

README.md

@@ -1,12 +1,45 @@
 # RS41ng - Amateur radio firmware for Vaisala RS41 radiosonde
 
-**NOTE:** This is a work in progress and some features do not work correctly yet!
+**NOTE:** This firmware is a work in progress and some features might not work as expected yet!
 
-This is a custom, amateur radio-oriented firmware for Vaisala RS41 radiosondes.
+This is a custom, amateur radio-oriented firmware for [Vaisala RS41 radiosondes](https://www.vaisala.com/en/products/instruments-sensors-and-other-measurement-devices/soundings-products/rs41).
 Some of the code is based on an earlier RS41 firmware project called [RS41HUP](https://github.com/df8oe/RS41HUP),
 but most of it has been rewritten from scratch. The Horus 4FSK code has been adapted from
 the [darksidelemm fork of RS41HUP](https://github.com/darksidelemm/RS41HUP).
 
+## What are the Vaisala RS41 radiosondes and how can I get one?
+
+The RS41 radiosondes are used extensively for atmospheric sounding by the meteorological institutes in various countries and thus easily
+available to be collected once they land, an activity called radiosonde hunting: see YouTube presentation about
+[Tracking and Chasing Weather Balloons by Andreas Spiess](https://www.youtube.com/watch?v=vQfztG60umI) or
+[Chasing Radiosonde Weather Balloons used in Meteorology for Fun by Mark VK5QI](https://www.youtube.com/watch?v=fb9gNomWrAY)
+for more details!
+
+You can track radiosondes without any additional equipment either via [SondeHub](https://tracker.sondehub.org/) or [radiosondy.info](https://radiosondy.info/)
+that both use an existing network of receiver stations. Alternatively, you can set up your own radiosonde receiver station.
+
+For your own receiver station, you will need:
+
+1. A cheap software-defined radio USB dongle, such as an [RTL-SDR](https://www.rtl-sdr.com/about-rtl-sdr/)
+2. An antenna suitable for receiving the 400 MHz radiosonde band transmissions. Antennas for the 70 cm amateur radio band usually work fine!
+3. Radiosonde tracker software: common choices are [RS41 Tracker](http://escursioni.altervista.org/Radiosonde/) for Windows
+   and [radiosonde_auto_rx](https://github.com/projecthorus/radiosonde_auto_rx) for Linux / Raspberry Pi.
+
+### What can I do with an RS41 radiosonde?
+
+The [Vaisala RS41 radiosondes](https://www.vaisala.com/en/products/instruments-sensors-and-other-measurement-devices/soundings-products/rs41)
+uses an off-the-shelf [STM32F100C8](https://www.st.com/en/microcontrollers-microprocessors/stm32f100c8.html)
+32-bit microcontroller, which can be reprogrammed using an [ST-LINK v2 programmer](https://www.st.com/en/development-tools/st-link-v2.html)
+or a smaller [ST-LINK v2 USB dongle]((https://www.adafruit.com/product/2548).
+
+The RS41 hardware can be programmed to transmit different kinds of RF modulations (morse code, APRS and different FSK modulations)
+on the 70 cm (~433 MHz) amateur radio band. The radiosonde contains a [UBX-G6010](https://www.u-blox.com/en/product/ubx-g6010-st-chip)
+GPS chip, so it can be used as a tracker device, e.g. for high-altitude balloons.
+
+The RS41ng firmware is just one example of what can be achieved with the RS41 hardware!
+
+## Why does the RS41ng firmware exist?
+
 The motivation to develop this firmware is to provide cleaner, customizable and
 more modular codebase for developing RS41 radiosonde-based experiments.
 
@@ -84,8 +117,10 @@ dnf install arm-none-eabi-gcc-cs arm-none-eabi-gcc-cs-c++ arm-none-eabi-binutils
 
 Hardware requirements:
 
-* A working Vaisala RS41 radiosonde :)
+* A working [Vaisala RS41 radiosonde](https://www.vaisala.com/en/products/instruments-sensors-and-other-measurement-devices/soundings-products/rs41) :)
-* A programmer for the STM32 microcontroller present in the RS41 radiosonde. ST-LINK v2 USB-dongles work well.
+* An [ST-LINK v2 programmer for the STM32 microcontroller](https://www.st.com/en/development-tools/st-link-v2.html) in the RS41 radiosonde. 
+  * These smaller [ST-LINK v2 USB dongles](https://www.adafruit.com/product/2548) also work well.
+  * [Partco sells the ST-LINK v2 USB dongles in Finland](https://www.partco.fi/en/measurement/debugging/20140-stlinkv2.html)
 
 The pinout of the RS41 connector (by DF8OE) is the following:
 
@@ -121,7 +156,7 @@ ______________________|           |______________________
   * GND -> Pin 5
   * 3.3V -> Pin 3
 3. Unlock the flash protection - needed only before reprogramming the sonde for the first time
-  * `openocd -f ./openocd_rs41.cfg -c "init; halt; flash protect 0 0 64 off; exit"`
+  * `openocd -f ./openocd_rs41.cfg -c "init; halt; flash protect 0 0 31 off; exit"`
 4. Flash the firmware
   * `openocd -f ./openocd_rs41.cfg -c "program build/src/RS41ng.elf verify reset exit"`
 5. Power cycle the sonde to start running the new firmware
@@ -239,6 +274,23 @@ rtl_fm -f 432500000 -M fm -s 250k -r 48000 -g 22 - | ./aprs -
 
 # Authors
 
+* Mikael Nousiainen OH3BHX <oh3bhx@sral.fi>
 * Original codebase: DF8OE and other authors of the [RS41HUP](https://github.com/df8oe/RS41HUP) project
 * Horus 4FSK code adapted from [darksidelemm fork of RS41HUP](https://github.com/darksidelemm/RS41HUP) project
-* Mikael Nousiainen OH3BHX <oh3bhx@sral.fi>
+
+# Additional documentation
+
+## Vaisala RS41 hardware documentation
+
+* https://github.com/bazjo/RS41_Hardware - Reverse-engineered documentation on the RS41 hardware
+* https://github.com/bazjo/RS41_Decoding - Information about decoding the RS41 data transmission
+* http://happysat.nl/RS-41/RS41.html - Vaisala RS-41 SGP Modification and info about the original firmware settings
+* https://destevez.net/2018/06/flashing-a-vaisala-rs41-radiosonde/
+* https://destevez.net/2017/11/tracking-an-rs41-sgp-radiosonde-and-reporting-to-aprs/
+
+## Alternative firmware projects
+
+* https://github.com/df8oe/RS41HUP - The original amateur radio firmware for RS41
+* https://github.com/darksidelemm/RS41HUP - A fork of the original firmware that includes support for Horus 4FSK (but omits APRS)
+* https://github.com/darksidelemm/RS41FOX - RS41-FOX - RS41 Amateur Radio Direction Finding (Foxhunting) Beacon
+* http://www.om3bc.com/docs/rs41/rs41_en.html

openocd_rs41.cfg

@@ -4,7 +4,7 @@
 #  - see: http://openocd.org/doc/html/Flash-Commands.html#flashprotect
 
 # Typical usages:
-#	openocd -f ./openocd_rs41.cfg -c "init; halt; flash protect 0 0 64 off; exit"
+#	openocd -f ./openocd_rs41.cfg -c "init; halt; flash protect 0 0 31 off; exit"
 #						to unlock 64k of Flash for programming
 #	openocd -f ./openocd_rs41.cfg -c "program RS41ng.elf verify reset exit"
 #						to program the connected rs41

src/config.h

@@ -18,6 +18,9 @@
 // Green LED: Blinking fast when there is no GPS fix. Blinking slowly when the GPS has a fix.
 #define LEDS_ENABLE true
 
+// Allow powering off the sonde by pressing the button for over a second (when the sonde is not transmitting)
+#define ALLOW_POWER_OFF false
+
 // Enable use of an externally connected I²C BMP280 atmospheric sensor
 #define SENSOR_BMP280_ENABLE false
 

src/hal/system.c

@@ -173,8 +173,8 @@ void system_handle_button()
     static uint16_t button_pressed_threshold = 2000;
     static bool shutdown = false;
 
-    // ~1450-1600 - button up
+    // ~1650-1850 - button up
-    // ~1780-1850 - button down
+    // ~2000-2200 - button down
 
     uint16_t current_value = system_get_button_adc_value();
 
@@ -316,6 +316,8 @@ void TIM4_IRQHandler(void)
 
         system_handle_timer_tick();
 
-        // TODO: fix detection of button state and enable: system_handle_button();
+#if ALLOW_POWER_OFF
+        system_handle_button();
+#endif
     }
 }