====== HOWTO Use WhatsPac With XRouter ======

This page is about using XRouter as the "Packet Engine" underlying the WhatsPac packet Radio client application. First of all..

===== What is WhatsPac? =====

WhatsPac is a new browser-based application for Packet Radio chat, that can run on desktop PC's, tablets and phones.

Unlike existing packet chat systems, WhatsPac offers much more than plain text. It allows both real-time and non-real-time chat, emojis, themed "channels", a packet terminal, and one-to-one chats. It can even support the sending of small images, and there will be lots more features to come!

WhatsPac began in May 2024 as a collaboration between Kevin M0AHN and Paula G8PZT, the author of XRouter. It was built upon XRouter's RHP (Remote Host Protocol) and REST APIs, so WhatsPac and XRouter are a natural fit for each other. 

===== What Does it Look Like? =====

There are 3 main parts to WhatsPac:

  - One to One Messaging
  - Discussion Channels
  - Terminal / Packet Monitor

==== Channels Display ====

Here's what the WhatsPac "Channels" display looks like on a desktop browser (shrunken to make way for the wiki menu):

{{whatspac01.png?600|WhatsPac Channels Display}}

==== Messages Display ====

And here's what the "Messages" display looks like:

{{whatspac02.png|WhatsPac Messages Display}}

==== Terminal / Packet Monitor ====

Finally, here's the "Terminal" display...

{{whatspac03.png|WhatsPac Terminal Display}}


===== Where Can I Get WhatsPac From? =====

That's easy. Just point your browser to [[http://whatspac.m0ahn.co.uk:88|http://whatspac.m0ahn.co.uk:88]]  The WhatsPac client runs in your browser, and when a new version comes along, just refresh the page.

 
===== How Does It Work? =====

Although WhatsPac runs in a browser, it is all about Packet RADIO. It does NOT use the Internet, apart from downloading the application in the first place.  

All WhatsPac clients connect to the WhatsPac server via the Packet Radio Network, and all data is exchanged via the server.

At present, there is only one server, located at node PEWSEY:MB7NPW in the south-west of the UK. The eventual plan is to link in more servers.

Therefore, to use Whatspac you WILL need some sort of connection to the Packet Radio network. That's where XRouter comes in - it is the middle-man between the browser and Packet radio.  Think of it as a "stack", with the browser at the top, XRouter in the middle, and the radio(s) at the bottom.

XRouter doesn't need to be on the same machine as the browser, so you can use whichever XR variant is the most convenient: XrPi (Raspberry Pi), XrLin (x86 Linux) or XrWin (Windows). The WhatsPac setup page has a link to download XRouter if you need to.  Or you can always get the latest version from the  [[https://groups.io/g/xrouter/files|https://groups.io/g/xrouter/files]] XRouter IO group files area.

{{whatspac04.png|XRouter Download Link on WhatsPac Setup Page}}

You can use XRouter as a simple "packet engine", letting WhatsPac create the configuration file for you. Or if you already have an XRouter setup, you can configure it manually. This page will attempt to cover the various options.

===== Option 1 - "I'm An Existing XRouter Sysop" =====

In this case we assume that you already have an existing XRouter packet node, and you just want to add WhatsPac to it. If you are a not a node sysop, jump to [[whatspac#option_2_-_i_m_not_a_node_sysop| Option 2 - I'm not a node sysop]]


==== Step 1: RHP Port ====

Firstly you will need to add the following line to XROUTER.CFG:

   RHPPORT=0 9000

That tells XRouter to listen for WhatsPac data on TCP port 9000, on the Linux/Windows IP stack. If you choose a different TCP port, remember it for later.

==== Step 2: HTTP Port ====

WhatsPac will also need to access XRouter's HTTP server. If you already have an HTTPPORT line in XROUTER.CFG, that's the number to use for WhatsPac. If you don't have an HTTPPORT line, the HTTP server defaults to port 8086 on the Linux/Windows stack.

==== Step 3: ====

After editing XROUTER.CFG, reboot XRouter.

==== Step 4: Get WhatsPac ====

Point your browser at [[http://whatspac.m0ahn.co.uk:88|http://whatspac.m0ahn.co.uk:88]]. WhatsPac works best on desktop browsers. Firefox should work with no issues. Chrome will need a tweak, as explained on the setup page. 

==== Step 5: Your Callsign and Name ====

Click the "setup" button on the left side of the page, and the following page will appear:

{{whatspac05-v0.42.png|WhatsPac Initial Setup Options}}

Fill in your callsign and name. Note that the callsign MUST NOT be identical to any of XRouter's callsigns, so pick an unused SSID. When you are done, click the "**Update Callsign and Display Name**" button.

==== Step 6: Set Up Endpoint ===

This sets up the communications between WhatsPac and XRouter...

From the "**Your Packet Setup**" selector, choose "**I am a Xrouter node sysop and want to connect directly**".

In the "**hostname or IP**" box, enter the hostname or IP address of the machine upon which XRouter is running.

In "**REST API Port**" enter the TCP port number specified by your HTTPPORT, or 8086 if you don't have an HTTPPORT.

Make sure the "**RHP Port**" matches the number you set up in XROUTER.CFG.

Now click "**Update Endpoint**" to save the config.

You should now see the following, with "Connected to..." on a green background, indicating a successful connection to XRouter.

{{whatspac06a.png|WhatsPac Successful Connect}}


==== Step 7: Packet Engine Configuration ====

Moving a little further down the setup page, the curiously-named "**Packet Engine Configuration**" selector allows you to choose the method for the //**initial**// connection to the Packet network. There are two choices, this is the first:

{{whatspac06b.png|Packet Engine Configuration}}

If you choose the above option, the initial connection into the Packet network will use plain AX25, via one of XRouter's PORTs. The source callsign of the packets will be the one that was set up in step 5 above.

This will work perfectly via a radio, but if you choose a non-radio PORT it will only work if the neighbouring node is another XRouter. If the neighbour is BPQ, it won't work.

The other option is to use Layer 4 (NetRom) for the initial connect:

{{whatspac09.png}}

If you choose this option, the initial connection into the packet network will use NetRom, and will require the initial node to be in XRouter's node table.

In the "**Xrouter Node call**" box, enter your XRouter's NODECALL, including its SSID if appropriate // <color #ed1c24>(If you don't enter the exact NODECALL, WhatsPac will never receive the replies)</color>//.



==== Step 8: Connection Script ====

This is where you set up a "script" which enables the WhatsPac client (your browser) to connect to the WhatsPac server. All clients exchange information via the server.

=== Topology: ===

At present, there is only one server, located at node PEWSEY:MB7NPW in the south-west of the UK. PEWSEY can only be reached via radio. Its direct RF neighbours are CALNE:M1BFP-1, SWINDN:GB7BDH, and BATH:GB7NBH. CALNE and SWINDON are AXUDP linked to KIDDER:G8PZT, which has both UK and international links. BATH is RF linked to WENVOE, which is also linked to KIDDER. KIDDER is AXUDP linked to BEDFRD:GB7BED-5, which also has many national and international links.

=== Format of Connect Script ===

The connect script is a JSON array of "hops". Each hop has 3 fields as follows:

  - "hop" - is a description which is displayed during the connection process.
  - "cmd" - is the command required to execute that step.
  - "val" - is a text string that indicates successful connection

{{whatspac07.png|Example WhatsPac Connection Script}}

NOTE: The first "cmd" MUST consist of a callsign only. For example "G8PZT" not "C G8PZT". All subsequent commands are as they would be typed into a node's command line.


For NetRom connections, the first "hop" in your connect script MUST be a callsign, not an alias.

== BUG ==

<color #005577>WhatsPac currently detects a successful first connection by looking for the text specified by "val". But some nodes don't send any text upon connection. This means that the script will hang waiting for text that will never come.  The solution is either to make the first connection to a node which DOES send a connect text, OR resort to jiggery-pokery.</color>


==== Jiggery-Pokery ====

If the initial connection hangs because the first node doesn't send any text upon connection, there are work-arounds...

a) If you are running Xrouter v504f or later, set the first "cmd" to the special callsign "SWITCH", and set "val" to "Connected to SWITCH". This causes WhatsPac to connect **TO** XRouter, instead of **THROUGH** it.

b) If you are running XRouter v504e or earlier, you can set up a loopback PORT in XROUTER.CFG, like this:

{{whatspac10.png}}

Then you can set your first "cmd" to XRouter's NODECALL or NODEALIAS.


===== Option 2 - "I'm Not a Node Sysop" =====

This section assumes that you want to join the WhatsPac fun, but you aren't an existing node operator, and that you have probably never run XRouter before. It assumes that you have some Packet Radio and computing experience.

IMPORTANT: In order to use WhatsPac in this mode, you will need to be within workable range of a packet radio "node". If you are NOT within range of a node, please join the [[https://groups.io/g/xrouter|XRouter IO group]], and contact G8PZT for a workaround. You may [[mailto:xrouter+subscribe@groups.io|subscribe]] to the group by email instead, if you wish.

==== Step 1: Get WhatsPac ====

Point your browser at [[http://whatspac.m0ahn.co.uk:88|http://whatspac.m0ahn.co.uk:88]]. WhatsPac works best on desktop browsers. Firefox should work with no issues. Chrome will need a tweak, as explained on the setup page. 


==== Step 2: Your Callsign and Name ====

Click the "setup" button on the left side of the page, and the following page will appear:

{{whatspac11.png}}

Fill in your callsign and name. When you are done, click the "**Update Callsign and Display Name**" button.


==== Step 3: Get XRouter ====

On the "**Your Packet Setup**" selector, choose "**I use a TNC or Software Modem attached to a radio**". The following text will appear:

{{whatspac12.png}}

Either follow the link, or download the latest XRouter executable from the [[https://groups.io/g/xrouter/files|https://groups.io/g/xrouter/files]] XRouter IO group files area.  Only the executable is required, as WhatsPac will do the necessary configuration for you.

The filenames are descriptive, e.g. "xrlin32v504c-buster" means //"Xrouter version 504c for 32-bit Linux, compiled on Debian Buster"//. Once you have downloaded the correct version, it is recommended that you rename the file to xrlin, xrpi or xrwin.exe as appropriate.

It is also recommended that you locate the executable to a directory of its own on the target machine, because it will create a few additional files.

For Linux you must make the file "executable", i.e. open a terminal in the xrouter directory and type the following:

  chmod +x xrlin
  
(Substitute "xrlin" with "xrpi" on a Raspberry Pi)
==== Step 4: Start XRouter ====

If you haven't already done so, open a terminal, and navigate to the directory containing the Xrouter executable.  On windows, type "**xrwin**". On X86 Linux, type "**./xrlin**" or on Raspberry Pi, type "**./xrpi**". You should see something like this:

{{whatspac16.png}}

Error 14 is perfectly normal on first boot. The configuration file will be created by WhatsPac.

==== Step 5: Configure the Endpoints ====

{{whatspac13.png}}

This sets up the communications between WhatsPac and XRouter...

In the "**hostname or IP**" box, enter the hostname or IP address of the machine upon which XRouter is running.

In "**REST API Port**" you can usually accept the default (8086), unless XRouter reports that it is listening a different port //(it will only do this if port 8086 was already in use by another program)//.

Leave "**RHP Port**" at the default value (9000).

Now click "**Update Endpoint**" to save the config.

You should now see the following, with "Connected to..." on a green background, indicating a successful connection to XRouter.

{{whatspac06a.png|WhatsPac Successful Connect}}


==== Step 6: Configure Packet Radio Connection ====

You now have two choices. One is to use a hardware TNC such as a Tiny2 (in KISS mode) or Nino-TNC, attached to a serial port, which is selected like this:

{{whatspac14.png}}

If you are using Windows, the com port will be something like "com1". For Linux it will be a device name such as '/dev/ttyUSB0' - remember that Linux is case-sensitive.

The "**port name**" will be displayed in Whatspac.

The other option is to use a "software" TNC such as Direwolf, Tomas Sailer's "Soundmodem, "UZ7HO sound modem", or "QTSoundmodem". These all use KISS protocol over a TCP/IP connection: 

{{whatspac15.png}}

If you choose this option, enter the hostname of IP address of the computer on which the sound modem is running, and the TCP port that the sound modem is listening on.

<color #ee0000>//(Setting up the sound modem software is beyond the scope of this document)//</color>

After clicking the big green "**Configure Xrouter**" button, you should see the following dialog. Click the **Close** button.

{{whatspac17.png|update successful}}

The XRouter terminal window should now be displaying XRouter's main window. You can explore other windows using the left/right "arrow" keys, but don't worry about this for now. You may minimise the terminal, but don't close it, otherwise WhatsPac wont work.

{{whatspac18.png|Xrouter in terminal}}

==== Step 6: Connection Script ====

This is where you set up a "script" which enables the WhatsPac client (your browser) to connect to the WhatsPac server. WhatsPac will not send or receive any messages unless it is connected to the server.

=== Topology: ===

At present, there is only one WhatsPac server, located at node PEWSEY:MB7NPW in the south-west of the UK. PEWSEY can only be reached via radio. If you aren't lucky enough to be with RF range of PEWSEY, you must find a route through the node network.  

PEWSEY's direct neighbours are CALNE:M1BFP-1, SWINDN:GB7BDH, and BATH:GB7NBH. CALNE and SWINDON are AXUDP linked to KIDDER:G8PZT, which has both UK and international links. BATH is RF linked to WENVOE, which is also linked to KIDDER. KIDDER is AXUDP linked to BEDFRD:GB7BED-5, which also has many national and international links. If you can't find KIDDER in the nodes tables, look for BAMPTN (Oxfordshire) DATXR (Ohio). JEDLIN (Jedburgh UK), HAMLET (Devon), BAUNOD or AQYNOD (both New Zealand), or PKTXRP (Canada), all of which are reliable XRouter nodes.

=== Format of Connect Script ===

The connect script is a JSON array of "hops". Each hop has 3 fields as follows:

  - "hop" - is a description which is displayed during the connection process.
  - "cmd" - is the command required to execute that step.
  - "val" - is a text string that indicates successful connection

In the following example, the first connection is to the KIDDER:G8PZT node. The connection uses the alias (KIDDER), because like many other nodes, connections to the callsign (G8PZT) are "silent", i.e. they don't send any text upon connection.

{{whatspac07.png|Example WhatsPac Connection Script}}

NOTE: The first "cmd" MUST consist of a callsign or alias only. For example "KIDDER" not "C KIDDER". All subsequent commands are as they would be typed into a node's command line.

==== Step 7: Connect to the Server ====

You are now ready to connect WhatsPac to its server.

Click on {{whatspac23.png|WhatsPac Messages Button}} or {{whatspac24.png|WhatsPac channels Button}} on the left hand navigation pane, and ensure that "**Xrouter Packet Engine**" is followed by a green blob.

Then press the connect button: {{whatspac22.png|Pressing the connect button}}

Wait for the script to finish, and both "lights" should now be green:

{{whatspac25.png|Successful Connection to WhatsPac Server}}


===== Troubleshooting The Connect Script =====

While WhatsPac is trying to connect to its server, it displays a button entitled "**Show Monitor**", as follows:

{{whatspac20.png}}

Clicking this button reveals what the connection script is doing, and where it gets stuck:

{{whatspac21.png}}


===== Using the WhatsPac Terminal =====

You may use the WhatsPac terminal for setting up and troubleshooting the connect script, or for general packet radio operations.  To select the terminal, press {{whatspac26.png|WhatsPac Terminal Button}} in the left-hand navigation pane.  The following screen should appear:

{{whatspac28.png}}

Click on the **Connect** button, then fill in the following dialog:

{{whatspac29.png}}

Click on the blue **Connect** button, and you should get connected:

{{whatspac30.png}}

You can now type commands into the white line at the bottom.

===== Using The Packet Monitor =====

The "**Packet Monitor**" pane (part of the terminal is for observing packet traffic.  To activate the monitor, pick a port from the selector, and click "**Start Monitor**". 

{{whatspac31.png}}

You should now see something like this, where the transmitted traffic is in <color #cc0000>**red**</color> and the received traffic is in <color #00cc00>**green**</color>:

{{whatspac32.png}}


===== Finally ======

Have fun, and we hope to see you on WhatsPac!

Paula Dowie,
February 2025