XRPi Home

Documentation Index
Alphabetic Index

XRPi Documentation - Introduction

Introduction

Prev: Documentation Index Next: Installing XRPi
  1. What is XRPi?
  2. Program Features
  3. XRPi Compared with XR16 and XR32
  4. It's Not NOS!
  5. Terminology
  6. Source Code
  7. Feedback
  8. Support
  9. Legal Stuff
  10. System Requirements
  11. Interfacing Choices
  12. Conventions Used in This Documentation

1) What is XRPi?

XRPi is a software AX25/NetRom/TCPIP router, intended for use in packet switched data-over-radio networks by radio hobbyists.

It is essentially the most recent version of XR32, ported from Windows to Linux. Although intended for use on the Raspberry Pi, it has also been compiled for some desktop Linux platforms as "XRLin".

XRPi runs in a Linux terminal. There is no GUI (yet)- everything is done via a Command Line Interface (CLI), allowing full local and remote control.

The program is free of charge for non-commercial use by radio and networking hobbyists.

2) Program Features:

XRPi packs a lot of functionality into a small program, so this is just a sample...

  • Single executable file - no need for complex "installation".
  • Compact program, using very few resources.
  • Minimal learning curve for XRouter and XR32 sysops.
  • Modern AX25 implementation, with Modulo-128, resequencing & selective reject.
  • AX25 digipeating, selective digipeating, frame piping
  • APRS generic digipeating, IGATE and APRS server.
  • IP over AX25/NetRom, with ARP, RIP2, RIP98, IP router, DNS etc.
  • Integral FTP server for remote maintenance.
  • Integral HTTP server, with proxy, tunnel, rewrite, SSI.
  • Password protected TELNET server.
  • Telnet, PING, FINGER and TraceRoute clients.
  • NetRom protocol with PING, record route, RSET
  • AXIP / AXUDP / AXTCP for AX25 linking via Internet.
  • IPIP, IPENCAP and IPUDP for IP tunnelling.
  • SLIP / KISS (normal and polled) / PPP / DHCP / TTY
  • Reed-Solomon Forward Error Correction.
  • L3RTT and INP3 for time-based NetRom routing metrics.
  • Comprehensive tracing / capture at all protocol layers.
  • Multiple concurrent console sessions.
  • Chat Server, compatible with XRChat, Ping Pong and RoundTable systems.
  • Integral Personal Mail Server (PMS).
  • Cross-protocol bridging.
  • NAT (Network Address Translation)
  • PZTDOS with line editor for remote file maintenance.
  • Application support via TNC2, WA8DED, AGWTCP and KISS TNC emulation.
  • Comprehensive INFO, HELP and MAN (sysop manual) pages, from command line.

(The above may look daunting, but you can configure an XRPi system to be as simple or as complex as you like, from a simple 1 port digipeater to a multi-protocol monster with hundreds of ports).

3) XRPi Compared with XR16 and XR32

If you are are already familiar with XRouter (XR16) or XR32, you might be wondering what sort of beast is XRPi? Is it radically different?

The answer is no. XRPi is just XR32 rebuilt to run natively on Linux instead of Windows. It was already possible to run XR32 on Linux, using Wine. But XRPi doesn't need Wine.

Everything has been kept as familiar as possible, so if you knew how to run XR16 you should have no trouble running XRPi.

Here are some of the main differences:

a) It's More Up to Date
MS-DOS had too little memory to allow further development of XR16. The move to Windows allowed development to continue, but the arrival of the Raspberry Pi more or less halted development of XR32, and switched it to XRPi.

b) It Has More Windows
The "consoles" of XR16 were joined in XR32 by several other windows, for sysop chat and activity monitoring. XRPi keeps those windows, and adds an intrusion detection window.

c) XRPi is Partly Case-Sensitive
XRPi commands are not case-sensitive, but anything related to the file system requires care. For instance XRPi looks for "IPROUTE.SYS", and won't see "iproute.sys". And a command such as "MD /TMP" is not the same as "MD /Tmp".

d) Slower Screen Writes
XRouter (XR16) wrote directly to video memory, which was very fast. XR32 used the Win32 API, which was a little slower. Writing to Linux terminals is even slower, so XRPi can not match the performance of its predecessors when it comes to tracing speed. But as the Raspberry Pi is far faster than the machines used for XRouter, screen writes are probably no slower in real terms.

e) Easier Ethernet
Ethernet on XR16 was easy. It was more difficult in XR32 because Windows prevented direct access to the hardware. The need to install a kernal-mode driver to overcome that, and the obstacles Windows put in place, prevented many sysops from realising the full potential of XR32. Linux makes it easier to access the Ethernet adaptors, so XRPi is fully functional without the need for drivers.

f) It Runs On Raspberry Pi!
XR16 tied up a whole PC. XR32 shared a PC, but Windows always needs rebooting, which disrupts the network. Plus in these energy-conscious times people are reluctant to leave a PC running 24/7. The Pi's low consumption means it can be left on, and being Linux, it rarely needs rebooting. That makes it ideal for Packet Radio networking.

g) It Doesn't Support "SCC" cards
Sorry, but there's no ISA socket on a Raspberry Pi! It might be possible to support SCC cards on the desktop version (XRLin), but it is doubtful whether anyone in the world still uses them?
h) To be continued?...

4) It's Not NOS!

It is a common misconception that XRPi is a variant of NOS. It is not NOS, and is not derived from NOS, so please don't expect it to work the same.

Some of XRPi's commands may be similar to NOS and *NIX ones, but the syntax may differ.

5) Terminology

Some of the terminology surrounding XRPi may be confusing for seasoned Linux users. For instance the terms "interface", "tty", "terminal" and "console" have different meanings in Linux than in XRPi. The concept of "ports" may be unfamiliar to those more used to dealing with Linux "interfaces".

One has to bear in mind that XRPi began life in the 1990s as "XRouter", running in MS-DOS on 4.77MHz "XT" machines with 5.25 inch floppy disks. Parts of it were imported from even earlier works such as PZTBBS and PEARL with their roots in the 1980s. It used terminology that was in common use at that time, e.g. the concept of PORTs for AX25 systems where more than one frequency was in use.

The distinction between interfaces and ports was developed back in PZTBBS, to accommodate cases where one physical interface could support more than one communication channel, e.g. with KISS. Rightly or wrongly, it worked, so it has stuck.

Linux was nowhere to be seen back then. If it existed at all, it wasn't generally known about. We developed our own nomenclature for XRouter, some of which now conflicts with Linux. It may be annoying to you, but we are not going to change anything now.

Where confusion is possible we will attempt to make it clear whether we are referring to XRPi terms or Linux ones. If in doubt, assume the former, because this documentation was originally written for the DOS version and we may not have found all the bugs yet.

6) Source Code

XRPi is closed source, and this is not negotiable. The pros and cons of open source have been extensively considered in this decision.

Requests for source code will be ignored, but the author will attempt to publish all new protocols and API's implemented by XRPi in due course.

We are not hiding anything by remaining closed source, we are just keeping the project more manageable. But if you are concerned that XRPi might be spyware or something, by all means sandbox it, virus-check it, Wireshark it, use its own trace function, or just don't run it.

7) Feedback

The software author welcomes any feedback, such as bug reports, suggestions, wishlists etc.

You are the beta testers. It is impossible for the author to test all combinations of hardware, software and configuration, so it is important that you report your findings.

If you find errors in the documentation, or you feel something isn't explained properly, please help us to improve it by letting us know.

All feedback should be sent via email to: vk2dot_[at]tpg.com.au or to the XRouter support group (see below).

8) Support

Please do not ask the author to personally help you with configuration issues. Time spent trying to solve your problems and answering emails slows down the development of XRPi.

It is believed that everything is adequately covered by this documentation. However, if you cannot find the answers here, please let us know. You are urged to join the "XRouter" group, and use it for support where possible.

The web interface for the group is https://groups.io/g/xrouter. You may also operate it by email - links are on the aforementioned page.

9) Legal Stuff

The terms "the code" and "the software" refer to XRPi and all components thereof, and all documentation relating to it.

You are not permitted to make any charge for, nor gain any pecuniary advantage directly or indirectly from, the copying, distribution or use of this software, or any component thereof, or any driver or utility written for use with the software, unless by prior written agreement with the author.

You must not patch, decompile, disassemble, reverse engineer or in any way modify the software, or cause a modified version or part thereof, or any portion of the source code to be distributed.

The use of the software is at your own risk. The author accepts no liability for any loss or damage incurred as a result of the installation or use of the software.

10) System Requirements

XRPi requires any model of Raspberry Pi, running Debian Wheezy, Jessie or Stretch. It has not (yet) been tested on other flavours of Linux that might be used on Raspberry PI.

The processor speed is not critical, and less than a megabyte of disk space is required for the program and its ancilliary files.

The program does not require formal "installation" and its root directory can be located anywhere, even on a USB pen drive. You may run multiple instances of XRPi concurrently on the same machine.

You may also need some form of physical interface to connect XRPi with the outside world. So either a USB to RS232 adaptor or a USB "sound fob" may be required. In the case of the Raspberry Pi "Zero", you may need an Ethernet adaptor.

11) Interfacing Choices

The following interconnections are possible:

  • Physical COM Port supports:

    • TNC's in KISS and "NetRom Backend" modes.
    • KISS / SLIP / PPP links with "external" systems located on another PC.
    • External application / user support via TTY, or via TNC2, WA8DED and KISS TNC emulators.
    • YAM Modem.

  • "Virtual" COM Port (pseudo-tty) supports:

    • KISS / SLIP / PPP links with systems located on the same PC.
    • Application / User support via TTY, or via TNC2, WA8DED and KISS TNC emulators.
    • Thomas Sailer's "Soundmodem" (packet driver for sound fobs) via KISS.

  • Ethernet supports:

    • IP-based links, using TCP/IP, AXIP, AXUDP, AXTCP, IPIP, IPUDP and IPENCAP.
    • AX25 over Ethernet (BPQETHER protocol).
    • External applications via AGW emulation and Remote Host Protocol.
    • Remote RF ports, using AGWTCP.

  • Internal loopback (127.0.0.1) supports:

    • IP-based links with systems on the same PC, using TCP/IP, AXIP, AXUDP, AXTCP, IPIP, IPUDP and IPENCAP.
    • Local applications via AGW emulation and Remote Host Protocol.

XRPi can emulate the following:

  • TNC2-type TNC
  • KISS TNC
  • WA8DED TNC
  • AGW Packet Engine (AGWTCP interface only at present)

12) Conventions

Certain conventions are used in this documentation to avoid unnecessary repetition. They are as follows:

      |               ("or") Separates alternative options or arguments.
      <>              Encloses a mandatory argument
      []              Encloses one or more optional arguments.
      callsign        A valid amateur radio callsign
      dir             Directory
      dirname         Directory name
      file            A unique file name without directory
      filename        A unique file name without directory
      filespec        Specifies one or more files, with or without directory        
      he              Represents both "he" and "she"
      path            A fully qualified directory path            
      pathname        A full directory plus filename.
      string          A contiguous sequence of non-whitespace characters.
      text            One or more strings separated by whitespace.
      whitespace      Spaces, tabs or newlines

      Example:  DIR [ filespec ]  - DIR command has one optional argument,
      which may be a file or file group description, with or without
      directory.


      In cases where a pathname is required, if only a filename is given, 
      the program's working directory is assumed.

Prev: Documentation Index Next: Installing XRPi