ParaTNC wersja 1.0-19082017
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

1. WSTĘP
ParaTNC jest oprogramowaniem wbudowanym (firmware) przeznaczonym do pracy na płytce STM32VLDISCOVERY w charakterze
uniwersalnego radiomodemu/sterownika sieci APRS, wyposażonego w szereg funkcjonalności takich jak:

-> Digipeater retransmitujący pakiety posiadające ustawioną ścieżkę WIDE1-1.
-> Dwustronna komunikacja z komputerem przy użyciu protokołu KISS po łączu szeregowym (TTL-UART).
-> Stacja pogodowa z obsługą wiatromierza TX20, termometru Dallas DS12B20 oraz czujnika ciśnienia MS5611.
-> Telemetria umożliwiająca monitorowanie ilości odbieranych, nadawanych i powtarzanych pakietów.
-> Obsługa protokołu tekstowego VE.Direct używanego przez systemu fotowoltaiki Victron Energy

Niewątpliwą zaletą ParaTNC są bardzo niskie koszta. Wynoszące jedynie 60~70pln bruttno na zakup STM32VLDISCOVERY. 
Ponieważ dekodowanie i generowanie transmisji APRS odbywa się w pełni programowo nie ma konieczności użycia tandetnych
podróbek modemu TCM, sprzedawanych obecnie na ebay i aliexpress przez dostawców z Chin. Lutowanie ogranicza się wyłącznie
do wykonania odpowienich kabli połączeniowch. stosowna instrukcja z pinoutami znajduje się w pliku WIRING.



2. LICENCJA
Warunki licencjonowania są zawarte w pliku LICENSE.   

3. WSPIERANE FUNKCJONALNOŚCI PROTOKOŁU VE.DIRECT
Protokół (w wersji tekstowej, nie binarnej) VE.Direct został stworzony przez firme Victron Energy i jest wykorzystywany
w produkowanych przez nią inwerterów, kontrolerów ładowania i innego sprzętu do instalacji fotowoltaicznych. Służy on do
przesyłania telemetrii z kontrolera do komputera PC, lub w tym przypadku sterownika ParaTNC. Jest on domyślnie włączony
w większości urządzeń i w trybie bezczynności, tj. bez komunikacji protokołem binarnym z aplikacją konfiguracyjną 
urządzenie będzie wysyłało co kilka sekund paczkę danych telemetrycznych.

Komunikacja z urządzeniami Victron Energy odbywa się przez złącze VE.Direct, które jest tak naprawdę zwykłym złączem szeregowym.
W przypadku regulatorów z serii MPPT (w moim przypadku model MPPT75/15) używane są sygnały na poziome TTL-3.3V, dlatego można
je podłączyć do sterownika ParaTNC/STM32VLDISCOVERY bezpośrednio, tj. bez użycia konwerterów typu MAX232.

Złącze VE.Direct w regulatorach z serii MPPT znajduje się poniżej bezpiecznika. Patrząc na złącze mając otwory montażowe w obudowie
zwrócone ku dołowi rozpiska jest taka (od prawej do lewej)
	-> Masa
	-> TX, dane z regulatora do hosta (kontrolera)
	-> RX, dane z hosta do regulatora. Nie wykorzystywany przez protokół tekstowy

VE.Direct wysyła bardzo wiele różnych parametrów i informacji statusowych. Oczywiście ze względu na ograniczenia standardu APRS
nie ma możliwości wysyłania wszystkiego, dlatego ostatecznie dokonano następującego wyboru

   a) Prąd akumulatora (ładowanie/rozładowywanie), jako trzeci kanał telemetrii
   b) Napięcie akulatora, jako czwarty kanał telemetrii
   c) Napięcie fotoogniwa, jako piąty kanał telemetrii
   d) Status urządzenia (aktualny tryby ładowania, brak ładowania, akumulator bliski rozładowania), jako część statusu
   e) Kody błędów (zwarcie, zbyt wysokie napięcie aku/panela, przegrzanie, przeciążenie itp), jako część statusu  


3. KONFIGURACJA
Na chwilę obecną ParaTNC jest dostarczane w formie kodów źródłowych do samodzielnej kompilacji. Ponieważ dostępne jest 
source, konfiguracja odbywa się przez edycję pliku ./include/station_config.h . Zawiera on komentarze tłumaczące znaczenie 
poszczególnych opcji. Oprócz typowych i raczej trywialnych ustawień APRS takich jak znak wywoławczy i temu podobne,
użytkownik może włączać i wyłączać poszczególne tryby pracy urządzenia. Możliwe są następujące kombinacje

-> KISS
-> KISS + DIGI
-> KISS + DIGI + METEO
-> VICTRON + DIGI + METEO
-> VICTRON + DIGI

Włączenie funkcjonalności stacji pogodowej (przez odkomentowanie _METEO) automatycznie włącza digipeater nawet jeżeli
zakomentowane jest #define _DIGI w pliku konfiguracyjnym. Komunikacja z komputerem odbywa się na prędkości 9600bps, a sam
protokół KISS działa od samego początku pracy urządzenia i nie musi być w żaden sposób inicjalizowany ze strony PC.

Włączenie wsparcia dla protokołu VE.Direct odbywa się przez odkomentowanie //#define _VICTRON. 
UWAGA!! Włączenie VE.Direct wyłącza i uniemożliwia wykorzystanie ParaTNC w trybie modemu KISS. 

Sterownik wysyła co 10 minut ramkę telemetryczną zawierającą informację o ilości odebranych, nadanych i powtórzonych
pakietów APRS przez okres minionych 10 minut. Ilość nadanych ramek jest sumą powtórzonych ramek i ramek własnych 
wliczając w to ramki telemetrii. Co ok 75 minut nadawane są pełne opisy kanałów.

Sterownik nie umożliwia bezpośrednie transmitowanie jakichkolwiek danych do internetu (do serwerów APRS-IS) z powodów 
oczywistych. Uruchomienie funkcjonalności igate wymaga podłączenia przez UART komputera PC, Raspberry-PI lub czegokolwiek
innego na czym można uruchomić oprogramowanie takie jak APRX, APRSIS32, czy UiView32. Na chwile obecną pakiety własne,
czyli generowane przez sterownik ramki pozycyjne, pogodowe czy telemetryczne są nadawane wyłącznie na port radiowy.
W przyszłości pojawi się funkcjonalność polegająca na wysyłaniu przez KISS do komputera nie tylko ramek odebranych drogą
radiową, ale również tych pochodzenia własnego.



4. KOMPILACJA
Do kompilacji oprogramowania ParaTNC na płytkę STM32VLDISCOVERY potrzebny jest zestaw narzędzi GNU ARM Embedded Toolchain 
w którego skład wchodzi kompilator gcc-arm-none-eabi, debugger gdb, linker, oraz zestaw bibliotek i plików include.
Dodatkowo niezbędny jest make i binutils znajdujący się w kazdej dystrybucji linuksa. ParaTNC został napisany i jest
rozwijany na systemie Xubuntu 16.04LTS z toolchainem w wersji 2016q-3, aczkolwiek bez problemu będzie się kompilował na 
dowolnie nowszej wersji. Kompilacja w systemie Windows czy MacOS nie jest wspierana ale powinna się udać, jeżeli ktoś
potrafi odpowiednio skonfigurować całe środowisko.
 
W przypadku systemów Debian i ubunto-podobnych zdecydowanie zaleca się instalację toolchain przez aptitude z repozytorium
internetowego. Jest to szybkie, wygodne i powoduje, że wszystkie komponenty są kopiowane do domyślnych folderów instalacji,
co pozwala uniknąć serii błędów ze względu na niemożność odnalezienia ścieżki do np. gcc przez make.

Informację na temat GNU ARM Embedded Toolchain, jego źródła, skompilowane wersję dystrybucyjne i dokumentację znajdują się:
https://launchpad.net/gcc-arm-embedded
https://developer.arm.com/open-source/gnu-toolchain/gnu-rm
Instrukcja konfiguracji repo i instalacji pakietu znajduje się tutaj.
https://launchpad.net/~team-gcc-arm-embedded/+archive/ubuntu/ppa

Binutils i make znajduje się w repozytorium debiana/ubuntu, w przypadku GNU ARM Embedded należy zgodnie z instrukcją z
powyższego linku dodać odpowiednie repozytorium zewnętrzne.

 'sudo add-apt-repository ppa:team-gcc-arm-embedded/ppa'
 'sudo aptiude update'
 'sudo aptitude install make automake binutils gcc-arm-embedded' 

Jeżeli źródła nie zostały jeszcze skonfigurowane należy zainstalować w systemie git i sklonować repozytorium kodu
na lokalny dysk twardy. W tym celu należy wydać polecenie będąc w katalogu gdzie chcemu aby znalazły się źródła:

 'git clone https://github.com/sp8ebc/para-tnc' 
 
a następnie skonfigurować plik ./include/station_config.h . Po instalacji wymaganego programowania należy wejść w podkatalog 
Debug i wydać polecenie 

 'make'. 

Źródła powinny się skompilować a w tymże katalogu pojawić się plik 'ParaTNC-ARM-Lite.hex' gotowy do wgrania do płytki.
Dowodem na poprawne zakończenie procesu są poniższe komunikaty w konsoli, które powinny pojawić się pod sam koniec procesu
kompilacji

	Finished building target: ParaTNC-ARM-lite.elf
	 
	Invoking: Cross ARM GNU Create Flash Image
	arm-none-eabi-objcopy -O ihex "ParaTNC-ARM-lite.elf"  "ParaTNC-ARM-lite.hex"
	Finished building: ParaTNC-ARM-lite.hex
	 
	Invoking: Cross ARM GNU Print Size
	arm-none-eabi-size --format=berkeley "ParaTNC-ARM-lite.elf"
	   text	   data	    bss	    dec	    hex	filename
	  36512	    552	   3312	  40376	   9db8	ParaTNC-ARM-lite.elf
	Finished building: ParaTNC-ARM-lite.siz




5. WGRYWANIE PLIKU HEX DO PŁYTKI STM32VLDISCOVERY
Płytka STM32VLDISCOERY ma wbudowany programator/debugger sprzętowy ST-Link v1. Komunikacja z nim odbywa się przez 
komendy SCSI passthrough a samo urządzenie wykrywa się w systemie jako pamięć masowa. W domyślnej konfiguracji po 
podłączeniu płytki prez USB do komputera system (a dokładnie modprobe) automatycznie załaduje dla tego urządzenia sterownik
mass-storage, system zamontuje emulowany przez programator system plików jako pendrive, co uniemożiwi zaprogramowanie. 
W związku z powyższym należy w jego konfiguracji zablokować takie zachowanie. Robi się to przy pomocy polecenia:

 'sudo echo "options usb-storage quirks=483:3744:i" >> /etc/modprobe.d/stlink_v1.conf'
 
Po ponownym uruchomieniu komputera warto sprawdzić, czy konfiguracja działa. Po podłączeniu STM32VLDISCOERY żadna dodatkowa
pamięć masowa (pendrive) nie powinna zostać zamontowana. Po sprawdzeniu przez 'dmesg' na końcu powinno być miej więcej coś 
takiego:

[90639.895886] usb 2-1.1: new full-speed USB device number 13 using ehci-pci
[90639.990288] usb 2-1.1: New USB device found, idVendor=0483, idProduct=3744
[90639.990294] usb 2-1.1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
[90639.990296] usb 2-1.1: Product: STM32 STLink
[90639.990298] usb 2-1.1: Manufacturer: STMicroelectronics
[90639.990300] usb 2-1.1: SerialNumber: QÿrI\xffffffc2\xffffff86RV%X\xffffffc2\xffffff87
[90639.990796] usb-storage 2-1.1:1.0: USB Mass Storage device detected
[90639.992973] usb-storage 2-1.1:1.0: device ignored

W dalszym ciągu należy zainstalować oprogramowanie texane-stlink które służy do obsługi programatora stlink-v1/v2 w 
systemie linux. 

  'git clone git://github.com/texane/stlink.git'
  'cd stlink.git'
  'make'
  'cd build/Relase'
  'sudo cp st-* /usr/bin'
  
 Na koniec, jeżeli programator działa można wrzucić program do płytki. Po przejściu do katalogu ./para-tnc/Debug
 wywołuje się następujące polecenie
 
  'sudo st-flash --format ihex write /dev/sr0 ParaTNC-ARM-lite.hex'
 
 Jeżeli podczas programowania w konsoli wyskoczy błąd -1, lub jakikolwiek inny warto zresetować płytkę przez wyjęcie
 i ponowne włożenie wtyczki USB (czarny przycisk RST jest podłączony do targetu a nie programatora).
