XRPi Home

Documentation Index
Alphabetic Index

XRPi Documentation - Configuration

Configuring Interfaces & Ports

Prev: Configuring XRPi Next: Configuring IP

You need to configure one or more INTERFACEs and PORTs, to allow XRPi to communicate with other systems.

The following sections are intended as a rough guide only. In most cases, only the mandatory parameters are shown. For more details of each type of interface or protocol, explore the links in each section.

An INTERFACE definition 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.

  • KISS TNC's / Links

    KISS can be used to link XRPi with KISS TNC's, or with other KISS systems via real or virtual COM ports. A typical configuration would be as follows: 

    	INTERFACE=1
		TYPE=ASYNC       <-- Serial RS232
		COM=/dev/ttyUSB1 <-- COM device	
		PROTOCOL=KISS    <-- Use KISS
		SPEED=38400      <-- Baud rate
		FLOW=0           <-- No flow control
		MTU=256          <-- See below
		KISSOPTIONS=NONE <-- Plain KISS
	ENDINTERFACE

    MTU specifies the largest size for the data portion of an AX25 frame, and the largest IP datagram that can be handled. This should be set to 256 for KISS TNC's because they usually have small packet buffers. For KISS links not using TNC's, MTU may be set larger, up to 1500.

    KISSOPTIONS are as follows:

    • NONE - Plain KISS (most TNC's use this) (default)

    • POLLED - For TNCs which send only when polled.

    • CHECKSUM - Packets 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, and their use of ACKMODE is optional.

    Up to 16 PORTs can be attached to one interface, each using a different CHANNEL. The bare minimum configuration for each port is as follows (see the PORTS page for details of other options): 

    	PORT=3
		ID=144.675MHz Users <-- Text for "ports" display
		INTERFACENUM=1      <-- Interface no. to attach to
		CHANNEL=B           <-- Channel on interface (A-P)
	ENDPORT

    CHANNEL defaults to "A" and is therefore only required if the TNC is not using its default channel / port.

    More information about KISS interfacing.


  • Interfacing to AGW Packet Engine

    You can use AGW Packet Engine (AGWPE) "underneath" XRPi to manage the hardware, or to provide access to hardware not directly supported by XRPi (e.g. soundcards).

    AGWPE may be located on the same PC or on a different PC, which could be anywhere in the world. Thus you could for example have a node in your shack whose RF ports are remotely located on a nice hilltop! Or you could remotely locate one of your ports to prevent desense etc.

    Here's how to specify an AGWPE interface: 

    	INTERFACE=2
		TYPE=AGW
		; IP addr of AGWPE. Default is localhost
		IOADDR=192.168.0.76
		; AGWPE port. Default is 8000	
		INTNUM=8001
		MTU=256
		CONFIG=MyAgwPassword	; Password for AGWPE
	ENDINTERFACE

    Note that IOADDR, INTNUM and CONFIG are all optional, and are only needed if you want to change the defaults.

    If you don't specify IOADDR, it defaults to 127.0.0.1, which is the same computer as XRPi is on. If AGWPE is on a different computer to XRPi, you need to enter its IP address here.

    If you don't specify INTNUM, it defaults to 8000, which is the normal AGWPE port.

    If you don't specify CONFIG, XRPi won't "authorise" with AGW. Authorisation is not usually needed if you're using XRPi and AGWPE on the same computer. You can adjust the requirement for authorisation in AGWPE. When CONFIG is used, the "username" sent to AGWPE is the NODECALL and the "password" is the string specified by CONFIG.

    The AGWPE interface can support 16 PORTs, which are declared in the usual way, each PORT using a different CHANNEL on the INTERFACE - for example: 

    	PORT=1
		ID=AGW Port 1
		INTERFACENUM=2
		CHANNEL=A
	ENDPORT

	PORT=2
		ID=AGW Port 2
		INTERFACENUM=2
		CHANNEL=B
	ENDPORT

  • LAN Interfacing

    There are TWO ways for XRPi to interface with the LAN / WiFi. Which one you choose depends on what facilities you need.

    a) The "basic" method accesses the LAN via the Linux kernal. It does not need an INTERFACE or PORT. This mode supports servers, AXIP, AXUDP, AXTCP, IPIP, IPUDP, Telnet, PING, TraceRoute etc. It does NOT support IP routing between "radio" ports and the LAN.

    b) The "regular" method bypasses the Linux kernal. It uses an EXTERNAL interface, to which a PORT is attached. This mode gives XRPi its own LAN address. It supports all the above modes, PLUS it supports IP routing between radio ports and the LAN.

    If you choose the "basic" method, all you need is a "type k" (kernal) default route in IPROUTE.SYS like this: 

    	ip route default  0  *  k

    If you choose the "regular" method, you need an EXTERNAL interface, which is declared like this: 

    	INTERFACE=3
		TYPE=EXTERNAL        ; External device driver
		ID=eth0              ; Device to use
		PROTOCOL=ETHER       ; Protocol
		MTU=1064             ; Largest packet size
	ENDINTERFACE

    Device "eth0" is usally the Ethernet adaptor and wlan0 is usually the WiFi adaptor. However, the WiFi may appear as "eth1".

    The corresponding Ethernet PORT is declared like this: 

               PORT=1                  ; Port number
        	ID=Ethernet            ; Description
        	INTERFACENUM=3         ; Interface to use
        	IPADDRESS=192.168.0.2  ; Ethernet IP address
        	NETMASK=255.255.255.0  ; Network mask
        	etc...

    Make sure you choose a different IP address to the one Linux is using!

    You will also need to set up some IP routing in IPROUTE.SYS, for example: 

    	# Default route via gateway 192.168.0.100 on port 1:
	ip route default  1  192.168.0.100  d
	#
	# Local subnet is routed direct on port 1:
	ip route add 192.168.0.0/24	  *  1  d

    More Information about LAN Interfacing


  • Interfacing With SLIP

    SLIP can be used to link XRPi with other IP systems (e.g. NOS) via real or virtual COM ports. SLIP interfaces support only one port. A typical configuration would be as follows: 

    	INTERFACE=4
		TYPE=ASYNC         <-- Serial RS232
		COM=/dev/ttyUSB3   <-- COM device	
		PROTOCOL=SLIP      <-- Use SLIP
		SPEED=38400        <-- Baud rate
		FLOW=0             <-- No flow control
		MTU=1500           <-- Allows largest IP
	ENDINTERFACE

	PORT=3
		ID=SLIP Link to BBS
		INTERFACENUM=4
	ENDPORT

    Serial lines used for SLIP must run at 8 data bits. Flow control must be hardware or none, as XON/XOFF flow control interferes with the protocol.

    If flow control is used, the cable must contain at least 5 cores, namely TXD, RXD, RTS, CTS and GND. If flow control is not used, only TXD, RXD and GND are required.

    In all cases, a NULL MODEM is required. In the case of "real" RS232 this could be an actual null modem device, or a cable that is wired such that the TXDs at each end go to the RXDs at the other end, and the RTSs at each end go to the CTSs at the other. "Virtual" COM port pairs such as Com0Com include this functionality as standard.

    More information about SLIP interfacing.


  • Interfacing With PPP

    Like SLIP, PPP can be used to link XRPi with other IP systems (e.g. NOS) via real or virtual COM ports. PPP interfaces support only one port. A typical configuration would be as follows: 

    	INTERFACE=5
              TYPE=ASYNC
              COM=/dev/ttyUSB1        ; COM device
              SPEED=19200             ; Adjust as necessary
              PROTOCOL=PPP
              MTU=1600
	ENDINTERFACE

	PORT=1
              ID=PPP link to Win98    ; Text to identify port
              INTERFACENUM=5          ; Bind to PPP interface
              IPADDRESS=192.168.0.4   ; Optional (see below)
	ENDPORT

    The use of IPADDRESS is optional. If the keyword is omitted, XRPi's "global" IP address will be used on that port. If the address is specified as 0.0.0.0, it signifies that a "dynamic" IP address should be obtained from the peer, otherwise the specified address will be used.

    The port is now ready for PPP using the standard PPP defaults, but if it requires any further configuration you may include the relevant PPP configuration commands in the file BOOTCMDS.SYS, which is read by XRPi at boot-up, after it has finished reading XROUTER.CFG.

    More information about PPP.


  • YAM Modem

    The "YAM" (Yet Another Modem) modem conects to a COM port, and implements the functions of a TNC in a FPGA (Field Programmable Gate Array).

    XRPi includes support for the YAM modem, and the interface should be defined as follows: 

               INTERFACE=6       <- Adjust to suit
              TYPE=YAM
              COM=/dev/ttyUSB1           <- COM port to which YAM is connected
              MTU=256
              SPEED=1200      <- Radio speed (not serial comms speed!)
              PROTOCOL=HDLC   <- Only HDLC supported at present
           ENDINTERFACE

    SPEED is the *radio* baud rate and should match the modem's configuration, otherwise TXDELAY and TXTAIL timings will be wrong. You can omit SPEED and define RFBAUDS in the port instead. Communication between between XRPi and YAM via the RS232 cable always takes place at 19200 bauds.

    PROTOCOL *must* be HDLC. No other protocols are supported at present.

    Each YAM interface supports only one PORT. You must use a separate INTERFACE and PORT for each YAM board. A typical PORT might be defined as follows: 

               PORT
              ID=YAM 1200 Bauds 144.650MHz
              INTERFACENUM=6
              CHANNEL=A
              SPEED=1200
              FULLDUP=0
              TXDELAY=150
           ENDPORT

    CHANNEL is ignored, but must be present. FULLDUP can be used, as the YAM is capable of full duplex operation, but SOFTDCD is ignored because it has no meaning for a YAM board.

    YAM will INTERLOCK with other YAM interfaces and with all types of SCC card, but not with KISS TNC's since XRPi has no knowledge of, or control over when a KISS TNC is transmitting.

    The YAM modem uses TXD, RXD, RTS, CTS, DTR, DSR, RI and DCD so a full 8 wire plus ground cable is required.

    XRPi does not program the FPGA therefore YAM modems must be initialised by running YAMINIT (supplied with the modem) before starting XRPi. It is probably best to do this in a startup batch file. "YAMINIT yam12v11.mcs 1" will program the YAM for COM1 with 1200 baud RF speed. The YAM is capable of 1200, 2400 or 9600 baud simply by choosing the appropriate .MCS file.

    For further information you must refer to the YAM manufacturer's documentation.


  • TTY Links

    A TTY ("Teletype") link, is a plain ASCII RS232 connection between a "dumb-terminal" and XRPi. This would typically be used by a sysop to operate a node which is located away from the control position, e.g. in an outdoor radio cabinet. It does the same job as a Telnet login, but doesn't require Ethernet and is "always on".

    A TTY interface is one example of an interface that doesn't have any PORTs attached. It is defined like this: 

    	INTERFACE=7
		TYPE=ASYNC
		COM=/dev/ttyUSB1
		SPEED=19200
		MTU=256
		PROTOCOL=ASCII
		FLOW=1          ; Hardware flow control
	ENDINTERFACE

    Flow control is optional. Be VERY careful if you are tracing traffic over a flow controlled link, because if you pause the display for a long time, the data may back-up in XRPi until it becomes strangled.


  • AXIP Interfacing

    AXIP is AX25 "encapsulated" within IP datagrams. This enables AX25 systems to communicate with each other via TCP/IP networks such as an Ethernet LAN or the Internet.

    A single AXIP interface can support an infinite number of ports, but you may define additional interfaces if you need different MTU's. The interface is configured as follows: 

    	INTERFACE=8
		TYPE=AXIP
		MTU=256
	ENDINTERFACE

    For each AXIP partner, add a PORT similar to this: 

    	PORT=9
		ID=AXIP link with WA3IP
		INTERFACENUM=8     <-- Points to the INTERFACE above
		IPLINK=55.73.88.69 <-- Partner's IP address/hostname
		etc...
	ENDPORT

    You must specify at least ID, INTERFACENUM, and IPLINK.

    IPLINK is the remote host's IP address or hostname. It is more efficient to use IP addresses, if you are able to do so, because it removes the need to resolve the hostnames, but you must use the hostname if the partner's IP address is "dynamic".

    MAC parameters such as TXDELAY, TXTAIL, SLOTTIME, PERSIST, FULLDUP, SOFTDCD etc. are meaningless for AXIP, but FRACK, RESPTIME, PACLEN, MAXFRAME, QUALITY etc. operate as normal. Values of 2000 for FRACK and 200 for RESPTIME are recommended.

    More information about AXIP.


  • AXUDP Interfacing

    AXUDP is AX25 "encapsulated" within UDP datagrams. This enables AX25 systems to communicate with each other via TCP/IP networks such as an Ethernet LAN or the Internet.

    AXUDP has a number of advantages over AXIP:

    • Unlike AXIP it is easily handled by domestic routers.
    • It allows several nodes on the same public IP address.
    • It allows nodes to share the same PC.

    A single AXUDP interface can support an infinite number of ports, but you may define additional interfaces if you need different MTU's. The interface is configured as follows: 

    	INTERFACE=9
		TYPE=AXUDP
		MTU=256
	ENDINTERFACE

    For each AXUDP partner, add a PORT similar to this: 

    	PORT=8
		ID=AXUDP link with VK9UDP
		INTERFACENUM=9     <-- Points to the INTERFACE above
		IPLINK=55.73.88.69 <-- Partner's IP address/hostname
		UDPLOCAL=93
		UDPREMOTE=93
		etc...
	ENDPORT

    You must specify at least ID, INTERFACENUM, and IPLINK.

    IPLINK is the remote host's IP address or hostname. It is more efficient to use IP addresses, if you are able to do so, because it removes the need to resolve the hostnames, but you must use the hostname if the partner's IP address is "dynamic".

    UDPLOCAL and UDPREMOTE are the UDP "service port" numbers for each end of the link, and if omitted they default to 93 (don't confuse these with *protocol number* 93, which is AXIP). The numbers are independent, e.g. you may use 93 for UDPLOCAL and 10093 for UDPREMOTE).

    MAC parameters such as TXDELAY, TXTAIL, SLOTTIME, PERSIST, FULLDUP, SOFTDCD etc. are meaningless for AXIP, but FRACK, RESPTIME, PACLEN, MAXFRAME, QUALITY etc. operate as normal. Values of 2000 for FRACK and 200 for RESPTIME are recommended.

    More information about AXUDP.


  • AXTCP Interfacing

    AXTCP is AX25 "encapsulated" within TCP datagrams. Like AXIP and AXUDP, this enables AX25 systems to communicate with each other via TCP/IP networks (e.g. the Internet).

    It is intended to be used in situations where AXIP and AXUDP are not possible, e.g. where one of the link partners is behind a firewall which blocks incoming AXIP or AXUDP.

    AXTCP is enabled by declaring an INTERFACE with TYPE=AXTCP. A single PORT is then attached to that interface.

    AXTCP interfaces can act as server, client, or both at once, depending on which keywords are included.

    An AXTCP server can support several simultaneous client connections, and a client can connect to several servers simultaneously.

    Note: When configuring a server, you must ensure that incoming TCP/IP connections are directed to the server's TCP port, i.e. there must be suitable NAT entries or "port forwarding" set up in the Internet "front end" router.

    The following configures an AXTCP server, listening for clients on TCP port 9393: 

    	INTERFACE=10           <-- change to suit yourself
		TYPE=AXTCP
		MTU=256
		INTNUM=9393   <-- Server port
	ENDINTERFACE

    The INTNUM parameter activates the server and specifies the TCP port that it listens on. If this is zero, or not specified, the server is disabled.

    This specifies a client which connects with the KIDDER node, whose address is g8pzt.ath.cx, port 9393: 

     
	INTERFACE=10
		TYPE=AXTCP
		MTU=256
		CONFIG=KIDDER g8pzt.ath.cx 9393
	ENDINTERFACE

    The CONFIG directive is used to specify a server to connect, thereby activating client mode. The format is as follows: 

    	CONFIG=<servname:> <hostname | ipaddr> <tcp_port>

    You may specify additional servers, by including a CONFIG for each one. There is no limit to the number of CONFIG directives that can be used with a single interface.

    A PORT attached to an AXTCP interface needs no special configuration, and should simply be configured with parameters (FRACK, RESPTIME, RFBAUDS) approriate to a high speed connection, for example: 

    	PORT=8
		ID=AXTCP Operations
		INTERFACENUM=10
		FRACK=2000
		RESPTIME=200
		RFBAUDS=56000
	ENDPORT

    You must NOT attach more than one PORT to an AXTCP interface.

    By default, all AXTCP connections use the same PORT, but if you prefer to use one port per neighbour you may configure several interfaces, each with a single PORT attached. The only proviso is that if INTNUM is used, no two AXTCP interfaces may use the same INTNUM.

    More information about AXTCP.


  • NetRom Backend

    XRPi can interface via a serial port to a TNC which is running NetRom software, using the so-called "NetRom Backend" protocol. To do this, configure an ASYNC interface, with NETROM protocol, and attach a single port as follows: 

    	INTERFACE=11
		TYPE=ASYNC
		COM=/dev/ttyUSB1
		SPEED=19200
		PROTOCOL=NETROM		; Netrom backend
		MTU=256
	ENDINTERFACE

	PORT=1
		ID=NetRom Backend       ; Text to identify port
		INTERFACENUM=11          ; Bind to backend interface
		etc...
	ENDPORT
  • WA8DED Emulator

    XRPi can emulate a WA8DED TNC, in both normal mode and "host" mode. This can be used for both manual operations and application support, just like a real TNC.

    To enable the WA8DED emulator, specify an interface similar to this: 

     
	INTERFACE=12
		TYPE=ASYNC
		COM=/dev/ttyUSB18
		PROTOCOL=DEDHOST
		APPLNUM=3	; see below
		CHANNELS=4
		SPEED=9600
		FLOW=0
		MTU=256
	ENDINTERFACE

    COM is the number of one of the real or virtual COM ports used to connect with the application. XRPi can use COM numbers up to COM32.

    CHANNELS specifies the max no. of host channels the interface will provide (between 1 and 32). The total number of host channels available to be shared between all applications is 64. If XRPi cannot allocate the requested number of channels it will fail to start.

    MTU must be 256

    APPLNUM specifies which application will be using this interface. Corresponds to "n" in APPL=n (see Applications section below). This directive is not required if the emulator is used in "normal TNC" mode.

    SPEED is the serial baud rate . Don't use too low a speed, otherwise applications may lose sync due to the time it takes for a poll to reach XRPi and the reply to get back. Speeds of 9600 and above should be OK.

    FLOW must always be set to 0 or 4. Setting FLOW to any value other than 0 or 4 may cause the application or XRPi to hang. FLOW=4 is a special case which forces the WA8DED emulator to default to host mode (see later).

    - Don't use CHANNEL, IOADDR, or INTNUM keywords.

    - Don't try to attach any PORTs to this interface, as they are not required.

    More information about WA8DED emulation.


  • TNC2 Emulator

    The TNC2 Emulator is a feature which allows RS232 devices such as weather stations, dumb terminals, GPS and telemetry devices to send and receive packets as if they were connected to a real TNC2.

    The emulator requires only an INTERFACE. It does *not* require a PORT. It is configured by defining an INTERFACE with TYPE=ASYNC and PROTOCOL=TNC2. Choose SPEED to suit the peripherals, and MTU=256. For example: 

    	INTERFACE=13
		TYPE=ASYNC
		COM=/dev/ttyUSB1
		SPEED=19200
		PROTOCOL=TNC2
		MTU=256
	ENDINTERFACE

    You can have as many TNC emulators as you wish, providing you have an RS232 port for each one. You should preferably use a different MYCALL or SSID for each one if there is any chance of more than one TNC being used on the same radio port.

    More information about TNC2 emulation.


Applications

If you have configured any DEDHOST interfaces, you must configure an APPL block for each one, to allow the application(s) to receive incoming connections. For example: 

	APPL=1
		APPLNAME=BBS
		APPLCALL=G8PZT-5
		APPLALIAS=PZTBBS
		APPLQUAL=50
	ENDAPPL

More information about applications.

Consoles

Consoles are XRPi windows which allow the sysop to interact with XRPi, for example to trace traffic, or make connections.

There are 3 consoles by default, so you don't need to bother with configuring them at this stage, unless you wish to change their parameters. You can always do this at a later date.

More information about consoles and their configuration.

Prev: Configuring XRPi Next: Configuring IP