Differences

This shows you the differences between two versions of the page.

--- packet:xrouter:howtos:whatspac [2025/02/19 18:30] – g8pzt
+++ packet:xrouter:howtos:whatspac [2025/02/21 15:19] (current) – [Channels Display] g8pzt
@@ Line 7: / Line 7: @@
 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! Here's what the "Channels" display looks like on a desktop browser:
+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!
-{{whatspac01.png|WhatsPac Channels Display}}
+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...
@@ Line 43: / Line 61: @@
 ===== 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.
+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 ====
@@ Line 154: / Line 173: @@
 ===== 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:[email protected]|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 ====
@@ Line 167: / Line 191: @@
 Fill in your callsign and name. When you are done, click the "**Update Callsign and Display Name**" button.
-Then on the "**Your Packet Setup**" selector, choose "**I use a TNC or Software Modem attached to a radio**". The following text wil appear:
+==== 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}}
-[work in progress]
+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