Basic Documentation for Moshe Braner's version of SoftRF ======================================================== By Moshe Braner This version last updated June 14, 2026 to fit software version MB203 The latest version of this document is always here: https://github.com/moshe-braner/SoftRF/blob/master/software/firmware/documentation or direct link: https://raw.githubusercontent.com/moshe-braner/SoftRF/refs/heads/master/software/firmware/documentation/SoftRF_MB_user_guide.txt Discussion group: https://groups.google.com/g/softrf_community PART 1: USER GUIDE WHAT IS SOFTRF SoftRF is a do-it-yourself, multifunctional, compatible, radio-based proximity awareness system for general aviation. SoftRF is free, open-source software that runs on inexpensive off-the-shelf hardware. This software, when installed on suitable hardware and carried in an aircraft, transmits data on its position, and receives position data from other aircraft with compatible systems. It can send information about nearby traffic, in standard formats, to visualization devices and to navigation software commonly used in sailplanes. Several radio communications and local data exchange protocols are supported. The one of interest to most glider pilots is the FLARM-compatible "Latest" mode. SoftRF can also work in the FANET protocol popular with paragliders, and more. Using SoftRF in your aircraft (when configured to use the "Latest" protocol) will: * make you visible to FLARMs and other SoftRF devices * make you visible to OGN ground stations, thus viewable on websites like https://glidertracker.org/ * make FLARMs and other SoftRF devices visible on your devices such as glide computers * generate collision warnings, alone or in conjuction with other devices Some people call this an "OGN tracker", although that label should be reserved for the devices used in some high level soaring competitions for the spectators' benefit - which are not compatible with FLARM. SoftRF is better described as a functional equivalent for, and compatible with, FLARM, if used in the "Latest" protocol. What can SoftRF do that FLARM cannot? On appropriate hardware, SoftRF can send traffic (and position) data out via WiFi or Bluetooth, which older FLARM models cannot do without additional hardware. (The new "Fusion" versions of FLARM do have wireless connectivity.) SoftRF can also operate using radio communications protocols other than the one used by FLARM, such as OGNTP, ADS-L, PilotAware or FANET. But for the vast majority of glider pilots the FLARM protocol is the important one, as it simultaneously offers both bidirectional air-to-air traffic awareness for collision avoidance and the option to be tracked by OGN ground stations. SoftRF can run all day on a small internal battery. What can FLARM do that SoftRF cannot? The more advanced PowerFLARM units can listen to FLARM signals via two antennas for more complete coverage. SoftRF is a DIY project requiring construction (other than perhaps the T-Echo), while FLARM is available off the shelf from an established company. But that comes at a significant monetary price. What can my version of SoftRF do that the mainline version cannot? My version can receive and transmit in the new FLARM protocol (V7) that went into effect in March 2024. My version also fixes some radio protocol bugs, making interoperability with FLARM more reliable. My version correctly transmits the curved path of the aircraft (if circling) so that FLARM units receiving the data can predict collisions accordingly. My version also receives and interprets the curved path of other aircraft as sent by FLARM units, and predicts collisions based on that. And it does so even when the aircraft are subject to significant wind drift. My version also offers built-in audible collision warnings in 3 levels of urgency, similar to what PowerFLARM Portable does. My version also offers some conveniences, such as assigning an ID to this aircraft, and specifying other IDs to ignore or to follow. And now also an option to record IGC flight log files. My version can transmit in an alternate protocol (OGNTP, ADS-L, FANET or PilotAware) once every few seconds, and can receive 2 or even 3 protocols at once. Additionally, my version has the option to add a hardware module to receive ADS-B signals from aircraft that do not have FLARM, and even as re-broadcast from air traffic control ground stations. This offers users awareness of some non-FLARM traffic, although the same is not true in reverse. And recent version of my SoftRF can also be configured to: * Relay selected other FLARM traffic, for increased range * Or, relay selected ADS-B traffic, if so equipped, for the benefit of nearby SoftRF that is not What can the mainline version of SoftRF do that my version cannot? The main branch of SoftRF offers compiled binaries for a wide variety of hardware platforms. So far my version has only been compiled for just a few hardware devices. It can in theory be compiled for other hardware, but that is not a quick and easy thing to do. I have concentrated on the "T-Beam" hardware because I believe it is the best choice at this time: is includes all the components one might want, integrated into a single board, including a holder for a 18650 size lithium cell, charger circuit, GNSS module, an ISM-band (900 MHz) radio, and a WiFi- and Bluetooth-capable CPU plus nonvolatile flash memory and additional volatile PSRAM. The T-Beam is also suitable for connecting other hardware to it, such as an SD card adapter, a pizeo buzzer, audio amplifier for voice warnings, a strobe, an alternative GNSS module, or an ADS-B receiver module. Note: only the plain "T-Beam" is supported, not the "T-Beam Supreme". And recently my version has expanded to support several NRF52-based hardware models beyond the T-Echo, including the M1, M3 and T1000E (see below). HISTORY FLARM, the traffic awareness and collision avoidance system which has been adopted by most glider (and many other aircraft) pilots in Europe, operates in the 866-928 MHz range (depending on what is legal in each region of the world - 470 MHz in China). It transmits in low power (25 milliwatts), in short bursts of a few milliseconds, once or twice per second. It was developed before the latest developments in hardware integration and modulation schemes, and is oriented towards collision avoidance, not long-range communications. The Open Glider Network (OGN) has encouraged the establishment of many ground stations, mainly in Europe, that listen to signals from FLARM and other devices, and feed the data to servers on the internet. Despite FLARM's low power, these stations can receive signals from tens, even hundreds, of km away. The "Internet of Things" (IoT) community has prompted manufacturers to develop inexpensive low-power hardware that integrates significant computing power and memory, along with communications capabilities including WiFi, Bluetooth, GNSS (such as GPS), and radios that operate in the unlicensed bands in the 400-1000 MHz range, in a variety of modulation schemes. Linar Yusupov ( https://github.com/lyusupov/SoftRF ) developed SoftRF, which (among other things) sends, receives and interprets signals to and from aircraft in the same protocol as used by FLARM, or in some other protocols. SoftRF runs on several types of the IoT hardware devices. Moshe Braner ( https://github.com/moshe-braner/SoftRF ) further developed SoftRF, filling in some gaps as described above, thus making it a more complete functional equivalent to FLARM. Ideally, these improvements would be incorporated into the main development branch of SoftRF. But so far Linar Yusupov has not done that. Thus to reap the benefits one must use this development fork. The software is "embedded", i.e., runs on the bare hardware without an operating system, although it incorporates software libraries from the hardware manufacturers and from third parties. The software is developed on other systems (e.g., Linux or Windows) and then copied ("flashed") into the flash memory of the IoT device, via a USB cable or Wifi. The size of this compiled firmware is less than 2 megabytes. HOW TO USE SOFTRF Hardware choices At this time my version of SoftRF runs specifically on certain devices with "system on a chip" CPU. Namely the device from the LilyGo (TTGO) company they call the "T-Beam" (not the "T-Beam Supreme"), and also several NRF52840-based devices including the LilyGo the T-Echo and T-Echo Plus, the Thinknode M1 and M3, and the Sensecap T1000-E (not the T1000-A). The T-Beam and T-Echo are also called the "Prime Mark II" and "Badge" editions of SoftRF, respectively. And the M1, M3 and T1000-E are also called the Handheld, Pocket and Card editions, respectively. If you are buying a device, be sure to order the version that fits your regional radio frequencies. I.e., in Europe the 868 MHz version, in the USA the 915 MHz version, etc. I suspect the two mentioned are really the same board, but with possibly different antennas. The 433/470 MHz board (for use in China) is definitely different! I've bought T-Beam boards from LilyGo directly: https://www.lilygo.cc/products/t-beam-v1-1-esp32-lora-module?variant=42204035186869 With my version of SoftRF you have the option of attaching a passive piezo buzzer to the T-Beam to get audible indications of collision warnings. A suitable buzzer is this one: https://www.digikey.com/en/products/detail/murata-electronics/PKM22EPPH4001-B0/1219323 This model also worked: "22x4mm AC With Lead Passive Piezo Electronic Alarm Buzzer 2204" https://www.ebay.com/itm/223511257011 Connect it between GPIO pins 14 and 15 in series with a 100-ohm resistor. (On the old T-Beam v0.7 GPIO 15 is not available, pin 25 is used instead - as long as the audio (voice) output is not turned on in the settings, in which case the buzzer output is turned off since pin 25 is then the audio output pin.) The beeps are higher pitched, shorter, and more numerous for higher alarm levels. If more than one aircraft is a collision danger, the beeps are split into double-beeps. The two-pin push-pull arrangement yields louder beeping than connecting the buzzer between one pin and ground. For even louder beeps, feed the pin 14 (and/or 15) signal to an external audio amplifier (or the aux audio input of an aircraft radio). Or, select "external" in the buzzer volume setting to get a +3v DC output signal on pin 14, and use it to trigger an external (12V) *active* buzzer via a transistor. Add a 1K resistor from pin 14 to ground to avoid a 1-second beep at boot since pin 14 starts with weak pull-up. An intentional 0.2s self-test beep will still sound. (Be sure to *remove* the battery from the T-beam before soldering wires for the buzzer. It is not enough to turn the T-Beam "off".) SoftRF also sends a special $PSRAA NMEA message whenever an audio alarm is called for. This version of SoftRF, on the T-Beam, also has the ability to generate *voice* warnings about traffic that is in danger of collision. For example, "traffic, 3 o'clock, low" for alarm levels 1 & 2, or "danger, ahead, level" for alarm level 3. If more than one aircraft is a collision danger, the word "traffic" is appended at the end. The audio data file needs to be uploaded via the web interface, see below. The voice audio output is from pin 25. This is a line-level output, it needs an external amplifier to drive a speaker. See: https://github.com/moshe-braner/SoftRF/blob/master/software/firmware/documentation/audio_output_circuit_.jpg for an example connection circuit. The resistors reduce the output signal level to what the amplifier probably wants - if it is too weak, increase the value of the 2.2K resistors. The 10 uF capacitor (positive side towards the T-Beam) blocks the DC component. The 10 nF capacitor tries to filter out high frequencies, from the DAC steps and from the circuit board as a whole. The amplifier can be a standalone device, or one can feed the signal into the AUX input of the aircraft communications radio, etc. Another option is an external I2S decoder/amplifier, such as those based on the Max98357 chip. The connection pins are: Serial Clock (SCK) (BCK): pin 14, Word Select (WS): pin 15, and Serial Data (SD): pin 25. Note that while using an external I2S decoder, both the internal analog signal generator (output to pin 25), and the piezo buzzer option (on pins 14,15), are not available. This digital-output method has not been tested yet, let me know if it works! You also have the option to attach (through a 100-ohm resistor) an LED, or LED-strobe-driving circuit, to pin 25 (note: strobe uses pin 15 if voice output is turned on which uses pin 25). This can be an LED on the T-Beam case, or elsewhere in the cockpit, that flashes in case of collision alarm. Or, it can trigger a high-intensity strobe mounted in the front of the canopy, to visually warn pilots of other aircraft - with periodic flashes, and more frequent flashes in case of collision alarm. For now, this needs a wired connection, specifically to a T-Beam. SoftRF now also sends a special $PSRSF NMEA message whenever a flash happens (or could happen). Utilizing that, can use a separate device ("SkyStrobe"), possibly embedded into the strobe unit, that receives data from SoftRF (or FLARM, wired or wirelessly), and controls the strobe based on that data. See pinout diagram here: https://github.com/moshe-braner/SoftRF/blob/master/software/firmware/documentation/T-beam_wiring.jpg Often T-Beams are sold with a small "OLED" display that one needs to solder to the board using a 4-pin header (or is already soldered). That is optional. SoftRF will run just fine without the OLED display. But if added, the OLED shows some information about SoftRF operation. During booting, it first shows the firmware version and whether the user settings have been restored. Later it shows the device ID, protocol, selected regional band, aircraft type, the number of aircraft tracked, the number of radio packets sent and received, the GNSS satellite reception status, battery voltage, IP address, and even lists the tracked aircraft. Press the power-on button briefly to rotate between several "pages" of information. This display is thus useful to verify operation and configuration. But it is too small and dim to be useful during flight. Be sure to *remove* the battery from the T-beam before soldering the OLED display to it. It is not enough to turn the T-Beam "off". See photo of the OLED attachement to pins 21 (SDA) and 22 (SCL): https://github.com/moshe-braner/SoftRF/tree/master/software/firmware/T-beam_OLED_attached.jpg It can alternatively be connected to pins 13 (SDA) and 2 (SCL), the software automatically detects which pins are used. (But be sure to connect pin 2 in a way that is easy to disconnect - see section on USB flashing.) Can share the same pins as the barometric sensor. (The AXP PMU too is using pins 21,22.) One needs to arrange a case for the T-Beam board. I've hacked the plastic shell the board arrives in into a workable case. If one uses the OLED display, note that it is very fragile, make sure the case protects it well. It is easiest to use a 3D-printed case. There are many designs available online as STL files for that purpose. Some of these files make a case that is too small, hard to use, or won't fit a gopro mount. One modified 3D model is available here: https://drive.google.com/drive/folders/1hdEJ-nRVz4D_sYihwv1Re2S-p8_nsYaM?usp=sharing which is a bit larger and has a gopro mount on the back of the enclosure. It connects with these or anything similar: https://www.amazon.com/GoPro-Grab-Bag-Official-Mount/dp/B01GCKO9IK I have adopted a slightly deeper (to the rear) case, my modified version here: https://github.com/moshe-braner/SoftRF/blob/master/case/T-Beam_case.zip that allows adding small items behind the board, e.g., a 12V to 5V converter, or a TTL to RS232 converter (or both!). Or this design which is even deeper, to facilitate mounting an ADS-B receiver module internally: https://github.com/moshe-braner/SoftRF/blob/master/case/T-Beam%20%2B%20ADS-B%20case.zip You don't have to have your own 3d printer. You can order a case via a service that allows you to upload the files, and have people with 3d printers make and ship them to you. The black ABS material works better than PLA. Cut out the middleman and go directly here: https://aero3ds.com/3d-printing - very reasonable prices especially if you buy several cases at once. A better antenna than the tiny whip that is included with these boards may be helpful. A true "dipole" antenna, which does not need a "ground plane" under the whip, may give better performance. An antenna with a cable, mounted far forward (in the nose) or rearwards (in the wing spar area or rear fuselage) should work better than an antenna in the instrument panel area that is cluttered with wires and metal instruments. Some dipole antennas have the cable exit the middle of the antenna on a right angle. Others have the cable exit off one end. For example: https://www.data-alliance.net/antenna-900mhz-3g-gsm-omni-directional-rp-sma-or-sma/ (select SMA male) or https://www.data-alliance.net/antenna-824-960-1710-2170mhz-sma-connector/ (select the narrower band version). Glue the antenna to a cockpit wall in as vertical an orientation as possible. Even when using an antenna with a cable, the T-Beam needs to be mounted with its antenna connector facing up, because there is a GNSS antenna attached to the board near there that needs to be horizontal and on top. Unless one attaches an external GNSS antenna via the UFL connector on the board - that can improve GNSS signal reception (especially if that antenna is larger and includes a built-in LNA). For example: https://www.data-alliance.net/antenna-gps-lna-embedded-u-fl-sma/ (choose the 25x25mm version with 4-inch cable and U.FL connector). SoftRF will only transmit its location, interpret transmissions from other aircraft, and be visible on OGN, when a GNSS (GPS) fix has been acquired. It may take anywhere from a few seconds to 30 minutes to obtain a "fix" after a cold start. The exact time may not be known for up to 12 more minutes, since the leap-second information is not transmitted by the GPS satellites very often. That may lead to lack of communications, or wrong positions being reported by OGN stations. For that reason SoftRF queries the GNSS module (if it is a Ublox type) whether the leap seconds are known. If they are not known, then 18 (the valid number of leap seconds in 2025) is assumed and the time is corrected accordingly. Until the leap seconds are known from the satellites, SoftRF on a T-Beam will show '!' rather than '+' under "FIX" in the second info page on the OLED, and the web page will say "leap seconds assumed", but it will transmit, with frequency hopping and encryption key based on the assumed time. The stock gps antenna is poor, it will not work indoors and needs a clear outdoor area to work. Some units seem better than others. With an add-on 25x25mm active antenna the performance is much better. Some units seem slower than others to get a fix, and some seem to get slower after some use. On the T-Beam only, there is now a button in the web interface (see below) to factory-reset the GNSS module settings and then cold-start it (and reboot the T-Beam). The first fix following that will be slow, but this may restore more rapid fix acquisition afterwards. Another alternative to the built-in GNSS module is to add an external one. See the section about connecting other hardware. The T-Echo (or Thinknode M1) offers a 1.5-inch e-paper display, which makes the device more self-contained. But adjusting the settings on the T-Echo is more difficult than on the T-Beam, because the T-Echo does not have WiFi connectivity. It also transmits at lower power, and the stock antenna is nice-looking but has low performance. And it is more difficult to attach other devices to it. The Thinknode M3 offers the ability to run SoftRF in a very compact self-contained unit. The Sensecap T1000-E is similar and also has extra flash memory which allows it to record flight logs, as can the T-Beam and T-Echo and M1 but not the M3. If you choose the T1000-E, be sure to read the instructions on how to do the necessary downgrade of the bootloader. See also Jim Hogue's detailed document: https://github.com/moshe-braner/SoftRF/blob/master/documents/Guide_to_Building_SoftRF_and_SkyView-Jim_Hogue.pdf How to power the SoftRF device There are basically 3 options, first explained here for the T-Beam: One can install an 18650 size cylindrical lithium-ion cell in the battery holder of the T-Beam (or a small Lithium-polymer pouch battery in the T-Echo), and run the device on that battery. (Be sure to buy FLAT TOP and not BUTTON TOP 18650 batteries as only FLAT TOP will fit in the holder on the T-Beam.) This will suffice for long flights. The battery can be charged via the USB port of the T-Beam or T-Echo. When a charger is attached, the board turns on, one can then turn it off to make the charging process somewhat faster. On the T-Beams with a PMU (v1.x), once turned "off", the blue LED indicates the charging. There is no indication on the older T-Beams (v0.7) of when the charging is complete. If your charger gets warm to the touch while charging, it will be cool to the touch when no longer charging at a significant rate. Or, one can power the T-Beam via the USB port, without installing a battery on the board. Any USB power source will do. You may install a 12V to 5V dc-dc converter and use the aircraft main power so that SoftRF (plugged in via a USB cable) turns on when aircraft power is turned on. The needed current is about 120 mA normally, perhaps double that during the very short transmission pulses (1 % of the time). A disadvantage of this approach is that, after sitting unpowered for a while, the device may take a relatively long time to acquire a GNSS fix. An advantage is that the device can be mounted "permanently" in the aircraft, one does not need to dismount it and take it elsewhere to charge it. Or, a hybrid power system can be used, combining external USB power and an on-board battery. That way the USB power charges the on-board battery while the device is in use. If the external power fails the device will keep running on the battery. If mounted in the aircraft in an inaccessible way, one can use the "power_ext" setting which will automatically turn the device off after several conditions are met: the device was running for at least an hour, the aircraft is not airborne, the external power has been turned off, and the battery voltage has decreased to under 3.9 volts. But, if you store the device, with a lithium battery, in the glider trailer that gets hot in the summer sun, you may be nervous about the possibility of a fire. Your choice. Yet another way to power the T-Beam, without a battery, is to supply it +5 volts but not via the USB jack. My preferred way to do that is to feed it to the + tab of the battery holder via a standard silicon diode (to reduce the voltage to about 4.3), and to add a resistor (about 2-5 Kohms) in parallel with the battery holder. (Or use a 3.7V power converter - the DD4012SA is available in that voltage - then there is no need for the diode.) This avoids needing space under the device for the USB plug. The other devices have the same options: internal battery, USB power, or both. The M3 and T1000-E are sealed, thus the internal battery is not accessible, and they use a magnetic USB connector. After several weeks in the apparently "off" mode, the battery installed in a SoftRF may be depleted. This seems to happen in some boards more than others. Always recharge the battery before attempting to use the device for a long flight following a storage period of more than a couple of weeks. Turning the device on and off To turn on the T-Beam, press and hold the button closest to the USB jack for about 2 seconds. Once LEDs and/or the OLED display light up, can let go of the button. To turn off the T-Beam, press and hold the button closest to the USB jack until the blue LED turns off, or the OLED display says "OFF", or the buzzer, if attached, makes a high-low sound. Shutdown takes a few seconds and will be complete when the red LED turns off. The middle button is usually not used (but see below), and the third button is a reset button. (On the old T-Beam v0.7 use the slide switch to turn it on and off.) After booting, the first button serves to switch between pages on the OLED display. Alternatively, simply connect to USB power, and the T-Beam will start up. But, if a battery is installed on the board, connecting to USB power (or (re)booting via a button while USB power is connected) will instead just charge the battery. To make it boot normally while attached to USB power, can use any of these three methods: * First let it fully boot on battery power, then connect USB power. Or, * Press the middle pushbutton before or while the OLED displays "CHARGE MODE" and hold it until the OLED says "NORMAL BOOT...". Or, * Enable the "power_ext" setting (mentioned above). The Power Management Unit (PMU) on the T-Beam (v1.x) is always active. The first pushbutton just sends instructions to the PMU. The PMU can turn the power to individual parts of the board (e.g., the CPU, or the GNSS module) on or off. There are 3 LEDs on the board. The bright blue LED near the PMU is controlled by the PMU (with indirect instructions from the CPU). The red LED near it signifies that the CPU is powered. The red LED near the GNSS module, when blinking, is indicating that the GNSS module has a "fix", i.e., is receiving signals from enough satellites. If any LED is lit, the board is not as close to "off" as it can be. If a battery is installed on the board, the T-Beam is never completely turned "off". Always remove the battery from the holder before soldering anything to the board. The T-Echo has a Reset button and a Mode button on the side, along with a touch pad on top. Pressing either the Reset button or the Mode button turns it on. To turn it off, press and hold the Mode button. Press the Mode button briefly to cycle through several screens. Some of the screens only show "NO FIX" if a GNSS fix is not yet available. The last screen (added in my version) shows some of the SoftRF settings - see below about changing the settings. Find more info about operating the T-Echo ("Badge Edition") here: https://github.com/lyusupov/SoftRF/wiki/Badge-Edition Note that in this version of SoftRF, if you touch and hold the touch pad, for 2 seconds, the display will show "SCREEN SAVER" and then go blank, but the device will keep operating. Click the Mode button to activate the display again. If you press and hold and then release the Mode button while touching the pad, the T-Echo will turn off with a sleepy-face icon on the display. Otherwise it will say "screen saver" and then the display will be blank. You can tell it is sleeping (unlike the screen saver mode while operating) by the 3-color LED next to the display being dark. The Thinknode M1 turns on and off the same way as the T-Echo. To turn on the Thinknode M3 or the T1000-E, click the button. Press and hold the button to turn it off. The LED will show red while booting and while shutting down, otherwise green or blue (see below). On the Thinknode M3 and T1000-E, too, when connected to (or disconnected from) USB power, will start up briefly but then go back to sleep and just charge the battery. (Before going back to sleep, and also when booting normally, the M1, M3 and T1000-E will make from 1 to 5 beeps to indicate the state of charge of the battery, from one low pitched beep for an empty battery, to 5 short high pitched beeps for a full battery.) To make these devices boot normally while attached to USB power, can either first let it fully boot on battery power, then connect USB power, or, enable the "power_ext" setting (mentioned above). After booting, SoftRF waits for the GNSS module to determine its location. On a T-Beam (v1.x) the blue LED blinks rapidly (4 times per second) until a "fix" is achieved, at which point the GNSS red LED starts blinking slowly (once per second). One can also see the number of satellites on the OLED display. After that, if transmissions are off the blue LED is off. If transmissions are on, the blue LED stays lit, unless the battery voltage is low, in which case it blinks slowly. On the T-Echo and M1 the display will show the number of GNSS satellites being received from, and more. In addition, on the T-Echo the green part of the LED closest to the display will change from rapid blinking to constantly on (or slow blinking it battery is low). Similarly on the M1 the LED will blink rapidly while waiting for a fix, and will stay lit once it is attained. On the M3 the LED will change from green to blue once a GNSS fix is attained. On the T1000-E the green LED will blink rapidly while waiting for a fix, and will stay lit once it is attained (or slow blinking it battery is low). If a buzzer is installed on a T-Beam, it will emit a series of 4 beeps rising in pitch when done booting. On the M1, M3 and T1000-E, an early beep (and turn-on of red LED) while booting, then when booting is complete a single beep followed by 1-5 short beeps to report the battery charge state (see above). Later the busser will emit 2 shorter beeps rising in pitch when a GNSS fix is achieved. FLARM does not generate collision warnings while it is not airborne. My version of SoftRF follows that rule. But to allow testing on the ground, my version does give such warnings - and sends signals out pretending to be airborne - for one minute after it is has booted and has acquired a GNSS fix. If a strobe is connected, it will fire during the first 9 seconds, despite not being airborne, for testing. Installing firmware for the first time The T-Beam often arrives from the factory with some version of SoftRF already installed. That allows installation of other versions of SoftRF via Wifi. See the section below about firmware updates. Note: if the board has the "RC9" version of SoftRF, do not update the firmware via WiFi. There is a bug in that version. It will fail! Use the USB method (later in this section) for the initial update of SoftRF. After that, it will be possible to update the firmware to later versions via WiFi. If the T-Beam board arrives with other software, e.g., "Meshtastic", or after a failed WiFi update, one may need to install SoftRF via the USB jack. Follow the instructions here: https://github.com/moshe-braner/SoftRF/tree/master/software/firmware/binaries/README.md#esp32 - substituting the .bin file for the desired version of the software (e.g., from here: https://github.com/moshe-braner/SoftRF/tree/master/software/firmware/binaries/ESP32/SoftRF ) instead of the original SoftRF.ino.bin file. A ZIP file with the other 3 small .bin files needed, and more detailed instructions, is available here: https://github.com/moshe-braner/SoftRF/tree/master/software/app/Flashing You will need a PC running Windows, that can recognize the USB interface inside the T-Beam as a virtual serial port. The copy of Windows 10 on my laptop did that as-is. If it does not, you need to find and install "driver" software that fits the USB hardware inside the T-Beam. Once the T-Beam shows up as a "COM port" (e.g., COM5) on the PC's device manager that hurdle is passed. Then you need to download and run the software (mentioned in the instructions) from Expressif, the makers of the ESP32 chips. It is not very intuitive to use, follow the written info, including the image: you must set the memory addresses as shown. And select the right COM port. If it goes horribly wrong the T-Beam may appear dead (won't boot any more), but so far I've always managed to bring it back to life with repeated attempts with that utility software. An alternative to the Windows-based ESP tool is a web-based tool available here: https://esp.huhn.me/ - works with Chrome, Edge or Opera browsers. Reportedly it will work with a Mac, for example. Or this tool, offered by the makers of the ESP32: https://espressif.github.io/esp-launchpad/ - only works on the Chrome browser. Note that anything connected to pin 2 on the T-Beam board may need to be disconnected to make firmware flashing via USB possible. (Or momentarily ground pin 2 via a 100-ohm resistor while the flashing tool is trying to connect.) Sometimes a board may behave strangely (e.g., WiFi will not connect) until the flash memory is fully erased (a function available in the USB flashing tool) before re-installing the firmware. The T-Echo, M1, and M3 usually include a "bootloader" which makes it easy to update the firmware. See the "updating the firmware" section below. The T1000-E comes with a bootloader that is not compatible with SoftRF. One needs to "downgrade" the bootloader and "soft device" to version 6.1.1. Can follow the instructions on this page set up by Vlad Belayev: https://slash-bit.github.io/SoftRF-PG/ or the more complicated method from this page from Linar Yusupov: https://github.com/lyusupov/SoftRF/wiki/Card-Edition.-Quick-start Once that is done, can update the firmware using the same method as the T-Echo, M1 and M3. The Web Interface (T-Beam only) After startup, SoftRF on a T-Beam tries to connect to the WiFi network specified in the settings (if both an SSID and a password were specified). If a connection is not successful (in 10 seconds), it creates its own Wifi network. Use a computer, tablet, or smartphone to connect to the network. If using an ambient network, connect to it as normal. Otherwise, the network SoftRF creates is named SoftRF-xxxxxx where xxxxxx is the device id. The device ID may differ from the aircraft ID shown on the OLED - check the fourth (or fifth) page on the OLED for the SSID. Or, you can specify the name for the network SoftRF creates in the "myssid" setting. Either way, the password is 12345678. Your phone or computer may complain that there is no internet access with this network, that is correct, allow it. Then open a web browser and point it to the IP address 192.168.1.1 if using the network created by SoftRF. If using the Chrome browser, it may refuse to connect unless you explicitly use "http://192.168.1.1" (not "https"), and dismiss warnings about "no internet access", "insecure", etc. If using an ambient network, check the fourth (or fifth) page on the T-Beam's OLED display for the IP address assigned to the SoftRF device by the network - click the button to progress through the pages. With the right IP address, the browser will connect to the mini web server built into SoftRF, allowing one to view SoftRF status info, see whether the user settings have been restored, change settings, or update the firmware via WiFi. This feature is NOT available on the T-Echo since it does not support WiFi. After connecting to the web interface, the home page seen is the SoftRF Status page. It shows some information, and offers buttons for launching several operations, such as viewing and changing settings, firmware update, downloading flight logs, etc. The web interface has been revised in version MB153 to be less cluttered and more intuitive. A button on the home page allows activation of "landed out" mode. Another way to activate this mode is via a long-press of the middle pushbutton on a T-Beam v1.x. See the "under the hood" document for more information about landed-out mode and relaying. Note that when Bluetooth is active, the web interface may not function (due to not enough memory). The currently implemented workaround is that, if memory space is low, web access automatically turns Bluetooth off (until you reboot). If that happens there will be a notice at the top of the web pages. If you still cannot get to the status page, one way to recover is via a USB (or BT) terminal and NMEA config (see the "under the hood" document). Choosing the operational settings Once the firmware is installed, before actual use in an aircraft, one must choose various options. The default settings often don't quite do what you want. The settings you choose are stored inside the device, and are not erased even when upgrading to a new version of the firmware - as long as the stored settings are in a format compatible with the new firmware version. If, for example, you upgrade from mainline v1.x to my version MBxxx, since my version has rather different settings, all the settings are reset to their defaults. Both the OLED and the settings web page warn about that having happened. On the T-Beam, connect to the SoftRF status web page as described above. Then click the "Basic Settings" button at the lower left. A new web page will load, where you can view and change the settings. Once you have selected the settings you want, scroll to the bottom of the web page and click "Save and Reboot". Once it is done rebooting, re-connect to the SoftRF WiFi network, go to the Settings page again, and double-check that your chosen settings are indeed in effect. Starting from version MB153, SoftRF has a much shorter "basic settings" web page, and a new auto-generated "advanced settings" web page which includes (almost) all the settings. There one can enter the raw code for each setting, then click "Save and Reboot". Comments appear on some lines explaining the values. The settings are now stored in a text file called "settings.txt" in the file system embedded into the flash memory of the device. The text in this file looks a lot like the text in the "advanced settings" web page. Buttons in the web interface allow downloading the file for backup elsewhere, uploading the file (possibly after manual editing), backing up the file to a copy within the flash memory, and swapping the current file with such a copy. Note that clicking "save and reboot" in the settings web page replaces the existing backup settings file (if any) with the current settings file before writing the new file. I.e., after the save and reboot, clicking the "Restore/Swap" button will revert to the previous settings. On the T-Echo, adjusting the settings is more difficult. Now that the settings are stored in a "settings.txt" file, the best way is to edit that file. After connecting the T-Echo to a computer via USB and opening it as a "drive", one can access that file from the computer. To prepare the file space so that SoftRF can then create the settings file, may first need to connect the T-Echo to a PC, format that "drive" (as "FAT"), then disconnect and restart SoftRF. Once you can see that file, you can edit it using a text editing app on the computer. Each line must have a setting label, comma, and setting value. The existing file will include comments further on some lines explaining the values. Save the file and reboot the T-Echo for the new settings to take effect. The older methods for changing the settings on the T-Echo include: I've added a method of adjusting some of the most important settings in the T-Echo, within the device, using the display & buttons. See instructions later in this document in the section "settings displayed, and adjusted, within the T-Echo". An Android app is available that can display and change some basic settings, see here: https://github.com/lyusupov/SoftRF/wiki/SoftRF-Configuration-Tool But that tool does not offer the "Latest" alarm trigger method as a choice. And it does not know about the additional settings in my version that are absent from the mainline version of SoftRF, e.g., setting the aircraft ID. Another method is to connect the T-Echo (or T-Beam, for that matter) via a USB cable to a computer with has a "terminal" program that can access the USB port as if it was a serial port. Alternatively, use a Bluetooth terminal app. Then look up the "Settings via NMEA" section in the "under the hood" document. A NEW and much better method is now available, and works for the T-Echo, M1, M3 and T1000-E: use the fantastic web page by Vlad Belayev (can be downloaded and used off-line too, at least via Bluetooth): https://skysignals.app/mysoftrf/ Open it in a browser that supports Web-BLE, e.g., Chrome or Edge, on a laptop or phone. It connects to the device via Bluetooth LE, shows device status and settings (and traffic), and allows an easy way to change the settings. It also allows connection via USB instead of Bluetooth (on some systems). Turn on Bluetooth on your phone (or laptop), but do not "pair" the phone with the SoftRF device. Instead, tap "BLE" (or "USB") in that web page, and select the SoftRF device in the list it shows. This tool is still under development, so check back. To use off-line on Android, tap the file in a file manager app and ask to open it in Chrome. Chrome does not allow entering (nor bookmarking) the URL. Tip: CX File Explorer allows adding a shortcut to the file to its home page. Description of the basic settings: (See the "under the hood" document for details of the advanced settings.) Mode: normally select "Normal". GNSS Bridge mode lets one communicate with the GNSS module directly from the USB port, for diagnostics (e.g., using the Ublox U-Center program). In this mode, the baud rate chosen for the external connection to USB is also used for the internal one to the GNSS. On the T-Echo, can enter this mode via NMEA config, escape this mode with a double-click. On the T-Beam can exit this mode (or any mode other than "Normal") via clicking the middle button, switching to Normal mode. (Long-press the first button on T-Beam v0.7.) Device ID: this is unique to each device and you cannot change it. The first hex digit is now always set to "8", to avoid possible duplication of a FLARM device ID. If your device ID (rather than ICAO ID) is registered with OGN, you will need to edit that registration. Aircraft ID: 6 hex digits. If your aircraft is registered, you can enter its ICAO ID, which is unique. You can obtain it from the authorities in your country. In the USA go here: https://registry.faa.gov/aircraftinquiry/Search/NNumberInquiry and in the search results look for "Mode S Code (Base 16 / Hex)". If you also have a transponder or some other device, setting all of them to the same ID will avoid duplicate reporting of the aircraft in OGN. ID type to use: You can choose ICAO (the ID entered above), or Device (the fixed device ID). (Additional ID types are available, see the "under the hood" document.) Keep in mind that the transmitted ID depends on TWO settings. E.g., if you enter the ICAO ID into the ID field but leave the ID Type as "device" then it will still transmit the device ID. Whether you choose ICAO ID, or device ID, you can register your chosen ID on http://ddb.glidernet.org/ as your aircraft. Then OGN viewers such as https://glidertracker.org/ will display your registration or contest ID. If you don't register it then only the cryptic (6 hex digits) transmitted ID will be shown in those viewers. Protocol: Choose "Latest" for compatibility with the new (2024) FLARM radio protocol. Choose "Legacy" for the older FLARM radio protocol. "Legacy" is visible to SoftRF devices and to OGN stations, but not to FLARMs. (FLARMs are visible to SoftRF devices set to either "Latest" or "Legacy" setting.) OGNTP is visible to OGN stations but invisible to FLARMS. If you are using this device to see and be seen by other FLARM-equipped gliders, choose "Latest". For towplanes: If the device is setting off collision alerts in gliders on tow (although that should not happen often), it can be configured to OGNTP (or Legacy), so that it does not alert FLARMs, but is still visible to OGN receivers on the ground for logging purposes. But it is best to have the tow plane transmit in a protocol that makes it visible to the other gliders. The FANET and PilotAware protocols are also available choices, commonly used by paragliders, and by light planes in the UK, respectively. Can also choose the ADS-L protocol. Note that you can also choose to operate in two protocols at once, see the "under the hood" document. Region (band): you must choose your geographical region, otherwise the radio will be on the wrong frequency and fail to communicate with the devices in other aircraft in your area. E.g., choose EU (868 MHz) in Europe, and US (915 MHz) in the USA and Canada. On devices other than the T-Beam the default region is "automatic", will be set upon first GNSS fix, but only saved for the future if the settings are saved manually. Aircraft type: E.g., glider, powered plane, etc. This is important for collision avoidance and situational awareness, and also for OGN tracking. This version of SoftRF added the aircraft type "winch", see the relevant section below. Alarm trigger: this setting chooses an algorithm to base collision warnings on. Recommended: "Latest" (unique to my version), which mimics what FLARM does, predicting near-future paths of circling aircraft. If neither aircraft is circling, this algorithm will automatically revert to the "Vector" method, which extrapolates straight lines. And if movement is not determined, that (in my version) will revert to "Distance", which warns simply by the distance between the aircraft. Thus, if you select "Latest", then ALL the algorithms are used as appropriate. If you select "None" then you will not get collision warnings. Volume: if a piezo buzzer is attached to the board for audible collision warnings, choose "Loud" here. (It is not quite loud enough.) If you get audible warnings via a connected device, e.g., XCsoar, then you can set the buzzer Volume to Low or Off. Built-in Bluetooth: On the T-Beam, leave Off, unless you want to connect to an external device (e.g., XCsoar) via Bluetooth, then choose SPP ("classic" BT) or LE ("low energy"). On the other devices, only BLE is available, and is turned on by default. NMEA output: this selects the port through which the data is sent out: Off (no data sent out), Serial (via the on-board serial interface, which also appears on the USB port), the auxiliary serial interface (T-Beam only), UDP (WiFi), TCP (another WiFi method), or Bluetooth. NMEA sentences: Data is sent to connected devices via text "sentences" in the NMEA format. You can turn on or off each of the following types of sentences: GNSS (position data), Sensors (e.g., barometric sensor, if you attach such to the board), Traffic (traffic data, reported to attached devices in the same format used by FLARM), and (in the advanced settings) External, meaning data arriving from external devices via other ports will be forwarded to this output port (see "data bridging"). Note that from version MB153 some of these settings are not simply on/off, but can control individual sentence subtype. E.g., enabling GNSS sentences in the basic settings only activates the RMC and GGA sentences. In the advanced settings (or via editing the settings.txt file) you can enter the value "3" (instead of "1") for this ("nmea_g") setting to also get GSA sentences (which are needed by Skydemon, for example). Similarly enter "3" in nmea_s to get LK8EX1 sentences in addition to PGRMZ. Enter "5" (or "7") in nmea_t to include FLARM messaging - see the under-the-hood document. NMEA secondary output: two output ports are allowed simultaneously, e.g., Bluetooth and USB. Or, UDP and TCP. Note: Bluetooth at the same time as another wireless option (UDP or TCP) is not a good idea, because they both use the same radio hardware and would thus be in contention. NMEA secondary output sentences: same choices as for the primary NMEA output. E.g., can choose to send only GNSS data to the primary port, and only traffic messages to the secondary. By default both NMEA output ports get the following sentences: (basic) GNSS, (basic) sensors, and (basic) traffic. I.e., GGA, RMC, RMZ, PFLAU, and PFLAA. Serial Port Baud Rate: the default is 38400, you can choose some other speed if your connected device cannot use 38400. E.g., the ILEC SN10 wants 19200. Speeds lower than 38400 may not be able to accept all the data, so pare down the output sentence types to what you really need. Stealth: if set to "On", your aircraft will not be shown on other aircraft' display, AND VICE VERSA (except at close range and in the case of collision danger). This is opting out of long-range "FLARM RADAR" mutual visibility. No track: this is similar to Stealth, but for the purpose of telling ground (OGN) stations to not report your position. Flight logging: Flight logging is possible on devices with a file system formatted in the SPI flash. This excludes the Thinknode M3. You may need to format the "drive" on a PC after connecting with a USB cable. This setting selects whether to write data to a flight log. "Airborne" means logging will automatically start on takeoff and stop after landing. "Traffic" also outputs data about nearby aircraft as comments in the flight log file. The interval, in seconds, between recorded fixes is settable, default is 4 seconds. See the "Flight Logging" section for more details. IGC encryption key: This is only shown if SoftRF is set to use the OGNTP protocol. The key is divided into 4 sections, each is 8 hexadecimal digits. For each section separately, if it's zero, it is shown as "00000000", otherwise as "88888888", masking the true key. If left as "88888888" then the current key is left intact. Overwrite with something else to change it. If set to all zeros then no encryption is done. The settings displayed, and adjusted, within the T-Echo or Thinknode M1 In the last display screen in the cycle of screens on the display, you will see something like this: Normal Glider _ < normal mode, aircraft type glider, relay landed-out aircraft US TX P:T+A A:LAT < US region, full power, Latest protocol + ADS-L alt-protocol, Latest alarm method Device: 60ABCD < device ID (internal, cannot be changed) Aircft: A23456 >> < aircraft ID - and this is transmitted (">>") --A34567 ++A45678 < ignore ID and follow ID NMEA1:BLT GT < NMEA output to Bluetooth, sends GNSS & Traffic data NMEA2:USB SD < NMEA output to USB, sends Sensors and Debug data When you double-click the mode button the device normally toggles the display backlight on or off. When this screen that shows various settings is displayed, if you double-click the mode button, it will instead go into change-settings mode. It will show one setting at a time on a page, like this: Aircraft Type: Glider Touching the "touch" button will change that setting, e.g., you will see: Aircraft Type: Towplane (Double-touch the touch button to move in the opposite direction.) A short-press of the mode button will switch to the next setting, e.g.: Frequency Band: EU And so forth. Note that after each "click" or "touch", it will take about 2 seconds for the next setting to appear on the screen - be patient. There are three ways to exit the change-settings mode: * single-click the mode button through all the settings until you see this: what to do next: cancel - use the touch button to select "cancel", "review", or "save" and then single-click the mode button. Or: * on any of the settings pages (no need to scroll through all the settings), double-click the mode button to save the new settings and reboot, or: * press the reset button to reboot without changing the settings. The settings accessible via this method are: * AIRCRAFT TYPE:Glider, Towplane Helicopter, Powered, Hangglider, Paraglider, Dropplane, Parachute, Balloon, UAV, Static. * RF PROTOCOL: LATEST, LEGACY, OGNTP, PAW, FANET, ADS-L. * ALTERNATE PROTOCOL: same list * RF BAND (REGION): EU, US, UK, AU, NZ, RU, CN, IN, IL, KR. (UK only for P3I.) * Collision prediction algorithm: Latest, Vector, Distance, None. * Relay mode: None, Landed, All. * Display units: Metric, Imperial, Mixed. * Display orientation: Track Up, North Up. * Aircraft ID (tedious) and ID type. Other settings are not adjustable this way. Edit the settings.txt file SoftRF creates in the file space that appears when you connect the T-Echo to a PC via USB. Or, can use a Bluetooth or USB terminal app and the HTML files mentioned above. About the settings file This fork of SoftRF stores the settings in a text file within the flash memory of the device, instead of an "EEPROM" binary block. (An exception is the Thinknode M3 which does not have flash memory for a file system, its settings are stored in EEPROM, but in a different format than other versions of SoftRF.) When SoftRF boots, it reads the existing settings from the file, or, if that fails, from "EEPROM", otherwise the default settings are used. Check the settings (in the web interface or Vlad's configuration web page) and click "save". In subsequent bootings, it will get the settings from the file, and ignore the EEPROM, unless the file is invalid or missing. If the file is invalid it will be automatically deleted. (Check the serial output for which line was invalid.) It is best to save a copy of the file in your phone or computer. On the T-Beam click the "download" button in web interface. You can restore the settings file (or an edited version of it) by clicking "upload". The file must be named "settings.txt" for upload. Uploading does not change the settings currently in effect, until SoftRF is rebooted. So, for example, in the web interface you can click "backup" (which copies settings.txt into settingb.txt), then upload an alternative settings.txt file, then click "swap". It will reboot with the same settings as before - but another "swap" will reboot with the alternative settings. The settings file is plain text, label,value pairs, one per line. The labels must be exactly as generated by the software - capitalization matters. Anything after a space (except for text fields such as pilot name) is a comment - some are added automatically, and can add some manually, e.g., "band,2 # US/CA". A "SoftRF,1" line must be included, but otherwise settings can be skipped in the file - any not mentioned in the file are set to their default values. Many of the lines in the settings file have comments added at the end of the line (following "#"), which explain the coding. That is handy when you are editing the file and want to know what code to enter after the comma. Here are the codes used for a few important settings: protocol (and altprotocol) 0 none /* for altprotocol */ 1 OGNTP 2 PAW /* PilotAware */ 5 FANET /* Skytraxx */ 6 Legacy /* Air V6 */ 7 Latest /* new 2024 Air V7 protocol */ 8 ADS-L band 0 AUTO /* will select the band after a GNSS fix is attained */ 1 EU /* 868.2 MHz band */ 2 US /* 915 MHz band */ 3 AU /* 921 MHz band */ 4 NZ /* 869.20 MHz band */ 5 RU /* 868.8 MHz band */ 6 CN /* 470 MHz band */ 7 UK /* treated as EU, unless P3I */ 8 IN /* 866.0 MHz band */ 9 IL /* 916.2 MHz band */ 10 KR /* 920.9 MHz band */ acft_type 0 unknown // marks as landed-out glider for relay purpose 1 glider 2 towplane 3 helicopter 4 parachute 5 dropplane 6 hangglider 7 paraglider 8 powered 15 static 16 winch // transmitted as static with variable altitude alarm 0 none 1 distance 2 vector 3 latest volume (buzzer) 0 off 1 low // on some devices this is same as "full" 2 full 3 external (active buzzer) nmea_out, nmea_out2, gdl90, gdl90_in and d1090 0 none 1 main serial 2 UDP 3 TCP 4 USB (same as main serial) 5 Bluetooth 6 aux serial baud_rate and baudrate2 0 default (38400 for main serial, OFF for aux serial) 1 4800 2 9600 3 19200 4 38400 5 57600 6 115200 bluetooth 0 off 1 classic (SPP) // (T-Beam only) 2 BLE // (T-Echo, M1, M3, T1000-E can only use BLE) logflight 0 none 1 always 2 airborne 3 also record close traffic Many settings use 0 for "no" and 1 for "yes", e.g., stealth, no_track, alarmlog, compflash. For more details about the "advanced" settings see the "under the hood" document. On the T-Beam one can view and edit the advanced settings in a web page, which looks similar to the text file, with settings labels, values, and comments. Collision alarms When a nearby aircraft is possibly on a collision course, SoftRF generates various types of alarms. The PFLAA and PFLAU NMEA sentences sent to connected devices include the alarm level in the standard format. Many external devices (e.g., XCsoar on a phone or tablet, or XCvario) give audio and visual indications as a result. In addition, SoftRF can provide its own audio (buzzer or voice) and visual (strobe) indications. On a T-Beam (v1.x) short-pressing the middle button activates a simple demo/test of the audio and visual alarms for 9 seconds. (It also causes the PFLAU output sentences to pretend it is airborne and there is a collision alarm, that can help test attached devices such a FLARMviewer, XCsoar, or a canopy flasher.) (On the old T-Beam v0.7 long-press the first button (between the slide switch and the reset button) for the same function.) The OLED will show "ALARM DEMO" during the demo period. Collision alarms are separated into 3 "alarm levels". Level 3 (high), the most urgent one, is triggered when a collision may happen within 9 seconds. Level 2 (medium) means a collision predicted within 13 seconds, and level 1 (low) within 19 seconds (roughly one typical turn of a glider in a thermal). The alarm indications differ between these levels. To avoid distraction, when SoftRF indicates a collision alarm with a buzzer or voice, it does not repeat that right away for the same aircraft, unless the alarm level has increased. After 9 seconds it may repeat. Here is a summary of the indications for each alarm level: Buzzer: single beep for alarm level 1, 2 faster beeps for level 2, and 5 quick beeps for level 3. In addition, the buzzer tone (if a passive type) increases in pitch with the alarm level. If there is more than one threat aircraft at the same time the 1 or 2 beeps are "doubled up" (or the 5 beeps are extended to 7). Voice: for levels 1 and 2 the format is: "traffic, 2 o'clock high". For level 3 it uses the word "danger" instead of "traffic", e.g., "danger, ahead low". Strobe: for any alarm level, a triple flash every 750 ms. Each triple flash is 50 ms on, 50 ms off, repeat twice more. The strobe output also flashes when there is no collision alarm, if that setting is chosen. It then emits a triple flash every 2400 ms: 40 ms on, 50 ms off, repeat twice more. Winch mode The "aircraft type" winch is intended for a device mounted on the ground (e.g., at the winch): The transmitted aircraft type is "static", and the transmitted altitude alternates between 100, 200, 300 and 400 meters above ground level (1 second each, then repeat). While in winch mode, clicking the middle button of the T-Beam (v1.x) toggles between full power transmissions and no transmissions. This allows turning on the warnings when launches are about to happen, and pause them when launches are paused. The transmissions being active is denoted by both the OLED display and the blue LED. Note: in winch mode, the middle-button function of activating a demo of the audio and visual collision alarms is not available. (On the old T-Beam v0.7 long-press the first button (between the slide switch and the reset button) for same function.) Uploading voice files (T-Beam only) If the voice warnings are activated but audio data has not been uploaded, the warnings will say the single word "traffic". To get the full voice messages, download the waves.tar file from this page: https://github.com/moshe-braner/SoftRF/tree/master/software/data/Audio Then start up SoftRF, access the web interface, click the "upload" button at the bottom of the status web page, browse to the location where you saved the "waves.tar" file, and click "upload". After that, it should say "17 WAV files found" at the bottom of the status page (refresh it). The audio data (waves.tar) is stored in the file-system ("SPIFFS") area within the T-Beam's flash memory. It is not erased when new firmware is uploaded. If you need to erase it, use the "clear" button in the web interface. If you want to create and upload customized audio files (e.g., in another language), use the supplied waves.tar file as a template. 17 files are needed, with the file names and meanings the same as in the supplied file. The WAV files must be PCM, mono, 8-bit, with a sample rate of 8000 Hz. I have used the free PC app "Wavosaur" to convert WAV files to this format. The total size of the WAV files should be no more than about 150 KB. Then use a file-compression utility (such as 7ZIP) to combine the 17 WAV files into one TAR file (not a ZIP file). The order of the WAV files within the TAR file does not matter. The name of the TAR file (unlike the WAV files within) does not matter, it will always be saved into SPIFFS as "waves.tar". How to connect external devices SoftRF can send data out to other devices, in several formats. Most commonly, the format is NMEA sentences, which are lines of text that start with a code that identifies the type of data. For example: $PFLAU,1,0,2,1,0,14,2,0,57,A8B031*7C which happens to be a FLARM-like sentence describing a nearby aircraft. GNSS data is sent out in NMEA sentences along with the traffic data. The external device can be a dedicated display for traffic data, for example: https://github.com/lyusupov/SoftRF/wiki/SkyView-EZ (and my github repository includes an improved version of the firmware for SkyView: https://github.com/moshe-braner/SoftRF/tree/master/software/firmware/binaries/ESP32/SkyView Alternatively, the external device can be a glide computer, such as the ILEC SN10, or an e-reader, phone or tablet running the XCsoar or Tophat software. In some cases such a device benefits from SoftRF also sending position (GNSS) data, e.g., XCsoar or Tophat on an e-reader which does not have GNSS hardware. The data can be sent out via a serial cable, a USB cable, WiFi (UDP or TCP), or Bluetooth (classic or LE). The wireless methods (WiFi or Bluetooth) are convenient in that no cable is needed. Only need to choose the relevant SoftRF settings as described above. Instructions on how to connect to XCSoar (or Tophat) via UDP (WiFi) are here: https://github.com/lyusupov/SoftRF/wiki/Prime-Edition-MkII.-Quick-start - the result is that traffic becomes visible right on the moving map in XCsoar, the FLARM RADAR screen is available, and you can get spoken collision warnings such as "Traffic, 2 O'Clock, High". The wired methods require additional hardware. At the least, a USB cable. For example, a PC can be connected via a USB cable and one can run terminal software on it (e.g., "Termite") that will display the data coming out of SoftRF. That is useful for debugging. But most external devices of interest do not have a USB interface that is capable of emulating a serial port. Instead, one can use two serial ports (UART) that are built into the T-Beam. Two pins at the corner of the board are labeled TX (transmit data) and RX (receive data), they are the primary serial port. But the RX pin is not actually usable, since it is controlled by the USB port. The TX pin of course needs to be used in combination with one of the Ground pins to complete the circuit. If serial data input is needed, can use the VP pin via the "Serial Port input pin" setting. Additionally, this version of SoftRF now supports a secondary serial port, using pins 39 ("VN") (RX) and 4 (TX). (On a T-Beam v0.7 input is on "VP" rather than "VN") But, these pins operate at TTL voltage levels (0v and about +3V). Many external devices are set up to use RS232 voltage levels, i.e., several volts negative and several volts positive. To bridge such devices to the TTL UART, one needs to add a voltage-level conversion interface circuit, e.g., based on the MAX232 chip. Such a chip can be powered from the 3.3V pins of the T-Beam. This is not hard to do in principle, but there are some issues. There may be little spare space inside the case holding the T-Beam. And some of the cheap MAX232-like chips may be unstable and oscillate, resulting in excessive power draw from the board. To protect the circuit, I suggest: (1) These conversion boards usually have two independent pairs of conversion circuits, thus one is used to connect to the T-Beam UART and one is not used. Connect unused TTL _inputs_ of the MAX232 board to +3.3V (via a resistor, about 22Kohms), do not leave them open-circuit. And: (2) connect the MAX232 board power input to the 3.3V source via a resistor (about 39 ohms) to limit the current in case it misbehaves. Before assembling such a converter, can try and use the T-Beam's secondary serial port with the "invert" setting instead. See details in the Data Bridging section below. Once connected, be sure to set the baud rate on the external device to match what SoftRF is using (38400 baud by default), or vice versa (my version of SoftRF allows you to choose the baud rate). Note that when the T-Beam starts up, it send some data at 115,200 baud, and then switches to the chosen baud rate. Devices that detect the baud rate automatically (e.g., the Sotecc canopy flasher) may get confused by that, so set the device to use a specific baud rate without auto-detection. If desired, a barometric sensor of the BMP280 (or BMP180) type can be connected to the T-Beam via an I2C connection. Use pins 21 (SDA) and 22 (SCL). Or can connect the barometric sensor to pins 13 (SDA) and 2 (SCL). (But be sure to connect pin 2 in a way that is easy to disconnect - see the section "Installing firmware for the first time".) Can use the same pins as the OLED display, they can share them. (The AXP PMU too is using pins 21,22.) Data from the barometric sensor will be sent out as NMEA sentences if the "sensors" NMEA output is turned on in the setttings. Connecting an SD card adapter Finally, a micro-SD card adapter can also be connected to the T-Beam. See the "under the hood" document for details on how to connect an SD adapter. Once the adapter is connected, prepare a micro-SD card. The card must be 32 GB or smaller (1GB is plenty), formatted FAT32. To reduce the wear on the SD card from re-writing the same sectors, it is best to format with a small "allocation size" of 1024 bytes (or 512 or 2048). Create two folders at the top level: "firmware" and "logs". In the "firmware" folder you can put a firmware update file (renamed the generic name SoftRF.bin), and then when SoftRF boots it will update the firmware - and delete that file. Once the card is installed, you will normally not need to physically access it (other than for firmware updates via the card, but those can normally be done via wifi instead). The web interface allows you to list the flight logs (which are kept in the "logs" folder), download the latest flight log or any file in the list, and to clear the flight logs to keep the list uncluttered. (Clearing moves them to an "old" subfolder, click "empty trash" to delete all files in the subfolder.) Flight logging The T-Beam's flash memory has very little space avaiable for flight logging. Also, the number of times flash memory (on either the T-Beam or the T-Echo) can be re-written is limited. After about 2000 hours of logging at 4 second intervals there is some possibility of the flash memory starting to fail. For most users this is not a problem. Flight logging on the T-Beam can be done into the volatile RAM memory space (PSRAM). Optionally flight logs can also be written to the flash memory in a compressed format. Or, logging can be done to an SD card if one is attached - see the section about "connecting an SD card adapter" for details on that option. Logging to RAM is limited to 3.5 megabytes, and only a single combined log file between starting up SoftRF and shutting it down. Most importantly, the RAM is volatile, so the log file must be downloaded (through the web interface to your phone or computer) before turning off or restarting the T-Beam. An option is to also archive the flight log in a compressed format into the flash memory ("SPIFFS"), as long as there is space. This needs to be enabled by changing the "compflash" setting to "1". The log files in flash memory persist even when the power is turned off. The space available depends on what else is stored there (e.g., voice files), but can be about 12 hours of flight recording at an interval of 4 seconds. The logging destination, SD vs. RAM (+ optionally flash), on a T-Beam is determined automatically, by whether an SD file system is "mounted". The status web page will show a message as appropriate. If logging is to RAM and/or flash then buttons will appear saying "download current", "List Archived" and "Clear Archive", and if a log is in progress, "Download Current" and "Clear Current". With an SD card there will be buttons for "Download Latest", "List Files" and "Clear Files". Flight logging is possible on the nRF52840 devices within the nonvolatile flash memory of the device. This excludes the Thinknode M3 which does not have SPI flash. You may need to format the "drive" on a PC after connecting with a USB cable. The flight log files are, by default, not compressed. The space for flight logs on the T-Echo is limited to about 2 megabytes - which is enough for about 12 hours of flight recording at one fix every second. If there is not enough free space for 3 hours of logging (at the chosen logging interval), a log will not be started. So it is best to select "airborne" logging and a less-frequent logging interval, and to download the flight logs and clear that space periodically between flights. Also, you have to choose whether to use the space mostly for flight logging, or mostly for the optional aircraft database, as explained here: https://github.com/lyusupov/SoftRF/wiki/Badge-Edition.-Aircrafts-database Another option in this version of SoftRF is to optionally write the flight logs in a compressed format. This needs to be enabled by changing the "compflash" setting to "1". See below on how to de-compress the files. Before creating flight logs, be sure to enter your chosen pilot name, aircraft type (model), aircraft registration ID, and callsign (contest/tail ID) into the corresponding fields (igc_pilot, etc) in the SoftRF settings. (This can be done by downloading the settings.txt file, editing it, and uploading.) This information will be embedded into the IGC flight log files SoftRf will create. Flight logging can be done in two different modes. In the "Airborne" mode the file is started when a takeoff is detected, and finalized upon landing - a new file is created upon the next takeoff. In the "Always" mode data is collected continuously into one file. "Traffic" mode is same as "Airborne" but also outputs data about nearby aircraft as comments in the flight log file. If the "log alarms" setting is enabled, data about alarm traffic is output to the flight log even if not in "traffic" mode. The simple compression algorithm is designed to make the position ("B") records in the IGC file about 5 times smaller. It does not compress other lines in the file. In particular, if the option to log nearby traffic as comments within the flight log is used, and there is a lot of nearby traffic, the file will be almost as large as the uncompressed version. To download the flight log(s) from the T-Beam use the "download" or "list" buttons in the flight logs section of the web page. Compressed log files on the T-Beam are automatically decompressed when the download links in the file list are clicked. To download log files from the T-Echo, M1, or T1000-E, connect to a computer via USB, and a files window will open. Download files by dragging them out of there. Note that SoftRF on a T-Echo cannot write (flight logs or settings) to the files area while it is connected to a computer. To download compressed log files from the T-Echo, M1, or T1000-E, there are two options. One can simply drag the compressed files (with the suffix .IGZ) to a computer, and decompress them there. A Windows (only) program "igz2igc.exe" to do that is available in the folder https://github.com/moshe-braner/SoftRF/tree/master/software/app - it is a command-line program, but if you drag and drop a .IGZ file onto the program's icon it will be decompressed into a .IGC file of the same name. The IGC file will be written to the same folder where the IGZ file is, so do not drag and drop a file onto this program directly from the window showing the T-Echo files! Copy the IGZ file to the computer's hard drive first, then drag and drop this copy onto the program icon. The other option for downloading compressed log files from the T-Echo is to have SoftRF decompress them. Follow these steps: * connect the T-Echo to a computer (or phone with files manager app) so a files window opens up. * delete old flight logs no longer needed on the T-Echo (maybe downloaded in the past). * note that the date stamp of the files on the T-Echo is incorrect. * you can identify the flight date from the first three characters in the file name: last digit of year, then month and day, using the coding 1-9 and then A-V meaning 10-31. * copy the .IGZ files from the T-Echo to the computer for safety. * if necessary, delete some files on the T-Echo to make room, can copy them back later. * need free space at least 6 times bigger than the size of the file(s) you want to decompress. * rename the xxxxxxxx.IGZ file(s) xxxxxxxx.IGX - ignore warnings from the computer about that. * "safely disconnect" from the computer, since the T-Echo cannot write files while connected. * reboot the T-Echo (press the reset button). * after booting, SoftRF will look for .IGX file(s) and decompress them. * the e-paper screen will say, for example, "DECOMP 5A9_1" when decompressing 5A9xxxx1.IGZ * when done, it will say "DECOMP DONE". * the .IGX files will be deleted once decompressed. * reconnect to the computer and look for the .IGC file(s) created. * if there was not enough file space to decompress all of the .IGX files, some may still exist. * download the IGC files(s) to the computer and delete them on the T-Echo. * if any .IGX files remain (or you drag them back onto the T-Echo) repeat from "safely disconnect". When logging to an SD card or to flash memory, if the T-Beam is shut down via a long-press of the pushbutton (on v1.x boards - or if the alarm-demo is activated on a v0.7 board via long-press of the button), or if any of the related buttons in the web-interface status page are clicked, the flight log (if still active) will be finalized. If the power supply is simply disconnected, the flight log will likely be valid, but may be missing the last few minutes of data. If the T-Echo is shut down via a long press of the Mode button, the flight log (if still active) will be finalized and remain in the flash memory. While connected to a computer via USB, additional flight logging may be blocked. To ensure the flight log is complete (as of that moment), click the Mode button before connecting to a computer. SoftRF will switch to another display page as normal, but also will silently finalize the flight log. The flight log files are "secured" (have G-records appended), and will be accepted as valid on Weglide and OLC. But they are not IGC-certified, so cannot be used for badges and records. Data Bridging A feature of this version of SoftRF, for now only on the T-Beam versions 0.7 - 1.2, is "data bridging". NMEA sentences arriving from external devices are copied to the NMEA destination devices (if the "external" NMEA sentences are activated in the settings for each destination device). But sentences are not echoed back to the same port they came from. GNSS (GPS) position sentences, and FLARM-format traffic messages, from external devices, are not forwarded. That is since they also originate from within SoftRF, thus any that arrive from external sources are redundant, and may be an echo of what was already sent from SoftRF. For example: connect an S7 vario via a bi-directional serial cable. (See above and below about how to get a bidirectional serial port on the T-Beam.) Configure SoftRF to send it position and traffic sentences. The S7 will echo them back on the same cable, along with its own added sentences carrying vario data (climb rate, airspeed, etc). If XCsoar on a phone or tablet is receiving data from SoftRF via WiFi or Bluetooth or the other serial port, the S7 vario data can also be forwarded to XCsoar by SoftRF. And S7 commands sent from XCsoar will be forwarded back to the S7. This can eliminate the need for a Bluetooth dongle. For data bridging, input from TCP is only active if TCP is set up as an NMEA destination. For NMEA via UDP, port 10110 is used. If UDP is chosen for NMEA output, then that is on port 10110, and UDP input is on port 4352. This version also adds the ability to make the main serial port bidirectional. The "RX" pin may work when the USB jack is not powered, but not when it is. And certainly not when the USB port is receiving serial data. You can't have two sources competing for control of the same input pin. Instead, a new option in the settings allows using pin 36 ("VP") instead of "RX". (This may not work well at high baud rates on the T-Beam v0.7, since it has a small capacitor between GPIO36 and GPIO37.) If this option is selected, serial input from USB is disabled. Serial output to USB (and to any serial device attached to "TX") is not affected. This version also adds the possible use of a second serial port, using pins RX=39 ("VN") and TX=4. (VP instead of VN on the T-Beam v0.7.) Note that pin 4 is shared with the red LED on the T-Beam (v1.x) board. When the second serial port is used, this LED will turn off, and just flicker on when data is being sent (which is actually useful). (With the "invert" option the LED will be lit, and flicker dimmer when transmitting data.) With two serial ports, the data bridging can forward data from one to the other, or combine data from both and send to a wireless stream. This can eliminate the need for an IOIO box. See pinout diagram here: https://github.com/moshe-braner/SoftRF/blob/master/software/firmware/documentation/T-beam_wiring.jpg On the second serial port only, can invert the logic. The voltage level is TTL, not RS232. But with inverted logic, you can try and connect to other devices that claim to be "RS232" but will actually accept zero volts as "low" and 3V as "high" without needing a conversion chip such as MAX232. (When the second serial port is "inverted", the red LED will be brightly lit most of the time, flickering off while sending data.) When using this connection method, need to protect the T-Beam's input pin from the high positive and negative voltages on a real RS232 line. If input is not needed, leave it unconnected. Otherwise, suggest a 3.3V zener diode from the pin to ground in parallel with a schottky diode, and a 1.2K resistor between the pin and the external wire. At least on the input wire, although the output wire may be accidentally connected to an RS232 output, so should be protected too. The input wire also needs a pull-up resistor, 10 Kohms from the pin to +3.3V. See an example protection circuit here: https://github.com/moshe-braner/SoftRF/blob/master/software/firmware/documentation/rs232_wiring.jpg Connecting an ADS-B receiver SoftRF can accept traffic data from an external device (typically an ADS-B receiver) in GDL90 format, and integrate it into its internal table of tracked traffic. In practice the input port can only be serial, WiFi/UDP, or WiFi/TCP. Not Bluetooth, because both SoftRF and the ADS-B receiver probably expect a phone on the other end of the BT connection, and choose the master/slave role for that, thus they won't connect to each other. Only GDL90 other-ship traffic messages are processed, all other message types are ignored. Traffic more than 15 nm away or more than 2000 meters above or below is ignored. NMEA messages are not sent to the GDL90-input source. Alternatively, from version MB130, on a T-Beam v1.x, SoftRF can use a hardwired GNS5892R ADS-B receiver module, which is small enough to fit inside the same case as a T-Beam. See wiring diagram here (on T-Beam v0.7 use "VP" rather than "VN"): https://github.com/moshe-braner/SoftRF/blob/master/software/firmware/documentation/GNS5892_wiring.jpg Photos of one actual installation: https://github.com/moshe-braner/SoftRF/blob/master/software/firmware/documentation/GNS5892_T_Beam_1_.jpg https://github.com/moshe-braner/SoftRF/blob/master/software/firmware/documentation/GNS5892_T_Beam_2_.jpg The antenna can be a vertical wire, about 65 mm long. Or can install a short coaxial cable from the module to an added jack on the case (e.g., SMA, see the photos) to which one can then connect a short whip antenna, either tuned to 1090 MHz or even one that is designed for a different frequency in the 800-1200 MHz range. The ADS-B signals are transmitted by transponders at high power, about 1000 times stronger than FLARM signals, thus are easy to receive at the intended range even with a poor antenna. (Anything more than 15 nautical miles away - or more than 2000 meters higher - is ignored by the software.) When installed, the GNS5892 takes up the auxilliary serial port, making it unavailable for any other use. The auxilliary serial port will appear as "disabled" in its baud-rate setting, but will actually be active at 921600 baud - keep those wires short. Note: ADS-B traffic data output is for situational awareness. Collision alarms are not generated for TIS-B traffic (due to imprecise location), and the vector (rather than the "latest") algorithm is used to predict collisions with ADS-R traffic (due to time delays). Connecting to XCvario XCvario can be connected via a custom-built serial cable. XCvario claims to work even at TTL levels, thus an RS232 level conversion chip is not required. XCvario, too, can then forward the data from SoftRF, along with its own added data, to other devices, via a wired or wireless connection. A wireless connection to XCvario is more difficult. With the stock XCvario firmware and my version of SoftRF there is now a way to do it: In SoftRF select WiFi client (SSID XCVario-XXXX, password xcvario-21), and TCP Client to IP address 192.168.4.1 and port 8880. Activate TCP output as the primary NMEA output. Also activate UDP output as the secondary NMEA output. In XCvario make sure that "wireless" is WiFi (Master or Standalone, and not Bluetooth) and that the wireless data route is connected to "vario". In XCsoar connect to the same XCvario WiFi network. Configure two "devices" in XCsoar. One a TCP client on port 8880, using XCvario protocol. The other a UDP listener on port 10110, using FLARM protocol. Magically, it works! With custom firmware (and possibly a future official version) XCvario can also accept the data on port 2000, which frees port 8880 to serve other functions in XCvario. Updating the firmware on the T-Beam When it's time install a newer version of the SoftRF firmware on your T-Beam, the easiest way is to do it via WiFi, also called On The Air (OTA). Note: if your T-Beam currently has the "RC9" version of SoftRF, do not update the firmware via WiFi. It will fail! There is a bug in that version. Use the USB method (above) for the initial installation, of either my version of SoftRF, or version 1.0 (or higher) of the main line SoftRF. After that, it will be possible to update the firmware to later versions via WiFi. Here are step by step instructions for OTA firmware update: * Download the .zip file with the most recent firmware. My version is here: https://github.com/moshe-braner/SoftRF/tree/master/software/firmware/binaries/ESP32/SoftRF * Unzip the firmware file, the actual firmware file has the suffix .bin and its size is about 1.7 megabytes. * Fully charge the battery in your SoftRF device. * Boot up SoftRF. * Connect your PC/Tablet/Cellphone to the Wi-Fi Access Point created by SoftRF SSID: SoftRF-XXXXXX Key: 12345678 (If SoftRF is already set up to connect as a client to an external WiFi network, and if this network is in range, you can skip this step, and have the PC/Tablet/Cellphone connected to the same external network.) * Open up a browser and proceed to the URL (IP address): 192.168.1.1 (If using an external network, press the button repeatedly until you see the OLED screen showing the needed IP address.) * Inspect the firmware version listed in the Status web page that opens up. * Go to the Settings page by clicking the button at the bottom-left of the Status page. * Write down your SoftRF settings, or take a screen shot of the SoftRF web-interface settings page from your browser. Return to the status page. * Click the "Firmware update" button in the SoftRF status web page. * Click the "Choose file" button and select the .bin file with the new firmware. * Click the "Update" button. * Wait until the web page says "UPDATE DONE, REBOOTING". This may take a minute or more, be patient. There is no indication of progress on the web page, but you can see a counter incrementing on the OLED display if so equipped. * The blue LED on the T-Beam will flash once a second while updating, and will stay on for several seconds when done. If instead it starts flashing 4 times per second (before rebooting), that means the update failed. * When the update is completed do not touch anything for another minute, or you may get a "bricked" device. The SoftRF device typically reboots automatically. If it does not reboot itself after a minute or two, press the reset (third) button on the T-Beam to force it to reboot. * Re-connect to the SoftRF Wi-Fi Access Point and inspect the firmware version listed on the status page. It should now show the new version. The version is also shown on the OLED, along with whether the user settings have been preserved, or replaced with the defaults. * Check and restore your settings if necessary. Depending on the old and new firmware versions, some, all, or none of your settings will still be remembered (where different from the defaults). Note: if you are using the wifi network created by SoftRF, and there is a strong signal from an external network which offers internet connection, your PC/Tablet/Cellphone may switch to the other network in the middle of the update. In that case the update will not complete - the OLED display will stop incrementing the "UPDATE" count. Try again with a different device, or farther from the external network, or turn the external network off, or change SoftRF's settings so that it will connect to the external network instead of creating its own. If this firmware update method fails (and it always fails if starting from the "rc9" firmware version), proceed to the first-time firmware installation procedure (via USB) mentioned above in this document. That usually works, even if the T-Beam is unable to boot after a failed update. See similar instructions with screen shots here: https://github.com/lyusupov/SoftRF/wiki/Firmware-update-%28Web-method%29#esp32 Updating the firmware on the T-Echo, M1, M3 or T1000-E These devices include a "bootloader" which makes it easy to update the firmware: * Download an appropriate version of SoftRF firmware, from here: https://github.com/moshe-braner/SoftRF/tree/master/software/firmware/binaries/nRF52840/SoftRF/MassStorage * Unzip the file and make sure you now have a .uf2 file. * Connect the SoftRF device to your PC by means of a USB cable * Enter "DFU mode", using the procedure that fits your device: - on the T-Echo or M1, double click (two clicks within 0.5 seconds) the RESET button - on the M3, press and hold the button for close to 20 seconds - on the T1000-E, flip the magnetic USB connector twice while holding the button pressed (see short video here: https://github.com/lyusupov/SoftRF/wiki/Card-Edition.-Quick-start ) - or, for any of these devices, connect from https://skysignals.app/mysoftrf/ and click "update firmware" - or, on any device, from a terminal program, send it the NMEA sentence $PSRFC,DFU*2F * A virtual mass storage device labeled TECHOBOOT, T1000-E or ThinknodeM1/3 will then appear in your computer. * Drag the .uf2 firmware file and drop it into the window showing the virtual drive contents. * Wait until the file transfer is complete, it takes about 30 seconds. The window will disappear and the device will normally reboot itself. See similar instructions here: https://github.com/lyusupov/SoftRF/blob/master/software/firmware/binaries/README.md#nrf52840 PART 2: UNDER THE HOOD - see separate document, here: https://raw.githubusercontent.com/moshe-braner/SoftRF/refs/heads/master/software/firmware/documentation/SoftRF_MB_under_the_hood.txt