Polska wersja tego pliku dostępna jest [tutaj](README_pl.md).
**VP-Digi** is a functional, affordable, easy-to-assemble, and configure STM32-based APRS digipeater controller with a built-in KISS modem.
**VP-Digi** is a functional, affordable, easy-to-assemble, and configure STM32-based APRS digipeater controller with a built-in KISS modem. VP-Digi can also run on [AIOC](https://github.com/skuep/AIOC)!
* FX.25 (AX.25 with error correction) coder/decoder, fully compatible with [Direwolf](https://github.com/wb2osz/direwolf) and [UZ7HO Soundmodem](http://uz7.ho.ua/packetradio.htm)
@ -31,7 +31,7 @@ The user manual and technical description are available [here](doc/manual.md).
## Source code
The firmware was written using STM32CubeIDE, and you should be able to import this repository directly into the IDE. You can get the source code using:
You can get the source code using:
```bash
git clone https://github.com/sq8vps/vp-digi.git
@ -42,7 +42,23 @@ Since version 2.0.0, you will also need to get the appropriate submodule ([LwFEC
git submodule init
git submodule update
```
Since version 2.0.0, there is also a possibility to build the firmware with or without FX.25 protocol support. The `ENABLE_FX25` symbol must be defined to enable FX.25 support. On STM32CubeIDE, this can be done under *Project->Properties->C/C++ Build->Settings->Preprocessor->Defined symbols*.
Since version 2.2.0, VP-Digi can also run on [AIOC](https://github.com/skuep/AIOC). The source code base is the same for the "Blue Pill" board and AIOC.
However, there are two STM32CubeMX configuration files: `vp-digi.ioc` and `vp-digi_aioc.ioc`. In order to be able to compile and run the project, you need to:
1. Open `vp-digi.ioc` or `vp-digi_aioc.ioc` in STM32CubeMX, depending on your target platform.
2. Generate files for the IDE/toolchain of your choice. Make sure *Generate Under Root* is checked. Under the *Code Generator* tab make sure *Generate peripheral initialization as a pair of '.c/.h' files per peripheral* is checked.
3. Import the generated project to your IDE.
4. If you want to use FX.25, you need to include the `lwfec` directory in your build. In STM32CubeIDE, this can be done under *Project->Properties->C/C++ General->Paths and Symbols* in *Includes* and *Source Locations* tabs.
5. If you are targetting the "Blue Pill" board with STM32F103Cx, then you need to adjust the optimization level to `Optimize For Size (-Os)` for a release build or `Optimize for Debug (-Og)` for a debug build.
On STM32CubeIDE, this can be done under *Project->Properties->C/C++ Build->Settings->MCU GCC Compiler->Optimization*. Otherwise, the program won't fit in the flash memory.
Since version 2.0.0, there is also a possibility to build the firmware with or without FX.25 protocol support. The `ENABLE_FX25` symbol must be defined to enable FX.25 support.
The easiest way is to define this symbol in `defines.h`. Alternatively, on STM32CubeIDE, this can be done under *Project->Properties->C/C++ Build->Settings->MCU GCC Compiler->Preprocessor->Defined symbols*.
When rebulding the project for different platform the code must be regenerated, as explained in the instructions above.
However, since some files remain and some are not regenerated, you need to manually remove them beforehand. This includes removing the `Drivers`, `Middlewares`, `USB_DEVICE` except `USB_DEVICE/App/usbd_cdc_if.c`,
`Core/Startup` directories, the `stm32f*_hal_msp.c`, `syscalls.c`, `sysmem.c`, `gpio.c`, `system_stm32f*.c` files from the `Core/Src` directory, `stm32f*_it.h`, `stm32f*_hal_conf.h`, and `gpio.h` files from the `Core/Inc` directory,
and `.project`, `.cproject`, and `.mxproject` from the main directory.
**VP-Digi** jest funkcjonalnym, tanim, łatwym w budowie i konfiguracji kontrolerem digipeatera APRS opartym na procesorze STM32 z wbudowanym TNC KISS.
**VP-Digi** jest funkcjonalnym, tanim, łatwym w budowie i konfiguracji kontrolerem digipeatera APRS opartym na procesorze STM32 z wbudowanym TNC KISS. VP-Digi może również działać na [AIOC](https://github.com/skuep/AIOC)!
* Wiele modemów:
* 1200 Bd AFSK Bell 202 (standard VHF)
* 300 Bd AFSK Bell 103 (standard HF)
* 9600 Bd GFSK G3RUH (standard UHF)
* 1200 Bd AFSK V.23
* Generowanie sygnału z użyciem PWM (lub R2R - niezalecane)
* Obsługa FX.25 (AX.25 z korekcją błędów), w pełni kompatybilna z [Direwolf](https://github.com/wb2osz/direwolf) i [UZ7HO Soundmodem](http://uz7.ho.ua/packetradio.htm)
@ -40,7 +40,22 @@ Począwszy od wersji 2.0.0 konieczne jest także pobranie odpowiedniego modułu
git submodule init
git submodule update
```
Począwszy od wersji 2.0.0 istnieje również możliwość kompilowania oprogramowania z obsługą lub bez obsługi protokołu FX.25. Symbol `ENABLE_FX25` musi zostać zdefiniowany, aby włączyć obsługę FX.25. W STM32CubeIDE można to zrobić w menu *Project->Properties->C/C++ Build->Settings->Preprocessor->Defined symbols*.
Począwszy od wersji 2.2.0, VP-Digi może także działać na AIOC [AIOC](https://github.com/skuep/AIOC). Kod źródłowy jest wspólny dla płytek "Blue Pill" i AIOC.
Do wyboru są dwa pliki konfiguracyjne do STM32CubeMX: `vp-digi.ioc` i `vp-digi_aioc.ioc`. W celu poprawnej kompilacji i uruchomienia projektu należy:
1. Otworzyć `vp-digi.ioc` albo `vp-digi_aioc.ioc` w STM32CubeMX, w zależności od docelowej platformy.
2. Wygenerować pliki dla wybranego IDE/toolchainu. Należy zaznaczyć *Generate Under Root*. W zakładce *Code Generator* należy zaznaczyć *Generate peripheral initialization as a pair of '.c/.h' files per peripheral*.
3. Zaimportować projekt do wybranego IDE.
4. W celu obsługi FX.25 należy dołączyć katalog `lwfec` do kompilacji. W STM32CubeIDE można to zrobić w zakładkach *Project->Properties->C/C++ General->Paths and Symbols* in *Includes* i *Source Locations*.
5. Jeśli projekt kompilowany jest na płytkę "Blue Pill" z mikrokontrolerem STM32F103Cx, to konieczne jest ustawienie poziomu optymalizacji na `Optimize For Size (-Os)` dla kompilacji release lub `Optimize for Debug (-Og)` dla kompilacji debug.
W STM32CubeIDE można to zrobić w zakładce *Project->Properties->C/C++ Build->Settings->MCU GCC Compiler->Optimization*. W przeciwnym wypadku program nie zmieści się w pamięci.
Począwszy od wersji 2.0.0 istnieje również możliwość kompilowania oprogramowania z obsługą lub bez obsługi protokołu FX.25.
Symbol `ENABLE_FX25` musi zostać zdefiniowany, aby włączyć obsługę FX.25. W STM32CubeIDE można to zrobić w menu *Project->Properties->C/C++ Build->Settings->MCU GCC Compiler->Preprocessor->Defined symbols*.
W przypadku ponownego budowania projektu dla innej platformy, należy przejść przez kroki opisane powyżej. Niestety pewne pliki mogą pozostać lub nie być ponownie wygenerowane, co poskutkuje błędem kompilacji.
Należy usunąć katalogi `Drivers`, `Middlewares`, `USB_DEVICE` z wyłączeniem pliku `USB_DEVICE/App/usbd_cdc_if.c`,
`Core/Startup`, pliki `stm32f*_hal_msp.c`, `syscalls.c`, `sysmem.c`, `gpio.c`, `system_stm32f*.c` z katalogu `Core/Src`, `stm32f*_it.h`, `stm32f*_hal_conf.h`, `gpio.h` z katalogu `Core/Inc` oraz `.project`, `.cproject` i `.mxproject` z głównego katalogu.
- [2.2.3. Received packet view](#223-received-packet-view)
- [2.3. KISS mode](#23-kiss-mode)
- [2.4. Signal level setting](#24-signal-level-setting)
- [2.5. Programming](#25-programming)
@ -96,7 +97,6 @@ The following commands are available in configuration mode:
- `quiet TIME` – sets the time that must elapse between channel release and transmission start. Value in milliseconds, ranging from 100 to 2550.
- `uart NUMBER baud RATE` - sets the baud rate (1200-115200 Bd) for the selected serial port.
- `uart NUMBER mode <kiss/monitor/config>` - sets the default operating mode for the selected serial port (0 for USB).
- `pwm <on/off>` – sets the DAC type. *on* when a PWM filter is installed, *off* when an R2R ladder is installed. Starting from version 2.0.0, it is recommended to use only PWM.
- `flat <on/off>` – configures the modem for use with a radio with *flat audio* output. *on* when the signal is fed from the *flat audio* connector, *off* when the signal is fed from the headphone jack. This option only affects 1200 Bd modems.
- `beacon NUMBER <on/off>` – *on* activates, *off* deactivates the beacon with the specified number, ranging from 0 to 7.
- `beacon NUMBER iv TIME` – sets the beacon transmission interval (in minutes) for the beacon with the specified number, ranging from 0 to 7.
@ -122,6 +122,12 @@ The following commands are available in configuration mode:
- `fx25 <on/off>` - *on* enables, *off* disables FX.25 protocol support. When enabled, both AX.25 and FX.25 packets will be received simultaneously.
- `fx25tx <on/off>` - *on* enables, *off* disables transmission using the FX.25 protocol. If FX.25 support is completely disabled (command *fx25 off*), packets will always be transmitted using AX.25.
On AIOC, the following commands are additionally available:
- `ptt <pri/sec>` - selects primary (*pri*) or secondary (*sec*) PTT output.
- `level VALUE` - sets TX signal level given in %.
- `gain <1/2/4/8/16>` - sets RX signal gain to 1, 2, 4, 8, or 16 (AIOC rev1.2+ only).
Additionally, there are control commands available:
- `print` – displays the current settings.
- `list` – displays the contents of the filtering list.
@ -192,7 +198,7 @@ In monitor mode, received and transmitted packets are displayed, and it is also
The following commands are available:
- `beacon NUMBER` - transmits a beacon from 0 to 7 if that beacon is enabled.
- `cal <low/high/alt/stop>` - starts or stops calibration mode: *low* transmits a low tone, *high* transmits a high tone, *alt* transmits zero bytes/alternating tones, and *stop* stops transmission. For the 9600 Bd modem, zero bytes are always transmitted.
- `cal` - enters interactive calibration mode.
Common commands are also available:
@ -201,8 +207,24 @@ Common commands are also available:
- `version` – displays software version information.
- `config` – switches the port to configuration mode.
- `kiss` – switches the port to KISS mode.
#### 2.2.2. Received packet view
#### 2.2.2. Calibration mode
The calibration mode is entered using `cal` command. The following keys are available:
On AIOC, the following keys are additionally available:
- `x` - switches TX attenuator on/off.
- `n` - decreases TX level by 1%.
- `m` - increases TX level by 1%.
The calibration mode does not require pressing the enter key. Remember to save the TX level set with `n` and `m` keys by switching to the configuration mode and using `save`.
#### 2.2.3. Received packet view
For each received AX.25 packet, the header is displayed in the following format:
> Frame received [...], signal level XX% (HH%/LL%)
@ -234,8 +256,8 @@ KISS mode is used for working as a standard TNC KISS, compatible with many Packe
After device startup, you should enter monitor mode (using the `monitor` command) and wait for packets to appear. You should adjust the signal level so that most packets have a signal level of around 50% (as described in [section 2.2.2](#222-received-packet-view)). The received signal level should be maintained within the range of 10-90%.\
The correct setting of the audio output type from the transceiver using the `flat <on/off>` command is crucial for the performance of the 1200 Bd modem. If you are using the headphone/speaker output (filtered), this option should be set to *off*. If you are using the *flat audio* output (unfiltered), this option should be set to *on*. This setting does not affect modems other than 1200 Bd.\
To ensure the best network performance, the transmitted signal level should also be properly set. This is especially important for the 1200 Bd modem, where the signal is transmitted through the standard microphone connector of an FM radio. Excessive signal levels can lead to distortion and significant tone amplitude imbalances.
Signal calibration requires an FM receiver tuned to the same frequency as the transmitter. You should enter monitor mode (using the `monitor` command) and enable high tone transmission (using the `cal high` command). You should set the potentiometer to the minimum amplitude level position and then slowly increase the level while carefully monitoring the signal strength in the receiver, which should increase. At some point, the signal level will stop increasing. At that point, gently retract the potentiometer and turn off the calibration mode (using the `cal stop` command). After this operation, the transmitter should be correctly driven.
> Note! If you fail to reach the point where the signal level stops increasing, the resistor value in the TX path is probably too high. If the signal level is clearly too low, reduce the value of this resistor. Otherwise, no action is necessary.
Signal calibration requires an FM receiver tuned to the same frequency as the transmitter. You should enter monitor mode (using the `monitor` command), switch to calibration mode (using the `cal` command) and enable high tone transmission (using `h` key). You should set the potentiometer to the minimum amplitude level position (or reduce TX level to 0% using `n` key on AIOC) and then slowly increase the level (using `m` key on AIOC) while carefully monitoring the signal strength in the receiver, which should increase. At some point, the signal level will stop increasing. At that point, gently retract the potentiometer (or use `n` key on AIOC) and turn off the calibration mode (using `q` key). After this operation, the transmitter should be correctly driven.
> Note! If you fail to reach the point where the signal level stops increasing, the resistor value in the TX path is probably too high. If the signal level is clearly too low, reduce the value of this resistor. On AIOC, consult AIOC documentation. Otherwise, no action is necessary.
### 2.5. Programming
Programming (flashing firmware) can be done in two ways: using an ST-Link programmer or through the UART1 serial port (e.g., using a USB-UART adapter).
@ -349,6 +371,8 @@ If *viscous delay* functionality is enabled for the matched alias, the completed
In addition, the *viscous delay* buffer is regularly refreshed. If the specified time has passed, and the packet has not been removed from the buffer (see *the beginning of this section*), its hash is saved to the duplicate filter buffer, the packet is transmitted, and removed from the *viscous delay* buffer.
## 4. Documentation changelog
### 2025/03/20
- Calibration instructions updated, AIOC instructions added - Piotr Wilkoń
@ -98,14 +99,13 @@ W trybie konfiguracji dostępne są następujące polecenia:
- `quiet CZAS` – ustawia czas, który musi upłynąć pomiędzy zwolnieniem się kanału a włączeniem nadawania. Wartość w milisekundach z zakresu od 100 do 2550.
- `uart NUMER baud PREDKOSC` - ustawia prędkość (1200-115200 Bd) pracy wybranego portu szeregowego.
- `uart NUMBER mode <kiss/monitor/config` - ustawia domyślny tryb pracy wybranego portu szeregowego (0 dla USB).
- `pwm <on/off>` – ustawia typ DAC. *on*, gdy zainstalowany jest filtr PWM, *off* gdy zainstalowana jest drabinka R2R. Od wersji 2.0.0 zalecane jest użycie wyłącznie PWM.
- `flat <on/off>` – konfiguruje modem do użycia z radiem z wyjściem *flat audio*. *on* gdy sygnał podawany jest ze złącza *flat audio*, *off* gdy sygnał podawany jest ze złącza słuchawkowego. Opcja ma wpływ jedynie na modemy 1200 Bd.
- `beacon NUMER <on/off>` – *on* włącza, *off* wyłącza beacon o podanym numerze z zakresu od 0 do 7.
- `beacon NUMER iv CZAS` – ustawia interwał nadawania (w minutach) beaconu o numerze z zakresu od 0 do 7.
- `beacon NUMER dl CZAS` – ustawia opóźnienie/przesunięcie nadawania (w minutach) beaconu o numerze z zakresu od 0 do 7.
- `beacon NUMER path SCIEZKAn-N[,SCIEZKAn-N]/none` – ustawia ścieżkę beaconu o numerze z zakresu od 0 do 7. Polecenie przyjmuje jeden (np. *WIDE2-2*) lub dwa (np. *WIDE2-2,SP3-3*) elementy ścieżki albo opcję *none* dla braku ścieżki.
- `beacon NUMER data TRESC` – ustawia treść beaconu o numerze z zakresu od 0 do 7.
- `digi NUMER <on/off>` – *on* włącza, *off* wyłącza obsługę aliasu o numerze z zakresu od 0 do 7.
- `digi NUMER alias ALIAS` – ustawia alias o numerze z zakresu od 0 do 7. W przypadku slotów 0-3 (typ *n-N*) przyjmuje do 5 znaków bez SSID, w przypadku slotów 4-7 (aliasy proste) przyjmuje aliasy w formie jak znak wywoławczy wraz z SSID lub bez.
- `digi NUMER max N` – ustawia maksymalne *n* (z zakresu od 1 do 7) dla normalnego powtarzania aliasów typu *n-N* (zakres od 0 do 3).
@ -124,6 +124,12 @@ W trybie konfiguracji dostępne są następujące polecenia:
- `fx25 <on/off>` - *on* włącza, *off* wyłącza obsługę protokołu FX.25. Po włączeniu jednocześnie będą odbierane pakiety AX.25 i FX.25.
- `fx25tx <on/off>` - *on* włącza, *off* wyłącza nadawanie z użyciem protokołu FX.25. Jeśli obsługa FX.25 jest wyłączona całkowicie (polecenie *fx25 off*), to pakiety zawsze będą nadawane z użyciem AX.25.
Dla platformy AIOC dostępne są dodatkowo następujące polecenia:
- `ptt <pri/sec>` - wybiera podstawowe (*pri*) lub dodatkowe (*sec*) wyjście PTT.
- `level WARTOSC` - ustawia poziom sygnału nadawanego podany w %.
- `gain <1/2/4/8/16>` - ustawia wzmocnienie sygnału odbieranego na 1, 2, 4, 8 lub 16 (tylko dla AIOC rev1.2+).
Ponadto dostępne są polecenia kontrolne:
- `print` – pokazuje aktualne ustawienia.
- `list` – pokazuje zawartość listy filtrującej.
@ -189,7 +195,7 @@ W trybie monitora wyświetlane są pakiety odbierane i nadawane, a ponadto możl
#### 2.2.1. Polecenia
Dostępne są następujące polecenia:
- `beacon NUMER` - nadaje beacon z zakresu 0 do 7, o ile ten beacon jest włączony.
- `cal <low/high/alt/stop>` - rozpoczyna lub kończy tryb kalibracji: *low* nadaje niski ton, *high* nadaje wysoki ton, *alt* nadaje bajty zerowe/zmieniające się tony, a *stop* zatrzymuje transmisję. Dla modemu 9600 Bd zawsze nadawane są bajty zerowe.
- `cal` - przechodzi do interaktywnego trybu kalibracji.
Dostępne są także polecenia wspólne:
- `help` – pokazuje stronę pomocy
@ -197,8 +203,24 @@ Dostępne są także polecenia wspólne:
- `version` – pokazuje informacje o wersji oprogramowania
- `config` – przełącza port do trybu konfiguracji
- `kiss` – przełącza port do trybu KISS
#### 2.2.2. Widok pakietów odbieranych
#### 2.2.2. Tryb kalibracji
Tryb kalibracji uruchamiany jest poprzez polecenie `cal`. W tym trybie dostępne są następujące klawisze:
- `l` - nadaje niski ton.
- `h` - nadaje wysoki ton.
- `a` - nadaje zmieniające się tony (logiczne zera).
- `s` - zatrzymuje transmisję.
- `q` - wychodzi z trybu kalibracji i zatrzymuje transmisję (jeśli to konieczne).
Na platformie AIOC dostępne są dodatkowo klawisze:
- `x` - włącza/wyłącza tłumik sygnału nadawanego.
- `n` - zmniejsza poziom sygnału nadawanego o 1%.
- `m` - zwiększa poziom sygnału nadawanego o 1%.
W trybie kalibracji nie jest konieczne zatwierdzanie enterem. Należy pamiętać, aby zapisać poziom sygnału nadawanego ustawiony klawiszami `n` i `m` poprzez przejście do trybu konfiguracji i użycie polecenia `save`.
#### 2.2.3. Widok pakietów odbieranych
Dla każdego odebranego pakietu AX.25 wyświetlany jest nagłówek w następującym formacie:
> Frame received [...], signal level XX% (HH%/LL%)
@ -229,7 +251,7 @@ Tryb KISS służy do pracy jako standardowe TNC KISS, współpracujące z wielom
Po uruchomieniu urządzenia należy przejść do trybu monitora (polecenie `monitor`) i czekać na pojawienie się pakietów. Należy wyregulować poziom sygnału tak, aby większość pakietów miała poziom sygnału ok. 50% (jak opisano w [sekcji 2.2.2](#222-widok-pakietów-odbieranych)) Poziom sygnału odbieranego należy utrzymywać w zakresie 10-90%.\
Istotne dla wydajności modemu 1200 Bd jest odpowiednie ustawienie typu wyjścia audio z radiotelefonu przy pomocy polecenia `flat <on/off>`. Jeśli używane jest wyjście słuchawkowe/głośnikowe (filtrowane), to opcja ta powinna być ustawiona na *off*. Jeśli używane jest wyjście zwane *flat audio* (niefiltrowane), to opcja ta powinna być ustawiona na *on*. To ustawienie nie ma wpływu na modemy inne niż 1200 Bd.\
Aby zapewnić najlepszą wydajność sieci, poziom sygnału nadawanego powinien być prawidłowo ustawiony. Jest to szczególnie istotne w przypadku modemu 1200 Bd, gdzie sygnał nadawany jest przez standardowe złącze mikrofonowe radiotelefonu FM. Zbyt duży poziom sygnału prowadzi do występowania zniekształceń i dużych dysproporcji amplitud tonów.\
Do kalibracji potrzebny jest odbiornik FM zestrojony na tę samą częstotliwość, co nadajnik. Należy przejść do trybu monitora (polecenie `monitor`) i właczyć nadawanie tonu wysokiego (polecenie `cal high`). Należy ustawić potencjometr do pozycji minimalnego poziomu wysterowania, a następnie powoli zwiększać poziom, jednocześnie uważnie nasłuchując siły sygnału w odbiorniku, który powinien rosnąć. W pewnym momencie poziom sygnału przestanie się zwiększać. Wówczas należy delikatnie cofnąć potencjometr i wyłączyć tryb kalibracji (polecenie `cal stop`). Po tej operacji nadajnik powinien być poprawnie wysterowany.
Do kalibracji potrzebny jest odbiornik FM zestrojony na tę samą częstotliwość, co nadajnik. Należy przejść do trybu monitora (polecenie `monitor`), uruchomić tryb kalibracji (polecenie `cal`) i właczyć nadawanie tonu wysokiego (klawisz `h`). Należy ustawić potencjometr do pozycji minimalnego poziomu wysterowania (lub zmniejszyć poziom sygnału do 0% używając klawisza `n` na AIOC), a następnie powoli zwiększać poziom (używając klawisza `m` na AIOC), jednocześnie uważnie nasłuchując siły sygnału w odbiorniku, który powinien rosnąć. W pewnym momencie poziom sygnału przestanie się zwiększać. Wówczas należy delikatnie cofnąć potencjometr (używając klawisza `n` na AIOC) i wyłączyć tryb kalibracji (klawisz `q`). Po tej operacji nadajnik powinien być poprawnie wysterowany.
> Uwaga! Jeśli nie uda się osiągnąć punktu, w którym poziom sygnału przestanie się zwiększać, to prawdopodobnie wartość rezystancji w torze nadawczym jest zbyt duża. Jeśli poziom sygnału jest wyraźnie zbyt niski, należy zmniejszyć wartość tej rezystancji. W przeciwnym wypadku nie jest konieczne podejmowanie kroków.
### 2.5. Programowanie
@ -333,6 +355,8 @@ Jeśli dla dopasowanego aliasu włączona jest funkcja *viscous delay*, to gotow
Ponadto regularnie odświeżany jest bufor funkcji *viscous delay*. Jeśli minął odpowiedni czas i pakiet nie został usunięty z bufora (patrz *początek tej sekcji*), to jego hasz jest zapisywany do bufora filtra duplikatów, pakiet jest wysyłany i usuwany z bufora *viscous delay*.
## 4. Rejestr zmian dokumentacji
### 2025/03/20
- Zaktualizowano instrukcję kalibracji, dodano instrukcje do AIOC - Piotr Wilkoń
Piotr Wilkon
9 months ago