====== Building libpixyusb on Linux ======


====== 1. Introduction ======

The libpixyusb library provides a software application programming interface (API) for communicating\\
with Pixy over USB. This allows you to write software that interfaces with Pixy like the PixyMon application.

The following procedure will outline the steps required for building the libpixyusb library and some example projects using the library. This procedure assumes the following:

  * Your system has Linux Mint-17 installed
  * Pixy firmware has been updated to 2.0.8
  * Your system is connected to the internet
  * libpixyusb version is 0.3
  * libusb version 1.0.9

The Mint-17 distribution of Linux can be downloaded here: http://www.linuxmint.com

Instructions for updating the Pixy firmware are here: [[wiki:v1:Uploading_New_Firmware|Uploading New Firmware]]

Although this procedure uses Linux Mint-17, it //should// work with any Linux distribution that uses the Debian package manager (e.g. Ubuntu).


====== 2. Procedure ======


===== 2.1. Install dependencies for building libpixyusb =====

Start the terminal application:

{{wiki:img:78184a8b63cf10782c18339b791db9f85a0d8bc0.png?400}}


==== 2.1.1. Install git ====

In the terminal window type:

''%%sudo apt-get install git%%''


==== 2.1.2. Install libusb-1.0-0-dev ====

In the terminal window type:

''%%sudo apt-get install libusb-1.0-0-dev%%''

{{wiki:img:da64e20cd40baefbd00b8bb4fce081a0f9b76abd.png?400}}


==== 2.1.3. Install g++ (compiler) ====

In the terminal window type:

''%%sudo apt-get install g++%%''

{{wiki:img:208f77c0feb60df1b578d0a67c31972a6e32e285.png?400}}


==== 2.1.4. Install libboost ====

In the terminal window type:

''%%sudo apt-get install libboost-all-dev%%''

This step will take some time. Time for a refreshing drink?


==== 2.1.5. Install cmake ====

In the terminal window type:

''%%sudo apt-get install cmake%%''

{{wiki:img:3ee2278e34e6576a7ff030e21718e71c9da9b447.png?400}}


===== 2.2. Build and install libpixyusb =====


==== 2.2.1 Download Pixy source code ====

In the terminal window type:

''%%git clone https://github.com/charmedlabs/pixy.git%%''

{{wiki:img:dcf634a40148751c2a5f59668335e326013c2183.png?400}}


==== 2.2.2. Build the library ====

In the terminal window type:

''%%cd pixy/scripts%%''\\
''%%./build_libpixyusb.sh%%''

{{wiki:img:a636c182eec2a7d020e836738a7d629fa4b5bb13.png?400}}


==== 2.2.3. Install the library ====

Installing the library files requires root privileges.

In the terminal window type:

''%%sudo ./install_libpixyusb.sh%%''

{{wiki:img:d35f59500541f5c21f6aa117ae10b1ecb6af8fba.png?400}}


====== 3. Example projects ======

Before trying the examples below, connect Pixy to your Linux system using a USB Mini cable:

{{wiki:img:e0e66b6f1b2c5231027c1d03c811e16207772021.jpg?400}}


===== 3.1. hello_pixy: A Simple IO Example =====

The example does the following:

  - Connects to Pixy using USB
  - Displays firmware version installed on Pixy
  - Block information is displayed (as shown in the image above) if color signatures have been set and if the signatures are currently being detected by Pixy.


==== 3.1.1. Build the 'hello_pixy' example ====

In the terminal window type:

''%%/pixy/scripts/build_hello_pixy.sh%%''

{{wiki:img:b08075eeb1c7200e464a5706b435b2f896f0bdc8.png?400}}


==== 3.1.2. Start the example ====

To start the libpixyusb example, run 'hello_pixy' as root.

In the terminal window type:

''%%cd /pixy/build/hello_pixy%%''\\
''%%sudo ./hello_pixy%%''

{{wiki:img:41f4b477ad456027832c83c4cb90c9b695a29b2e.png?400}}

Block data received from Pixy is displayed in stdout.


===== 3.2. pan_tilt: An Object Tracking Example =====

This example does the following:

  - Connects to Pixy using USB
  - Pixy will track objects with color signature '0'

Before starting the tracking demo, make sure you've set color signature '0'. Look here: [[wiki:v1:Teach_Pixy_an_Object_2|Teach_Pixy_an_Object_2]]


==== 3.2.1. Build the 'pan_tilt' example ====

In the terminal window type:

''%%/pixy/scripts/build_pantilt_c_demo.sh%%''


==== 3.2.2. Start the example ====

To start the pan_tilt demo, run 'pan_tilt' as root.

''%%cd ../build/pantilt_in_c%%''\\
''%%sudo ./pantilt_c%%''

{{wiki:img:ecd3c47f5b3959e279d1678becdfbbbc9854009c.jpg?400}}

Pixy should track objects that have color signature '0' programmed. If the tracking is not smooth try the following:

  * Use Pixymon to verify that Pixy is getting a good lock on the object.
  * Try making adjustments to the ambient lighting.

Note: If this example freezes, make sure that your version of libusb is at least 1.0.9.


====== 3. Comments ======

We welcome your thoughts and feedback! Please let us know how we can improve.