Difference between revisions of "APRX"

From OnnoWiki
Jump to navigation Jump to search
Line 1: Line 1:
 +
'''Aprx''' was originally a receive-only APRS iGate (see [[APRS iGate properties]]) software, now extended to do digipeating, and Tx-iGate. It works on any UNIX-like systems with minimal requirements of system services, or system libraries beyond basic POSIX libc.
 +
 +
There are readily usable binary packages for some Fedora and Debian environments.  Other platforms should be easily compilable for, and it is tested for compilation and use at times also on BSD family of systems.
 +
 +
The software is to be installed on a suitable UNIX-like system, and its configuration file is then to be adjusted.
 +
Then it can:
 +
* Handle arbitrary number of radio modems connected to itself
 +
* Optionally relay APRS packets from radio receivers to APRS-IS (http://www.aprs-is.net) network
 +
* Optionally digipeat AX.25 packets with and without APRS NEWn-N paradigm rules
 +
* Optionally relay APRS packets from APRS-IS network to radio channel (Tx-iGate)
 +
 +
This software is intended for very limited resources environment, like small embedded-like machines barely able to run the operating system with TCP/IP networking.
 +
 +
'''''A receive-only Rx-iGate does not need any sort of licenses in most parts of the world where radio amateur hobby is permitted to begin with.'''''
 +
 +
On version 2, the '''Aprx''' has gotten ability to do [[APRS Digipeater]] function, '''Aprx Tx-iGate''', as well as a variation of that called [[Viscous APRS Digipeater]], which is excellent choice for a Fill-In digipeater like on a mobile station.  Viscousness means that it will listen for other copies of same packet for a small configurable number of seconds, and if it hears same packet only once, it will do normal digipeating for it.
 +
 +
== Distribution ==The software is downloadable at:
 +
 +
http://ham.zmailer.org/oh2mqk/aprx/
 +
 +
Manual is downloadable at:
 +
 +
http://ham.zmailer.org/oh2mqk/aprx/aprx-manual.pdf
 +
 +
== Features ==
 +
Originally this software was written for the need of densifying receiver network feeding things to APRS-IS network, and the software did only things necessary for a receive-only APRS iGate.  New version can also do stand-alone Digipeat of APRS packets as well as digipeat and Rx-/Tx-iGate.
 +
 +
The basic design criteria have also included something called ''minimum technology'', whereby the software does not need any external software or libraries in order to function.  However when additional technology is available, some are being used (like Linux kernel AX.25 network, POSIX Threads, etc.)
 +
This also minimized system resource requirements, which in case of APRS iGates do include networking, but can be done with very small machines, like Linux with 8 MB RAM.
 +
Also the software should be able to function on any minimally compliant POSIX system.
 +
 +
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.
 +
Of those around 100 kB are directly for the Aprx's own usage. Rest is probably glibc's use.
 +
 +
 +
For Rx-iGate use the minimum configuration with tunable parts highlighted:
 +
  mycall  '''OH2XYZ'''
 +
  <aprsis>
 +
    server  rotate.aprs.net  14580
 +
  <aprsis>
 +
  <interface>
 +
    serial-device '''/dev/ttyS0  19200'''  8n1    KISS
 +
  </interface>
 +
 +
For a stand-alone APRS Digipeater the configuration would be:
 +
  mycall  '''OH2XYZ'''
 +
  <interface>
 +
    serial-device '''/dev/ttyS0  19200'''  8n1    KISS
 +
  </interface>
 +
  <digipeater>
 +
    transmitter  $mycall
 +
    <source>
 +
        source    $mycall
 +
    </source>
 +
  </digipeater>
 +
 +
A stand-alone Digipeater can be made into ''Digi + Rx-iGate'' by adding the <nowiki><aprsis></nowiki> block on its configuration.
 +
 +
As this software must operate in extremely memory limited systems, its writers have seen no need to make any memory hungry configuration tools, and instead the installer must be able to edit the text format configuration file by means of some simple editor (like ''nano'') existing in the system, or perhaps downloading the file from external editor.
 +
 +
=== Operating systems ===
 +
Observed to work:
 +
* Linuxes (Fedora, RedHat, SuSE, Debian) (--with-pthreads)
 +
* Embedded Linux (NSLU2, with compilation time configure option:  --with-embedded,  OpenWrt --with-embedded)
 +
* Apple OSX
 +
"Should work":
 +
* uCLinux (--with-pthreads --with-embedded)
 +
* FreeBSD/NetBSD/OpenBSD
 +
* Solaris / OpenSolaris
 +
* HP-UX
 +
* Windows+CygWin
 +
(in other words: any POSIX compliant system should work)
 +
 +
There is no integrated installation package for all the systems in the world, but things should not be too difficult to cook up your own.
 +
 +
=== Radio modem connections ===
 +
It listens on radio modems speaking so called KISS protocol on any system attached serial ports.  The modems can also speak of so called TNC2 monitor format:
 +
* Has support for principally unlimited number of serial ports on single machine
 +
* Works also with USB serial ports
 +
* Works also with serial ports on remote servers, as long as they are connectible with "TCP STREAM" service initiated from server running the ''Aprx'' program (like Cisco router AUX ports.)
 +
Supports also AX.25 protocol in a machine, where such exist (mainly Linuxes) and radio modems attached on it.
 +
 +
== APRS Rx-iGate properties ==
 +
* Connects with single callsignSSID to APRS-IS core network for all radio receiver ports attached on it, optionally can also identify all receiver ports with separate call-signs
 +
* Knows that following tokens in AX.25 address VIA fields are a reason for not relaying message to APRS-IS network:
 +
** RFONLY, NOGATE, TCPIP, TCPXX
 +
* Knows that following AX.25 source addresses are bogus, and packets with them are not to be relayed to APRS-IS network:
 +
** WIDE*, RELAY*, TRACE*, TCPIP, TCPXX, NOCALL, N0CALL
 +
* Does not relay any query messages ("?")
 +
* Opens all "3rd-party" messages to determine if any intermediate or the innermost addresses (and possibly data) are a reason for not relaying to APRS-IS.
 +
* Relays received APRS messages to APRS-IS network in network standard form
 +
 +
Simplest way to configure Rx-iGate is to define following on configuration:
 +
mycall  OH2XYZ
 +
<aprsis>
 +
    server  rotate.aprs.net  14580
 +
<aprsis>
 +
<interface>
 +
    serial-device /dev/ttyS0  19200  8n1    KISS
 +
</interface>
 +
 +
== APRS Tx-iGate properties ==
 +
The Tx-iGate is implemented as a possible data source for a digipeater transmitter.
 +
The APRS Tx-iGate:
 +
* Follows basic APRS Tx-iGate rules as defined at http://www.aprs-is.net/IGateDetails.aspx
 +
* Can use a comprehensive set of filter rules that look into message context to determine if the packet in question should or should not be gated from APRS-IS to RF
 +
 +
Adding APRS Tx-iGate on Aprx configuration is a matter of adding suitable <nowiki><source></nowiki> block on digipeater configuration:
 +
 +
  <aprsis>
 +
    server  rotate.aprs.net  14580
 +
    '''#filter      b/a0good'''  # Tx-iGate everything always from this call
 +
  </aprsis>
 +
  <digipeater>
 +
    transmitter  $mycall      # radio port
 +
    <source>
 +
        source    $mycall      # radio port
 +
    </source>
 +
    '''<source>'''
 +
        '''source        APRSIS'''
 +
        '''relay-mode    3rd-party'''
 +
        '''viscous-delay 5'''
 +
        '''#filter      b/a0good'''  # Tx-iGate everything always from this call
 +
        '''#filter      -b/aa0bad'''  # Tx-iGate never anything from this call
 +
    '''</source>'''
 +
  </digipeater>
 +
 +
== Digipeater properties ==
 +
The digipeater functionality handles standard AX.25 1.x/2.0 digipeating with additional specialities for APRS. This permits the digipeater to pass along other traffic in addition to APRS, like TCPIP, AX.25 CONS, etc.
 +
 +
=== For APRS messages ===
 +
* Does standard duplicate detection on APRS messages (with timing window of 30 seconds)
 +
* Does standard "New-N-paradigm" processing of "WIDEn-N" and "TRACEn-N" tokens.
 +
* Accounts the number of all digipeat requests over all fields, when doing analysis of "are there too many hops requested or done?"
 +
* Does not accept requests like:  "WIDE3-6", where SSID field stored value is larger than the one immediately following the keyword.
 +
 +
By default the system treats WIDE as TRACE, and inserts digipeater's transmitter identity on each packet it sends out.  It can be configured to "classical WIDE", as well as adding other keywords that are treated as WIDE or TRACE.
 +
 +
== Complex properties ==
 +
This software has some unique complex capabilities:
 +
 +
=== Serial ports ===
 +
* The serial ports can be physical D9/D25 ports on machine, or perhaps USB ports, as long as they offer standard POSIX serial port semantics along with a "device" to be opened:  /dev/ttyUSB02
 +
* The serial ports can be elsewhere on the internet, as long as they are reachable with TCP STREAM without any sort of encapsulation protocols (like without TELNET escapes)
 +
* There can in principle be unlimited number of serial ports, each need around 30 kB of memory.
 +
* The serial ports can speak a few variations of the KISS protocol, including SMACK (recommended to be used, where available)
 +
* The serial ports can also receive TNC2 monitor format, but that is only for Rx-iGate use, not for digipeater, nor for transmit.
 +
On Linux systems the system does also understand machine internal AX.25 network, and radios attached on it.
 +
 +
=== Optionally multiple callsignSSIDs ===
 +
System defaults all call-signs to be what "MYCALL" configuration entry sets, however to refer on multiple interfaces in like <nowiki><digipeater></nowiki> definitions, they each will need unique call-signs.  Those call-signs need not to be strictly AX.25 conformant if they have no transmitters, in particular the SSID part can be any one or two character upper-case alphanumeric string.  (The call-signs are converted to upper-case if they are entered lower-case or mixed-case.)
 +
 +
=== Measuring radio channel occupancy ===
 +
There are lots of rumours about APRS radio channel occupancy, but very little measured hard facts.
 +
To help on this issue, the ''Aprx''-program has a ''radio channel occupancy measurement estimator'' calculating the number of received bytes from radio and making some fuzzy guesses on how much more time transmitters did spend on channel before and after each packet.
 +
 +
The ''Aprx''-program will also send telemetry packets about each receiver which can then be graphed at APRS-IS, like happens with  http://aprs.fi/telemetry/OH2RDK-5?range=week
 +
 +
With digipeater enabled, this telemetry shows also number of transmitted packets.
 +
 +
=== Radio port telemetry ===
 +
By default the system is telemetering all radio ports to APRS-IS, through which each port behaviour can be viewed via telemetry browsing service as http://aprs.fi/
 +
 +
Optionally for installations used as pure digipeater without internet connection to APRS-IS, the telemetry data can also be sent over radio port:
 +
  <telemetry>
 +
        transmitter  $mycall
 +
        via          TRACE1-1
 +
        source      $mycall
 +
  </telemetry>
 +
See details in ''aprx-manual.pdf''
 +
 +
=== Multiple Digipeaters ===
 +
When an Aprx server node has multiple transmitters associated on it, each that is wanted to digipeat out something will need a digipeater definition, and they act individually!
 +
 +
One can use this to build:
 +
* Cross-band / cross-channel digipeater
 +
* Digipeater with diversity receivers
 +
* Digipeater with distributed receiver network (interconnected preferably using other means than by the radio)
 +
 +
=== Viscous Digipeater ===
 +
Special function mode is called "viscous digipeater", which puts received APRS packets on a short term delay storage (configurable from 1 to 9 seconds, 5 is usually a good value to use), and it counts all instances of that same packet heard from from radio.  If the count at the end of this viscous delay is just 1, then that packet is digipeated.
 +
 +
See [[Viscous APRS Digipeater]] for an illustrative transmission monitoring graphs of normal digipeater vs. viscous digipeater.
 +
 +
== Installation ==
 +
Usually the freshest pre-compiled binary packages have been made for a Debian Etch (4.0) series i386 systems, and they work on most of newer Debian derivative systems, like Ubuntus.
 +
 +
  # dpkg -i aprx_1.99.382-1_i386.deb
 +
 +
The default installation package will place <code>/etc/aprx.conf</code> and all other necessary startup files and scripts into the system, however the defaults are such that the system ''will not'' start with them automatically.
 +
You will need to do:
 +
* Use the <code>aprx-manual.pdf</code> to guide you to edit the <code>/etc/aprx.conf</code> file
 +
* Edit also file <code>/etc/default/aprx</code>
 +
 +
Then the program will start and stop with commands:
 +
  # /etc/init.d/aprx start
 +
  # /etc/init.d/aprx stop
 +
 +
At Debian, doing the installation does often mean that system asks you essentially: "May I overwrite configuration files?"
 +
There you will always reply "N", unless you want to do all configuration work all over again.
 +
 +
== Configuring ==
 +
See examples at <code>aprx-manual.pdf</code> file.
 +
 +
When you have edited the configuration to be more suitable to your environment, try it with the program like this:
 +
  # aprx -d -f /etc/aprx.conf
 +
(this program terminates with Control-C)
 +
 +
If it doesn't spew any "ERROR:" texts, then at least it passes the configuration reading machinery.
 +
 +
Shut down possible earlier running copy of the program:
 +
  # /etc/init.d/aprx stop
 +
Start it fresh:
 +
  # /etc/init.d/aprx start
 +
 +
 
==Referensi==
 
==Referensi==
  

Revision as of 08:32, 2 November 2013

Aprx was originally a receive-only APRS iGate (see APRS iGate properties) software, now extended to do digipeating, and Tx-iGate. It works on any UNIX-like systems with minimal requirements of system services, or system libraries beyond basic POSIX libc.

There are readily usable binary packages for some Fedora and Debian environments. Other platforms should be easily compilable for, and it is tested for compilation and use at times also on BSD family of systems.

The software is to be installed on a suitable UNIX-like system, and its configuration file is then to be adjusted. Then it can:

  • Handle arbitrary number of radio modems connected to itself
  • Optionally relay APRS packets from radio receivers to APRS-IS (http://www.aprs-is.net) network
  • Optionally digipeat AX.25 packets with and without APRS NEWn-N paradigm rules
  • Optionally relay APRS packets from APRS-IS network to radio channel (Tx-iGate)

This software is intended for very limited resources environment, like small embedded-like machines barely able to run the operating system with TCP/IP networking.

A receive-only Rx-iGate does not need any sort of licenses in most parts of the world where radio amateur hobby is permitted to begin with.

On version 2, the Aprx has gotten ability to do APRS Digipeater function, Aprx Tx-iGate, as well as a variation of that called Viscous APRS Digipeater, which is excellent choice for a Fill-In digipeater like on a mobile station. Viscousness means that it will listen for other copies of same packet for a small configurable number of seconds, and if it hears same packet only once, it will do normal digipeating for it.

== Distribution ==The software is downloadable at:

http://ham.zmailer.org/oh2mqk/aprx/

Manual is downloadable at:

http://ham.zmailer.org/oh2mqk/aprx/aprx-manual.pdf

Features

Originally this software was written for the need of densifying receiver network feeding things to APRS-IS network, and the software did only things necessary for a receive-only APRS iGate. New version can also do stand-alone Digipeat of APRS packets as well as digipeat and Rx-/Tx-iGate.

The basic design criteria have also included something called minimum technology, whereby the software does not need any external software or libraries in order to function. However when additional technology is available, some are being used (like Linux kernel AX.25 network, POSIX Threads, etc.) This also minimized system resource requirements, which in case of APRS iGates do include networking, but can be done with very small machines, like Linux with 8 MB RAM. Also the software should be able to function on any minimally compliant POSIX system.

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. Of those around 100 kB are directly for the Aprx's own usage. Rest is probably glibc's use.


For Rx-iGate use the minimum configuration with tunable parts highlighted:

 mycall  OH2XYZ
 <aprsis>
    server   rotate.aprs.net  14580
 <aprsis>
 <interface>
    serial-device /dev/ttyS0  19200  8n1    KISS
 </interface>

For a stand-alone APRS Digipeater the configuration would be:

 mycall  OH2XYZ
 <interface>
    serial-device /dev/ttyS0  19200  8n1    KISS
 </interface>
 <digipeater>
    transmitter  $mycall
    <source>
       source     $mycall
    </source>
 </digipeater>

A stand-alone Digipeater can be made into Digi + Rx-iGate by adding the <aprsis> block on its configuration.

As this software must operate in extremely memory limited systems, its writers have seen no need to make any memory hungry configuration tools, and instead the installer must be able to edit the text format configuration file by means of some simple editor (like nano) existing in the system, or perhaps downloading the file from external editor.

Operating systems

Observed to work:

  • Linuxes (Fedora, RedHat, SuSE, Debian) (--with-pthreads)
  • Embedded Linux (NSLU2, with compilation time configure option: --with-embedded, OpenWrt --with-embedded)
  • Apple OSX

"Should work":

  • uCLinux (--with-pthreads --with-embedded)
  • FreeBSD/NetBSD/OpenBSD
  • Solaris / OpenSolaris
  • HP-UX
  • Windows+CygWin

(in other words: any POSIX compliant system should work)

There is no integrated installation package for all the systems in the world, but things should not be too difficult to cook up your own.

Radio modem connections

It listens on radio modems speaking so called KISS protocol on any system attached serial ports. The modems can also speak of so called TNC2 monitor format:

  • Has support for principally unlimited number of serial ports on single machine
  • Works also with USB serial ports
  • Works also with serial ports on remote servers, as long as they are connectible with "TCP STREAM" service initiated from server running the Aprx program (like Cisco router AUX ports.)

Supports also AX.25 protocol in a machine, where such exist (mainly Linuxes) and radio modems attached on it.

APRS Rx-iGate properties

  • Connects with single callsignSSID to APRS-IS core network for all radio receiver ports attached on it, optionally can also identify all receiver ports with separate call-signs
  • Knows that following tokens in AX.25 address VIA fields are a reason for not relaying message to APRS-IS network:
    • RFONLY, NOGATE, TCPIP, TCPXX
  • Knows that following AX.25 source addresses are bogus, and packets with them are not to be relayed to APRS-IS network:
    • WIDE*, RELAY*, TRACE*, TCPIP, TCPXX, NOCALL, N0CALL
  • Does not relay any query messages ("?")
  • Opens all "3rd-party" messages to determine if any intermediate or the innermost addresses (and possibly data) are a reason for not relaying to APRS-IS.
  • Relays received APRS messages to APRS-IS network in network standard form

Simplest way to configure Rx-iGate is to define following on configuration:

mycall  OH2XYZ
<aprsis>
   server   rotate.aprs.net  14580
<aprsis>
<interface>
   serial-device /dev/ttyS0  19200  8n1    KISS
</interface>

APRS Tx-iGate properties

The Tx-iGate is implemented as a possible data source for a digipeater transmitter. The APRS Tx-iGate:

  • Follows basic APRS Tx-iGate rules as defined at http://www.aprs-is.net/IGateDetails.aspx
  • Can use a comprehensive set of filter rules that look into message context to determine if the packet in question should or should not be gated from APRS-IS to RF

Adding APRS Tx-iGate on Aprx configuration is a matter of adding suitable <source> block on digipeater configuration:

 <aprsis>
    server  rotate.aprs.net   14580
    #filter       b/a0good   # Tx-iGate everything always from this call
 </aprsis>
 <digipeater>
    transmitter  $mycall       # radio port
    <source>
       source    $mycall       # radio port
    </source>
    <source>
       source        APRSIS
       relay-mode    3rd-party
       viscous-delay 5
       #filter       b/a0good   # Tx-iGate everything always from this call
       #filter       -b/aa0bad  # Tx-iGate never anything from this call
    </source>
 </digipeater>

Digipeater properties

The digipeater functionality handles standard AX.25 1.x/2.0 digipeating with additional specialities for APRS. This permits the digipeater to pass along other traffic in addition to APRS, like TCPIP, AX.25 CONS, etc.

For APRS messages

  • Does standard duplicate detection on APRS messages (with timing window of 30 seconds)
  • Does standard "New-N-paradigm" processing of "WIDEn-N" and "TRACEn-N" tokens.
  • Accounts the number of all digipeat requests over all fields, when doing analysis of "are there too many hops requested or done?"
  • Does not accept requests like: "WIDE3-6", where SSID field stored value is larger than the one immediately following the keyword.

By default the system treats WIDE as TRACE, and inserts digipeater's transmitter identity on each packet it sends out. It can be configured to "classical WIDE", as well as adding other keywords that are treated as WIDE or TRACE.

Complex properties

This software has some unique complex capabilities:

Serial ports

  • The serial ports can be physical D9/D25 ports on machine, or perhaps USB ports, as long as they offer standard POSIX serial port semantics along with a "device" to be opened: /dev/ttyUSB02
  • The serial ports can be elsewhere on the internet, as long as they are reachable with TCP STREAM without any sort of encapsulation protocols (like without TELNET escapes)
  • There can in principle be unlimited number of serial ports, each need around 30 kB of memory.
  • The serial ports can speak a few variations of the KISS protocol, including SMACK (recommended to be used, where available)
  • The serial ports can also receive TNC2 monitor format, but that is only for Rx-iGate use, not for digipeater, nor for transmit.

On Linux systems the system does also understand machine internal AX.25 network, and radios attached on it.

Optionally multiple callsignSSIDs

System defaults all call-signs to be what "MYCALL" configuration entry sets, however to refer on multiple interfaces in like <digipeater> definitions, they each will need unique call-signs. Those call-signs need not to be strictly AX.25 conformant if they have no transmitters, in particular the SSID part can be any one or two character upper-case alphanumeric string. (The call-signs are converted to upper-case if they are entered lower-case or mixed-case.)

Measuring radio channel occupancy

There are lots of rumours about APRS radio channel occupancy, but very little measured hard facts. To help on this issue, the Aprx-program has a radio channel occupancy measurement estimator calculating the number of received bytes from radio and making some fuzzy guesses on how much more time transmitters did spend on channel before and after each packet.

The Aprx-program will also send telemetry packets about each receiver which can then be graphed at APRS-IS, like happens with http://aprs.fi/telemetry/OH2RDK-5?range=week

With digipeater enabled, this telemetry shows also number of transmitted packets.

Radio port telemetry

By default the system is telemetering all radio ports to APRS-IS, through which each port behaviour can be viewed via telemetry browsing service as http://aprs.fi/

Optionally for installations used as pure digipeater without internet connection to APRS-IS, the telemetry data can also be sent over radio port:

 <telemetry>
       transmitter  $mycall
       via          TRACE1-1
       source       $mycall
 </telemetry>

See details in aprx-manual.pdf

Multiple Digipeaters

When an Aprx server node has multiple transmitters associated on it, each that is wanted to digipeat out something will need a digipeater definition, and they act individually!

One can use this to build:

  • Cross-band / cross-channel digipeater
  • Digipeater with diversity receivers
  • Digipeater with distributed receiver network (interconnected preferably using other means than by the radio)

Viscous Digipeater

Special function mode is called "viscous digipeater", which puts received APRS packets on a short term delay storage (configurable from 1 to 9 seconds, 5 is usually a good value to use), and it counts all instances of that same packet heard from from radio. If the count at the end of this viscous delay is just 1, then that packet is digipeated.

See Viscous APRS Digipeater for an illustrative transmission monitoring graphs of normal digipeater vs. viscous digipeater.

Installation

Usually the freshest pre-compiled binary packages have been made for a Debian Etch (4.0) series i386 systems, and they work on most of newer Debian derivative systems, like Ubuntus.

 # dpkg -i aprx_1.99.382-1_i386.deb

The default installation package will place /etc/aprx.conf and all other necessary startup files and scripts into the system, however the defaults are such that the system will not start with them automatically. You will need to do:

  • Use the aprx-manual.pdf to guide you to edit the /etc/aprx.conf file
  • Edit also file /etc/default/aprx

Then the program will start and stop with commands:

 # /etc/init.d/aprx start
 # /etc/init.d/aprx stop

At Debian, doing the installation does often mean that system asks you essentially: "May I overwrite configuration files?" There you will always reply "N", unless you want to do all configuration work all over again.

Configuring

See examples at aprx-manual.pdf file.

When you have edited the configuration to be more suitable to your environment, try it with the program like this:

 # aprx -d -f /etc/aprx.conf

(this program terminates with Control-C)

If it doesn't spew any "ERROR:" texts, then at least it passes the configuration reading machinery.

Shut down possible earlier running copy of the program:

 # /etc/init.d/aprx stop

Start it fresh:

 # /etc/init.d/aprx start


Referensi


RaspberryPi