//=============================================================================
// Copyright © 2017 FLIR Integrated Imaging Solutions, Inc. All Rights Reserved.
//
// This software is the confidential and proprietary information of FLIR
// Integrated Imaging Solutions, Inc. ("Confidential Information"). You
// shall not disclose such Confidential Information and shall use it only in
// accordance with the terms of the license agreement you entered into
// with FLIR Integrated Imaging Solutions, Inc. (FLIR).
//
// FLIR MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
// SOFTWARE, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
// PURPOSE, OR NON-INFRINGEMENT. FLIR SHALL NOT BE LIABLE FOR ANY DAMAGES
// SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
// THIS SOFTWARE OR ITS DERIVATIVES.
//=============================================================================

===============================================================================
==
== README
==
===============================================================================

===============================================================================
TABLE OF CONTENTS
===============================================================================
1. DEPENDENCIES
1.1. DEPENDENCY INSTALLATION
2. SPINNAKER INSTALLATION
3. SPINNAKER REMOVAL
4. RUNNING PREBUILT UTILITIES
4.1. SPINUPDATECONSOLE
5. TROUBLESHOOTING NOTES
5.1 TROUBLESHOOT USB STREAM
5.2 TROUBLESHOOT GIGE CAMERA SETUP
5.3 TROUBLESHOOT GIGE STREAM


===============================================================================
1. DEPENDENCIES
===============================================================================

To install Spinnaker on Linux you will need to have a few prerequisite
libraries installed.  Below is a list of libs that Spinnaker depends on.

Required:
1) libusb-1.0-0 (version 1.0.17 or greater recommended)

Strongly recommended:
Ubuntu 16.04 LTS:   Linux kernel version 4.4.19-35 or later.

-------------------------------------------------------------------------------
1.1. DEPENDENCY INSTALLATION
-------------------------------------------------------------------------------

To install these dependencies, the most straightforward approach is to use your
system's built-in package management utility. In the case of Ubuntu, the utility
is named "apt". Below is a set of one-line commands that can be used to install
all the required dependencies for various releases of Ubuntu Long Term Support
(LTS).

Ubuntu 16.04:
user$:  sudo apt-get install libusb-1.0-0


===============================================================================
2. SPINNAKER INSTALLATION
===============================================================================

Once all the dependencies are installed, just install the Spinnaker deb files.
There are eight different packages that need to be installed.

The Spinnaker packages are:
- libspinnaker-<version>_<platform>.deb
- libspinnaker-<version>_<platform>-dev.deb
- libspinnaker-c-<version>_<platform>.deb
- libspinnaker-c-<version>_<platform>-dev.deb
- spinupdate-<version>_<platform>.deb
- spinupdate-<version>_<platform>-dev.deb
- spinnaker-<version>_<platform>.deb
- spinnaker-doc-<version>_<platform>.deb

The packages with a preceding 'lib' are all the shared objects and their
respective dev packages.  The spinnaker-doc package contains our documentation in
pdf format (located in /usr/share/doc/spinnaker-doc).

To install these packages, we provide an easy to use install script. You can
run the script in the same directory that you have unpacked the software into.
The install script is called 'install_spinnaker_arm.sh'

code eg:
user$ sudo sh install_spinnaker_arm.sh

This script will install all the Spinnaker libraries, example code, example
apps and documentation.  The Spinnaker install script will also ask you to
configure udev so that a user will be able to use the USB devices.  If
you choose to configure the USB devices this script will change
permissions on the nodes to give this particular user full read and write
access to the device nodes.  It will overwrite the default Ubuntu permissions.
After running this script everything should be installed and set up for use.

Unfortunately restarting udev doesn't seem to set the permissions on the device
nodes immediately.  You may need to restart the machine before the user can
access the device nodes.


===============================================================================
3. SPINNAKER REMOVAL
===============================================================================

To remove Spinnaker just run the uninstall script that we provide.  The
removal script will also remove the udev rules therefore restoring the original
ubuntu permissions on the device nodes.

code eg:
user$: sudo sh remove_spinnaker_arm.sh


===============================================================================
4. RUNNING PREBUILT UTILITIES
===============================================================================

In addition to prebuilt examples (eg: Acquisition, ChunkData, etc),
along with the source code for these examples, Spinnaker SDK also ships a tool
for upgrading firmware (ie: SpinUpdateConsole).

To make using these tools more convenient, Spinnaker SDK ships with a few
command-line scripts used to automatically set the appropriate environment
variables so these tools can be run from any PWD via the command-line, or when
launching the tools via a custom icon/shortcut. To run the following tools,
simply invoke their "launcher" command via the command line, and you will not
have to change the PWD to "/usr/bin" or modify environment variables in order
to launch them.

-------------------------------------------------------------------------------
4.1. SpinUpdateConsole
-------------------------------------------------------------------------------

SpinUpdateConsole: A console application for updating the firmware on FLIR cameras.
Location:   /usr/bin/SpinUpdateConsole
Short Name: SpinUpdateConsole
Launcher:   SpinUpdateConsole


===============================================================================
5. Troubleshooting Notes
===============================================================================

A summary for streaming FLIR machine vision cameras using FlyCapture2 or
Spinnaker SDK on ARM based embedded boards can be found at:
<http://www.ptgrey.com/TAN/10699>

-------------------------------------------------------------------------------
5.1 TROUBLESHOOT USB STREAM
-------------------------------------------------------------------------------

On Linux systems, image size is restricted to 2MiB or less by default. To
increase this limit so that you can make use of your imaging hardware's full
capabilities, you will need to make a minor change to your system. More information
for streaming on embedded systems can be found at:
<http://www.ptgrey.com/KB/10699#Troubleshooting>

1. Open the /etc/default/grub file in any text editor. Find and replace:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"

with this:

GRUB_CMDLINE_LINUX_DEFAULT="quiet splash usbcore.usbfs_memory_mb=1000"

2. Update grub with these settings:
$ sudo update-grub

3. Reboot and test a USB 3.1 camera.
If this method fails to set the memory limit, run the following command:
$ sudo sh -c 'echo 1000 > /sys/module/usbcore/parameters/usbfs_memory_mb'

To confirm that you have successfully updated the memory limit, run the following command:
$ cat /sys/module/usbcore/parameters/usbfs_memory_mb

Note that if you set the memory limit this way, you will have to set the memory limit every time
you restart your system. 
-------------------------------------------------------------------------------
5.2 TROUBLESHOOT GIGE CAMERA SETUP
-------------------------------------------------------------------------------

To setup your network interface to use GigE cameras, run ifconfig and find the
network adapter that you intend to use the cameras on (eg. enp15s0):

code eg:
user$: ifconfig

Then, open up /etc/network/interfaces in a text editor (as sudo):

code eg:
user$: sudo gedit /etc/network/interfaces

and add the following lines (change enp15s0 to match the one shown in ifconfig):

    iface enp15s0 inet static
    address 169.254.0.64
    netmask 255.255.0.0
    mtu 9000

    auto enp15s0

If using multiple interfaces, ensure that the addresses used are on different subnets
(eg. 169.254.0.64 and 169.253.0.64).

Lastly, restart the network service to apply the new settings:

code eg:
user$: sudo /etc/init.d/networking restart

You may need to restart the machine before the new interface settings are applied.

Other ways of setting up GigE cameras to be recognized on Linux systems can be
found at:
<https://www.ptgrey.com/KB/10933>

-------------------------------------------------------------------------------
5.3 TROUBLESHOOT GIGE STREAM
-------------------------------------------------------------------------------

On Linux systems, you may experience poor streaming performance due to lost data
packets. To improve streaming performance, you can adjust the some settings on the
camera side as well as on the system side. Full instructions on making these changes
can be found at:
<http://www.ptgrey.com/kb/10016>
