got rid of real-time operations

CHANGELOG.md

@@ -7,6 +7,7 @@
 * none
 ## Other
 * New signal level measurement method
+* Got rid of float operations for PLL adjustment
 * Full documentation (English and Polish) in Markdown
 * Project moved to STM32CubeIDE
 * Updated HAL version used for USB

Core/Src/ax25.c

@@ -911,7 +911,7 @@ void Ax25TransmitBuffer(void)
  * @brief Start transmission immediately
  * @warning Transmission should be initialized using Ax25_transmitBuffer
  */
-/*static */void transmitStart(void)
+static void transmitStart(void)
 {
 	txCrc = 0xFFFF; //initial CRC value
 	txStage = TX_STAGE_PREAMBLE;

Core/Src/main.c

@@ -115,7 +115,6 @@ static void handleFrame(void)
 			{
 				TermSendToAll(MODE_MONITOR, (uint8_t*)"\r\nInput level too low! Please increase so most stations are around 30-50%.\r\n", 0);
 			}
-
 			TermSendToAll(MODE_MONITOR, (uint8_t*)"(AX.25) Frame received [", 0);
 			for(uint8_t i = 0; i < ModemGetDemodulatorCount(); i++)
 			{

Core/Src/modem.c

@@ -18,7 +18,7 @@ along with VP-Digi.  If not, see <http://www.gnu.org/licenses/>.
 
 #include <string.h>
 #include <math.h>
-#include <modem.h>
+#include "modem.h"
 #include <stdlib.h>
 #include <stdbool.h>
 #include "ax25.h"
@@ -28,28 +28,39 @@ along with VP-Digi.  If not, see <http://www.gnu.org/licenses/>.
 
 /*
  * Configuration for PLL-based data carrier detection
- * DCD_MAXPULSE is the maximum value of the DCD pulse counter
- * DCD_THRES is the threshold value of the DCD pulse counter. When reached the input signal is assumed to be valid
- * DCD_MAXPULSE and DCD_THRES difference sets the DCD "inertia" so that the DCD state won't change rapidly when a valid signal is present
- * DCD_DEC is the DCD pulse counter decrementation value when symbol changes too far from PLL counter zero
- * DCD_INC is the DCD pulse counter incrementation value when symbol changes near the PLL counter zero
+ * 1. MAXPULSE - the maximum value of the DCD pulse counter. Higher values allow for more stability when a correct signal is detected,
+ * but introduce a delay when releasing DCD
+ * 2. THRES - the threshold value of the DCD pulse counter. When reached the input signal is assumed to be valid. Higher values mean more immunity to noise,
+ * but introduce delay when setting DCD
+ * 3. MAXPULSE and THRES difference sets the DCD "inertia" so that the DCD state won't change rapidly when a valid signal is present
+ * 4. INC is the DCD pulse counter incrementation value when symbol changes near the PLL counter zero
+ * 5. DEC is the DCD pulse counter decrementation value when symbol changes too far from PLL counter zero
+ * 6. TUNE is the PLL counter tuning coefficient. It is applied when there is a symbol change (as the symbol change should occur when the PLL counter crosses zero)
+ *
+ * [       DCD OFF    *      |    DCD ON   ]
+ * 0               COUNTER THRES        MAXPULSE
+ *        <-DEC INC->
+ *
  * The DCD mechanism is described in demodulate().
  * All values were selected by trial and error
  */
-#define DCD1200_MAXPULSE 100
-#define DCD1200_THRES 30
-#define DCD1200_DEC 2
-#define DCD1200_INC 1
+#define DCD1200_MAXPULSE 60
+#define DCD1200_THRES 20
+#define DCD1200_INC 2
+#define DCD1200_DEC 1
+#define DCD1200_TUNE 0.74f
 
-#define DCD9600_MAXPULSE 70
-#define DCD9600_THRES 50
-#define DCD9600_DEC 5
+#define DCD9600_MAXPULSE 60
+#define DCD9600_THRES 40
 #define DCD9600_INC 1
+#define DCD9600_DEC 1
+#define DCD9600_TUNE 0.74f
 
-#define DCD300_MAXPULSE 140
-#define DCD300_THRES 120
-#define DCD300_DEC 3
-#define DCD300_INC 5
+#define DCD300_MAXPULSE 80
+#define DCD300_THRES 20
+#define DCD300_INC 4
+#define DCD300_DEC 1
+#define DCD300_TUNE 0.74f
 
 #define N1200 8 //samples per symbol @ fs=9600, oversampling = 38400 Hz
 #define N9600 4 //fs=38400, oversampling = 153600 Hz
@@ -73,6 +84,8 @@ along with VP-Digi.  If not, see <http://www.gnu.org/licenses/>.
 
 #define DAC_SINE_SIZE 128 //DAC sine table size
 
+#define PLL_TUNE_BITS 8 //number of bits when tuning PLL to avoid floating point operations
+
 
 struct ModemDemodConfig ModemConfig;
 
@@ -161,7 +174,7 @@ static const int16_t lpf1200[15] =
 
 //fs=38400 Hz, Gaussian, fc=4800 Hz (9600 Bd), N=9, gain=65536
 //seems like there is almost no difference between N=9 and any higher order
-static int16_t lpf9600[9] = {497, 2360, 7178, 13992, 17478, 13992, 7178, 2360, 497};
+static const int16_t lpf9600[9] = {497, 2360, 7178, 13992, 17478, 13992, 7178, 2360, 497};
 
 #define LPF_MAX_TAPS 15
 
@@ -190,8 +203,8 @@ struct DemodState
 
 	int32_t pll; //bit recovery PLL counter
 	int32_t pllStep;
-	float pllLockedAdjust;
-	float pllNotLockedAdjust;
+	int32_t pllLockedTune;
+	int32_t pllNotLockedTune;
 
 	int32_t dcdPll; //DCD PLL main counter
 	uint8_t dcdLastSymbol; //last symbol for DCD
@@ -200,6 +213,7 @@ struct DemodState
 	uint16_t dcdThres;
 	uint16_t dcdInc;
 	uint16_t dcdDec;
+	int32_t dcdTune;
 
 	int16_t peak;
 	int16_t valley;
@@ -476,17 +490,18 @@ static int32_t demodulate(int16_t sample, struct DemodState *dem)
 		sample = (abs(outLoI) + abs(outLoQ)) - (abs(outHiI) + abs(outHiQ));
 	}
 
-
 	//DCD using "PLL"
 	//PLL is running nominally at the frequency equal to the baudrate
 	//PLL timer is counting up and eventually overflows to a minimal negative value
 	//so it crosses zero in the middle
 	//tone change should happen somewhere near this zero-crossing (in ideal case of exactly same TX and RX baudrates)
 	//nothing is ideal, so we need to have some region around zero where tone change is expected
-	//if tone changed inside this region, then we add something to the DCD pulse counter (and adjust counter phase for the counter to be closer to 0)
+	//however in case of noise the demodulated output is completely random and has many symbol changes in different places
+	//other than the PLL zero-crossing, thus making it easier to utilize this mechanism
+	//if tone changed inside this region, then we add something to the DCD pulse counter and adjust counter phase for the counter to be closer to 0
 	//if tone changes outside this region, then we subtract something from the DCD pulse counter
 	//if some DCD pulse threshold is reached, then we claim that the incoming signal is correct and set DCD flag
-	//when configured properly, it's generally immune to noise, as the detected tone changes much faster than 1200 baud
+	//when configured properly, it's generally immune to noise and sensitive to correct signal
 	//it's also important to set some maximum value for DCD counter, otherwise the DCD is "sticky"
 
 
@@ -494,20 +509,26 @@ static int32_t demodulate(int16_t sample, struct DemodState *dem)
 
 	if((sample > 0) != dem->dcdLastSymbol) //tone changed
 	{
-		if((uint32_t)abs(dem->dcdPll) <= (uint32_t)(dem->pllStep)) //tone change occurred near zero
+		if((uint32_t)abs(dem->dcdPll) < (uint32_t)(dem->pllStep)) //tone change occurred near zero
+		{
 			dem->dcdCounter += dem->dcdInc; //increase DCD counter
+			if(dem->dcdCounter > dem->dcdMax) //maximum DCD counter value reached
+				dem->dcdCounter = dem->dcdMax; //avoid "sticky" DCD and counter overflow
+		}
 		else //tone change occurred far from zero
 		{
 			if(dem->dcdCounter >= dem->dcdDec) //avoid overflow
 				dem->dcdCounter -= dem->dcdDec; //decrease DCD counter
+			else
+				dem->dcdCounter = 0;
 		}
-		dem->dcdPll = 0;
+
+		//avoid floating point operations
+		dem->dcdPll = ((int64_t)dem->dcdPll * (int64_t)dem->dcdTune) >> PLL_TUNE_BITS;
 	}
 
 	dem->dcdLastSymbol = sample > 0; //store last symbol for symbol change detection
 
-	if(dem->dcdCounter > dem->dcdMax) //maximum DCD counter value reached
-		dem->dcdCounter = dem->dcdMax; //avoid "sticky" DCD and counter overflow
 
 	if(dem->dcdCounter > dem->dcdThres) //DCD threshold reached
 		dem->dcd = 1; //DCD!
@@ -565,13 +586,14 @@ static void decode(uint8_t symbol, uint8_t demod)
 
 	if(((dem->rawSymbols & 0x03) == 0b10) || ((dem->rawSymbols & 0x03) == 0b01)) //if there was a symbol transition, adjust PLL
 	{
+		//avoid floating point operations. Multiply by n-bit value and shift by n bits
 		if(!dem->dcd) //PLL not locked
 		{
-			dem->pll = (int)(dem->pll * dem->pllNotLockedAdjust); //adjust PLL faster
+			dem->pll = ((int64_t)dem->pll * (int64_t)dem->pllNotLockedTune) >> PLL_TUNE_BITS; //adjust PLL faster
 		}
 		else //PLL locked
 		{
-			dem->pll = (int)(dem->pll * dem->pllLockedAdjust); //adjust PLL slower
+			dem->pll = ((int64_t)dem->pll * (int64_t)dem->pllLockedTune) >> PLL_TUNE_BITS; //adjust PLL slower
 		}
 	}
 
@@ -729,20 +751,22 @@ void ModemInit(void)
 		baudRate = 1200.f;
 
 		demodState[0].pllStep = PLL1200_STEP;
-		demodState[0].pllLockedAdjust = PLL1200_LOCKED_TUNE;
-		demodState[0].pllNotLockedAdjust = PLL1200_NOT_LOCKED_TUNE;
+		demodState[0].pllLockedTune = PLL1200_LOCKED_TUNE * (float)((uint32_t)1 << PLL_TUNE_BITS);
+		demodState[0].pllNotLockedTune = PLL1200_NOT_LOCKED_TUNE * (float)((uint32_t)1 << PLL_TUNE_BITS);
 		demodState[0].dcdMax = DCD1200_MAXPULSE;
 		demodState[0].dcdThres = DCD1200_THRES;
 		demodState[0].dcdInc = DCD1200_INC;
 		demodState[0].dcdDec = DCD1200_DEC;
+		demodState[0].dcdTune = DCD1200_TUNE * (float)((uint32_t)1 << PLL_TUNE_BITS);
 
 		demodState[1].pllStep = PLL1200_STEP;
-		demodState[1].pllLockedAdjust = PLL1200_LOCKED_TUNE;
-		demodState[1].pllNotLockedAdjust = PLL1200_NOT_LOCKED_TUNE;
+		demodState[1].pllLockedTune = PLL1200_LOCKED_TUNE * (float)((uint32_t)1 << PLL_TUNE_BITS);
+		demodState[1].pllNotLockedTune = PLL1200_NOT_LOCKED_TUNE * (float)((uint32_t)1 << PLL_TUNE_BITS);
 		demodState[1].dcdMax = DCD1200_MAXPULSE;
 		demodState[1].dcdThres = DCD1200_THRES;
 		demodState[1].dcdInc = DCD1200_INC;
 		demodState[1].dcdDec = DCD1200_DEC;
+		demodState[1].dcdTune = DCD1200_TUNE * (float)((uint32_t)1 << PLL_TUNE_BITS);
 
 		demodState[1].prefilter = PREFILTER_NONE;
 		demodState[1].lpf.coeffs = (int16_t*)lpf1200;
@@ -797,12 +821,13 @@ void ModemInit(void)
 		spaceFreq = 1800.f;
 
 		demodState[0].pllStep = PLL300_STEP;
-		demodState[0].pllLockedAdjust = PLL300_LOCKED_TUNE;
-		demodState[0].pllNotLockedAdjust = PLL300_NOT_LOCKED_TUNE;
+		demodState[0].pllLockedTune = PLL300_LOCKED_TUNE * (float)((uint32_t)1 << PLL_TUNE_BITS);
+		demodState[0].pllNotLockedTune = PLL300_NOT_LOCKED_TUNE * (float)((uint32_t)1 << PLL_TUNE_BITS);
 		demodState[0].dcdMax = DCD300_MAXPULSE;
 		demodState[0].dcdThres = DCD300_THRES;
 		demodState[0].dcdInc = DCD300_INC;
 		demodState[0].dcdDec = DCD300_DEC;
+		demodState[0].dcdTune = DCD300_TUNE * (float)((uint32_t)1 << PLL_TUNE_BITS);
 
 		demodState[0].prefilter = PREFILTER_FLAT;
 		demodState[0].bpf.coeffs = (int16_t*)bpf300;
@@ -820,12 +845,13 @@ void ModemInit(void)
 		markFreq = 38400.f / (float)DAC_SINE_SIZE; //use as DAC sample rate
 
 		demodState[0].pllStep = PLL9600_STEP;
-		demodState[0].pllLockedAdjust = PLL9600_LOCKED_TUNE;
-		demodState[0].pllNotLockedAdjust = PLL9600_NOT_LOCKED_TUNE;
+		demodState[0].pllLockedTune = PLL9600_LOCKED_TUNE * (float)((uint32_t)1 << PLL_TUNE_BITS);
+		demodState[0].pllNotLockedTune = PLL9600_NOT_LOCKED_TUNE * (float)((uint32_t)1 << PLL_TUNE_BITS);
 		demodState[0].dcdMax = DCD9600_MAXPULSE;
 		demodState[0].dcdThres = DCD9600_THRES;
 		demodState[0].dcdInc = DCD9600_INC;
 		demodState[0].dcdDec = DCD9600_DEC;
+		demodState[0].dcdTune = DCD9600_TUNE * (float)((uint32_t)1 << PLL_TUNE_BITS);
 
 		demodState[0].prefilter = PREFILTER_NONE;
 		//this filter will be used for RX and TX

doc/LICENSE_FDL

@@ -0,0 +1,451 @@
+
+                GNU Free Documentation License
+                 Version 1.3, 3 November 2008
+
+
+ Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
+     <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+0. PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+functional and useful document "free" in the sense of freedom: to
+assure everyone the effective freedom to copy and redistribute it,
+with or without modifying it, either commercially or noncommercially.
+Secondarily, this License preserves for the author and publisher a way
+to get credit for their work, while not being considered responsible
+for modifications made by others.
+
+This License is a kind of "copyleft", which means that derivative
+works of the document must themselves be free in the same sense.  It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does.  But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book.  We recommend this License
+principally for works whose purpose is instruction or reference.
+
+
+1. APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work, in any medium, that
+contains a notice placed by the copyright holder saying it can be
+distributed under the terms of this License.  Such a notice grants a
+world-wide, royalty-free license, unlimited in duration, to use that
+work under the conditions stated herein.  The "Document", below,
+refers to any such manual or work.  Any member of the public is a
+licensee, and is addressed as "you".  You accept the license if you
+copy, modify or distribute the work in a way requiring permission
+under copyright law.
+
+A "Modified Version" of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A "Secondary Section" is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall
+subject (or to related matters) and contains nothing that could fall
+directly within that overall subject.  (Thus, if the Document is in
+part a textbook of mathematics, a Secondary Section may not explain
+any mathematics.)  The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The "Invariant Sections" are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.  If a
+section does not fit the above definition of Secondary then it is not
+allowed to be designated as Invariant.  The Document may contain zero
+Invariant Sections.  If the Document does not identify any Invariant
+Sections then there are none.
+
+The "Cover Texts" are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.  A Front-Cover Text may
+be at most 5 words, and a Back-Cover Text may be at most 25 words.
+
+A "Transparent" copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, that is suitable for revising the document
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters.  A copy made in an otherwise Transparent file
+format whose markup, or absence of markup, has been arranged to thwart
+or discourage subsequent modification by readers is not Transparent.
+An image format is not Transparent if used for any substantial amount
+of text.  A copy that is not "Transparent" is called "Opaque".
+
+Examples of suitable formats for Transparent copies include plain
+ASCII without markup, Texinfo input format, LaTeX input format, SGML
+or XML using a publicly available DTD, and standard-conforming simple
+HTML, PostScript or PDF designed for human modification.  Examples of
+transparent image formats include PNG, XCF and JPG.  Opaque formats
+include proprietary formats that can be read and edited only by
+proprietary word processors, SGML or XML for which the DTD and/or
+processing tools are not generally available, and the
+machine-generated HTML, PostScript or PDF produced by some word
+processors for output purposes only.
+
+The "Title Page" means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page.  For works in
+formats which do not have any title page as such, "Title Page" means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+The "publisher" means any person or entity that distributes copies of
+the Document to the public.
+
+A section "Entitled XYZ" means a named subunit of the Document whose
+title either is precisely XYZ or contains XYZ in parentheses following
+text that translates XYZ in another language.  (Here XYZ stands for a
+specific section name mentioned below, such as "Acknowledgements",
+"Dedications", "Endorsements", or "History".)  To "Preserve the Title"
+of such a section when you modify the Document means that it remains a
+section "Entitled XYZ" according to this definition.
+
+The Document may include Warranty Disclaimers next to the notice which
+states that this License applies to the Document.  These Warranty
+Disclaimers are considered to be included by reference in this
+License, but only as regards disclaiming warranties: any other
+implication that these Warranty Disclaimers may have is void and has
+no effect on the meaning of this License.
+
+2. VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no
+other conditions whatsoever to those of this License.  You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute.  However, you may accept
+compensation in exchange for copies.  If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+
+3. COPYING IN QUANTITY
+
+If you publish printed copies (or copies in media that commonly have
+printed covers) of the Document, numbering more than 100, and the
+Document's license notice requires Cover Texts, you must enclose the
+copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover.  Both covers must also clearly and legibly identify
+you as the publisher of these copies.  The front cover must present
+the full title with all words of the title equally prominent and
+visible.  You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a computer-network location from which the general network-using
+public has access to download using public-standard network protocols
+a complete Transparent copy of the Document, free of added material.
+If you use the latter option, you must take reasonably prudent steps,
+when you begin distribution of Opaque copies in quantity, to ensure
+that this Transparent copy will remain thus accessible at the stated
+location until at least one year after the last time you distribute an
+Opaque copy (directly or through your agents or retailers) of that
+edition to the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to
+give them a chance to provide you with an updated version of the
+Document.
+
+
+4. MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it.  In addition, you must do these things in the Modified Version:
+
+A. Use in the Title Page (and on the covers, if any) a title distinct
+   from that of the Document, and from those of previous versions
+   (which should, if there were any, be listed in the History section
+   of the Document).  You may use the same title as a previous version
+   if the original publisher of that version gives permission.
+B. List on the Title Page, as authors, one or more persons or entities
+   responsible for authorship of the modifications in the Modified
+   Version, together with at least five of the principal authors of the
+   Document (all of its principal authors, if it has fewer than five),
+   unless they release you from this requirement.
+C. State on the Title page the name of the publisher of the
+   Modified Version, as the publisher.
+D. Preserve all the copyright notices of the Document.
+E. Add an appropriate copyright notice for your modifications
+   adjacent to the other copyright notices.
+F. Include, immediately after the copyright notices, a license notice
+   giving the public permission to use the Modified Version under the
+   terms of this License, in the form shown in the Addendum below.
+G. Preserve in that license notice the full lists of Invariant Sections
+   and required Cover Texts given in the Document's license notice.
+H. Include an unaltered copy of this License.
+I. Preserve the section Entitled "History", Preserve its Title, and add
+   to it an item stating at least the title, year, new authors, and
+   publisher of the Modified Version as given on the Title Page.  If
+   there is no section Entitled "History" in the Document, create one
+   stating the title, year, authors, and publisher of the Document as
+   given on its Title Page, then add an item describing the Modified
+   Version as stated in the previous sentence.
+J. Preserve the network location, if any, given in the Document for
+   public access to a Transparent copy of the Document, and likewise
+   the network locations given in the Document for previous versions
+   it was based on.  These may be placed in the "History" section.
+   You may omit a network location for a work that was published at
+   least four years before the Document itself, or if the original
+   publisher of the version it refers to gives permission.
+K. For any section Entitled "Acknowledgements" or "Dedications",
+   Preserve the Title of the section, and preserve in the section all
+   the substance and tone of each of the contributor acknowledgements
+   and/or dedications given therein.
+L. Preserve all the Invariant Sections of the Document,
+   unaltered in their text and in their titles.  Section numbers
+   or the equivalent are not considered part of the section titles.
+M. Delete any section Entitled "Endorsements".  Such a section
+   may not be included in the Modified Version.
+N. Do not retitle any existing section to be Entitled "Endorsements"
+   or to conflict in title with any Invariant Section.
+O. Preserve any Warranty Disclaimers.
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant.  To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section Entitled "Endorsements", provided it contains
+nothing but endorsements of your Modified Version by various
+parties--for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version.  Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity.  If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+
+5. COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice, and that you preserve all their Warranty Disclaimers.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy.  If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections Entitled "History"
+in the various original documents, forming one section Entitled
+"History"; likewise combine any sections Entitled "Acknowledgements",
+and any sections Entitled "Dedications".  You must delete all sections
+Entitled "Endorsements".
+
+
+6. COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other
+documents released under this License, and replace the individual
+copies of this License in the various documents with a single copy
+that is included in the collection, provided that you follow the rules
+of this License for verbatim copying of each of the documents in all
+other respects.
+
+You may extract a single document from such a collection, and
+distribute it individually under this License, provided you insert a
+copy of this License into the extracted document, and follow this
+License in all other respects regarding verbatim copying of that
+document.
+
+
+7. AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, is called an "aggregate" if the copyright
+resulting from the compilation is not used to limit the legal rights
+of the compilation's users beyond what the individual works permit.
+When the Document is included in an aggregate, this License does not
+apply to the other works in the aggregate which are not themselves
+derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one half of
+the entire aggregate, the Document's Cover Texts may be placed on
+covers that bracket the Document within the aggregate, or the
+electronic equivalent of covers if the Document is in electronic form.
+Otherwise they must appear on printed covers that bracket the whole
+aggregate.
+
+
+8. TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections.  You may include a
+translation of this License, and all the license notices in the
+Document, and any Warranty Disclaimers, provided that you also include
+the original English version of this License and the original versions
+of those notices and disclaimers.  In case of a disagreement between
+the translation and the original version of this License or a notice
+or disclaimer, the original version will prevail.
+
+If a section in the Document is Entitled "Acknowledgements",
+"Dedications", or "History", the requirement (section 4) to Preserve
+its Title (section 1) will typically require changing the actual
+title.
+
+
+9. TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense, or distribute it is void, and
+will automatically terminate your rights under this License.
+
+However, if you cease all violation of this License, then your license
+from a particular copyright holder is reinstated (a) provisionally,
+unless and until the copyright holder explicitly and finally
+terminates your license, and (b) permanently, if the copyright holder
+fails to notify you of the violation by some reasonable means prior to
+60 days after the cessation.
+
+Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, receipt of a copy of some or all of the same material does
+not give you any rights to use it.
+
+
+10. FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions of the
+GNU Free Documentation License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in
+detail to address new problems or concerns.  See
+https://www.gnu.org/licenses/.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License "or any later version" applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation.  If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.  If the Document
+specifies that a proxy can decide which future versions of this
+License can be used, that proxy's public statement of acceptance of a
+version permanently authorizes you to choose that version for the
+Document.
+
+11. RELICENSING
+
+"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
+World Wide Web server that publishes copyrightable works and also
+provides prominent facilities for anybody to edit those works.  A
+public wiki that anybody can edit is an example of such a server.  A
+"Massive Multiauthor Collaboration" (or "MMC") contained in the site
+means any set of copyrightable works thus published on the MMC site.
+
+"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
+license published by Creative Commons Corporation, a not-for-profit
+corporation with a principal place of business in San Francisco,
+California, as well as future copyleft versions of that license
+published by that same organization.
+
+"Incorporate" means to publish or republish a Document, in whole or in
+part, as part of another Document.
+
+An MMC is "eligible for relicensing" if it is licensed under this
+License, and if all works that were first published under this License
+somewhere other than this MMC, and subsequently incorporated in whole or
+in part into the MMC, (1) had no cover texts or invariant sections, and
+(2) were thus incorporated prior to November 1, 2008.
+
+The operator of an MMC Site may republish an MMC contained in the site
+under CC-BY-SA on the same site at any time before August 1, 2009,
+provided the MMC is eligible for relicensing.
+
+
+ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+    Copyright (c)  YEAR  YOUR NAME.
+    Permission is granted to copy, distribute and/or modify this document
+    under the terms of the GNU Free Documentation License, Version 1.3
+    or any later version published by the Free Software Foundation;
+    with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+    A copy of the license is included in the section entitled "GNU
+    Free Documentation License".
+
+If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
+replace the "with...Texts." line with this:
+
+    with the Invariant Sections being LIST THEIR TITLES, with the
+    Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+
+If you have Invariant Sections without Cover Texts, or some other
+combination of the three, merge those two alternatives to suit the
+situation.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.

doc/manual.md

@@ -0,0 +1,341 @@
+# VP-Digi - documentation
+Copyright 2023 Piotr Wilkoń\
+Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A copy of the license is available under [LICENSE_FDL](LICENSE_FDL).\
+The changelog is placed at the bottom of this document.
+## Table of contents
+- [VP-Digi - documentation](#vp-digi---documentation)
+  - [Table of contents](#table-of-contents)
+  - [1. Functional description](#1-functional-description)
+  - [2. User manual](#2-user-manual)
+    - [2.1. Configuration mode](#21-configuration-mode)
+      - [2.1.1. Commands](#211-commands)
+      - [2.1.2. Example configuration](#212-example-configuration)
+    - [2.2. Monitor mode](#22-monitor-mode)
+      - [2.2.1. Commands](#221-commands)
+      - [2.2.2. Received packet view](#222-received-packet-view)
+    - [2.3. KISS mode](#23-kiss-mode)
+    - [2.4. Signal level setting](#24-signal-level-setting)
+    - [2.5. Programming](#25-programming)
+      - [2.5.1. Programming using an ST-Link programmer](#251-programming-using-an-st-link-programmer)
+      - [2.5.2. Programming using a USB-UART adapter](#252-programming-using-a-usb-uart-adapter)
+    - [2.6. Setup](#26-setup)
+  - [3. Technical description](#3-technical-description)
+    - [3.1. Hardware](#31-hardware)
+      - [3.1.1. Reception](#311-reception)
+      - [3.1.2. Transmission](#312-transmission)
+    - [3.2. Software](#32-software)
+      - [3.2.1. Modem](#321-modem)
+        - [3.2.1.1. Demodulation](#3211-demodulation)
+        - [3.2.1.2. Modulation](#3212-modulation)
+        - [3.2.1.3. Bit recovery](#3213-bit-recovery)
+      - [3.2.2. Protocols](#322-protocols)
+        - [3.2.2.1. Reception](#3221-reception)
+        - [3.2.2.2. Transmission](#3222-transmission)
+      - [3.2.3. Digipeater](#323-digipeater)
+  - [4. Documentation changelog](#4-documentation-changelog)
+    - [2023/09/06](#20230906)
+
+## 1. Functional description
+VP-Digi is a standalone AX.25 digipeater controller (e.g., APRS) and a KISS TNC controller. The software is equipped with the following modems:
+- Bell 202 AFSK 1200 Bd 1200/2200 Hz (VHF standard)
+- G3RUH GFSK 9600 Bd (UHF standard)
+- Bell 103 AFSK 300 Bd 1600/1800 Hz (HF standard)
+- V.23 AFSK 1200 Bd 1300/2100 Hz (alternative VHF standard)
+
+Each modem utilizes carrier detection based on detecting the correct modulating signal rather than decoded data, increasing reliability and reducing collisions.
+
+Furthermore, the software supports the following protocols:
+- AX.25 (Packet Radio/APRS standard)
+- FX.25 - AX.25 with error correction, fully compatible with AX.25
+
+VP-Digi allows configuration of:
+- Your own callsign, SSID, and destination address
+- Modem parameters (*TXDelay*, *TXTail*, quiet time, DAC type, receiver type)
+- Serial port baud rates
+- 4 digipeater aliases of the *New-N* type (e.g., *WIDEn-N*)
+- 4 simple digipeater aliases (e.g., *CITY*)
+- Hop count thresholds for *New-N* type aliases
+- Enabling tracing for each alias
+- *Viscous delay* mode and *direct only* mode for each alias
+- Filtering lists (excluding or including)
+- Enabling reception of non-APRS packets
+- Enabling monitoring of own packets through the KISS port
+
+The device provides:
+- 2 serial ports
+- USB port
+
+Each port operates independently and can function in the following modes:
+- TNC KISS
+- Frame monitor
+- Configuration terminal
+
+## 2. User manual
+### 2.1. Configuration mode
+Device configuration can be done through any port (USB, UART1, UART2). To enter configuration mode, use the `config` command.
+> Note! If the port is in KISS mode (default after startup), the entered characters will not be visible.
+
+> Note! After completing the configuration, remember to save it to memory using the `save` command.
+
+#### 2.1.1. Commands
+The following commands are available in configuration mode:
+- `call CALLSIGN-SSID` - sets the callsign along with SSID. The callsign must consist of a maximum of 6 A-Z and 0-9 characters. SSID is optional and must be within the range of 0-15.
+- `dest ADDRESS` – sets the destination address. The address must consist of a maximum of 6 A-Z and 0-9 characters , without SSID. *APNV01* is the official and recommended address for VP-Digi.
+- `modem <1200/300/9600/1200_V23>` - sets the modem type: *1200* for 1200 Bd modem, *300* for 300 Bd modem, *9600* for 9600 Bd modem, or *1200_V23* for the alternative 1200 Bd modem.
+- `txdelay TIME` – sets the preamble length before transmitting a frame. Value in milliseconds, ranging from 30 to 2550.
+- `txtail TIME` – sets the tail length after a frame transmission. Value in milliseconds, ranging from 10 to 2550. Set to the minimum value if not needed.
+- `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.
+- `beacon NUMBER dl TIME` – sets the delay/offset for beacon transmission (in minutes) for the beacon with the specified number, ranging from 0 to 7.
+- `beacon NUMBER path PATHn-N[,PATHn-N]/none` – sets the beacon path for the beacon with the specified number, ranging from 0 to 7. The command accepts one (e.g., *WIDE2-2*) or two (e.g., *WIDE2-2,MA3-3*) path elements or the *none* option for no path.
+- `beacon NUMBER data CONTENT` – sets the content of the beacon with the specified number, ranging from 0 to 7.
+- `digi <on/off>` – *on* enables, *off* disables the digipeater.
+- `digi NUMBER <on/off>` – *on* enables, *off* disables the handling of the alias with the specified number, ranging from 0 to 7.
+- `digi NUMBER alias ALIAS` – sets an alias with the specified number, ranging from 0 to 7. For slots 0-3 (type *n-N*), it accepts up to 5 characters without SSID, and for slots 4-7 (simple aliases), it accepts aliases in the form of callsigns with SSID or without.
+- `digi NUMBER max N` – sets the maximum *n* (ranging from 1 to 7) for normal repeating of *n-N* type aliases (ranging from 0 to 3).
+- `digi NUMBER rep N` – sets the minimum *n* (ranging from 0 to 7) from which *n-N* type aliases (ranging from 0 to 3) will be processed as simple aliases. Setting *N* to 0 disables this feature.
+- `digi NUMBER trac <on/off>` – sets the selected alias (ranging from 0 to 7) as traceable (*on*) or non-traceable (*off*).
+- `digi NUMBER viscous <on/off>` – *on* enables, *off* disables the *viscous delay* function for the alias with the specified number, ranging from 0 to 7.
+- `digi NUMBER direct <on/off>` – *on* enables, *off* disables the function of repeating only frames received directly for the alias with the specified number, ranging from 0 to 7.
+> The operation of the digipeater is described in [section 3.2.3](#323-digipeater).
+- `digi NUMBER filter <on/off>` – *on* enables, *off* disables frame filtering for the alias with the specified number, ranging from 0 to 7.
+- `digi filter <black/white>` – sets the type of frame filtering list: *black* (exclusion - frames from characters on the list will not be repeated) or *white* (inclusion - only frames from characters on the list will be repeated).
+- `digi dupe TIME` – sets the duplicate filtering buffer time, preventing multiple repetitions of a previously repeated packet. Time in seconds, ranging from 5 to 255.
+- `digi list POSITION set CALLSIGN-SSID` – enters a call sign into the selected position (ranging from 0 to 19) of the filtering list. You can use \* to mask all characters to the end of the call sign. *?* masks a single letter in the call sign. To mask the SSID, you can use \* or *?*.
+- `digi list POSITION remove` – removes the selected position (ranging from 0 to 19) from the filtering list.
+- `monkiss <on/off>` – *on* enables, *off* disables sending own and repeated frames to KISS ports.
+- `nonaprs <on/off>` – *on* enables, *off* disables the reception of non-APRS packets (e.g., for Packet Radio).
+- `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.
+
+Additionally, there are control commands available:
+- `print` – displays the current settings.
+- `list` – displays the contents of the filtering list.
+- `save` – saves the settings to memory and restarts the device. Always use this command after completing configuration. Otherwise, unsaved configuration will be discarded.
+- `eraseall` – clears the entire configuration and restarts the device.
+
+Common commands are also available:
+- `help` – displays the help page.
+- `reboot` – restarts the device.
+- `version` – displays software version information.
+- `monitor` – switches the port to monitor mode.
+- `kiss` – switches the port to KISS mode.
+
+
+#### 2.1.2. Example configuration
+
+- Beacon\
+    Example for beacon number 0. Beacons are available from 0 to 7.
+    1. *beacon 0 data !5002.63N/02157.91E#Digi Rzeszow* – setting APRS standard beacon data
+    2. *beacon 0 path WIDE2-2,SP2-2* – setting the path
+    3. *beacon 0 iv 15* – transmitting every 15 minutes
+    4. *beacon 0 dl 5* – the beacon will be transmitted for the first time after 5 minutes from device startup
+    5. *beacon 0 on* – enabling the beacon
+- Fill-in WIDE1-1 digipeater\
+    Example for alias number 0. Alias numbers range from 0 to 3.
+    1. *digi 0 alias WIDE* – repeating WIDEn-N type aliases. Numbers n and N are NOT set here.
+    2. *digi 0 max 1* – repeating paths up to a maximum of WIDE1-1
+    3. *digi 0 rep 0* – disabling path limiting and simplification
+    4. *digi 0 trac on* – enabling path tracing (WIDEn-N paths are traced)
+    5. *digi 0 on* – enabling handling of the alias
+    6. *digi on* – enabling the digipeater
+
+- Fill-in digipeater with *viscous delay* (recommended configuration)\
+    Example for alias number 0. Alias numbers range from 0 to 3.
+    1. *digi 0 alias WIDE* – repeating WIDEn-N type aliases. Numbers n and N are NOT set here.
+    2. *digi 0 max 2* – repeating paths up to a maximum of WIDE2-2
+    3. *digi 0 rep 3* – WIDE3-3 and longer paths will be simplified when repeated
+    4. *digi 0 trac on* – enabling path tracing (WIDEn-N paths are traced)
+    5. *digi 0 viscous on* – enabling the *viscous delay* mode
+    6. *digi 0 on* – enabling handling of the alias
+    7. *digi on* – enabling the digipeater
+
+- Regional WIDEn-N + MAn-N digipeaters (recommended configuration)\
+    Examples for aliases 0 (for WIDE) and 1 (for MA).
+    1. *digi 0 alias WIDE* – repeating WIDEn-N type aliases. Numbers n and N are NOT set here.
+    2. *digi 0 max 2* – repeating paths up to a maximum of WIDE2-2
+    3. *digi 0 rep 3* – WIDE3-3 and longer paths will be simplified when repeated
+    4. *digi 0 trac on* – enabling path tracing (WIDEn-N paths are traced)
+    5. *digi 0 on* – enabling handling of the alias
+    6. *digi 1 alias MA* – repeating MAn-N type aliases. Numbers n and N are NOT set here.
+    7. *digi 1 max 7* – repeating paths up to a maximum of SP7-7
+    8. *digi 1 rep 0* – no path hop limiting
+    9. *digi 1 trac off* – disabling path tracing (regional paths are not traced)
+    10. *digi 1 on* – enabling handling of the alias
+    11. *digi on* – enabling the digipeater
+
+
+### 2.2. Monitor mode
+
+Device operation can be observed through any port (USB, UART1, UART2). Switching to monitor mode is done by issuing the `monitor` command.
+> Note! If the port is in KISS mode (default after startup), entered characters will not be visible.
+
+In monitor mode, received and transmitted packets are displayed, and it is also possible to perform signal level calibration.
+
+#### 2.2.1. Commands
+
+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.
+
+Common commands are also available:
+
+- `help` – displays the help page.
+- `reboot` – restarts the device.
+- `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
+
+For each received AX.25 packet, the header is displayed in the following format:
+> Frame received [...], signal level XX% (HH%/LL%)
+> 
+For each received FX.25 packet, the format is as follows:
+> Frame received [...], N bytes fixed, signal level XX% (HH%/LL%)
+
+Where:
+- *...* specifies which modems received the packet and what type of filter was used. The following statuses are possible:
+  - *P* - high tone pre-emphasis filter
+  - *D* - high tone de-emphasis filter
+  - *F* - flat filter
+  - *N* - no filter
+  - *_* - modem did not receive the frame\
+For example, the status *[_P]* indicates that the first modem did not receive the frame, and the second modem received the frame and uses a pre-emphasis filter. Another example status *[N]* means that only one modem without a filter is available, and it received the frame.
+- *N* specifies how many bytes were fixed by the FX.25 protocol. This field is not displayed for AX.25 packets.
+- *XX%* indicates the signal level, i.e., its amplitude.
+- *HH%* indicates the level of the upper peak of the signal.
+- *LL%* indicates the level of the lower peak of the signal.
+> Note! The level of the upper peak should be positive, and the level of the lower peak should be negative. Furthermore, these levels should be symmetrical with respect to zero. A large imbalance indicates incorrect polarization of the ADC input.
+
+
+### 2.3. KISS mode
+KISS mode is used for working as a standard TNC KISS, compatible with many Packet Radio, APRS, and similar programs. In this mode, there is no echo (typed characters are not displayed). The available commands for switching modes are:
+- `monitor` – switches the port to monitor mode
+- `config` – switches the port to configuration mode
+
+### 2.4. Signal level setting
+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.
+
+### 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).
+In both methods, you need to download the VP-Digi software (HEX file) beforehand.
+
+#### 2.5.1. Programming using an ST-Link programmer
+1. Download and install the *ST-Link Utility* program along with the appropriate drivers.
+2. Connect VP-Digi to the programmer.
+3. Connect the programmer to the USB port.
+4. In *ST-Link Utility*, go to *File->Open file* and select the downloaded HEX file with the firmware.
+5. Go to *Target->Program & Verify* and click *Start*. After a while, the device will restart, and the actual software will start.
+
+#### 2.5.2. Programming using a USB-UART adapter
+1. Ensure that the adapter works with logic levels of 0/3.3V.
+2. If necessary, install drivers for the adapter.
+3. Download and install the *Flasher-STM32* program.
+4. On the board, set the jumper closer to the reset button to position 0, and the one farther away to 1.
+5. Connect the *TX* pin of the adapter to the *PA10* pin and *RX* to *PA9*. Connect power (e.g., from the adapter).
+6. Determine which COM port the adapter is available on.
+7. Start *Flasher-STM32*, select the appropriate COM port, and click *Next*.
+   > If an error occurs, reset the microcontroller and check the connections and jumper settings.
+8. On the next screen, click *Next*.
+9. On the following screen, select the option *Download to device* and choose the downloaded HEX file.
+10. Check the options *Erase necessary pages* and *Verify after download*, then click *Next*. After a moment, the device should be programmed. Revert both jumpers to position 0, reset the microcontroller, and disconnect the adapter. The proper software should start running.
+
+### 2.6. Setup
+To use the device, you should assemble it according to the schematic presented in [section 3.1](#31-hardware), program it (description in [section 2.5](#25-programming)) and calibrate (description in [section 2.4](#24-signal-level-setting)).
+After startup, all ports (USB, UART1, UART2) operate in KISS mode, and the baud rate for UART1 and UART2 ports is 9600 Bd (the USB port's speed doesn't matter).
+To configure VP-Digi or monitor frames, you need to connect it to a computer via the USB or UART port and install a terminal program (*TeraTerm*, *RealTerm*, etc.). As mentioned in the preceding sections, switching to configuration and monitor mode is done by entering the commands `config` and `monitor` respectively and confirming with the Enter key.
+> In KISS mode, echo (displaying entered characters) is disabled, so you won't see the entered commands.
+
+Device configuration should be carried out using the commands described in [section 2.1](#21-configuration-mode).
+
+
+## 3. Technical description
+### 3.1. Hardware
+VP-Digi natively operates on the STM32F103C8T6 microcontroller with a core frequency of 72 MHz, requiring an external 8 MHz resonator. It is recommended to build the device using the *STM32 Blue Pill* board.
+
+The construction of VP-Digi based on the *STM32 Blue Pill* board is presented in the schematic:
+![VP-Digi schematic](schematic.png)
+
+#### 3.1.1. Reception
+The received signal is provided to pin *PA0* using decoupling capacitors (*C4*, *C6*), polarizing resistors (*R6*, *R9*), and limiting resistors (*R7*, *R11*). To ensure proper reception of FSK modulation, capacitors with relatively large capacitance values must be used. To achieve correct reception, the DC voltage at pin *PA0* should be around half of the supply voltage, i.e., 1.65 V. Incorrect polarization manifests as asymmetry in the signal level (see [section 2.2.2](#222-received-packet-view)) or loss of reception.
+In the receiving path, a serial resistor *R7* is used to limit the maximum pin current. This is done to protect the converter from damage caused by excessive signal levels using the microcontroller's built-in diodes as a voltage limiter.
+If the transceiver has an adjustable output signal level, the installation of components *RV2*, *R11*, and *C6* is not necessary.
+
+#### 3.1.2. Transmission
+The transmitted signal can be generated using PWM or R2R (not recommended from version 2.0.0 onwards) converter. PWM conversion utilizes hardware pulse width modulation and a second-order RC filter (*R5*, *C3*, *R3*, *C2*) to filter out unwanted components. The filter consists of two first-order RC filters with a cutoff frequency of approximately 7200 Hz to ensure an adequate passband for the 9600 Bd modem. Furthermore, for proper FSK modulation, a decoupling capacitor *C1* with a relatively large capacitance must be used.
+Resistor *R2* is used to significantly reduce the signal amplitude when using a standard microphone input with high gain. The value of this resistor should be selected individually.
+The transceiver is switched to the transmission state by applying a low state through the NPN transistor *Q1*. If the transceiver has a PTT input, it should be connected directly to the collector of the transistor, and resistor *R1* should not be installed. For standard transceivers with a microphone input, resistor *R1* should be installed.
+
+
+### 3.2. Software
+VP-Digi's software is written in the C language using standard CMSIS libraries and ST headers for the microcontroller, with register-level operations. The HAL library is used only for USB support and configuring clock signals.
+
+#### 3.2.1. Modem
+##### 3.2.1.1. Demodulation
+Receiving frames begins with sampling the input signal. The input signal is oversampled four times, resulting in a sampling rate of 153600 Hz for the 9600 Bd modem and 38400 Hz for the other modems. After receiving four samples, they are decimated and sent for further processing (resulting in frequencies of 38400 Hz and 9600 Hz, respectively). For the 1200 Bd modem, 8 samples per symbol are used, for the 300 Bd modem, 32 samples per symbol, and for the 9600 Bd modem, 4 samples per symbol are used. The signal's amplitude is tracked using a mechanism similar to AGC. If the modem has a pre-filter, the samples are filtered. For AFSK modems, the current sample and the previous sample are multiplied with signal of the numerical generator at frequencies corresponding to the *mark* and *space* frequencies (correlation is calculated, which corresponds to discrete frequency demodulation). The results of multiplication in each path are summed, and then the results are subtracted from each other, yielding a *soft* symbol. For the (G)FSK modem, this step does not occur because the FM (FSK) demodulation function is performed by the transceiver. At this stage, carrier detection is performed, based on a simple digital PLL. This loop nominally operates at a frequency equal to the symbol rate of the signal (e.g., 1200 Hz = 1200 Bd). When a change in the *soft* symbol is detected, the distance from the PLL counter zero crossing is checked. If it is small, indicating that the signals are in phase, the input signal is likely correct. In this case, an additional counter is increased. If it exceeds a set threshold, the signal is finally considered correct. The algorithm also works in the reverse direction: if the signals are out of phase, the counter value is decreased. The demodulated signal (*soft symbol*) is filtered by a low-pass filter (appropriate for the symbol rate) to remove noise, and then the symbol value is determined and sent to the bit recovery mechanism.
+
+##### 3.2.1.2. Modulation
+The AFSK modulator is based on outputting samples of a sinusoidal signal generated at startup to the digital-to-analog converter. Depending on the symbol frequency, the sample output frequency is changed, i.e., for an array with length *N* and signal frequency *f*, successive samples are output at a frequency of *f/N*. During signal generation, continuity of the array indices is maintained, resulting in phase preservation.
+
+For the GFSK modem, symbols from the higher layer (square wave) are filtered by a low-pass filter (common for both demodulator and modulator) and output at a constant frequency of 38400 Hz to the converter.
+
+##### 3.2.1.3. Bit recovery
+Bit recovery is performed by the modem. A digital PLL (similar to carrier detection) operating at the symbol frequency is used. At the end of each full period, the final symbol value is determined based on several previously received symbols. At the same time, the loop phase is adjusted to the signal phase, i.e., to the moments of symbol changes. For modems using bit scrambling (e.g., G3RUH modem), descrambling is performed. Finally, NRZI decoding is executed, and the bits are passed to the higher layer.
+
+#### 3.2.2. Protocols
+##### 3.2.2.1. Reception
+The HDLC, AX.25, and FX.25 protocols are handled by a single module that functions as a big state machine. Received bits are continuously written to a shift register. This register is monitored for the presence of the HDLC flag to detect the beginning and end of an AX.25 frame, as well as for bit synchronization with the transmitter (i.e., alignment to a full byte). When FX.25 reception is enabled, the occurrence of any of the correlation tags is simultaneously monitored, which also serves as a synchronization marker and the beginning of an FX.25 frame. Received bits are written to a buffer, and the checksum is calculated in real-time. An important moment is the reception of the first eight data bytes, during which it is not known whether it is an FX.25 frame or not. Therefore, both protocol decoders work simultaneously during this time. If the correlation tag does not match any known tags, the frame is treated as an AX.25 packet. In this case, bits are written until the next flag is encountered. Subsequently, if only APRS packet reception is allowed, the Control and PID fields are checked. Finally, the checksum is verified. If it is correct, modem multiplexing is performed (in case more than one modem receives the same packet). If the correlation tag is valid, its expected packet length is determined based on it, and all bytes are written until that length is reached. Then, data correctness is checked, and any necessary fixes are made using the Reed-Solomon algorithm. Regardless of the operation's result, the raw frame is decoded as an AX.25 packet (additional bits and flags are removed), and the checksum is verified. If it is correct, modem multiplexing is similarly performed.
+
+##### 3.2.2.2. Transmission
+Similar to reception, the bit generation module for transmission is a state machine. Initially, a preamble of a specified length is transmitted. When the AX.25 protocol is used, a certain number of flags are transmitted, followed by data bits. Bit stuffing and checksum calculation are performed in real-time, and the checksum is appended after the entire frame is transmitted. A specified number of flags is transmitted, and if there are more packets to be sent, the actual data is sent immediately. Finally, a tail of a specified length is transmitted, concluding the transmission.
+
+For FX.25, the input packet is previously encoded as an AX.25 packet, i.e., additional bits, flags and CRC are added, and it is placed in a separate buffer. This allows receivers that do not support FX.25 to still receive this packet. The remaining part of the buffer is filled with the appropriate bytes. Then, Reed-Solomon encoding is performed, which inserts parity bytes into the buffer. When transmission begins, a preamble is sent, followed by the appropriately selected correlation tag. Then, the previously prepared frame is transmitted. If there are more packets to be sent, the process is repeated. Finally, a tail is transmitted, concluding the transmission.
+
+#### 3.2.3. Digipeater
+After receiving a packet, its hash is calculated (CRC32 algorithm). Then, the occurrence of the same hash is checked in the *viscous delay* buffer. If the hashes match, the packet is removed from the buffer, and no further action is taken. Similarly, the occurrence of the same hash is checked in the duplicate filter buffer. If the hashes match, the packet is immediately discarded. Next, the *H-bit* is searched in the path, indicating the last element of the path processed by other digipeaters. If there is no next element ready for processing, the packet is discarded. If there is a ready-to-process element, the following steps are taken:
+- The element is compared to digipeater's own call sign (i.e., whether the own call sign appears explicitly in the path). If the comparison is successful, only the *H-bit* is added to the element, e.g., *SR8XXX* becomes *SR8XXX\**.
+- The element is similarly compared to all simple aliases entered in the configuration (if they are enabled). If the comparison is successful:
+  - If the alias is traced, it is replaced with the own call sign, and an *H-bit* is added (e.g., *RZ* becomes *SR8XXX\**).
+  - If the alias is untraced, only the *H-bit* is added (e.g., *RZ* becomes *RZ\**).
+
+The first part of the element is compared to all *New-N* aliases (if they are enabled). If the comparison is successful, the *n* number is extracted, and the SSID called *N* is saved (e.g., in the path *WIDE2-1*, *n* is 2, and *N* is 1). Initially, the path's validity conditions are checked, i.e., whether 0 < *n* < 8, 0 <= *N* < 8, and *N* <= *n*. If any of the conditions are not met, the packet is discarded. Examples of invalid paths include:
+- *WIDE8-1*
+- *WIDE1-2*
+- *WIDE0-3*
+- *WIDE2-8*
+- and many others
+
+Simultaneously, if in the element *N* = 0, the path is exhausted, and the packet is discarded. Then, *n* is compared to the configured values of *max* and *rep*. If *max* < *n* < *rep* (the number is not within any of the ranges), the packet is discarded. If the path is traced, then if:
+- *n* <= *max* and *N* > 1, e.g., *WIDE2-2*, the call sign of the digipeater with the *H-bit* is added before the element, and *N* is reduced by 1, e.g., *SR8XXX\*,WIDE2-1*.
+- *n* <= *max* and *N* = 1, e.g., *WIDE2-1*, the call sign of the digipeater with the *H-bit* is added before the element, *N* is reduced by 1 (becoming zero), and the *H-bit* is added, e.g., *SR8XXX\*,WIDE2\**.
+- *n* >= *rep* (if *rep* > 0), e.g., *WIDE7-4*, the element is replaced with the call sign of the digipeater with the *H-bit*, e.g., *SR8XXX\** (limiting the path). The value of *N* is not considered.
+
+If the path is untraced, then if:
+- *n* <= *max* and 1 < *N* < *n*, e.g., *SP3-2*, *N* is reduced by 1, e.g., *SP3-1*.
+- *n* <= *max* and *N* = *n*, and it is not the first element in the entire path, e.g., *...,SP3-3*, *N* is reduced by 1, e.g., *...,SP3-2* (behavior identical to before).
+- *n* <= *max* and *N* = *n*, and it is the first element in the entire path (the first hop of the packet), e.g., *SP3-3*, the path is treated as traced, i.e., the call sign of the digipeater with the *H-bit* is added before the element, and *N* is reduced by 1, e.g., *SR8XXX\*,SP3-2*.
+- *n* <= *max* and *N* = 1, e.g., *SP3-1*, *N* is reduced by 1 (becoming zero), and the *H-bit* is added, e.g., *SP3\**.
+- *n* >= *rep* (if *rep* > 0), e.g., *SP7-4*, the element is replaced with the call sign of the digipeater with the *H-bit*, e.g., *SR8XXX\** (limiting the path). The value of *N* is not considered.
+
+> Note! If *max* and *rep* values create overlapping intervals (*max* >= *rep*), the *max* value is given priority.
+
+> Note! If *rep* = 0, the path limiting functionality is disabled.
+
+If *direct only* functionality (repeating only packets received directly) is enabled for the matched alias, and the element is not the first element in the entire path or *N* < *n*, the packet is discarded.
+If *viscous delay* functionality is enabled for the matched alias, the completed packet is stored in a buffer, and its transmission is delayed. If the same packet is repeated by another digipeater within a specified time, the buffered packet is removed (see *the beginning of this section*). If none of these functions is enabled, the hash of the packet is saved to the duplicate filter buffer, and the packet is transmitted.
+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
+### 2023/09/06
+- First version - Piotr Wilkoń

doc/manual_pl.md

@@ -0,0 +1,325 @@
+# VP-Digi - dokumentacja
+Copyright 2023 Piotr Wilkoń\
+Zezwala się na kopiowanie, rozpowszechnianie i/lub modyfikowanie tego dokumentu na warunkach Licencji GNU Wolnej Dokumentacji (GNU Free Documentation License) w wersji 1.3 lub dowolnej nowszej opublikowanej przez Free Software Foundation,
+bez żadnych Części nienaruszalnych, bez Tekstów przedniej
+lub tylnej strony okładki. Egzemplarz licencji zamieszczono w pliku [LICENSE_FDL](LICENSE_FDL).\
+Rejestr zmian dostępny jest na końcu tego dokumentu.
+## Spis treści
+- [VP-Digi - dokumentacja](#vp-digi---dokumentacja)
+  - [Spis treści](#spis-treści)
+  - [1. Opis funkcjonalny](#1-opis-funkcjonalny)
+  - [2. Podręcznik użytkownika](#2-podręcznik-użytkownika)
+    - [2.1. Tryb konfiguracji](#21-tryb-konfiguracji)
+      - [2.1.1. Polecenia](#211-polecenia)
+      - [2.1.2. Przykładowe ustawienia](#212-przykładowe-ustawienia)
+    - [2.2. Tryb monitora](#22-tryb-monitora)
+      - [2.2.1. Polecenia](#221-polecenia)
+      - [2.2.2. Widok pakietów odbieranych](#222-widok-pakietów-odbieranych)
+    - [2.3. Tryb KISS](#23-tryb-kiss)
+    - [2.4. Kalibracja poziomów sygnału](#24-kalibracja-poziomów-sygnału)
+    - [2.5. Programowanie](#25-programowanie)
+      - [2.5.1. Programowanie za pomocą programatora ST-Link](#251-programowanie-za-pomocą-programatora-st-link)
+      - [2.5.2. Programowanie za pomocą przejściówki USB-UART](#252-programowanie-za-pomocą-przejściówki-usb-uart)
+    - [2.6. Uruchomienie](#26-uruchomienie)
+  - [3. Opis techniczny](#3-opis-techniczny)
+    - [3.1. Sprzęt](#31-sprzęt)
+      - [3.1.1. Odbiór](#311-odbiór)
+      - [3.1.2. Nadawanie](#312-nadawanie)
+    - [3.2. Oprogramowanie](#32-oprogramowanie)
+      - [3.2.1. Modem](#321-modem)
+        - [3.2.1.1. Demodulacja](#3211-demodulacja)
+        - [3.2.1.2. Modulacja](#3212-modulacja)
+        - [3.2.1.3. Odzyskiwanie bitów](#3213-odzyskiwanie-bitów)
+      - [3.2.2. Protokoły](#322-protokoły)
+        - [3.2.2.1. Odbiór](#3221-odbiór)
+        - [3.2.2.2. Nadawanie](#3222-nadawanie)
+      - [3.2.3. Digipeater](#323-digipeater)
+  - [4. Rejestr zmian dokumentacji](#4-rejestr-zmian-dokumentacji)
+    - [2023/09/06](#20230906)
+
+## 1. Opis funkcjonalny
+VP-Digi jest samodzielnym sterownikiem digipeatera AX.25 (np. APRS) oraz kontrolerem TNC w standardzie KISS.\
+Oprogramowanie wyposażone jest w modemy:
+- Bell 202 AFSK 1200 Bd 1200/2200 Hz (standard VHF)
+- G3RUH GFSK 9600 Bd (standard UHF)
+- Bell 103 AFSK 300 Bd 1600/1800 Hz (standard HF)
+- V.23 AFSK 1200 Bd 1300/2100 Hz (alternatywny standard VHF)
+
+Każdy modem wykorzystuje mechanizm wykrywania nośnej w oparciu o detekcję prawidłowego sygnału modulującego, a nie zdekodowanych danych, dzięki czemu zwiększona jest niezawodność, a ilość kolizji - zmniejszona.
+
+Ponadto oprogramowanie obsługuje protokoły:
+- AX.25 (standard Packet Radio/APRS)
+- FX.25 - AX.25 z korekcją błędów, w pełni kompatybilny z AX.25
+
+VP-Digi umożliwia konfigurację:
+- Własnego znaku, SSID i adresu przeznaczenia
+- Parametrów modemu (*TXDelay*, *TXTail*, czasu ciszy, typu DAC, typu odbiornika)
+- Prędkości pracy portów szeregowych
+- 4 aliasów digipeatera typu *New-N* (np. *WIDEn-N*)
+- 4 aliasów prostych digipeatera (np. *MIASTO*)
+- Progów ilości skoków dla aliasów typu *New-N*
+- Włączenia trasowania każdego aliasu
+- Trybu *viscous delay* i tylko bezpośredniego dla każdego aliasu
+- Listy filtrującej (wykluczanie lub wyłączność)
+- Włączenia odbioru pakietów niebędących pakietami APRS
+- Włączenia monitorowania własnych pakietów przez port KISS
+
+Urządzenie daje do dyspozycji:
+- 2 porty szeregowe
+- port USB
+
+z których każdy pracuje niezależnie i może działać w trybie:
+- TNC KISS
+- monitora ramek
+- terminala konfiguracyjnego
+
+## 2. Podręcznik użytkownika
+### 2.1. Tryb konfiguracji
+Konfiguracja urządzenia może być dokonana przez dowolny port (USB, UART1, UART2). Przejście do trybu konfiguracji następuje po wydaniu polecenia `config`.
+> Uwaga! Jeśli port pracuje w trybie KISS (domyślnym po uruchomieniu), to wpisywane znaki nie będą widoczne.
+
+> Uwaga! Po zakończeniu konfiguracji należy zapisać ją do pamięci poleceniem `save`
+
+#### 2.1.1. Polecenia
+W trybie konfiguracji dostępne są następujące polecenia:
+- `call ZNAK-SSID` - ustawia znak wywoławczy wraz z SSID. Znak wywoławczy musi składać się z maksymalnie 6 znaków A-Z i 0-9. SSID jest opcjonalne. SSID musi zawierać się w zakresie 0-15.
+- `dest ADRES` – ustawia adres przeznaczenia. Adres musi składać się z maksymalnie 6 znaków A-Z i 0-9, bez SSID. *APNV01* jest oficjalnym i zalecanym adresem dla VP-Digi.
+- `modem <1200/300/9600/1200_V23>` - ustawia typ modemu: *1200* dla modemu 1200 Bd, *300* dla modemu 300 Bd, *9600* dla modemu 9600 Bd lub *1200_V23* dla alternatywnego modemu 1200 Bd. 
+- `txdelay CZAS` – ustawia długość preambuły do nadania przed ramką. Wartość w milisekundach z zakresu od 30 do 2550
+- `txtail CZAS` – ustawia ogona nadawanego po ramce. Wartość w milisekundach, z zakresu od 10 do 2550. Jeśli nie zachodzi potrzeba, należy ustawić wartość minimalną.
+- `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 <on/off>` – *on* włącza, *off* wyłącza digipeater
+- `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).
+- `digi NUMER rep N` – ustawia minimalne *n* (z zakresu od 0 do 7), od którego aliasy typu *n-N* (zakres od 0 do 3) będą przetwarzane jak aliasy proste. *N* równe 0 wyłącza tę funkcję.
+- `digi NUMER trac <on/off>` – ustawia wybrany alias (z zakresu od 0 do 7) jako trasowalny (*on*) lub nietrasowalny (*off*)
+- `digi NUMER viscous <on/off>` – *on* włącza, *off* wyłącza funkcję *viscous delay* dla aliasu z zakresu od 0 do 7.
+- `digi NUMER direct <on/off>` – *on* włącza, *off* wyłącza funkcję powtarzania tylko ramek odebranych bezpośrednio dla aliasu z zakresu od 0 do 7.
+> Zasadę działania digipeatera opisano w [sekcji 3.2.3](#323-digipeater).
+- `digi NUMER filter <on/off>` – *on* włącza, *off* wyłącza filtrowanie ramek dla aliasu z zakresu od 0 do 7.
+- `digi filter <black/white>` – ustawia typ listy filtrującej ramki: *black* (wykluczenie - ramki od znaków z listy nie będą powtarzane) lub *white* (wyłączność – tylko ramki od znaków z listy będą powtarzane).
+- `digi dupe CZAS` – ustawia czas bufora filtrującego duplikaty, który zapobiega wielokrotnemu powtarzaniu już powtórzonego pakietu. Czas w sekundach z zakresu od 5 do 255.
+- `digi list POZYCJA set ZNAK-SSID` – wpisuje znak na wybraną pozycję (z zakresu od 0 do 19) listy filtrującej. Można używać znaku \* do zamaskowania wszystkich liter do końca znaku. *?* maskuje pojedynczą literę w znaku. Do zamaskowania SSID można użyć \* lub *?*.
+- `digi list POZYCJA remove` – usuwa wybraną pozycję (z zakresu od 0 do 19) z listy filtrującej
+- `monkiss <on/off>` – *on* włącza, *off* wyłącza wysyłanie własnych i powtórzonych ramek na porty KISS
+- `nonaprs <on/off>` – *on* włącza, *off* wyłącza odbiór pakietów niebędących pakietami APRS (np. dla Packet Radio)
+- `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.
+
+Ponadto dostępne są polecenia kontrolne:
+- `print` – pokazuje aktualne ustawienia.
+- `list` – pokazuje zawartość listy filtrującej.
+- `save` – zapisuje ustawienia do pamięci i restartuje urządzenie. Należy zawsze użyć tej komendy po zakończeniu konfiguracji. W przeciwnym wypadku niezapisana konfiguracja zostanie porzucona.
+- `eraseall` – czyści całą konfigurację i restartuje urządzenie.
+
+Dostępne są także polecenia wspólne:
+- `help` – pokazuje stronę pomocy
+- `reboot` – restartuje urządzenie
+- `version` – pokazuje informacje o wersji oprogramowania
+- `monitor` – przełącza port do trybu monitora
+- `kiss` – przełącza port do trybu KISS
+
+#### 2.1.2. Przykładowe ustawienia
+
+- Beacon\
+    Przykład dla beaconu o numerze 0. Dostępne są beacony od 0 do 7.
+    1. *beacon 0 data !5002.63N/02157.91E#Digi Rzeszow* – ustawienie danych beaconu w standardzie APRS
+    2. *beacon 0 path WIDE2-2,SP2-2* – ustawienie ścieżki
+    3. *beacon 0 iv 15* – nadawanie co 15 minut
+    4. *beacon 0 dl 5* – beacon będzie nadany po raz pierwszy po 5 minutach od uruchomienia urządzenia
+    5. *beacon 0 on* – uruchomienie beaconu
+- Digipeater WIDE1-1 (pomocniczy)\
+    Przykład dla aliasu o numerze 0. Dostępne są aliasy 0-3.
+    1. *digi 0 alias WIDE* – powtarzanie aliasów typu WIDEn-N. Liczby n i N NIE są ustawiane tutaj.
+    2. *digi 0 max 1* – powtarzanie ścieżek maksymalnie WIDE1-1
+    3. *digi 0 rep 0* – wyłączenie limitowania i upraszczania ścieżek
+    4. *digi 0 trac on* – włączenie trasowania ścieżki (ścieżki typu WIDEn-N są trasowane)
+    5. *digi 0 on* – włączenie obsługi danego aliasu
+    6. *digi on* – włączenie digipeatera
+
+- Digipeater pomocniczy *viscous delay* (zalecana konfiguracja)\
+    Przykład dla aliasu o numerze 0. Dostępne są aliasy 0-3.
+    1. *digi 0 alias WIDE* – powtarzanie aliasów typu WIDEn-N. Liczby n i N NIE są ustawiane tutaj.
+    2. *digi 0 max 2* – powtarzanie ścieżek maksymalnie WIDE2-2
+    3. *digi 0 rep 3* – ścieżki WIDE3-3 i dłuższe będą upraszczane przy powtarzaniu
+    4. *digi 0 trac on* – włączenie trasowania ścieżki (ścieżki typu WIDEn-N są trasowane)
+    5. *digi 0 viscous on* – włącznie trybu *viscous delay*
+    6. *digi 0 on* – włączenie obsługi danego aliasu
+    7. *digi on* – włączenie digipeatera
+
+- Digi regionalne WIDEn-N + SPn-N (zalecana konfiguracja)\
+    Przykład dla aliasów 0 (dla WIDE) i 1 (dla SP).
+    1. *digi 0 alias WIDE* – powtarzanie aliasów typu WIDEn-N. Liczby n i N NIE są ustawiane tutaj.
+    2. *digi 0 max 2* – powtarzanie ścieżek maksymalnie WIDE2-2
+    3. *digi 0 rep 3* – ścieżki WIDE3-3 i dłuższe będą upraszczane przy powtarzaniu
+    4. *digi 0 trac on* – włączenie trasowania ścieżki (ścieżki typu WIDEn-N są trasowane)
+    5. *digi 0 on* – włączenie obsługi danego aliasu
+    6. *digi 1 alias SP* – powtarzanie aliasów typu SPn-N. Liczby n i N NIE są ustawiane tutaj.
+    7. *digi 1 max 7* – powtarzanie maksymalnie ścieżek SP7-7
+    8. *digi 1 rep 0* – brak limitu dla ścieżki
+    9. *digi 1 trac off* – wyłączenie trasowania ścieżki (ścieżki regionalne nie są trasowane)
+    10. *digi 1 on* – włączenie obsługi danego aliasu
+    11. *digi on* – włączenie digipeatera
+
+### 2.2. Tryb monitora
+Praca urządzenia może być obserwowana przez dowolny port (USB, UART1, UART2). Przejście do trybu monitora następuje po wydaniu polecenia `monitor`.
+> Uwaga! Jeśli port pracuje w trybie KISS (domyślnym po uruchomieniu), to wpisywane znaki nie będą widoczne.
+
+W trybie monitora wyświetlane są pakiety odbierane i nadawane, a ponadto możliwe jest dokonanie kalibracji poziomów sygnału.
+
+#### 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. 
+
+Dostępne są także polecenia wspólne:
+- `help` – pokazuje stronę pomocy
+- `reboot` – restartuje urządzenie
+- `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
+
+Dla każdego odebranego pakietu AX.25 wyświetlany jest nagłówek w następującym formacie:
+> Frame received [...], signal level XX% (HH%/LL%)
+> 
+natomiast dla każdego odebranego pakietu FX.25:
+> Frame received [...], N bytes fixed, signal level XX% (HH%/LL%)
+
+Gdzie kolejno:
+- *...* określa, które modemy odebrały pakiet i jakiego rodzaju filtr został użyty. Możliwe są następujące statusy:
+  - *P* - filtr z preemfazą wysokiego tonu
+  - *D* - filtr z deemfazą wysokiego tonu
+  - *F* - filtr płaski
+  - *N* - brak filtra
+  - *_* - modem nie odebrał ramki\
+Przykładowo status *[_P]* oznacza, że pierwszy modem nie odebrał ramki, a drugi odebrał ramkę i używa filtru z preemfazą. Inny przykładowy status *[N]* oznacza, że dostępny jest tylko jeden modem bez filtra i to on odebrał ramkę.
+- *N* określa, ile bajtów zostało naprawionych przez protokół FX.25. Dla pakietów AX.25 pole to nie jest wyświetlane.
+- *XX%* określa, jaki jest poziom sygnału, tj. jego amplituda.
+- *HH%* określa, jaki jest poziom górnego piku sygnału.
+- *LL%* określa, jaki jest poziom dolnego piku sygnału.
+> Uwaga! Poziom górnego piku powinien być dodatni, a dolnego ujemny. Ponadto poziomy te powinny być symetryczne względem zera. Duża dysproporcja świadczy o nieprawidłowej polaryzacji wejścia przetwornika ADC.
+
+### 2.3. Tryb KISS
+Tryb KISS służy do pracy jako standardowe TNC KISS, współpracujące z wieloma programami do Packet Radio, APRS i podobnych. W trybie tym nie jest dostępne tzw. echo (odsyłanie wpisywanych znaków). Dostępne są jedynie polecenia przełaczenia trybu:
+- `monitor` – przełącza port do trybu monitora
+- `config` – przełącza port do trybu konfiguracji
+
+### 2.4. Kalibracja poziomów sygnału
+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.
+> 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
+Programowanie (wgranie oprogramowania) można przeprowadzić na dwa sposoby: za pomocą programatora *ST-Link* lub poprzez port szeregowy UART1 (np. za pomocą przejściówki USB-UART).\
+W obydwu sposobach konieczne jest wcześniejsze pobranie oprogramowania VP-Digi (plik HEX).
+#### 2.5.1. Programowanie za pomocą programatora ST-Link
+1. Pobrać i zainstalować program *ST-Link Utility* wraz z odpowiednimi sterownikami.
+2. Podłączyć VP-Digi do programatora.
+3. Podłączyć programator do złącza USB.
+4. W *ST-Link Utility* przejść do *File->Open file* i wybrać pobrany plik HEX z oprogramowaniem.
+5. Przejść do *Target->Program & Verify* i kliknąć *Start*. Po chwili urządzenie się zrestartuje i uruchomi się właściwe oprogramowanie.
+
+#### 2.5.2. Programowanie za pomocą przejściówki USB-UART
+1. Upewnić się, że przejściówka pracuje z poziomami logicznymi 0/3.3V. 
+2. Jeśli to konieczne, zainstalować sterowniki do przejściówki. 
+3. Pobrać i zainstalować program *Flasher-STM32*. 
+4. Na płytce ustawiamy zworkę bliższą przycisku reset na położenie 0, a dalszą na 1. 
+5. Podłączyć pin *TX* przejściówki do pinu *PA10*, a *RX* do *PA9*. Podłączyć zasilanie (np. z przejściówki). 
+6. Ustalić pod którym portem COM dostępna jest przejściówka.
+7. Uruchomić *Flasher-STM32*, wybrać odpowiedni port COM i kliknąć *Next*. 
+    > Jeżeli ukazał się błąd, należy zresetować mikrokontroler i sprawdzić połączenia oraz ustawienie zworek. 
+8. W następnym ekranie nacisnąć *Next*.
+9. Na kolejnym ekranie wybrać opcję *Download to device* i wybrać pobrany plik HEX. 
+10. Zaznaczyć opcje *Erase neccesary pages* oraz *Verify after download* i kliknąć *Next*. Po chwili układ powinien być zaprogramowany. Przestawić obydwie zworki z powrotem na położenie 0 i zresetować mikrokontroler, a przejściówkę odłączyć. Powinno uruchomić się właściwe oprogramowanie.
+### 2.6. Uruchomienie
+Urządzenie należy skonstruować wg schematu przedstawionego w [sekcji 3.1](#31-sprzęt), zaprogramować (opis w [sekcji 2.5](#25-programowanie)) i skalibrować (opis w [sekcji 2.4](#24-kalibracja-poziomów-sygnału)).\
+Po uruchomieniu wszystkie porty (USB, UART1, UART2) pracują w trybie KISS, a prędkość pracy portów UART1 i UART2 to 9600 Bd (prędkość portu USB nie ma znaczenia).\
+W celu konfiguracji VP-Digi lub monitorowania ramek koniecznie jest połączenie z komputerem przez port USB lub UART i zainstalowanie programu terminalowego (*TeraTerm*, *RealTerm* itp.). Jak wspominano w sekcjach poprzedzających, przejście do tryb konfiguracji i monitora następuje po wprowadzeniu poleceń, odpowiednio, `config` i `monitor` i zatwierdzeniu enterem. 
+> W trybie KISS odsyłanie wprowadzanych znaków (*echo*) jest wyłączone, zatem nie będzie widać wprowadzanych poleceń.
+
+Konfigurację urządzenia należy przeprowadzić za pomocą poleceń opisanych w [sekcji 2.1](#21-tryb-konfiguracji).
+
+## 3. Opis techniczny
+### 3.1. Sprzęt
+VP-Digi natywnie pracuje na mikrokontrolerze STM32F103C8T6 z częstotliwością rdzenia równą 72 MHz, co wymaga użycia zewnętrznego rezonatora 8 MHz. Do budowy urządzenia zalecane jest użycie płytki znanej jako *STM32 Blue Pill*.
+
+Budowę VP-Digi w oparciu o płytkę *STM32 Blue Pill* przedstawiono na schemacie:
+![VP-Digi schematic](schematic.png)
+#### 3.1.1. Odbiór
+Sygnał odbierany podawany jest na pin *PA0* z użyciem układu kondensatorów odsprzęgających (*C4*, *C6*) oraz rezystorów polaryzujących (*R6*, *R9*) i ograniczających (*R7*, *R11*). W celu zapewnienia poprawnego odbioru modulacji FSK muszą być zastosowane kondensatory o stosunkowo dużych pojemnościach. Dla zapewnienia poprawnego odbioru napięcie stałe na pinie *PA0* musi być w okolicach połowy napięcia zasilania, tj. 1.65 V. Nieprawidłowa polaryzacja objawia się w postaci asymetrii poziomu sygnału (patrz [sekcja 2.2.2](#222-widok-pakietów-odbieranych)) lub zanikiem odbioru.
+W torze odbiorczym zastosowano szeregowy rezystor *R7* mający na celu ograniczenie maksymalnego prądu pinu, aby wykorzystując wbudowane w mikrokontroler diody wykonać ogranicznik napięcia chroniący przetwornik przed uszkodzeniem spowodowanym zbyt dużym poziomem sygnału.\
+Jeśli radiotelefon ma regulowany poziom sygnału wyjściowego, to instalacja elementów *RV2*, *R11* i *C6* nie jest konieczna.
+#### 3.1.2. Nadawanie
+Sygnał nadawany może zostać generowany z użyciem przetwornika PWM lub R2R (niezalecany od wersji 2.0.0). Przetwornik PWM wykorzystuje sprzętową modulację szerokości impulsów oraz filtr RC drugiego rzędu (*R5*, *C3*, *R3*, *C2*) do odfiltrowania składowych niepożądanych. Filtr zbudowany jest z dwóch filtrów RC pierwszego rzędu o częstotliwości odcięcia ok. 7200 Hz w celu zapewnienia odpowiedniego pasma przenoszenia dla modemu 9600 Bd. Ponadto dla poprawnego nadawania modulacji FSK musi być zastosowany kondensator odsprzęgający *C1* o stosunkowo dużej pojemności.
+Rezystor *R2* służy do znacznego zmniejszenia amplitudy sygnału gdy używane jest standardowe wejście mikrofonowe o dużym wzmocnieniu. Wartość tego rezystora należy dobrać indywidualnie.
+Radiotelefon przełączany jest w stan nadawania poprzez podanie stanu niskiego przez tranzystor NPN *Q1*. Jeśli radiotelefon ma wejście PTT, to należy połączyć je bezpośrednio do kolektora tranzystora i nie montować rezystora *R1*. Dla standardowych radiotelefonów z wejściem mikrofonowym należy zainstalować rezystor *R1*.
+
+### 3.2. Oprogramowanie
+Oprogramowanie VP-Digi napisane jest w języku C z użyciem standardowych bibliotek CMSIS i nagłówków ST dla mikrokontrolera z użyciem operacji na rejestrach. Biblioteka HAL wykorzystana wyłącznie do obsługi USB oraz konfiguracji sygnałów zegarowych.
+#### 3.2.1. Modem
+##### 3.2.1.1. Demodulacja
+Odbiór ramek rozpoczyna się od próbkowania sygnału wejściowego. Sygnał wejściowy jest nadpróbkowany czterokrotnie, co daje odpowiednio próbkowanie 153600 Hz dla modemu 9600 Bd i 38400 Hz dla pozostałych modemów. Po odebraniu czterech próbek są one decymowane i wysyłane do dalszego przetwarzania (z wynikową częstotliwością, odpowiednio, 38400 Hz i 9600 Hz). Dla modemu 1200 Bd wykorzystywane jest 8 próbek na symbol, dla modemu 300 Bd - 32 próbki na symbol, a dla modemu 9600 Bd - 4 próbki na symbol. Z użyciem mechanizmu podobnego do AGC śledzona jest amplituda sygnału. Jeśli modem posiada filtr wstępny, to próbki są filtrowane. Dla modemów AFSK próbka obecna i poprzednie mnożone są przez sygnały liczbowego generatora o częstotliwościach odpowiadających częstoliwości tzw. *mark* i *space* (liczona jest korelacja, która tutaj odpowiada dyskretnej demodulacji częstotliwości). Wynik mnożenia w każdej ścieżce jest sumowany, a następnie wyniki są od siebie odejmowane, co daje "miękki" symbol. W przypadku modemu (G)FSK omówiony krok nie występuje, gdyż funkcję demodulatora FM (FSK) pełni radiotelefon. Na tym etapie prowadzone jest wykrywanie nośnej, które oparte jest o prostą cyfrową PLL. Pętla ta nominalnie działa z częstotliwością równą prędkości symbolowej sygnału (np. 1200 Hz = 1200 Bd). W momencie zmiany "miękkiego" symbolu odbieranego sprawdzana jest odległość od przejścia licznika PLL przez zero. Jeśli jest ona niewielka, tzn. sygnały te są w fazie, to sygnał wejściowy jest prawdopodobnie prawidłowy. Wówczas zwiększana jest wartość dodatkowego licznika. Jeśli przekroczy ona ustalony próg, to ostatecznie sygnał jest uznawany za prawidłowy. Algorytm działa również w drugą stronę - jeśli sygnały nie są w fazie, to wartość licznika jest zmniejszana.
+Sygnał zdemodulowany ("miękki symbol") jest filtrowany przez filtr dolnoprzepustowy (odpowiedni do prędkości symbolowej) w celu usunięcia szumu, a następnie wartość symbolu jest określana i przesyłana do mechanizmu odzyskiwania bitów.
+##### 3.2.1.2. Modulacja
+Modulator AFSK oparty jest o wystawianie próbek sygnału sinusoidalnego, wygenerowanego w momencie startu urządzenia, na przetwornik cyfrowo-analogowy. W zależności od częstotliwości symbolu zmieniana jest częstotliwość wystawiania próbek, tzn. dla tablicy o długości *N* i częstotliwości sygnału *f* kolejne próbki wystawiane są z częstotliwością *f/N*. W trakcie generowania sygnału zachowywana jest ciągłość indeksów tablicy, co skutkuje zachowaniem fazy sygnału.\
+W przypadku modemu GFSK symbole z warstwy wyższej (sygnał prostokątny) są filtrowane przez filtr dolnoprzepustowy (wspólny dla demodulatora i modulatora) i wystawiane ze stałą częstotliwością 38400 Hz na przetwornik.
+##### 3.2.1.3. Odzyskiwanie bitów
+Odzyskiwanie bitów prowadzone jest przez modem. Zastosowana jest cyfrowa PLL (podobna jak w przypadku wykrywania nośnej), działająca z częstotliwością równą częstotliwości symbolowej. W momencie każdego pełnego okresu pętli określana jest ostateczna wartość symbolu na podstawie kilku poprzednio odebranych symboli. W tym samym czasie faza pętli dostrajana jest do fazy sygnału, tzn. do momentów zmiany symbolu. W przypadku modemu wykorzystującego mieszanie bitów (*scrambling*, np. modem G3RUH) wykonywany jest *descrambling*. Ostatecznie wykonywane jest dekodowanie NRZI i bity są przekazywane do wyższej warstwy.
+#### 3.2.2. Protokoły
+##### 3.2.2.1. Odbiór
+Protokoły HDLC, AX.25 i w dużej mierze FX.25 obsługiwane są przez jeden moduł będący dość rozbudowaną maszyną stanów.
+Odebrane bity są na bieżąco zapisywane w rejestrze przesuwnym. Rejestr ten monitorowany jest pod kątem wystąpenia flagi HDLC w celu wykrycia początku i końca ramki AX.25, ale również synchronizacji bitowej z nadajnikiem (tzn. wyrównania do pełnego bajtu). Gdy włączony jest odbiór FX.25, to równoczeście monitorowane jest wystąpienie któregoś z tagów korelacyjnych, który również pełni funkcję synchronizacyjną i początku ramki, ale tym razem FX.25. Odbierane bity są zapisywane do bufora, a suma kontrolna jest na bieżąco liczona. Istotnym momentem jest odbiór pierwszych ośmiu bajtów danych, podczas których nie wiadomo, czy jest to ramka FX.25, czy nie, więc wówczas dekodery obydwu protokołów pracują równocześnie. Jeśli tag korelacyjny nie pokrywa się z żadnym znanym, to ramka traktowana jest jako pakiet AX.25. Wówczas bity zapisywane są aż do momentu wystąpienia kolejnej flagi. Następnie, jeśli dozwolony jest wyłącznie odbiór pakietów APRS, sprawdzane są pola Control i PID. Ostatecznie sprawdzana jest suma kontrolna. Jeśli jest prawidłowa, to dokonywana jest multipleksacja modemów (w wypadku gdy więcej niż jeden modem odbierze ten sam pakiet). W przypadku, gdy tag korelacyjny jest prawidłowy, to na jego podstawie określana jest oczekiwana długość pakietu i zapisywane są wszystkie bajty aż do osiągnięcia tej długości. Następnie sprawdzana jest poprawność danych i ewentualna naprawa z użyciem algorytmu Reeda-Solomona. Niezależnie od wyniku operacji surowa ramka jest dekodowana jak pakiet AX.25 (usuwane są dodatkowe bity, flagi) i sprawdzana jest suma kontrolna. Jeśli jest prawidłowa, to podobnie dokonywana jest multipleksacja modemów.
+##### 3.2.2.2. Nadawanie
+Podobnie jak w przypadku odbioru moduł generujący bity do nadania jest maszyną stanów. Początkowo nadawana jest preambuła o zadanej długości. Gdy używany jest protokół AX.25, to nadawana jest określona ilość flag i nadawane są bity informacyjne. Na bieżąco realizowane jest nadziewanie bitami (*bit stuffing*) i liczenie sumy kontrolnej, która jest dołączana po nadaniu całej ramki. Następuje nadanie określonej liczby flag, i jeżeli są kolejne pakiety do nadania, to od razu następuje przejście do nadania właściwych danych. Ostatecznie nadawany jest ogon o zadanej długości i transmisja kończy się.\
+W przypadku FX.25 pakiet wejściowy jest wcześniej kodowany jak pakiet AX.25, tzn. zostają dodane dodatkowe bity, flagi, CRC i pakiet jest umieszczany w oddzielnym buforze. Dzięki temu odbiorniki nieobsługujące FX.25 nadal będą mogły odebrać ten pakiet. Pozostała część bufora zostaje wypełniona odpowiednimi bajtami. Następnie wykonywane jest kodowanie Reeda-Solomona, które wprowadza do bufora bajty parzystości. Gdy rozpoczyna się transmisja, nadana zostaja preambuła, ale po niej nadawany jest odpowiednio dobrany tag korelacyjny. Wówczas następuje nadanie wcześniej przygotowanej ramki. Jeśli są do nadania kolejne pakiety, to proces się powtarza. Ostatecznie nadawany jest ogon i transmisja kończy się.
+#### 3.2.3. Digipeater
+Po odebraniu pakietu liczony jest jego hasz (algorytm CRC32). Następnie sprawdzane jest wystąpienie takiego samego haszu w buforze *viscous delay*. Jeśli hasze są takie same, to pakiet jest usuwany z bufora i nie są podejmowane żadne dalsze działania. Podobnie sprawdzane jest wystąpienie takiego samego haszu w buforze filtra duplikatów. Jeśli hasze są takie same, to pakiet jest od razu odrzucany. Następnie w ścieżce wyszukiwany jest *H-bit*, informujący o ostatnim elemencie ścieżki przetworzonym przez inne digipeatery. Jeśli nie ma kolejnego elementu gotowego do przetworzenia, to pakiet jest odrzucany. Jeśli występuje element gotowy do przetworzenia, to podejmowane są kroki:
+- element porównywany jest z własnym znakiem (tj. czy własny znak występuje *explicite* w ścieżce). Jeśli porównanie jest pomyślne, to do elementu dodawany jest tylko *H-bit*, np. *SR8XXX* przechodzi w *SR8XXX\**.
+- element jest w identyczny sposób porównywany z wszystkimi aliasami prostymi wpisanymi do konfiguracji (o ile są one włączone). Jeśli porównanie jest pomyślne, to:
+  - jeśli alias jest trasowalny, to zastąpiony zostaje własnym znakiem i dodany zostaje *H-bit* (np. *RZ* zostanie zmienione w *SR8XXX\**)
+  - jeśli alias nie jest trasowalny, to dodany zostaje tylko *H-bit* (np. *RZ* zostanie zmienione w *RZ\**)
+
+Pierwsza cześć elementu jest porówywana z wszystkimi aliasami *New-N* (o ile są one włączone). Jeśli porównanie jest pomyślne, to z elementu wyciągana jest liczba zwana *n*, a także zapisywane jest SSID zwane *N* (np. w ścieżce *WIDE2-1* liczba *n*=2, a *N*=1). Początkowo sprawdzane są warunki poprawności ścieżki, tzn. czy 0<*n*<8, czy 0<=*N*<8 oraz czy *N*<=*n*. Jeśli któryś z warunków nie jest spełniony, to pakiet jest odrzucany. Przykłady ścieżek niepoprawnych to:
+- *WIDE8-1*
+- *WIDE1-2*
+- *WIDE0-3*
+- *WIDE2-8*
+- i wiele innych 
+
+Jednocześnie jeśli w elemencie *N*=0, to ścieżka jest wyczerpana i pakiet jest odrzucany. Potem *n* porównywana jest z zapisaną wartością *max* oraz *rep*. Jeśli *max*<*n*<*rep* (liczba nie zawiera się w żadnym z ustawionych zakresów), to pakiet jest odrzucany. W przypadku, gdy ścieżka jest trasowana, to jeśli:
+- *n* <= *max* i *N* > 1, np. *WIDE2-2*, to przed elementem dodawany jest znak digipeatera z *H-bitem*, a *N* jest pomniejszane o 1, np. *SR8XXX\*,WIDE2-1*
+- *n* <= *max* i *N*=1, np. *WIDE2-1*, to przed elementem dodawany jest znak digipeatera z *H-bitem*, *N* jest pomniejszane o 1 (czyli staje się zerem) i dodawany jest *H-bit*, np. *SR8XXX\*,WIDE2\**
+- *n* >= *rep* (o ile *rep*>0), np. *WIDE7-4*, to element zostaje zastąpiony znakiem digipeatera z *H-bitem*, np. *SR8XXX\** (następuje ograniczenie ścieżki). Wartość *N* nie jest brana pod uwagę.
+
+W przypadku, gdy ścieżka nie jest trasowana, to jeśli:
+- *n* <= *max* i 1 < *N* < *n*, np. *SP3-2*, to *N* jest pomniejszane o 1, np. *SP3-1*
+- *n* <= *max* i *N* = *n* i nie jest to pierwszy element całej ścieżki, np. *...,SP3-3*, to *N* jest pomniejszane o 1, np. *...,SP3-2* (zachowanie identyczne jak wcześniej)
+- *n* <= *max* i *N* = *n* i jest to pierwszy element całej ścieżki (jest to pierwszy skok pakietu), np. *SP3-3*, to ścieżka traktowana jest jak trasowalna, tzn. przed elementem dodawany jest znak digipeatera z *H-bitem*, a *N* jest pomniejszane o 1, np. *SR8XXX\*,SP3-2*
+- *n* <= *max* i *N* = 1, np. *SP3-1*, to *N* jest pomniejszane o 1 (staje się zerem) i dodawany jest *H-bit*, np. *SP3\**
+- *n* >= *rep* (o ile *rep* > 0), np. *SP7-4*, to element zostaje zastąpiony znakiem digipeatera z *H-bitem*, np. *SR8XXX\** (następuje ograniczenie ścieżki). Wartość *N* nie jest brana pod uwagę.
+
+> Uwaga! Jeśli wartości *max* i *rep* tworzą zachodzące na siebie przedziały (*max* >= *rep*), to wartość *max* jest traktowana priorytetowo.
+
+> Uwaga! Jeśli *rep*=0, to funkcjonalność ograniczania ścieżki jest wyłączona.
+
+Jeśli dla dopasowanego aliasu włączona jest funkcja *direct only* (powtarzania wyłącznie pakietów odebranych bezpośrednio), a element nie jest pierwszym elementem w całej ścieżce lub *N* < *n*, to pakiet jest odrzucany.
+Jeśli dla dopasowanego aliasu włączona jest funkcja *viscous delay*, to gotowy pakiet zapisywany jest w buforze, a jego nadanie jest odkładane. Jeśli ten sam pakiet zostanie powtórzony przez inny digipeater w określonym czasie, to zbuforowany pakiet zostanie usunięty (patrz *początek tej sekcji*). Jeśli żadna z tych funkcji nie jest włączona, to do bufora filtra duplikatów zapisywany jest hasz pakietu i pakiet jest wysyłany.\
+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
+### 2023/09/06
+- Pierwsza wersja - Piotr Wilkoń