File: aprx.8.in

package info (click to toggle)
aprx 2.9.0+dfsg-2
  • links: PTS, VCS
  • area: main
  • in suites: bullseye, buster, sid
  • size: 2,352 kB
  • sloc: ansic: 15,809; sh: 598; makefile: 160
file content (1427 lines) | stat: -rw-r--r-- 44,813 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
.TH aprx 8 "@DATEVERSION@"
.SH NAME
.B Aprx-2
\- An APRS iGate application with integrated Digipeater.
.SH SYNOPSIS
.B aprx
.RB [ \-d [ d [ d ]]]
.RB [ \-e ]
.RB [ \-i ]
.RB [ \-v ]
.RB [ \-V ]
.RB [ \-l " \fIsyslogfacilityname\fR]"
.RB [ \-f " \fI@CFGFILE@\fR]"
.SH DESCRIPTION
The
.B aprx
program is a special purpose Ham-radio application supplying
infrastructure services for APRS protocol use.
.PP
A more detailed manual is available at:
.br
http://ham.zmailer.org/oh2mqk/aprx/aprx-manual.pdf
.PP
.SH FEATURES
The Aprx begun as a receive-only APRS iGate application with minimum system
support technology requirements.
This version has also multi-port digipeater support, transmit iGate,
and experimental D-PRS-to-APRS RF/Rx-iGate.
.PP
.IP \(bu 3
The Aprx does not require machine to have any other software in it, than things
in UNIX standard libc. In particular no special AX.25 libraries at all, nor
widgets or even C++ runtime.
.IP \(bu 3
Important goal has been to keep R/W memory footprint as small as possible,
and on general purpose i386 Linux a single radio port iGate+digipeater is
now around 250 kB of R/W memory allocations.
.IP \(bu 3
Any UNIX (and UNIX like) platform should work for the Aprx, or be trivially ported.
.IP \(bu 3
The Aprx can listen "TNC2 monitor" and "KISS" speaking TNCs on any serial ports.
.IP \(bu 3
For Aprx the serial port can be ordinary host computer port, a USB serial port,
or remote port on a remote server behind the internet, like cisco router AUX
ports (port 4001, TCP STREAM without TELNET escapes.)
.IP \(bu 3
The Aprx does not require machine to have AX.25 protocol support internally!
(Thus this works also on e.g. Solaris and BSD machines without PF\_AX25 sockets.)
.IP \(bu 3
On Linux machine with kernel internal AX.25 protocol support,
the Aprx can listen on it with promiscuous mode and in order to use that,
the Aprx must be started as
.I root
user, and be configured to list interface callsigns that APRS packets are
coming in.
The AX.25 socket listening is not in itself configurable, it is always exists
in Linux systems, and related configuration parameters are ignored in other
platforms.
This socket listening does not need auxiliary "libax25" to function.
.IP \(bu 3
The Aprx program can be run without root privileges at least against remote
serial port servers.  One must change local serial port ownership or
access-groups (if any are used) to userid that runs the program and possibly
do several changes of file paths in configuration file beginning
with its location (startup parameter).
How that is done is up to the user or system integrator of this program.
.IP \(bu 3
The Aprx connects with one callsign-ssid pair to APRS-IS core for all received
radio ports.
.IP \(bu 3
The Aprx Rx-iGate knows that messages with following tokens in AX.25 VIA
fields are not to be relayed into APRS-IS network:
.RS 9
.B "RFONLY, NOGATE, TCPIP, TCPXX"
.RE
.IP \(bu 3
The Aprx Rx-iGate knows that following source address prefixes are bogus and
thus messages with them are to be junked:
.RS 9
.B "WIDE, RELAY, TRACE, TCPIP, TCPXX, NOCALL, N0CALL"
.RE
.IP \(bu 3
The Aprx Rx-iGate Drops all
.I query
messages ("?").
.IP \(bu 3
The Aprx Rx-iGate opens up all 3rd party messages ("}"), and checks the internal
data if it is OK to be gated out to APRS-IS.
.IP \(bu 3
The Aprx has built-in "Erlang monitor" mechanism that telemeters each receiving
interface to APRS-IS. It can also syslog the interface specific channel occupancy,
and optionally can output to STDOUT.
.IP \(bu 3
The Aprx (since version 1.91) can do digipeater functions.
.IP \(bu 3
The Aprx (since version 1.99) does have experimental D-STAR D-PRS to APRS
gateway functionality.  See the
.I aprx-manual.pdf
for details.
.IP \(bu 3
The Aprx can be run on systems without writable storage, even with very little
memory, like on NSLU2, and OpenWrt platforms.
The experiments have shown that a single radio Tx-iGate+digipeater works
with less than 300 kB of writable RAM for the Aprx itself.
Additional memory is necessary for operating system services of TCP/IP
networking, and serial port drivers.
.PP
.SH OPTIONS
The
.B aprx
has following runtime options:
.TP
.B "\-i"
Keep the program foreground without debugging outputs.
.TP
.B "\-d"
Turn on verbose debugging, outputs data to STDOUT.
.TP
.B "\-dd"
the "more debug" mode shows also details of network interaction with
the APRS-IS network service.
.TP
.B "\-ddd"
the "even more debug" mode shows also detail classification of
every kind of frame received in KISS variants.
.TP
.B "\-e"
.I "Erlang output"
prints 10 minute and 60 minute traffic accumulation byte counts, and guestimates
on channel occupancy, alias "Erlang".
These outputs are sent to STDOUT, which system operator may choose to log elsewere.
This is independent if the "\-l" option below.
.TP
.BI "\-f " "@CFGFILE@"
Configuration file, given path is built-in default, and can be overridden by the program runner.
.TP
.BR "\-l" " \fIsyslogfacilityname\fR"
Defines
.RB syslog (3)
facility code used by the erlang reporter by defining its name.
Default value is:
.BR NONE ,
and accepted values are:
.BR LOG_DAEMON ,
.BR LOG_FTP ,
.BR LOG_LPR ,
.BR LOG_MAIL ,
.BR LOG_NEWS ,
.BR LOG_USER ,
.BR LOG_UUCP ,
.BR LOG_LOCAL0 ,
.BR LOG_LOCAL1 ,
.BR LOG_LOCAL2 ,
.BR LOG_LOCAL3 ,
.BR LOG_LOCAL4 ,
.BR LOG_LOCAL5 ,
.BR LOG_LOCAL6 ,
.BR LOG_LOCAL7 .
That list is subject to actual facility code set in the system,
and in any case if you specify a code that is not known, then the program
will complain during the startup, and report it.
This is independent of the "\-e" option above.
.TP
.B "\-v"
Verbose logging of received traffic to STDOUT.
Lines begin with reception timestamp (UNIX time_t seconds), then TAB,
and either data as is, or with prefix byte: "*" for "discarded due to data content",
or possibly "#" for "discarded due to APRS-IS being unreachable".
.TP
.B "\-V"
Print source version compiled to this binary, and exit.
.PP
.SS DEBUGGING SYSTEM
Use parameter set 
.B "\-ddv"
(or
.BR "\-dddv" )
to test new configuration by running it synchronously to console.
.PP
.SS NORMAL OPERATION
Running the
.B aprx
program without any of option flags:
.BR "\-d" ,
.BR "\-v" ", or"
.B "\-e"
reads possibly given configuration, then automatically backgrounds the process, and writes
.IR pidfile .
When the process whose number written in
.I pidfile
is then sent a SIGTERM signal, it automatically shuts down itself, and removes the
.IR pidfile .
The
.I pidfile
can be runtime configured with the
.BI \-f " @CFGFILE@"
file, and it has default name of:
.IR "@VARRUN@/aprx.pid" .
.PP

.SH CONFIGURATION FILE
The configuration file is used to setup the program to do its job.
.PP
You can construct following configurations:
.PP
.IP \(bu 3
A
.I receive-only
iGate server.
.IP \(bu 3
A digipeater with bi-directional iGate server.
.IP \(bu 3
A
.I "single radio"
digipeater.  (The most common type of digipeater.)
.IP \(bu 3
A
.I multi-interfaced
digipeater relaying traffic in between multiple radios.  (On same or on separate frequencies.)
.IP \(bu 3
A
.I "viscuous digipeater,"
which relays a packet it heard from viscuous source after the viscuous delay,
.I unless it was heard more times than only once,
or it was heard from non-viscuous source before the viscuous one was digipeated.
This allows of making fill-in digipeaters that will not digipeat the packet,
if that same packet was heard twice or more before the viscuos delay expired.
.PP
In the configuration file a line ending backslash (\\) character concatenates
next input line into itself. Combined result can be up to 8000 bytes long.
This combination can be a bit surprising:
.RS 3em
.nf
\fC#beacon .... long text  \\
       continuation\fR
.fi
.RE
results in single long input line that begins with '#' (it is comment) and all
continuations following it have been folded in.
Presented line number of combined continuation is the line number of the
.I last
line segment in this type of multi-line input.
.PP
In the configuration file there is special treatment for quoted strings.
They are stripped of the outer quotes, and "\fC\\\fR" character is processed within
the source string to produce an output string.
The escapes are:
.TP
.B "\fC\\\\n"
Produces newline character (Control-J) on the output string.
.TP
.B "\fC\\\\r"
Produces carriage return character (Control-M) on the output string.
.TP
.B "\fC\\\\\\\\"
Places a back-slash on the output string.
.TP
.B "\fC\\\\""
.\" foo "
Places a double-quote on the output string.
.TP
.B "\fC\\\\'"
Places a single-quote on the output string.
.TP
.B "\fC\\\\xHH"
Lower-case "x" precedes two hex digits which ensemble is then converted to a single byte in the output string.
.PP
The complex encodings are for possible initstrings of the external devices,
and in particular for initstrings even a nul byte ( \\x00 ) is supported.
.PP
A configuration token without surrounding quotes does not understand the backslash escapes.
.PP
.nf
\fC
#
#  Sample configuration file for the APRX -- an Rx-only APRS iGate with
#  Digipeater functionality.
#
#
# Simple sample configuration file for the APRX-2
#
# This configuration is structured with Apache HTTPD style tags
# which then contain subsystem parameters.
#

#
# For simple case, you need to adjust 4 things:
#   - Mycall parameter
#   - Select correct type of interface (ax25-device or serial-device)
#   - Optionally set a beacon telling where this system is
#   - Optionally enable digipeater with or without tx-igate
#

#
#
# Define the parameters in following order:
#   1)  <aprsis>     ** zero to many
#   2)  <logging>    ** zero or one
#   3)  <interface>  ** one to many
#   4)  <beacon>     ** zero to many
#   5)  <telemetry   ** zero to many
#   6)  <digipeater> ** zero to many (at most one for each Tx)
#

#
# Global macro for simplified callsign definition:
# Usable for 99+% of cases.
#

mycall  N0CALL-1

#
# Global macro for simplified "my location" definition in
# place of explicit "lat nn lon mm" at beacons. Will also
# give "my location" reference for "filter m/100".
#
#myloc lat ddmm.mmN lon dddmm.mmE

<aprsis>
# The  login  parameter: 
# Station call\-id used for relaying APRS frames into APRS\-IS.
# Use this only to define other callsign for APRS\-IS login.
#
#login      OTHERCALL-7  # login defaults to $mycall

#
# The passcode parameter:
# Unique code for your callsign to allow transmitting packets
# into the APRS-IS.
#
passcode \-1



# APRS-IS server name and portnumber.
# Every reconnect does re\-resolve the name to IP address.
# Some alternates are shown below, choose something local to you.
#
server    rotate.aprs2.net    14580
#server    noam.aprs2.net     14580
#server    soam.aprs2.net     14580
#server    euro.aprs2.net     14580
#server    asia.aprs2.net     14580
#server    aunz.aprs2.net     14580

# Some APRS\-IS servers tell every about 20 seconds to all contact
# ports that they are there and alive. Others are just silent.
# Recommended value 3*"heartbeat" + some  \-> 120 (seconds)
#
#heartbeat\-timeout  0  # Disabler of heartbeat timeout

# APRS-IS server may support some filter commands.
# See:  http://www.aprs-is.net/javAPRSFilter.aspx
#
# You can define the filter as single long quoted string, or as
# many short segments with explaining comments following them.
#
# Usability of these filters for a Tx-iGate is dubious, but
# they exist in case you for example want to Tx-iGate packets
# from some source callsigns in all cases even when they are
# not in your local area.
#
#filter "possibly multiple filter specs in quotes"
#
#filter "m/100"          # My-Range filter
#filter "f/OH2XYZ\-3/50"  # Friend-Range filter
</aprsis>


<logging>
# pidfile is UNIX way to tell that others that this program is
# running with given process-id number.  This has compiled-in
# default value of:  pidfile @VARRUN@/aprx.pid
#
#pidfile @VARRUN@/aprx.pid

# rflog defines a rotatable file into which all RF-received packets
# are logged.
#
#rflog @VARLOG@/aprx\-rf.log

# aprxlog defines a rotatable file into which most important 
# events on APRS\-IS connection are logged, namely connects and
# disconnects.
#
#aprxlog @VARLOG@/aprx.log

# erlangfile defines a mmap():able binary file, which stores
# running sums of interfaces upon which the channel erlang
# estimator runs, and collects data.
# Depending on the system, it may be running on a filesystem
# that actually retains data over reboots, or it may not.
# With this backing store, the system does not loose cumulating
# erlang data over the current period, if the restart is quick,
# and does not stradle any exact minute.
# (Do restarts at 15 seconds over an even minute..)
# This file is around 0.7 MB per each interface talking APRS.
# If this file is not defined and can not be created,
# internal non-persistent in-memory storage will be used.
#
# Built-in default value is: @VARRUN@/aprx.state
#
#erlangfile @VARRUN@/aprx.state

# erlang\-loglevel is config file edition of the "\-l" option
# pushing erlang data to syslog(3).
# Valid values are (possibly) following: NONE, LOG_DAEMON,
# LOG_FTP, LOG_LPR, LOG_MAIL, LOG_NEWS, LOG_USER, LOG_UUCP,
# LOG_LOCAL0, LOG_LOCAL1, LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4,
# LOG_LOCAL5, LOG_LOCAL6, LOG_LOCAL7.  If the parameter value is
# not acceptable, list of accepted values are printed at startup.
#
#erlang\-loglevel NONE

# erlanglog defines a rotatable file into which erlang data
# is written in text form.
#
#erlanglog @VARLOG@/erlang.log

# erlang\-log1min option logs to syslog/file also 1 minute
# interval data from the program. (In addition to 10m and 60m.)
#
#erlang\-log1min
</logging>



# ***********  Multiple <interface> definitions can follow   *********

# ax25\-device  Lists AX.25 ports by their callsigns that in Linux
#              systems receive APRS packets.  If none are defined,
#              or the system is not Linux, the AX.25 network receiver
#              is not enabled.  Used technologies need at least
#              Linux kernel 2.4.x
#
# tx\-ok        Boolean telling if this device is able to transmit.
#
#<interface>
#   ax25\-device $mycall  # Either $mycall macro, or actual callsign
#   #tx\-ok      false  # transmitter enable defaults to false
#   #telem\-to\-is true # set to false to disable
#</interface>

# The  TNC serial  options.  Parameters are:
#   \- /dev/ttyUSB1    \-\- tty device
#   \- 19200           \-\- baud rate, supported ones are:
#                        1200, 2400, 4800, 9600, 19200, 38400, ...
#   \- 8n1             \-\- 8\-bits, no parity, one stop\-bit,
#                        no other supported modes
#   \- "KISS"                  \- plain basic KISS mode
#   \- "XORSUM" alias "BPQCRC" \- KISS with BPQ "CRC" byte
#   \- "SMACK"  alias "CRC16"  \- KISS with real CRC
#   \- "FLEXNET"               \- KISS with real CRC
#   \- "TNC2"                  \- TNC2 monitor format
#   \- "DPRS"                  \- DPRS (rx) Gateway
#
#<interface>
#   serial\-device /dev/ttyUSB0  19200 8n1    KISS
#   #callsign     $mycall  # Either $mycall macro, or actual callsign
#   #tx\-ok        false    # transmitter enable defaults to false
#   #telem\-to\-is true # set to false to disable
#</interface>
#
#<interface>
#   serial\-device /dev/ttyUSB1  19200 8n1    TNC2
#   #callsign     $mycall  # Either $mycall macro, or actual callsign
#   #tx\-ok        false    # TNC2 monitor can not have transmitter
#   #telem\-to\-is true # set to false to disable
#</interface>
#
#<interface>
#   serial\-device /dev/ttyUSB1  19200 8n1    DPRS
#   callsign     dprsgwcallsign  # must define actual callsign
#   #tx\-ok        false    # DPRS monitor can not do transmit
#   #telem\-to\-is true # set to false to disable
#</interface>
#


# ***********  Multiple <beacon>  definitions can follow   *********
<beacon>
#
#  Beacons are sent out to radio transmitters AND/OR APRSIS.
#  Default is "both", other modes are settable.
#
#beaconmode { aprsis | both | radio }
#
#  Beacons are sent from a circullar transmission queue, total cycle time
#  of that queue is 20 minutes by default, and beacons are "evenly"
#  distributed along it.  Actual intervals are randomized to be anything
#  in between 80% and 100% of the  cycle-size / number-of-beacons.
#  First beacon is sent out 30 seconds after system start.
#  Tune the cycle-size to be suitable to your number of defined beacons.
#
#cycle-size  20m
#
#
# Basic beaconed thing is positional message of type "!":
#
#beacon symbol "R&" lat "0000.00N" lon "00000.00E" comment "Rx-only iGate"
#beacon symbol "R&" $myloc comment "Rx-only iGate"
#
# Following are basic options:
#  'symbol'    no default, must be defined!
#  'lat'       coordinate latitude:   ddmm.mmN  (no default!)
#  'lon'       coordinate longitude: dddmm.mmE  (no default!)
#  '$myloc'    coordinate values taken from global 'myloc' entry,
#              and usable in place of explicit 'lat'+'lon'.
#  'comment'   optional tail part of the item, default is nothing
#
# Sample symbols:
#   R&   is for "Rx-only iGate"
#   I&   is for "Tx-iGate"
#   /#   is for "Digipeater"
#   I#   is for "Tx-iGate + Digipeater"
#
# Additional options are:
# 'srccall'   parameter sets claimed origination address.
# 'dstcall'   sets destination address, default "APRXnn"
# 'interface' parameter picks an interface (must be "tx-ok true" type)
# 'via'       sets radio distribution pattern, default: none.
# 'timefix'  On APRS messages with HMS timestamp (hour:min:sec), the
#            system fixes appropriate field with transmit time timestamp.
#
# Message type is by default '!', which is positional no timestamp format.
# Other possible formats are definable with options:
# 'type'   Single character setting type:  ! = / @ 
# 'item'   Defines a name of Item (')') type beacons.
# 'object' Defines a name of Object (';') type beacons.
#
# 'file' option tells a file at which a _raw_ APRS message content is
#        expected to be found as first line of text. Line ending newline
#        is removed, and no escapes are supported.  The timefix is
#        available, though probably should not be used.
#
# 'exec' option defines program path for a program whose stdout is
#        read up to first newline (which must be present), and then
#        transmit as beacon content. No format helpers are supplied,
#        although 'timefix' can be used.
# 'timeout' option is associated with 'exec', and defines when the
#        exec must by latest produce the output, or the subprogram
#        execution is killed. Default value is 10 seconds.
#
# The parameter sets can vary:
#  a) 'srccall nnn-n dstcall "string" symbol "R&" lat "ddmm.mmN" lon "dddmm.mmE" [comment "any text"]
#  b) 'srccall nnn-n dstcall "string" raw "string"'
#
# The a) form flags on some of possible syntax errors in parameters.
# It will also create only "!" type messages.  The dest parameter
# defaults to "APRS", but can be used to give other destinations.
# The via parameter can be used to add other keywords, like "NOGATE".
#
# Writing correct RAW format beacon message is very hard,
# which is evidenced by the frequency of bad syntax texts
# people so often put there...   If you can not be persuaded
# not to do it, then at least VERIFY the beacon result on
# web service like  findu.com,  or  aprs.fi
#
#beacon                 file /tmp/wxbeacon.txt
#beacon srccall N0CALL\-3 raw "!0000.00NR00000.00E&aprx \- an Rx\-only iGate"
#beacon srccall N0CALL\-3 raw "!0000.00NI00000.00E&aprx \- an iGate"
#beacon srccall $mycall symbol "R&" lat "0000.00N" lon "00000.00E"  \\
                        comment "aprx \- an Rx\-only iGate"
#beacon srccall $mycall symbol "I&" lat "0000.00N" lon "00000.00E"  \\
                        comment "aprx iGate"
</beacon>

# ***********  <telemetry>  definition(s) follow   *********
#
# The system will always send telemetry for all of its interfaces
# to APRSIS, but there is an option to define telemetry to be sent
# to radio channel by using following sections for each transmitter
# that is wanted to send out the telemetry.
#
#   transmitter   -  callsign referring to <interface>
#   via           -  optional via-path, only 1 callsign!
#   source        -  one or more of <interface> callsigns for which
#                    the telemetry transmission is wanted for
#
#<telemetry>
#	transmitter	$mycall
#	via		TRACE1-1
#	source		$mycall
#</telemetry>


# ***********  <digipeater>  definition(s) follow   *********
#
#  The digipeater definitions tell transmitters that receive
#  AX.25 packets from possibly multiple sources, and then what
#  to do on the AX.25 headers of those messages.
#
#  There is one transmitter per digipeater \-\- and inversely, there
#  can be at most one digipeater for each transmitter.
#
#  In each digipeater there is at least one <source>, usually same
#  as the transmitter.
#
#<digipeater>
#    transmitter     $mycall
#    #ratelimit      60 120      # default: average 60 packets/minute,
#                                #          burst max 120 packets/minute
#    #srcratelimit   10 20       # Example: by sourcecall:
#                                #          average 10 packets/minute,
#                                #          burst max 20 packets/minute
#
#    <source>
#        source         $mycall
#    #   ratelimit      60 120      # default: average 60 packets/minute,
#    #                              #          burst max 120 packets/minute
#    #   viscous\-delay  0     # no viscous delay for RF\->RF digipeat
#    #   ratelimit      120   # default: max 120 packets/minute
#    </source>
#
#    #<source>          # Adding APRSIS source makes this tx-igate
#    #   source        APRSIS
#    #   ratelimit      60 120      # default: average 60 packets/minute,
#    #                              #          burst max 120 packets/minute
#    #   relay\-type    third\-party  # Must define this for APRSIS source!
#    #   viscous\-delay  5 # Recommendation: 5 seconds delay to give
#    #                    # RF delivery time make itself known.
#    #   filter         t/m  # Tx-iGate only messages sent to me by APRSIS
#    #</source>
#
#</digipeater>
\fR
.fi
.PP
.SH GLOBAL MYCALL PARAMETER
In majority of usage models, system needs single configured callsign.
This is set by using the
.B mycall
configuration option, and latter referred to in configurations as
.B $mycall
parameter in place of callsigns.
.PP
.SH GLOBAL MYLOC PARAMETER
Usually multiple beacons, and simple filter rules are wanted to be using
same reference coordinate for this system.
This is set by using the
.B myloc
configuration option, and latter referred to in configurations as
.B $myloc
parameter in place of "lat nn lon mm" coordinate pair of beacons.
.SH APRSIS SECTION FOR APRSIS CONNECTIVITY
Settings in the
.B <aprsis>
section define connectivity with the APRS-IS network service.
.PP
Necessary option is
.IR server ,
and others are optional.
.PP
Available options are:
.IP "\fClogin $mycall\fR" 8em
The APRSIS network login.
Defaults to the
.B mycall
configuration entry.
.IP "\fCpasscode -1\fR" 8em
Defining a small integer in range of 0 to 32767 authenticating your login
to APRS-IS server. Ask for assistance from your APRS-IS managers, or calculate
it yourself with
.I aprspass
program. (Web search engines do find several of them.)
.IP "\fCserver \fIserver-name 14850\fR" 8em
Define which APRS-IS is being connected to.
Multiple definitions are used in round-robin style,
if the connection with the previous one fails for some reason.
.PP
.IP "\fCfilter \fI'filter specs in quotes'\fC # \fIcomments" 8em
Set filter adjunct definitions on APRS-IS server.
Multiple entries are catenated together in entry order,
when connecting to the server.
.PP
.SH LOGGING SECTION
The
.B <logging>
section defines miscellaneous file names and options for state tracking and logging use.
.PP
.IP "\fCpidfile \fI@VARRUN@/aprx.pid\fR" 8em
The pidfile is UNIX way to tell that others that this program is
running with given process-id number.
This has compiled-in default value of: \fCpidfile @VARRUN@/aprx.pid
.IP "\fCrflog \fI@VARLOG@/aprx\-rf.log\fR" 8em
The
.I rflog
defines a rotatable file into which all RF-received packets are logged.
There is no default.
.IP "\fCaprxlog \fI@VARLOG@/aprx.log\fR" 8em
The
.I aprxlog
defines a rotatable file into which most important events on APRS-IS
connection are logged, namely connects and disconnects.
There is no default.
.IP "\fCerlangfile \fI@VARRUN@/aprx.state\fR" 8em
The
.I erlangfile
defines a mmap():able binary file, which stores running sums of interfaces
upon which the channel erlang estimator runs, and collects data.
Depending on the system, it may be running on a filesystem that actually
retains data over reboots, or it may not.
With this backing store, the system does not loose cumulating erlang data
over the current period, if the restart is quick, and does not stradle
any exact minute.
This file is around 0.7 MB per each interface talking APRS.
If this file is not defined and can not be created,
internal non-persistent in-memory storage will be used.
Built-in default value is: @VARRUN@/aprx.state
.IP "\fCerlang\-loglevel \fINONE\fR" 8em
The
.I erlang\-loglevel
is config file edition of the "\-l" option pushing erlang data to
.IR syslog (3).
Valid values are (possibly) following: NONE, LOG_DAEMON,
LOG_FTP, LOG_LPR, LOG_MAIL, LOG_NEWS, LOG_USER, LOG_UUCP,
LOG_LOCAL0, LOG_LOCAL1, LOG_LOCAL2, LOG_LOCAL3, LOG_LOCAL4,
LOG_LOCAL5, LOG_LOCAL6, LOG_LOCAL7.
If the parameter value is not acceptable, list of accepted
values are printed at startup.
.IP "\fCerlanglog \fI@VARLOG@/erlang.log\fR" 8em
The erlanglog defines a rotatable file into which erlang data
is written in text form.
There is no default.
.IP "\fCerlang\-log1min\fR" 8em
The
.I erlang\-log1min
option logs to syslog/file also 1 minute interval data from the program.
(In addition to 10m and 60m.)
Default is off.
.PP
.SH INTERFACE SECTIONS FOR RADIO PORTS
The
.B <interface>
sections define connections to radio modems.
Several different styles are available:
.IP \(bu 2
Local serial ports in the machine
.RB ( "device\-serial /dev/ttyS0 " "\fIspeed encapsulation\fR)"
.IP \(bu 2
Local USB serial ports in the machine
.RB ( "device\-serial /dev/ttyUSB0 " "\fIspeed encapsulation\fR)"
.IP \(bu 2
Remote served serial ports over a TCP stream.
Implemented to talk with Cisco AUX ports on "range 4000"
(TCP STREAM, no TELNET escapes)
.RB ( "tcp\-device 12.34.56.78 4001 " "\fIencapsulation\fR)"
.IP \(bu 2
Linux internal AX.25 network attached devices
.RB ( "ax25\-device CALLSIGN\-1" )
are only available when running on a Linux system.
On a non-Linux system it connects to a null interface, never
getting anything and can always sink everything.
.PP
The serial port name tells what kind of port is in question,
and while port baud-rate (9600) and character settings (8n1)
must always be set, they are ignored for the remote connection.
.PP
Following
.I speed
modes are available:
.br
.B "    " 1200,
.I 1800,
.B 2400, 4800, 9600, 19200,
.I 38400, 57600,
.br
.I "    " 115200, 230400, 460800, 500000, 576000
.br
Likely available speeds are in bold, other supported values
are listed in italics.
.PP
Following
.I encapsulation
modes are available:
.TP 10em
.B TNC2
is capable only to monitor the packets reported by TNC2 type
debug output, and Rx-iGate, but they are not acceptable as
source for a <digipeater>.
.TP 10em
.B DPRS
is special mode for gateway from D-STAR D-PRS to APRS.
This must always have a callsign definition for the gateway.
.TP 10em
.B KISS
Basic KISS encapsulation.
No checksums.
Will autodetect (sometimes) packets with SMACK or FLEXNET characteristics.
.TP 10em
.B SMACK
.IR "Stuttgart Modified Amateurradio-CRC-KISS" ,
which runs CRC-16 checksum on KISS datastream much in the same
way as HDLC has CCITT-CRC checksum on it.
.TP 10em
.B FLEXNET
.IR "FLEXNET"
which runs a CRC checksum of its own polynomial on KISS datastream
much in the same way as HDLC has CCITT-CRC checksum on it.
.TP 10em
.B BPQCRC
XOR "checksum" on dataframes.
Also known as "XKISS", and "XORSUM".
This detects single bit failure, but weakly any multibit failures.
Extra 0x00 bytes have no effect on checksum, etc.
.PP
On
.BI "<kiss\-subif " "tncid" ">"
sub-options the parameter is
.IR tncid ,
which sets up KISS multiplexer parameter so that subsequent
options applies only on designated KISS sub-port.
.PP
The
.I callsign
option sets port specific callsign when relaying to APRS-IS.
.PP
The
.I "telem\-to\-is true"
option can be used to disable (by explicitly setting it to 'false')
radio interface telemetry transmission to APRS-IS.
By default it is on.
This is separate from <telemetry> sections, which send telemetry
to RF interfaces.
.PP
.nf
\fC<interface>
   serial\-device /dev/ttyUSB1 19200 8n1 KISS
   tx\-ok         false          # receive only (default)
   callsign      OH2XYZ\-R2      # KISS subif 0
   initstring    "...."         # initstring option
   timeout       900            # 900 seconds of no Rx
</interface>

<interface>
   serial\-device /dev/ttyUSB1 19200 8n1 SMACK
   tx\-ok         false          # receive only (default)
   callsign      OH2XYZ\-R2      # KISS subif 0
   initstring    "...."         # initstring option
   timeout       900            # 900 seconds of no Rx
</interface>

<interface>
   serial\-device /dev/ttyUSB2 19200 8n1 KISS
   initstring    "...."
   timeout       900            # 900 seconds of no Rx
   <kiss\-subif 0>
      callsign OH2XYZ\-2
      tx\-ok    true             # This is our transmitter
   </kiss\-subif>
   <kiss\-subif 1>
      callsign OH2XYZ\-R3        # This is receiver
      tx\-ok    false            # receive only (default)
   </kiss\-subif>
</interface>

<interface>
   tcp\-device   172.168.1.1 4001 KISS
   tx\-ok         false          # receive only (default)
   callsign      OH2XYZ\-R4      # KISS subif 0
   initstring    "...."         # initstring option
   timeout       900            # 900 seconds of no Rx
</interface>

<interface>
   ax25\-device OH2XYZ\-6         # Works only on Linux systems
   tx\-ok       true             # This is also transmitter
</interface>

<interface> # \fBRX-IGATE ONLY, NOT USABLE AS DIGIPEATER SOURCE\fR\fC
   serial\-device /dev/ttyUSB1 19200 8n1 TNC2
   callsign      OH2XYZ\-R6      # TNC2 has no sub-ports
   initstring    "...."         # initstring option
   timeout       900            # 900 seconds of no Rx
</interface>
.fi

.SH BEACON DEFINITIONS
The beacons are defined using
.B <beacon>
configuration sections.
.PP
Because classical beacon definitions are highly error\-prone, this program
has a new way to define them:
.IP \(bu 2
The new way to define beacons:
.nf
\fCbeacon symbol "R&" lat "0000.00N" lon "00000.00E"  \\\fR
\fC       comment "aprx \- iGate" \fR
.fi
.IP \(bu 2
Semi-clasical definition of raw APRS packet:
.nf
\fCbeacon raw "!0000.00NR00000.00E&aprx \- iGate"\fR
.fi
.IP \(bu 2
Load beacon text from a file, path data is configurable:
.nf
\fCbeacon file \fR\fI/path/to/file\fR
.fi
.IP \(bu 2
Run a program to produce beacon data in raw format:
.nf
\fCbeacon exec \fR\fI/path/to/file\fR\fC timeout \fR\fI10\fR 
.fi
.PP
The fields and parameters:
.TP 12em
.B interface
An
.I optional
"interface" parameter tells that this beacon shall be sent only to
interface whose callsign is named.
Default is to send to all interfaces that have "tx\-ok true" setting.

.TP 12em
.B type
An
.I optional
one character string parameter, with one of following
contents:  "!", "=", "/", "@", ";" and ")".

.TP 12em
.B srccall
An
.I optional
"srccall" parameter tells callsign which is claimed as this particular
beacon source.
It must be valid AX.25 callsign in text format.
When this "srccall" parameter is not given, value of "mycall" configuration
entry is used.
.TP 12em
.B dstcall
An
.I optional
"dstcall" parameter has built-in software version dependent value,
but it can be used to define another value.
.TP 12em
.B via
An
.I optional
"via" parameter defaults to nothing, but can be used to define additional
"VIA" path tokens, for example: "WIDE1\-1".
.TP 12em
.B item
An
.I optional
"item" parameter is for defining a name for an item type APRS packet.
.TP 12em
.B object
An
.I optional
"object" parameter is for defining a name for an object type APRS packet.
.TP 12em
.B symbol
A
.I mandatory
"symbol" parameter is two character code, which for Rx-only iGate is pair: "R&"
.TP 12em
.B lat
This
.I mandatory
parameter defines
.I latitude
coordinate (that is: north/south.)
It is expected to be of format: "ddmm.mmN" where "dd" defines
.I two digits
of
.I degrees
of latitude, and "mm.mm" defines two digits + decimal dot + two digits of
.I minutes
of latitude.
Then comes literal "N" or "S" indicating hemisphere.
.TP 12em
.B lon
This 
.I mandatory
parameter defines
.I longitude
coordinate (that is: east/west.)
It is expected to be of format: "dddmm.mmE" where "ddd" defines
.I three digits
of
.I degrees
of longitude, and "mm.mm" defines two digits + decimal dot + two digits of
.I minutes
of longitude.
Then comes literal "E" or "W" indicating hemisphere.
.TP 12em
.B comment
This
.I optional
parameter defines commentary text tail on the beacon packet.
If you need characters outside US-ASCII character set, use of UTF-8 encoded
UNICODE character set is recommended.

.TP 12em
.B raw
This
.I alternate
format defines whole APRS packet content in raw text format.
.I Currently this type of packets are not validated for syntax at all!
.TP 12em
.B file
This
.I alternative
way defines path to a file with single text line defining
content of
.I raw
message data.
.TP 12em
.B exec
This
.I alternative
mode runs designated program, and waits for at most a
.I timeout
number of seconds (default 10) for the program to produce the result.
.TP 12em
.B timeout
This is optional parameter for
.I exec
allowing altered timeout (number of seconds) for waiting the program to respond.
Default is 10 seconds.
.PP
The type/symbol/lat/lon/comment-format supports only
a few types of APRS packets.
It splits input into small slices that are possible
to validate in detail.
(See "DEBUGGING SYSTEM" above.)
.PP
.SH RF-TELEMETRY
The
.I aprx
system will always send telemetry for all of its interfaces
to APRSIS, but there is an option to define telemetry to be sent
to radio channel by using following sections for each transmitter
that is wanted to send out the telemetry.
.PP
The parameters of
.B <telemetry>
configuration section are:
.TP 12em
.B transmitter
A mandatory callsign referring to an
.I interface.
.TP 12em
.B via
An optional
.I via-path
parameter.  Only 1 callsign!
.TP 12em
.B source
One or more of
.I interface
callsigns for which the telemetry transmission is made.
.SH DIGIPEATER
The
.I aprx
is possible to configure as a AX.25 digipeater with APRS twists.
This is done with
.B <digipeater>
configuration section and its subsections.
.PP
.I There can be at most one <digipeater> definition per each
.I transmit capable interface in the system.
.I On a system with multiple transmitters, this means there can
.I be multiple digipeaters, each with different behaviour rules.
.PP
Minimalistic setup for a digipeater will be as follows:
.PP
.nf
\fC<digipeater>
    transmitter     $mycall
    <source>
        source      $mycall
    </source>
</digipeater>\fR
.fi
.PP
In minimalistic approach the system does digipeating of packets heard
on the
.I $mycall
interface back to same interface.
Single requirement is that the
.I <interface>
block has
.I "tx\-ok true"
setting on it.
.PP
In more complicated approaches it is possible to define multiple sources
for packets:
.IP \(bu 3
Multiple device ports.
.IP \(bu 3
APRSIS pseudoport, which creates the Tx-iGate functionality.
.PP
.SS <digipeater> options
Main-level <digipeater> options are:
.PP
.IP \(bu 3
.I transmitter
defines which interface the digipeater will output to.
.IP \(bu 3
.IR <trace> " and " <wide>
sub-options are explained below.
.IP \(bu 3
.I <source>
sub-option is explained below.
.PP
.SS <trace> and <wide> sub-options
The
.I <trace>
sub-option has priority over the
.I <wide>
sub-option, otherwise they are configured the same way.
.PP
The
.I <trace>
sub-option defines which AX.25 address contained keywords
are treated with APRS "New-N paradigm" rules in a way
where each processing node always marks its transmitter
callsign on the transmitted AX.25 packet address header.
.PP
The
.I <wide>
sub-option defines which AX.25 address contained keywords
are treated with APRS "New-N paradigm" rules in a way where
processing node does not mark its transmitter callsign
on the transmitted AX.25 packet address header.
.PP
Available parameters are:
.TP 9em
.B keys
A string of comma-separated set of string tokens:
.br
\fC   keys "TRACE,WIDE"\fR
.br
Alternative form for this entry is:
.br
\fC   keys "TRACE"\fR
.br
\fC   keys "WIDE"\fR
.TP 9em
.B maxdone
Defines maximum number of redistribution hops that these keywords
can have completed when reaching here.
If accounting finds more done, the system will just drop the packet
instead of digipeating it onwards.
.TP 9em
.B maxreq
Defines maximum number of redistribution hops that these keywords
can define.
If accounting finds more requested, the system will just drop
the packet instead of digipeating it onwards.
.PP
.SS <source> sub-options
Primary definer option is
.B source
which gives callsign of an
.I <interface>
from which the AX.25 packets are received for this
.I <source>
block.
.PP
Available
.B relay\-type
modes on <source> definitions are:
.TP 14em
.B digipeater
Normal AX.25 digipeater behaviour with APRS New-N paradigm support.
This is default mode.
.TP 14em
.B directonly
Digipeat only directly heard packets.
Useful for systems that are designated as "fill-in".
See also "viscous\-delay".
.TP 14em
.B third\-party
Special mode for Tx-iGate.
.PP
The
.B ratelimit
defines two parameters:
.I average
and
.I limit
number of packets sent in 60 seconds.
Its definitions can be both in
.I <digipeater>
and in
digipeater's
.I <source>
sections, and therefore you can limit each individual source to
a max accepted rate as well as define separate rate limits for
the transmitter.
.PP
The
.B viscous\-delay
defines a number of seconds from 0 (default) maximum of 9 that
the source will put the message on duplicate detector delay processing.
All occurrences of same packet per duplicate detector during that time
will be accounted on duplicate detection, and if at the end of the delay
period there are more than one hit, the packet is discarded.
Use delay of 0 seconds for normal digipeater, 5 seconds for a fill-in,
or a Tx-iGate.
.PP
A javAPRSSrvr filter-adjunct style rules are possible with the
.B filter
options.
When you want multiple filters, use multiple options with associated parameters:
.nf
\fC
    filter t/m            # APRS messaging type packets
    filter a/la/lo/la/lo  # APRS positional packets within this area
\fR
.fi
.LP
Also negative filters are possible (prefixed with minus character),
which upon match cause rejection of the packet.
Filters are evaluated in definition order, and first matching one will
terminate the evaluation.
When no filters are defined, everything is passed thru.
When any filter is defined, only those matching non-negative filters
are passed thru, and no default "pass everything else" behaviour exists.
.LP
Supported "adjunct filters" are following:
.TP 8em
.B A/latN/lonW/latS/lonE
Area filter, defined as area enclosing within latS/latN and lonW/lonE.
Latitude and longitude are entered as degrees and decimals.
.TP 8em
.B B/call1/call2...
Budlist filter.  Supports *-wildcards.
.TP 8em
.B D/digi1/digi2...
.I Not supported at APRX internal filters
.TP 8em
.B E/call1/call2/...
.I Not supported at APRX internal filters
.TP 8em
.B F/call/dist_km
Great-circle distance in kilometers from friend's coordinates.
No wildcarding.
.br
.I (TODO: check that it really works!)
.TP 8em
.B M/dist
The
.I "range around my location"
filter requires that you have defined also the "myloc" configuration entry.
It defines acceptance of positions and messages with senders within
.I dist
kilometers of the "myloc" position.
.TP 8em
.B O/object1/obj2...
Object name filter.  Supports *-wildcards.
.TP 8em
.B P/aa/bb/cc...
Prefix filter.
.TP 8em
.B Q/con/ana
.I The Q-construct filter is not supported.
.TP 8em
.B R/lat/lon/dist
Range filter.
Latitude and longitude are in degrees and decimals.
Distance is in kilometers.
No wildcards.
.TP 8em
.B S/pri/alt/over
Symbol filter
.TP 8em
.B T/..../call/km
.RS
Type filter.
Couple possible usages:
.IP "\fC  -t/c\fR" 22em
Everything except CWOP
.IP "\fC   t/*/OH2RDY/50\fR" 22em
Everything within 50 km of OH2RDY's last known position
.PP
Type code characters are:
.TP 3em
.B *
An "all" wild-card.
.TP 3em
.B C
A CWOP.
.TP 3em
.B I
An ITEM.
.TP 3em
.B M
A MESSAGE.
.TP 3em
.B N
A NWS message.
.TP 3em
.B O
An OBJECT.
.TP 3em
.B Q
A QUERY.
.TP 3em
.B S
A STATUS response.
.TP 3em
.B T
A TELEMETRY packet or parameter message.
.TP 3em
.B U
A USERDEF message.
.TP 3em
.B W
A WX data packet
.RE
.TP 8em
.B U/unproto1/unproto2...
Filters by value in destination address field, supports wildcard.
.PP
The
.B <trace>
and
.B <wide>
sub-options exist also within each <source>.
Where such occur, the <source> specific <trace> sub-option
trumps the definition on <digipeater> level, and same with
<wide> sub-options.
This allows things like overriding flooding control keywords
on source basis, should such be necessary.
.PP
A set of
.B regex\-filter
rules can be used to reject packets that are not of approved kind.
Available syntax is:
.IP "regex\-filter source RE"
source address field
.IP "regex\-filter destination RE"
destination address field
.IP "regex\-filter via RE"
any via path field
.IP "regex\-filter data RE"
payload content
.PP
The regex\-filter exists as ad-hoc method when all else fails.
.PP
.SH NOTES: ERLANG
The
.I Erlang
is telecom measurement of channel occupancy, and in this application sense
it does tell how much traffic there is on the radio channel.
.PP
Most radio transmitters are not aware of all transmitters on channel,
and thus there can happen a collision causing loss of both messages.
The higher the channel activity, the more likely that collision is.
For further details, refer to statistical mathematics books, or perhaps
on Wikipedia.
.PP
In order to measure channel activity, the
.B aprx
program suite has these built-in statistics counter and summary estimators.
.PP
The
.I Erlag
value that the estimators present are likely somewhat
.I underestimating
the true channel occupancy simply because it calculates estimate of channel
bit transmit rate, and thus a per-minute character capacity.
It does not know true frequency of bit-stuffing events of the HDLC framing,
nor each transmitter pre- and port frame PTT times. The transmitters need to
stabilize their transmit oscillators in many cases, which may take up to
around 500 ms!
The counters are not aware of this preamble-, nor postamble-times.
.PP
The HDLC bit stuffing ratio is guessed to be 1:1.025 (1 extra bit every 5 bytes)

.SH NOTES: PROGRAM NAME
Initially this program had name
.IR aprsg-ng ,
which was too close to another (a less low-tech C++ approach) program had.

.SH BUGS/WARTS
The
.IR Erlang -monitor
mechanisms are of rudimentary quality, and can seriously underestimate
the channel occupancy by ignoring pre- and postample transmissions,
which can be as high as 50 centiseconds for preample, and 20 centiseconds
for postample!
When entire packet takes 50 centiseconds, such preample alone doubles channel
occupancy.
A 6pack protocol on serial link (instead of KISS) could inform receiver
better on carrier presence times, however even that underestimates RF power
presence (RSSI) signal.  (6pack is not supported.)
.PP
On serial lines supports really only 8n1 mode, not at all like: 7e1.
On the other hand, there really is no sensible usage for anything but 8n1...

.SH SEE ALSO
Couple web sites:
.br
.IR "http://www.aprs2.net/" ,
.br
.IR "http://www.aprs-is.net/" ,
.br
.IR "http://wiki.ham.fi/Aprx.en" ,
.br
.I "http://ham.zmailer.org/oh2mqk/aprx/aprx-manual.pdf"
.PP
.BR aprx-stat (8)

.SH AUTHOR
This little piece was written by
.I "Matti Aarnio, OH2MQK"
during a dark and rainy fall and winter of 2007-2008 after a number
of discussions grumbling about current breed of available software
for APRS iGate use in Linux (or of any UNIX) platforms.
Fall and winter 2009-2010 saw appearance of digipeater functionality.
.PP
Principal contributors and test users include:
.IR "Pentti Gronlund, OH3BK" ,
.IR "Reijo Hakala, OH1GWK" .
Debian packaging by
.IR "Kimmo Jukarinen, OH3GNU" .
Testing of SMACK variant of KISS by
.IR "Patrick Hertenstein, DL1GHN" .
The beacon exec functionality prototype by
.IR "Kamil Palkowiski SQ8KFH" .