************************************************************************
*  CCSLoad Programmer Control Software Linux Installation Instructions *
************************************************************************

1.  Download the latest version of the CCSLoad Programmer Control
    Software for Linux from the following link:

      http://www.ccsinfo.com/downloads/CCSLoadInstall.run

2.  Open a terminal window and use the following command to install:

      sudo ./CCSLoadInstall.run

3.  The installer will request you to restart your PC.  It is HIGHLY recommended
    to do so or you will run into issues running the software and accessing any
    programmers.

4.  Once restarted, plug in your programmer.

5.  If the programmer has been picked up properly, you should have a 
    /dev/ttyUSB* device.  To determine which device belongs to your
    programmer, you can use the following command:
     
      dmesg | grep "ttyUSB"
     
    You should see the /dev/ttyUSB* device at the end of the output.  If you
    do not a /dev/ttyUSB* device, see Appendix A for troubleshooting.

6.  There should also be a /dev/ttyS* device that points to the /dev/ttyUSB0
    device.  To determine which one points to your programmer, do the 
    following:
     
      ls -l /dev/ttyS* | grep "ttyUSB"
     
    You should see a /dev/ttyS* device pointing to your /dev/ttyUSB* device.
    Make note of the number of the /dev/ttyS* device.  If you do not see a
    /dev/ttyS* device, see Appendix A for troubleshooting.

7.  Once you know the number, add 1 to it and this will be the 'COM' number
    you will pass to CCSLoad.  To test if your programmer is being detected
    you can run the following command:

      ccsloader port=COMX +test

    Where COMX would be COM1 if your device is tied to /dev/ttyS0 or COM2
    for /dev/ttyS1.  If this command fails, see Appendix A for troubleshooting.

8.  Once the programmer test has passed, connect the target board to the
    programmer and run CCSLoad with the command options below from a
    terminal window to test that the programmer can communicate with the
    target board:

      ccsloader port=COMX test=PICXXXXXXX

    Where PICXXXXXXX should be replaced with the type of PIC chip on the
    target board the programmer is connected to.

9.  To bring up the help documentation, including a list of the commands
    and options avaliable in Linux, you can run the following command:

      ccsloader help=firefox

************************************************************************
* Appendix A: Troubleshooting                                          *
************************************************************************

------------------------------------------------------------------------
Issue:
  No /dev/ttyUSB* device is found

Things to Check:
  This can occur for a few different reasons.  The most common reason
  is having an older Linux kernel.  If the following command returns
  anything less than 2.6.30, this may be your issue:
  
    uname -r
  
  If you do have an older kernel, attempt to update it to a newer
  version to obtain support for our devices.  If this is not possible,
  you should be able to do the following:
  
  1) Open /etc/modules in a text editor (must be edited as root).
  2) Add a line like the following:
       
       ftdi_sio vendor=0x403 product=0xF9DX
     
     Where the X above is obtained from this table:     
       
       0 = ICD-U20
       1 = ICD-U40
       2 = MachX
       3 = Load-n-Go
       4 = ICD-U64
       5 = Prime8
------------------------------------------------------------------------

------------------------------------------------------------------------
Issue:
  No /dev/ttyS* device is found

Things to Check:
  This symbolic link is created by a udev rule that is placed at
  /etc/udev/rules.d/99-CCS-USB.rules.  If your version of udev is older
  or does not pick up the file for any reason, the link will not be
  created.  If this is the case, you can manually create the link with 
  the following command:
  
    sudo ln -s /dev/ttyUSB<1> /dev/ttyS<2>
    
  Replace <1> with the appropriate number found in step 5 of the
  instructions.  Replace <2> with a number that doesn't conflict with
  any existing /dev/ttyS* devices.  Note that CCSLoad will not work
  with any /dev/ttyS* devices beyond 7.    
------------------------------------------------------------------------

------------------------------------------------------------------------
Issue:  
  CCSLoad requests a COM Port even when one is specified:

Things to Check:
  This happens when CCSLoad cannot find the programmer at the given
  port.  The most common reason for this is permissions.  Your user
  may need to be added to a specific group to access the programmer.
  To check if this is the issue, run the ccsloader command with sudo.
  If this works then you most likely have a permissions issue.

Solution:
  To allow your user to access the device, do the following:

  1) Find out which user/group can access the device by doing:
  
       ls -l /dev/ttyUSB*
  
     You should get a line like:
    
       crw-rw---- 1 root uucp 188, 0 Jun 22 19:33 /dev/ttyUSB0
  
  2) The group who owns the device above is uucp.  Your distribution
     may use a different group for these devices.  To add your user to
     the group that owns the programmer device, do the following:
     
       sudo usermod -a -G <group> <username>

     Where <group> should be replaced by the device's group and the 
     <username> should be replaced by your username.
  
  3) You will now need to log out/reboot for the your user to be added
     to the group.
  
  4) Starting with step 7 above, you can begin testing if this fix has
     corrected your problem.
------------------------------------------------------------------------