UIChat Files

################################################################################
# File Name : README.txt
# Author : Mitch Winkle, AB4MW
# Version : ROLLING
# Date : 9 May 2016
# License : Gnu GPL v3.0
# Description : README for UIChat
################################################################################
The UIChat program is a direct result of the fine work of the authors of FSQCall.

"FSQ was developed by Con Wassilieff ZL2AFP with the assistance of Murray 
Greenman ZL1BPU."  

More information about FSQ and FSQCall can be found at:

http://www.qsl.net/zl1bpu/MFSK/FSQweb.htm

In short, the model of the FSQCall program is one of simplicity, yet surprising
power.  It allows a pair of users, or a set of users (net), to communicate
directly and also allows passing of messages via an intervening third party. 
Messages may be written to disk.  A user may request your QTH information, or 
your software version, or any number of handy actions, all of which are handled
by the sofware automatically!

The most intriguing part of FSQCall for me is the SELCAL mode or Directed Mode.
In this mode, only messages destined for me are printed on my "screen".  This
makes for a neato way to use even a busy channel for chatting between two 
stations.  UIChat is built around the concept of FSQCall's SELCAL mode.  It also
allows the "allcall" and "cqcqcq" special identifiers in order to display 
multicast messages (just like FSQCall).

UIChat is a specific subset of the FSQCall action set.  Since it is designed to
work over AX.25 using UI (Un-numbered Information) frames, there is
little need for a signal report (? action character).  At this time, the user is
greeted with a station status message of your choice.  The "*" action character
forces FSQCall to active mode if put into sleep mode.  This too is not required
for UIChat.  The speed action characters ( < and > ) are also not needed since
UIChat is not integrated to any one modem, but can use ANY modem that you can
connect to the Native Linux AX.25 stack (hint: there are a LOT of them!).  The
"|" alert action character is supported, but does not (in v1.07) create a
pop-up message for the receiving user, rather it moves down two blank lines and
surrounds the message with the word "ALERT" multiple times.  Lastly, the image
transfer function of FSQCall is not supported.

WHY AX.25 and WHY UI FRAMES?

From the AX.25 specification version 2.2 section 6.3.7 Connectionless Operation

"AX.25 uses a special frame for this operation, the Unnumbered Information (UI) 
frame. In this type of operation, the destination address has a code word 
installed in it that prevents users of that specific round-table from seeing all
frames going through the shared RF medium. For example, if a group of amateurs 
are engaged in a round-table discussion about packet radio, they could put 
“PACKET” in the destination address; they will receive frames only from others 
in the same discussion. An added advantage of the use of AX.25 in this manner
is that the source of each frame is in the source address subfield; software 
could be written to automatically display who is making what comments."

That last sentence is what UIChat is attempting to do!

PRIMARY PURPOSE of UIChat

My thinking with the creation of UIChat was that the SELCAL functionality of it
is so useful; that it would be rather helpful on directed nets on VHF/UHF
as well as HF for that matter.  Having the ability to use digipeaters to extend
one's reach is also quite valuable in the VHF/UHF bands but can be used on HF
also using tools like N1URO's cross-port digipeater, axdigi.

NOTE: Use of a digipeater is a global setting.  It will be used for ALL 
communications if specified in the config file or at the command line.

The use of UIChat is not limited to AFSK or FSK however, since ANY modem which 
can present a KISS interface, even via TCP/IP on another computer, may be used
with UIChat.  This includes the venerable FLDIGI and it's KISS interface which
allows the use of a subset of it's modems to act as a KISS TNC to AX.25.  
Therefore, one may choose MFSK or BPSK instead of traditional "packet" modems.  
This gives the operator more flexibility, particularly on HF where band 
conditions may dictate the choice of modem type.

INHERENT LIMITATIONS IN UIChat v2.0 Beta

1. Frame size is limited to 255, and as yet, no mechanism for at least marking
frames as (1of2) or such has been coded.  This is at least a possibility 
however, and would give the receiving station a clue to a missing frame.
2. No image transfer capability is included.  
3. There is no built-in way to enable a signal report so I use that action
character, "?" as a station status message as stored in the config file or set
using the "status" command at the UICHAT> prompt.
4. Version 2.0 uses a Java GUI and encodes and decodes UI frames internally thus 
requires no AX.25 stack to be installed or configured.  A working Java install
of at least version 1.6 is required.  The Raspbian distribution for the 
Raspberry Pi already has a working version of Java installed.

INSTALLING UIChat v2.0 Beta

Download the UIChat201xmmDD.zip file and extract it in a convenient directory.  
I suggest using your home directory.

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!	
!!! Now Edit/Preferences from the meny system and make it your own. !!!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

ON THE NETWORK TAB

"Mode" -- Select the modem connection type.  Either KISS Serial or
KISS TCP.  Future selection will include the ARDOP modem when available.

IF USING A KISS SERIAL PORT CONNECTION (otherwise may be left blank)

"Serial Port" - the name of the serial port.  In Windows, typically
COM1 or COM6...  In Linux the full device file path such as /dev/ttySO

"Serial Baud Rate" is the baud rate between the program and the serial
port.  This has NOTHING to do with the over the air baud rate.

IF USING A KISS TCP MODEM (like Direwolf or UZ7HO)

"TCP Host" is the computer where the modem is running.

"TCP Port" is the TCP Port that the modem listens on. (Direwolf commonly
8001, UZ7HO commonly 8100, FLDIGI commonly 7342).

"Digipeater" is a SINGLE digipeater to use.  You may change the digi value at 
any time from the program and it's value will be stored back to the config file.
If you do not need a digipeater, leave this blank.  This is a global value and
will be used for all communications until it is either changed or 
removed (made blank).
	
ON THE STATION TAB	

"Station Call Sign" should be set to lower case.  
The program will change it anyway!

"Name" is the operator name.

"Current Status Message" is the message returned when the "?" action is sent 
to you.  You may change this value at any time from the preferences.
	ab4mw online...
		or
	ab4mw away from the shack...
		or
 	ab4mw -- use # to leave me a message...

"Sounding Interval" is the default number of minutes between soundings, default is 15.
	
"Sounding Text" is a short message used on your sounding transmission.  

Something like :

	ab4mw FM17gf
	
This is useful on HF to map propagation in combination with the heard list.

"Station Info Message" is the message returned when the "&" action is sent to you.

"QTH" is the message returned when the "@" action is sent to you.

"Maidenhead Grid Square" is your grig square.


USING UIChat

To start UIChat, simply open a terminal window and type:

	Change to that directory and run the following command :
	cd ~    (or to wherever you saved the UIChat.jar file)
	java -jar UICHat.jar
	
You will be presented with a graphical user interface with a receive text area,
a transmit text area, a heard list and some other controls and a menu system.
	
You will type commands in the transmit text area near the bottom of the screen.
When messages or action commands arrive via the radio for your station, then
you will see them displayed in the receive area preceided by "RX< " and then the
information.  When you send text or a response to an action command, it is 
preceded by "TX> " in the receive text area.

	RX< this message is for you
	RX< ab4mw: QTH Request
	TX> ve1jot: Matoaca, VA USA FM17gf
	
In the Receive Text area there is a right-click popup menu with helpful text
operations.

In the Transmit Text area there is a right-click popup menu with helpful text
operations, plus the ability to retrieve the last sent message, and to send
the current text.

HEARD LIST

The upper right portion of the screen contains the Heard List of UIChat 
stations.  If a call sign is selected with a left click, a right click will
popup a menu of query actions that will be immediately sent to that station.
If a station call sign is selected, that same list is available from the
Action menu.
	
MENUS

Under the Help menu, you will find a list of Commands to send to the other
station from your transmit text area.  You will also find the License notice and
an About dialog.

Under the Action menu you will see a list of 5 actions that can be requested 
from the remote station.  First, select the remote UIChat station from your 
heard list if there are any and then select an Action to be sent.  If the other 
UIChat station hears your request, it will respond with the appropriate answer.

Under the View menu, only the Clear RX selection is functional and it will clear
the receive text area of the screen.  The Messages item is for stored messages
which were created by the remote station on your computer using the "#" action
command.  This is a future feature.

The Edit/Preferences menu item shows you a two-tabbed settings dialog which has
helper text included.

File/Exit terminates UIChat v2.0.