APCComm 3.1.3
^^^^^^^^^^^^^

This is APCComm, a program for transferring files between Amiga and PC
running GNU/Linux using the parallel or serial port and a LapLink
cable or null-modem cable.

It's distributed under the GNU General Public License and comes with full source-
code for the PC and Amiga. Please read COPYING for details.
For installing read the file INSTALL.
It's fast (up to 38 KByte/s, see Speed below), easy to use (no configuration
needed) and the amiga part has a GUI.
It can transfer whole directories so it can also be used as a simple backup
solution. It can also read and write ADF disk images.

The Amiga GUI was created with GadToolsBox V2 and also uses the
reqtools.library (ReqTools is Copyright  Nico Franois and Magnus Holmgren).

Requirements:
^^^^^^^^^^^^^
 Hardware:
  Amiga (ClassicAmiga with 68k processor and standard parallel or serial port.
         NOTE: the Amiga 1000 has a different parallel port and needs
               an adapter!)
  PC (with standard parallel port or any Linux supported parallel port interface,
      or a serial port)
  LapLink cable (See file README-CABLE) or Null-Modem cable
  
 Software:
  PC:
   Linux x86
   C-Compiler (gcc recommended)

  Amiga:
   AmigaOS >1.0 for text only version (apccomm-nogui)
   AmigaOS >=2.0 for GUI version
   reqtools.library V38 (only for the GUI version)
   NOTE: no compiler needed

APCComm uses the Parapin library for direct access to the parallel port. This
  library is included in the directory src/parapin-1.0.0. It will be used
  automatically but if you have an installed version and want to use it
  instead, uncomment the line "USE_SP=1" in the Makefile.config.

  The version included in this package comes without the documentation and
  example codes to keep the archive size small. You can download the full
  version at:
      http://parapin.sourceforge.net/

APCComm also comes with the tavvva_ppdrv library for indirect access
  through ioctl calls to any parallel port supported by
  Linux. Therefore, USB-to-parallel devices can also be used. However,
  many devices only simulate a printer device and cannot be used.

Usage:
^^^^^^
In short, start "apccomm" with all files and directories you want to send as
arguments on the corresponding computer. Start apccomm on the other side and
all files will be transfered automatically.

The long story:

For Linux you need (at the moment) root-privileges to get access to the parallel
port!
You can make apccomm suid-root, apccomm will drop root-privileges after
initialization but be warned that this can open security holes!
I'm not responsible for any error or damage that occurs by using this program.

The default port is LPT1 but can be changed, see Options below.

PC:
---
If you want to receive files, start apccomm without any non-option arguments.
If there is at least one non-option argument to apccomm, it will send all
given files and directories to the amiga.

Amiga:
------
Start apccomm by entering apccomm in a CLI or double click on the icon at the
Workbench.

At the top of the window, you can select the hardware port to use
(either parallel or serial), and for the serial connection you can
select the transmission speed.

If you want to receive files, the top box is of interest for you. Select, if
you want to ignore the protection bits send by the PC.
Choose the directory where the incoming files and directories should be stored
by changed the value or click on "G" to select the dir with a requester.
Then click "Receive" and the transfer starts.

If you want to send files, add all files and directories by clicking at "Add"
and select them in the requester. You can do multi-select by holding the shift
key while selecting. With Remove you can remove the selected entry from the
list.
Finally click on "Send" and the transfer starts.

If you start the GUI version from a CLI and give some files as arguments, they
will be added the list so you can still add more files or remove some from
the list before sending them.

APCComm understands 5 Tool Types:
 - PUBSCREEN=<Public screen to use>
   Enter the name of the public screen on which APCComm should open it's
   window
 - VERBOSE_LEVEL=0-2
   Select one of three verbose levels. 1 and 2 are almost the same at the
   moment, but level 0 means quiet and there will be no requester after transfer
   start when everything runs okay
 - IGNORE_PROT=true or false
   Set it to the value you prefer but you can still change it in the main-
   window
 - PORT=parallel or serial
   select the port to use. Defaults to parallel port
 - SPEED=<speed name or value>
   selects the speed for the serial port communication.
   Value can be either "slow", "normal" or "fast" for 9600, 57600 or 115200 baud, or
   a number specifying the speed. Supported numerical values are 9600, 19200, 38400, 57600,
   and 115200.

Examples:
^^^^^^^^^
1) PC: apccomm
   Amiga: apccomm SYS:
   
   Will send the whole sys partition to the pc

2) PC: apccomm *
   Amiga: apccomm
   
   Will send all files and subdirectories in the current dir to the amiga

The amiga version without GUI (apccomm-nogui) works just like the linux version,
try "apccomm-nogui --help" to show all options.

Options:
^^^^^^^^
 -v, --version     prints the program version
 -h, --help        shows a little help
 -V, --verbose     make apccomm print more information
 --license         shows program license
 -q, --quiet       no output except error messages
 -i                ignore protection bits (file permissions) while receiving
 --speed=<value>   select serial transmission speed. Values are slow, normal,
                   fast, or 9600, 19200, 38400, 57600, 115200.
 --save-settings   save device settings for permanent use

special linux options:
 -p, --port=<port> set the parallel port to <port>
                   <port> can be lpt1 or lpt2, or any base address (starting
                   with 0x...), or any parallel port device (starting with
                   /dev/...)
 -s, --serial=<port> set the serial port to use. Typical values are
                   "/dev/ttyS0" or "/dev/ttyUSB0"

special amiga options:
 -s, --send           immediately start sending
 -r, --receive        immediately start receiving
 --pubscreen PUBSCREENNAME    use given pubscreen for the GUI
 -d                   read/write ADF images
 -t, --track min,max  read from min to max track
 --verify             verify written ADF image
 --serial             use the serial port instead of the parallel port
 --parallel           use the parallel port
 --keep-settings      store device settings in ENV variable

 Any other option is taken as filename.
 Filenames can be normal files or directories or even patterns like *.c at linux
 or #?.c at the amiga (NOTE: at linux patterns are resolved using the shell so
 don't use single quotes ('))
 You can give as much filenames you need.
 NOTE:Pattern matching is not available on AmigaOS<2.0 !

ADF mode:
^^^^^^^^^

ADF images can be written/read directly from/to floppy disk. To use
this mode, you have to select the option in the GUI or use the -d CLI
argument.

When reading a disk, APCComm will ask for a file name that will be
used at the Linux side for the name of the ADF image. Via CLI argument
-t you can also select to only a certain range of tracks. To specify
which floppy drive shall be used, you need to use df0: to df3: as send
name.

When writing an ADF file, just send the file from the Linux. APCComm
will ask which drive to use before actually writing it. You can choose
the verify the written tracks by choosing the GUI option or using the
CLI argument --verify. When receiving ADF images, you can also send
more than one ADF file or even complete directories. Only file names
ending with .adf will be written, everything else will be ignored.

Examples:

1) read image from df0 and send it to Linux:

apccomm -d -s df0:

2) receive image from Linux and write image to df0:

apccomm -d -r

and choose df0 in the requester or enter it in the CLI.

Speed:
^^^^^^

Here are some measurements from my test system:

Amiga: A600 with 68030 @ 25 Mhz, 10 MB RAM, OS 2.1, HD
PC: Linux 2.4.18 with Intel PIII 800, 704 MB RAM

Parallel port:

           | RAM<->HD   | HD<->HD    |
-----------+------------+------------+
Amiga ->PC | 38 KByte/s | 32 KByte/s |
Amiga<- PC | 18 KByte/s | 15 KByte/s |
-----------+------------+------------+

Serial port:

           | Transfer speed | Effective speed |
-----------+----------------+-----------------+
Amiga<->PC | 57600          | 5.2 KByte/s     |
Amiga<->PC | 115200         | 9.4 KByte/s     |
-----------+----------------+-----------------+

There is no crunching code so the speed doesn't depend on the content of the
files you are transferring. You can get lower or ever higher values.
You can expect decent rates even when using slower systems.

Direct disk access to read/write ADF images is slower, I got write speed of
around 11 KByte/s and read speed of around 22 KByte/s. So it takes around 40
seconds to create an ADF image and 1 minute, 20 seconds to write it back to
floppy disk.

Notes:
^^^^^^

The quality and performance of the serial communication on the Amiga
with multitasking enabled depends heavily on the load of the
system. When a lot of interrupt related stuff is going on, like disk
access, sound, graphics, etc., the serial port may experience hardware
overrun which leads to missing data and eventually aborted
transmission. If you get such a message, try stopping CPU intensive
programs or select a slower speed.

The fast setting (115200) usually is only reliable if nothing else is
running on the system (and it might also require a faster CPU).

########
FINALLY:
########

Use this at your own risk. There is a very basic checksum for correct
transmitting but there is no guarantee for correct transmission. I
recommend using some packers like lha to be able to better detect
errors.

There are different versions of a parallel null modem cable out there. Using
the wrong cable CAN damage both computers. Take a look at the cable description
in the file README-CABLE. And remember: USE THIS SOFTWARE AT YOUR OWN RISK.

I'm not responsible for any error or damage that occurs by using this program.

Legal stuff:
^^^^^^^^^^^^

APCComm was written by Ralf Hoffmann and it's released under the GNU General
Public License:

Copyright (C) 2000-2025 Ralf Hoffmann

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA.

Use this at your own risk. I have some checksum for correct transmitting (and
I never get an error at my machine) but there is no warranty for correct trans-
mitting. You have been warned!
I'm not responsible for any error or damage that occurs by using this program.

Homepage: http://www.boomerangsworld.de/apccomm
EMail: Ralf Hoffmann <ralf@boomerangsworld.de>
