XRPi Home

Documentation Index
Alphabetic Index

XRPi Documentation - Interfacing

Interfaces

An XRPi INTERFACE is a physical (e.g. a COM port) or virtual point of connection between XRPi and somewhere else. The "somewhere else" is usually the world outside the PC, but it may also be an internal connection to other applications on the same PC.

This is not to be confused with Linux interfaces, which exist at a lower level, within the Linux kernal.

Apart from the keyboard input, the screen output, and the internal connection with Linux's TCP/IP services, everything that enters or leaves XRPi must ultimately pass through an INTERFACE.

Some types of interface support only a single "channel" of data, whilst others can support multiple channels, either due to their physical construction or the protocol used.

Interfaces usually have one or more PORTS attached to them. However some interfaces, such as those used by XRPi to emulate other types of hardware or software, do not support ports. An example of this latter type would be the TNC2 interface.

Defining Interfaces in XRPi

XRPi interfaces are configured using INTERFACE definition blocks within XROUTER.CFG.

The interface definition block must reside in the GLOBAL section of XROUTER.CFG, i.e. you cannot define an interface within any other block.

The block starts with the directive "INTERFACE=n", where n is a unique number used to identify the interface. The actual number is unimportant, as long as it is greater than zero and no other interface uses the same number. The block ends with ENDINTERFACE.

The block must contain at least the TYPE and MTU directives, otherwise XRPi will refuse to start. Additional directives may be required, depending on the TYPE. The full range of interface keywords is summarised below (*=mandatory):

Interface Keywords - Overview

        APPLNUM         Application number (DEDHOST only)
        CHANNEL         Channel on multi-channel hardware
        CHANNELS        No. of TNC channels (DEDHOST only)
        COM             Usually the hardware device name
        CONFIG          Hardware-specfic config options
        ENDINTERFACE  * Ends interface definition block
        ETHADDR         Ethernet address (NdisXpkt only)
        FLOW            Flow control options (async only)
        ID              Interface identification string
        INTNUM          Was interrupt number, now multi-purpose
        IOADDR          Was I/O address, now multi-purpose
        KISSOPTIONS     Options for KISS interfaces only
        MTU           * Maximum Transmission Unit
        PROTOCOL        Protocol used on this interface
        SPEED           Serial (async) or RF (SCC) baud rate
        TYPE          * Type of hardware

Interface Keywords - Detail

APPLNUM
Application number (WA8DED hostmode interfaces only). Specifies which application will be using this interface. Must match the number in the corresponding APPL block.
CHANNEL
Channel on multi-channel hardware (e.g. SCC cards). XRPi does not currently support SCC cards, so this keyword should not be used.
CHANNELS
For WA8DED hostmode interfaces only. Specifies the max no. of host channels (between 1 and 32) the interface will provide.
COM
Communication device name, e.g. "/dev/tty0". COM=0 is a "dummy" COM port which does nothing. It can be used to "park" ports when not in use.
CONFIG

Hardware-specific config options. The format depends on the interface type.

ENDINTERFACE *
Marks the end of the INTERFACE definition block. Subsequent keywords will be treated as GLOBAL. This keyword is mandatory.
ETHADDR
(Not currently used in XRPi and might be removed) Ethernet address in form xx:xx:xx:xx:xx:xx. Was used in XR32 only for EXTERNAL drivers using ETHER protocol, such as the NdisXpkt driver.
FLOW
Flow control options (ASYNC interfaces only): 
	0 = No flow control
	1 = Hardware (RTS/CTS) flow control
	2 = Software (XON/XOFF) flow control (TTY link only)
	3 = Hardware AND software flow control

If not specified, flow control defaults to NONE. Don't use Xon/Xoff with KISS.

ID
Interface Identification. This is a plain text string which identifies the interface on various displays. Keep it concise, e.g "Ethernet".
INTNUM
Server TCP Port (AGW and AXTCP interfaces). For the AXTCP server, this specifies the TCP port the server should listen on. For the AGW interface it specifies the TCP port used to connect with the AGW Packet Engine.

(This is a recycled keyword, which was used in XR16 top specify a hardware interrupt number).

IOADDR
For AGW interfaces, this specifies the IP address of the AGW packet Engine. If not specified, it defaults to 127.0.0.1 (localhost). Not currently used anywhere else.

(This is another recycled keyword, which was used in XR16 to specify an hardware IO address.)

KISSOPTIONS
Options for KISS interfaces only: 
	NONE     - Plain KISS (most TNC's use this) (default)

	POLLED   - For TNCs which send only when polled.

	CHECKSUM - Packets are protected by checksum.  You can
                   only use this option if your TNC supports it.

	ACKMODE  - For TNC's which inform XRPi when a
                   frame has been transmitted on air.

	SLAVE    - XRPi will act like a polled KISS TNC,
                   sending only when commanded to do so.

POLLED and SLAVE are mutually exclusive. BPQKISS eproms require POLLED and CHECKSUM, but their use of ACKMODE is optional.

MTU *
Maximum Transmission Unit. This specifies the maximum size for the data portion of an IP packet transmitted on the interface.

Datagrams are sized or fragmented according to the MTU of the interface on which they are transmitted.

XRPi allows MTU's up to 1500 bytes, but setting MTU over 256 is not recommended on AX25 ports, because the buffer size on TNC-based nodes is usually only big enough for a 256-byte data field.

This is a mandatory keyword, although for some interface types the value has no meaning and is ignored. If in doubt, use 256.

PROTOCOL
Protocol to use on the interface: 
	ASCII    - Remote consoles (TTY) via ASYNC ports
	ETHER    - Ethernet
	HDLC     - For use with YAM modem, and some EXTERNAL
	           drivers.
	KISS     - For driving KISS TNCs or wired links.
	MODEM    - Hayes compatible PSTN modem.
	NETROM   - Netrom backend serial link.
	NONE     - Use this with type=loopback
	PPP      - Point to Point Protocol (TCP/IP over RS232)
	SLIP     - Serial Line Interface Protocol  (TCP/IP over RS232)
	TNC2     - TNC2 emulation.
SPEED
The serial port baud rate for ASYNC interfaces only. Don't include a comma.
TYPE *
Interface type as follows: 
	AGW            AGW Packet Engine
	ASYNC          Serial (e.g. RS232)
	AXIP           AX25 over IP
	AXTCP          AX25 over TCP
	AXUDP          AX25 over UDP
	EXTERNAL       External driver
	LOOPBACK       Internal loopback
	TCP            TCP pseudo-interface
	YAM            YAM 1200/2400/9600 modem

This keyword is mandatory.

Example Interfaces

  1. BPQKISS TNC on COM1: 
          INTERFACE=1
              TYPE=ASYNC
              COM=/dev/ttyUSB1
              SPEED=9600
              PROTOCOL=KISS
              KISSOPTIONS=POLLED,CHECKSUM,ACKMODE
              MTU=256
      ENDINTERFACE
  2. Ethernet: 
          INTERFACE=2
	     TYPE=EXTERNAL
	     ID=/dev/eth0
	     PROTOCOL=ETHER
	     MTU=1064
      ENDINTERFACE
  3. AXUDP Interface: 
          INTERFACE=9
              TYPE=AXUDP
              MTU=256
      ENDINTERFACE

See also

XROUTER.CFG - Main Configuration File
PORTS