readme.txt

Lady Heather Version 4.0 (with Linux and macOS (OS/X) support)

To use this program on Linux, macOS, and FreeBSD:

1) Create a directory to install it in and switch to that directory.

2) Unzip the zip file into the directory

   In the X11 distribution .ZIP file is a file "heathosx".  This is a
   pre-compiled executable for macOS (aka OS/X) (tested under El Capitan).
   If you are using macOS install the XQuartz package from xquartz.org.
   Note that you need to logout/login or restart your system after installing
   XQuartz for it to work.

   Then, from a terminal window:
       unzip -q heatherx11.zip
       cd heatherx11
       mv heathosx heather
       chmod +x heather
       xattr -d com.apple.quarantine heather

   Double-click the "heather" file to launch the program (depending upon your 
   system settings you might need to right-click it and select OPEN to allow it 
   to run)

   If you don't rename the file, Heather will attempt to use "heathosx.cfg" 
   and "heathosx.cal" for its' configuration and calendar files.  You could
   also just rename those files.


3) Make sure you have the g++ compiler and libx11-dev packages installed:
      sudo apt-get install g++
      sudo apt-get install libx11-dev

   For some Fedora Linux distros your may need to edit the makefile and 
   change "OS = g++" to "OS = gpp".  Also the X11 development package is 
   called libX11-devel (with a capital 'X')

   For macOS you will need to install the XQuartz package from XQuartz.org)
   (note: their installer time remaining message is rather optimistic)
   You will also need to install XCode from Apple (WARNING: it's HUGE).

   If you use the "N" keyboard command to open the NANO text editor from
   within Heather, you will need make sure that xterm is installed (Raspberry
   Pi's don't have it installed by default).
      sudo apt-get install xterm


4) Compile the code (the make file auto-detects Linux, macOS, and FreeBSD):
      make clean
      make

5) Edit the heather.cfg file to suit your needs.  It sets the values of the
   initial command line options to use.  Place one command line option per
   line, starting in column one.  If a line does not start with a '/' or 
   a '-', the line is considered a comment. You can also use '@' lines in
   a .cfg file to send what are normally keyboard only commands.  All the '@'
   lines are written to a temporary file which is then processed as a keyboard
   .SCRipt file once Heather has finished initializing the hardware.

6) Run it:
   ./heather -1u             (for ttyUSB0 serial input)
   ./heather -1a             (for ttyACM0 serial input)
   ./heather -1              (for ttyS0 serial input)
   ./heather -id=device_name (for using a non-standard serial device name)
   ./heather -ip=addr:port   (for internet connected server)

   (macOS use /dev/tty.usbserial# for its USB serial port identifiers and 
    /dev/ttys# for hardware serial ports)

   You can use a different digit for the -1 or -1u options if your are using
   a different serial device.  

   Note: THE NUMBER THAT HEATHER USES FOR THE SERIAL DEVICE IS ONE GREATER THAN
   THE OPERATING SYSTEM DEVICE DEVICE NUMBER.  Sorry for the kludge... Heather
   has its roots in Windows where com port numbers start from one and Heather
   used port 0 to indicate that no serial port was to be used.


   To run heather on Linux, the user must have access permissions
   for the serial device.  You can run Heather with sudo or
   (much better idea) give the user access to the "dialout" group:
       sudo usermod -a -G dialout user_name
   You must reboot or log out and log back in for usermod to take effect.
   You only need to run usermod once. Its setting is persistent between
   boots.  Some Linux distros use the "uucp" group instead of "dialout".

   Under macOS, serial port device driver installers usually ask what users
   to give serial port access permission to.
   

Known issues:
   With some (older) Linux distros you may need to add a -lrt option to the
   linker command in the makefile.  This links in the the library for getting
   and setting the system clock.  Most distros have these functions in the
   standard C library. 

   For the system clock setting functions to work, you need to have
   root permissions.  Since most Linux boxes have NTP running, you
   probably should not be using the system time setting commands, anyway.
   If you do a TS command from the keyboard, you should hear a beep (after a
   few seconds) if the clock set command worked.

   On macOS, if you go to full screen mode by clicking the maximize button,
   clicking it again won't usually restore the window size to its previous
   value.  Also when resizing the window by dragging the lower right corner of
   the window,  make sure the mouse cursor has "caught up" with the window 
   corner before releasing the mouse button. Window resizing under XQuartz is
   a bit laggy,

   Beware of cheap Chinese USB-Serial converters.  They often use iffy "clone"
   chips that may not be compatible with standard Linux drivers.  For example, 
   a lot of "CH3xxx" clones do not seem to let you set the baud rate under 
   Linux when using the drivers shipped with the Linux distro.


   To use the TAPR TICC Arduino based time interval counter, your system will 
   need to have support for CDC ACM devices enabled.  If your system does not
   recognize the TAPR TICC USB port try:
      sudo modprobe cdc_acm
   to enable the CDC ACM driver.  Also you will probably have to specify the
   device id for Heather use.  On my system I use the command line option:
      /id=/dev/ttyACM0   -or-
      /1a