OS - Linux: Difference between revisions

From Phidgets Support
 
(223 intermediate revisions by 10 users not shown)
Line 1: Line 1:
__TOC__
<metadesc>Communicate over USB with sensors, controllers and relays with Phidgets! Program in Linux using a wide variety of programming languages.</metadesc>
[[Category:OS]]
{|
|style="vertical-align:middle; width: 60%;"|
==Getting Started with Linux==
Welcome to using Phidgets with Linux!


Phidgets can run on Linux directly using USB, or remotely over a network using the [[Phidget Webservice]].
If you are ready to go, the first step in creating Linux applications with Phidgets is installing our libraries.
|{{TOC limit|3}}
|}
===Install===
The first step to using Phidgets with Linux is installing the Phidget22 libraries.
{{LinuxSupport}}
If you're running one of the supported distros, we recommend using the '''Package Install'''. For other systems, you can use the '''Source Install'''.  


You need kernel '''version 2.6''' (released in 2003) or later.
<div class="bigTabs">
<tabber>
Package Install=
====Install Script====
To run the install script and install phidget22, enter the following command in the terminal:


==Getting Started (Libraries and Drivers)==
{{LinuxInstallScript}}


Linux does not have a graphical user interface to check your Phidget, but we walk your through a method on the command line below.  Once you have your systems set up properly, you can pick your programming language and start creating code; we describe the Linux steps in detail in this document.
====Manual Install====
To install our package repository manually, enter the following command in the terminal, replacing ''distro'' with your distro codename:


If you are already a pro, and just want the downloads:
{{LinuxGetKey}}
*[http://www.phidgets.com/downloads/libraries/libphidget_2.1.8.20110615.tar.gz Phidget Libraries for Linux]
*[http://www.phidgets.com/downloads/examples/phidget21-c-examples_2.1.8.20111028.tar.gz Phidget Generic C Examples]
*[http://www.phidgets.com/downloads/libraries/phidgetwebservice_2.1.8.20120123.tar.gz Phidget Webservice Libraries for Linux]


===Installing===
We support Debian releases from 6 to current, and Ubuntu LTS releases from 14.04 to current. If you are using another flavour of Linux (such as Mint), which is based on Ubuntu or Debian, use the corresponding Ubuntu or Debian codename.


To install the libraries, follow these steps:
Update your package lists:
{{LinuxAptUpdate}}


#Download '''libusb-0.1''' and its development libraries
Finally, install the Phidget package by entering the command below:
#*Try {{Code|apt-cache search libusb}} in a terminal to find current packages
{{LinuxAptInstall}}
#*Or install [http://www.libusb.org/ from source], which includes the libusb development libraries
#Unpack and install the [http://www.phidgets.com/downloads/libraries/libphidget_2.1.8.20110615.tar.gz Phidget Libraries]
#*From the main unpacked libraries directory, run:
#*:{{Code|./configure}}
#*:{{Code|make}}
#*:{{Code|sudo make install}}
#*This will compile phidget21.h and place the library into your gcc path


'''Note:''' Although the libraries are written in C, the libraries for Python, Java, and most other Phidget-supported languages depend on them.
====Additional Packages====
You may also want to apt-get install the following optional packages:
* '''libphidget22-dev''': The C development libraries for Phidget22
* '''libphidget22extra''': Extra runtime library required for the Network Server and Admin tools
* '''phidget22networkserver''': The [[Phidget Network Server]], which enables use of Phidgets over your network
* '''libphidget22java''': The Java libraries for Phidget22
* [[Phidget22admin Guide|'''phidget22admin''']]: An administrator utility for listing Phidgets and upgrading firmware
* '''phidget22wwwjs''': The JavaScript libraries for Phidget22. This package also installs the HTML examples which can be accessed through the web interface


===Checking===


To confirm the libraries were installed and work correctly, you can check both the hardware and software sides of the interface. It is worth checking the software side first, because if it works then you know the hardware side is also okay.
The libraries are now installed on your machine. Next, set up the UDev rules below.


====Software====
|-|
Source Install=
====Source Install====
To install our libraries, first install libusb-1.0 development libraries. The exact command and package name will vary depending on distribution. For Debian based distributions, including Ubuntu and Mint, the command would be:
<syntaxhighlight lang=bash>
apt-get install libusb-1.0-0-dev
</syntaxhighlight>


To confirm that the libraries were installed correctly and can be used in code, you can use the [http://www.phidgets.com/downloads/examples/phidget21-c-examples_2.1.8.20111028.tar.gz Phidget Generic C Examples].


The easiest way to confirm correct installation will be to compile and run the '''{{Code|HelloWorld}}''' C example, included in the examples download. This does not involve writing any C code, but it does involve compiling the example and running it, which is a quick process as we show below.  If you feel more comfortable running the '''{{Code|HelloWorld}}''' example for your specific language, you can skip below and pick your language, but keep in mind that any problems could be with the C library installation and not necessarily with your language.
Next, download and unpack the following files:
*[https://cdn.phidgets.com/downloads/phidget22/libraries/linux/libphidget22.tar.gz libphidget22] (Mandatory)
*[https://cdn.phidgets.com/downloads/phidget22/libraries/linux/libphidget22extra.tar.gz libphidget22extra] (Optional - needed by NetworkServer and Admin)
*[https://cdn.phidgets.com/downloads/phidget22/libraries/linux/libphidget22java.tar.gz libphidget22java] (Optional - Java Libraries)
*[https://cdn.phidgets.com/downloads/phidget22/servers/linux/phidget22networkserver.tar.gz phidget22networkserver] (Optional - [[Phidget Network Server]])
*[https://cdn.phidgets.com/downloads/phidget22/tools/linux/phidget22admin.tar.gz phidget22admin] (Optional - Phidget Admin Tool)
Open the README file that is included at the top of each directory. This file will give you important information about how to properly install the files.


To compile and run the basic C example for checking your installation:


1. Unpack the [http://www.phidgets.com/downloads/examples/phidget21-c-examples_2.1.8.20111028.tar.gz Phidget Generic C Examples]<br>
Libraries are installed in /usr/local/lib by default. If you run into trouble finding the libraries during linking or at runtime, this probably means that /usr/local/lib is not on the library path for your distribution.
2. Open a terminal (often Ctrl-Alt-T) and go to the directory where the examples are unpacked<br>
3. Compile the {{Code|HelloWorld.c}} example:<br>
<div class="source">
<source lang=bash>


    gcc HelloWorld.c -o HelloWorld -lphidget21
You can handle this in a number of ways:


</source>
Specify a different install folder during compile
</div>
<syntaxhighlight lang=bash>./configure --prefix=/usr && make && sudo make install</syntaxhighlight>
4. Run the {{Code|HelloWorld}} example:<br>
OR Add /usr/local/lib to the system-wide library path
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<syntaxhighlight lang=bash>echo /usr/local/lib >> /etc/ld.so.conf && sudo ldconfig</syntaxhighlight>
<font size="3">
OR Add /usr/local/lib in your local shell every time
<source lang=bash>
<syntaxhighlight lang=bash>export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib</syntaxhighlight>


    sudo ./HelloWorld
The libraries are now installed on your machine. Next, you should set the UDev Rules.
 
</tabber>
</source>
</font>
</div>
</div>
:(The sudo is needed for USB access for now)
The {{Code|-lphidget21}} will look in the standard library location for your Linux distribution (usually {{Code|/usr/lib/}}) for the Phidget 21 library file. 
Generally, libraries to be linked on Linux through {{Code|gcc}} have a naming convention.  For example, {{Code|-lphidget21}} looks for the binary files '''{{Code|libphidget21.a}}''' and '''{{Code|libphidget21.so}}''' in the library location (usually '''{{Code|/usr/lib}}''').  These files are automatically put in the library location during the {{Code|make install}} step of [[#Installing | installing the libraries above]].
The HelloWorld program will simply print out basic information for any device you plug in, and print a message upon unplugging the device.  For example, starting the program, plugging in an Interface Kit Phidget, unplugging the Interface Kit, and pressing Enter displays:


<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
=== Setting UDev Rules ===
<font size="3">
By default, Linux will not grant permission to regular users to access physical hardware as a security feature.  This means that in order to run Phidgets code from user space you must grant yourself root privileges via sudo.  For example:
<source lang=bash>


  $ sudo ./HelloWorld  
sudo ./HelloWorld
 
  Opening...
  Press Enter to end


  Hello to Device Phidget InterfaceKit 8/8/8, Serial Number: 37299
You can grant access manually or, more commonly, set up a rules file to do it automatically keying off of the vendor code for Phidget USB devices.  To do this, create a text file called "99-libphidget22.rules" with the following contents:
  Goodbye Device Phidget InterfaceKit 8/8/8, Serial Number: 37299


  Closing...
# All current and future Phidgets - Vendor = 0x06c2, Product = 0x0030 - 0x00af
SUBSYSTEMS=="usb", ACTION=="add", ATTRS{idVendor}=="06c2", ATTRS{idProduct}=="00[3-a][0-f]", MODE="666"


</source>
Where mode 666 means every user has permission to read and write to the specified file/device.  You need to then move this file to "/etc/udev/rules.d".  Now you can run Phidget related code as a regular user without the OS denying permission. 
</font>
</div>


====Hardware====
===Verify===
The best way to verify that your libraries are working properly is to compile and run an example program.


If the out-of-the-box examples do not work, make sure the Phidget is seen by your USB interface.  To check this, you can use the kernel log reader '''{{Code|dmesg}}'''.  Pipe the output of '''{{Code|dmesg}}''' into the utility '''{{Code|tail}}''' to simply read the last ten lines of the log:


<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
First, download and unpack this C example:
<font size="3">
*[https://cdn.phidgets.com/downloads/phidget22/examples/c/Manager/Phidget22_HelloWorld_C_Ex.zip HelloWorld C example]
<source lang=bash>


    $> dmesg | tail
'''Note:''' If using the Debian intallation methods, you will need to install the '''libphidget22-dev''' package to use the C libraries for Phidget22
    ....(9 lines)....
    [24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd


</source>
Next, open the terminal at the example location. Compile the example by entering the following command:
</font>
<syntaxhighlight lang=bash>
</div>
gcc HelloWorld.c -o HelloWorld -lphidget22
</syntaxhighlight>


The number between the [ ] is the system time in seconds since the last boot up, so you can tell whether the event was recent or not.  (This will also tell you the interrupt type of Phidget that is registered by the USB interface, see the [[#Limitations | limitations section below]] for more information on what this means.)


The Phidget should both connect and disconnect properly, so unplugging it should result in an additional line at the tail:
Run the HelloWorld example:
<syntaxhighlight lang=bash>
./HelloWorld
</syntaxhighlight>


<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=bash>


    $> dmesg | tail
Your terminal should look something like this:
    ....(8 lines)....
[[File:linux_helloworld.PNG|link=|center]]
    [24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd
    [25094.809328] usb 2-1.2: USB disconnect, device number 5


</source>
</font>
</div>


If you don't see similar lines to these at the tail of your kernel log, take a look at the [[#Troubleshooting|troubleshooting]] section below, as well as the '''Communications''' section of our [[General Troubleshooting#Communications Troubleshooting|general troubleshooting page]].
The HelloWorld program will simply communicate when a Phidget has been attached or detached, as can be seen in the image above.


====Troubleshooting====


If the examples '''do not''' work but USB '''does''' work (i.e. your computer can consistently see the device in the [[#Hardware|hardware]]), take a moment to check the basics:
Your Phidget is now able to communicate with your development machine. The next step is selecting a programming language so you can start to write some code!
* No other programs, drivers, or processes are using that USB port in software
* You are running the example program as root (or your udev rules have been set properly)
* You are using libusb 0.1 (not 1.0 or later)
* You have compiled versions of libphidget21.a and libphidget21.so in your system library location (usually {{Code|/usr/lib}})
* The Phidget libraries are the latest version (visit the [[#Getting Started (Libraries and Drivers)| getting started section above]] to download them)
* Your Linux kernel version is 2.6 or later (type '''{{Code|uname -r}}''' in a terminal to get your kernel version)
* Check the [[#Limitations|limitations]] section below, some specific combinations can cause problems


If your problem doesn't seem to be fixed by the steps above, make sure that the Phidget is seen '''consistently''' by USB (if it is erratic, try our [[General Troubleshooting|general troubleshooting guide]]).  If you are still having problems after the troubleshooting guide, please [[Contact Information|ask us]]!
==Programming==
 
Ready to write some code? Select one of the programming languages below:
==Programming Languages==
 
Now that you have the basic libraries installed, you can pick your language and begin programming! 
 
If you are not using the [[#Webservice | webservice]] (discussed below) to control a Phidget over a network, your next step will be to delve into the use of your specific language.  Each page has its own set of specific libraries, code examples, and setup instructions. 
 
On Linux, we recommend the following languages:
 
*[[Language - C/C++|C/C++]]
*[[Language - Java | Java]]
*[[Language - Python | Python]]
*[[Language - C Sharp | C#]] (Using [[Language - C Sharp#Mono|Mono]])
*[[Language - Flash AS3 | Flash AS3]]
 
You can also use these languages, but they do not support [[General Phidget Programming#Event Driven Code | event driven code]], and must use [[General Phidget Programming#Logic Code | logic code]] only:
 
*[[Language - MATLAB|MATLAB]]
 
==Webservice==
 
The Phidget Webservice allows you to remotely control a Phidget over a network.<br>
Before using these webservice drivers, it may help to learn about how the [[Phidget Webservice]] works.
 
*[http://www.phidgets.com/downloads/libraries/phidgetwebservice_2.1.8.20111028.tar.gz Linux Phidgets Webservice] libraries
*The Webservice on Linux uses {{Code|avahi}}
 
===Installing the Webservice===
 
To install the webservice, you must first have the [[#Installing|Phidget libraries installed]].  Then, follow these steps:
 
#Download '''avahi''' and its development libraries (mdnsresponder/bonjour is also an option, see [[#Webservice with mDNSResponder|below]])
#*Try {{Code|apt-cache search avahi}} in a terminal to find current packages
#*Often, this is installed in a default system, you may already have it
#Unpack and install the '''Phidget Webservice''' source code tarball for Linux (download above)
#*From the unpacked Webservice source code directory, run:
#*:{{Code|./configure}}
#*:{{Code|make}}
#*:{{Code|sudo make install}}
#*This will compile the executable '''{{Code|phidgetwebservice21}}''' and place it into '''{{Code|/usr/bin/phidgetwebservice21}}'''
 
====Webservice with BSD====
 
For '''BSD''', the webservice has been found to work (BSD 8+) but requires a special configuration at the '''{{Code|./configure}}''' step:
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=bash>
./configure LIBS=/usr/lib/libphidget21.so CFLAGS=-pthread
</source>
</font>
</div>
 
Then '''{{Code|make}}''' and '''{{Code|sudo make install}}''' are the same.
<br>
The '''{{Code|LIBS}}''' argument may not be necessary, but sometimes BSD has trouble finding the library install location.  The '''{{Code|CFLAGS}}''' argument is needed because BSD needs explicit linking for using threads.
 
====Webservice with mDNSResponder====
 
To use '''mdnsresponder''' instead of avahi, change the configure script to be:
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=bash>
  ./configure --enable-zeroconf=bonjour
</source>
</font>
</div>
 
(To see all options, use '''{{Code|./configure --help}}''' like you would any configure script)
 
===Setting Up the Webservice===
 
To set up and use the webservice, it helps to have [[#Setting udev Rules|set your udev rules]].  Otherwise, you must run the webservice as root.
 
You can get command line help with '''{{Code|phidgetwebservice21}}''' by using the '''{{Code|-h}}''' option:
 
[[Image:Linux_phidget21webservice_help.png]]
 
You will see this help regardless of whether the webservice was correctly hooked in to avahi.  In fact, you will see it even if you explicitly disabled mDNS in the '''{{Code|./configure}}''' step at compile:
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=bash>
  ./configure --disable-zeroconf
</source>
</font>
</div>
 
(To see all options, use '''{{Code|./configure --help}}''' like you would any configure script)
 
Using a server name to connect would not be an option without avahi or some other mDNS service; otherwise you would have to use an IP address.  In that case, the command line is the fastest way to learn the default server name and IP address of your computer:
*For the default server name, use '''{{Code|hostname}}''' on the command line.
*For your IP address, use '''{{Code|ifconfig -a}}''' on the command line.
**A line in the return text, under your main internet connection (usually '''{{Code|eth0}}''') will say something like '''{{Code|inet addr:192.168.3.178}}''', which is your IP.
 
===Using the Webservice===
 
To use a Phidget over the webservice, you'll want to:
* Obtain code you can use to open a Phidget remotely
* Start the webservice on the computer that directly connects to the Phidget
* Run your program on the remote computer that will control the Phidget over the network
 
The easiest way to test these steps on Linux is simply to set up the webservice and run the Phidget program on the same computer.  Later, you can replace one of the two ends with a different computer and/or operating system.
 
To quickly create code to run remotely, in our examples we include commented out lines with openRemote() function calls of different types.  In the C example for your device, find the line that says:
 
'''{{Code|CPhidget_open((CPhidgetHandle) device, -1)}}'''
 
and change it to be:
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=c>
  int serial_number = 37299
  CPhidget_openRemoteIP ((CPhidgetHandle) device, serial_number, "127.0.0.1", 5001, NULL)
</source>
</font>
</div>
 
Except that you should replace '''37299''' with the serial number of your Phidget, which you can obtain from either the Phidget board itself, or from when you ran the [[#Checking|HelloWorld example code above]].  The IP address "127.0.0.1" simply loops back to the same computer, and 5001 is the default port as found from using '''{{Code|phidget21webservice -h}}''' [[#Setting Up the Webservice|as shown above]].  The NULL is used to not specify a password.
 
Save the changed example under a different filename.  In the walkthrough here, we were using the '''{{Code|InterfaceKit.c}}''' example, and renamed it to be '''{{Code|InterfaceKitRemote.c}}'''
 
Compile your new C file. In the '''{{Code|InterfaceKitRemote.c}}''' case, this would be by:
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=bash>
  gcc InterfaceKitRemote.c -o InterfaceKitRemote -lphidget21
</source>
</font>
</div>
 
1. Start two terminals to run this test, usually opened via Ctrl-Alt-T.  Your [[#Setting udev Rules|udev rules]] need to be set up or you should use sudo for every command.  First, start the webservice in Terminal #1:
 
[[Image:Linux_ws_start.png]]
 
This will broadcast any Phidget events, and receive any Phidget requests, both over the network.
 
2. Start the program that you compiled above which will open the remote Phidget.  In this case, it is '''{{Code|InterfaceKitRemote}}''':
 
[[Image:Linux_ws_step2.png]]
 
3. Now, plug in the Phidget!  The '''{{Code|phidget21webservice}}''' program captures the attach and other events and sends them out over the network (in the background in Terminal #1) and the Phidget software objected opened with openRemote in Terminal #2 receives them:
 
[[Image:Linux_ws_step3.png]]
 
4. You can confirm that the webservice was indeed behind this exchange by killing the webservice process while still allowing the remote program to run:
 
[[Image:Linux_ws_step4.png]]
 
===Debugging the Webservice===
 
In addition to enabling [[General Phidget Programming#Logging|logging]] in your Phidget code, you can get additional debugging information from the Webservice itself.  This additional debugging is enabled via a re-compile of the webservice.  From the source code directory, do:
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=bash>
  make clean
 
  ./configure --enable-debug
 
  make
 
  sudo make install
</source>
</font>
</div>
 
If you suspect multicast DNS (mDNS) may be the problem, you can:
* Try compiling the webservice with mDNSResponder, as described above in [[#Installing the Webservice|Installing the Webservice]], or
* Try compiling the webservice completely without mDNS, as described above in [[#Setting Up the Webservice|Setting Up the Webservice]]
 
==Advanced Uses==
 
===Setting udev Rules===
 
If you don't want to be using '''{{Code|sudo}}''' to run Phidget programs (including the webservice) forever, you will want to create a '''{{Code|udev}}''' rule to allow yourself access to the Phidget when you are not root.
 
Udev has an easy way to set the owner and permissions of the USB interface of the Phidget. But you need to give udev something to match in order to apply the new settings.  Here, we will tell udev to match the vendor code for Phidgets, Inc.  You can get the vendor code in hex by using '''{{Code|lsusb}}''':
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=bash>
  $> lsusb
  ....Information about other devices...
  Bus 002 Device 013: ID 06c2:0045 Phidgets Inc. (formerly GLAB) PhidgetInterface Kit 8-8-8
</source>
</font>
</div>
 
The two numbers separated by a colon are the codes for '''vendor:product'''.  Since we want to set up the rule so that all Phidgets, no matter what product, can be used without root privileges, we use the vendor code, which is '''06c2'''.
 
The rules for udev are kept in files in '''{{Code|/etc/udev/rules.d/}}''' and are traditionally grouped into order of running (10 runs before 20, 30, etc) and device type (cd, network, etc).  There should be one or more files in there already - if this is your first time editing udev rules take a look at them to see the syntax to use:
* Commas separate each pair with == or =
* One rule on each line, no line breaks
* Quotes around the value to be matched or changed
* Comments can be added on lines starting with #
 
Strictly speaking, the files run in lexical order (i.e. the order they're listed when you use '''{{Code|ls}}''').  A device can match many rules, and all will apply (if possible).  If conflicting rules are found, the first rule found is followed.
 
To make sure the Phidget udev rules are found first, we can create a file '''{{Code|10-persistent-usb.rules}}''' (all udev rule files need to end with '''{{Code|.rules}}''') and add one line to it:
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=bash>
  SUBSYSTEM=="usb", ATTRS{idVendor}=="06c2", MODE="0666", OWNER="user"
</source>
</font>
</div>
 
Make sure to replace '''{{Code|user}}''' with your user name.  You probably recognize the '''06c2''' from the vendor discussion above.  We have added the match on '''{{Code|SUBSYSTEM}}''' to search first within usb (within a possibly big database).  The '''{{Code|MODE}}''' sets read and write privileges for everyone to the device, and '''{{Code|OWNER}}''' sets the owner to be you.
 
Save the '''{{Code|10-persistent-usb.rules}}''' in '''{{Code|/etc/udev/rules.d/}}''' and then change its permissions so it can be read by all:
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=bash>
  sudo chmod a+r /etc/udev/rules.d/10-persistent-usb.rules
</source>
</font>
</div>
 
The udev rule is now set, and it just has to get read in.  The reading of the rules is goverened by a daemon, '''{{Code|udevd}}''', which you can manage via the program '''{{Code|udevadm}}'''.  The '''{{Code|udevadm}}''' man page is quite extensive for all sorts of uses of '''{{Code|udevadm}}''' while you are testing this or other udev rules.  To re-read and implement the rules without having to reset the daemon or reset the computer, you can use:
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=bash>
  sudo udevadm control --reload-rules
</source>
</font>
</div>
 
Finally, if you performed all of these steps with the Phidget plugged in to your computer, you will need to unplug and plug the Phidget back in before trying to use usb access without root privileges.
 
===Starting the Webservice at Boot===
 
If you are tired of starting the webservice on the command line all the time, you can have the webservice start when your system starts, every time.
 
====User Space====
 
If you are running a standard Linux machine with an X-server (Unity, KDE) the easiest way to do this is to have it start when your x server starts.
 
In this case, the webservice will be running in user space, so your [[#Setting udev Rules|udev rules need to be set up]] for the your user permissions to be able to access the USB ports using libusb.
 
Within the X-windowing system, there is usually some sort of '''{{Code|System &rarr; Settings/Preferences &rarr; Startup}}''' that you can choose to add programs that start when a user session starts.  On Ubuntu you can use Unity to find programs listing "startup" in their names to accomplish the same thing.  This will eventually lead you to a graphical tool like this to simply add the '''{{Code|/usr/bin/phidgetwebservice21}}''' program:
 
[[Image:linux_ws_boot.png|400px]]
 
====As A Service====
 
You would want to set the boot start of '''{{Code|phidgetwebservice21}}''' to be a service if you are running a server, or a headless machine.  It is handy any time you need the webservice to be started as a booted, respawning service with a presence in different run levels and for all users.
 
A service is essentially a program that hangs out in the background, waiting to be used by some incoming task.  When the service is needed, the service forks a program to handle that need.  Most services that run on your Linux computer already have the ability to fork themselves. 
 
The webservice, however, is just a binary on Linux - '''{{Code|phidgetwebservice21}}''' - and so we need a program that handles the forking for us.  For this, we use the '''{{Code|start-stop-daemon}}''' program to spawn a standalone process for us, or kill it, based on our service-like start, stop, and restart commands.
 
To do this, we need:
# A script that tells the boot process how to start and handle the webservice (i.e. by using '''{{Code|start-stop-daemon}}''')
# A link from that script to the boot list
# An initialization file for the script
 
First, the script.  We will walk through Debian here, both because it is such a common distribution and because it is the distribution that our [[SBC|Single Board Computer]] runs.  But '''{{Code|init}}''' is surprisingly diverse on Linux, including everything from a different boot order, to different initialization programs and structure, and even different runlevels. 
 
On Debian (including Ubuntu), the initialization script covers:
* Runlevels that the service should be present on
* Dependencies of the service
* Name of the service and other informative data
* The location of the PIDFILE, which stores the process ID (pid) for later dealing with a spawned instance
* Any configuration file locations
* What to do when the service is given instructions to '''start''', '''stop''', or '''reload'''.
 
The Debian script we use to start the webservice on the [[SBC|Single Board Computer]]:
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed; padding: 15px;">
<font size="3">
<source lang=bash>
 
#!/bin/sh
 
### BEGIN INIT INFO
# Provides:          phidgetwebservice
# Required-Start:    $network $remote_fs
# Required-Stop:    $network $remote_fs
# Should-Start:      avahi
# Should-Stop:      avahi
# Default-Start:    2 3 4 5
# Default-Stop:      0 1 6
# Short-Description: Phidget Webservice
# Description:      Phidget Webservice for controlling Phidgets over the network.
### END INIT INFO
 
DESC="Phidget Webservice"
NAME=phidgetwebservice
BIN=phidgetwebservice21
DAEMON=/usr/bin/$BIN
PIDFILE=/var/run/$NAME.pid
CFG=/etc/default/$NAME
 
# Gracefully exit if the package has been removed.
test -x $DAEMON || exit 0
 
# load config
pws_port="5001"
pws_serverid=""
pws_password=""
[ -f $CFG ] && . $CFG
 
start() {
[ -z "$pws_port" ] || OPTIONS="-p $pws_port "
[ -z "$pws_password" ] || OPTIONS="$OPTIONS-P $pws_password "
 
if [ -z "$pws_serverid" ]; then
OPTIONS="$OPTIONS -n $( hostname )"
else
OPTIONS="$OPTIONS -n $pws_serverid"
fi
echo -n "Starting $DESC: "
start-stop-daemon -S -b -q -p $PIDFILE -m -x $DAEMON -- $OPTIONS && echo "OK" || echo "ALREADY RUNNING"
}
 
stop() {
echo -n "Stopping $DESC: "
start-stop-daemon -K -q -p $PIDFILE -x $DAEMON && echo "OK" || echo "NOT RUNNING"
}
 
case "$1" in
  start)
start
;;
  stop)
stop
;;
  restart|force-reload)
stop
sleep 1
start
;;
  *)
echo "Usage: $0 {start|stop|restart}"
esac
 
exit 0
</source>
</font>
</div>
 
Save the script into a file called '''{{Code|phidgetwebservice}}''', and use '''{{Code|chmod 755}}''' to make it executable.
 
Also on Debian, startup service scripts should go in '''{{Code|/etc/init.d}}''', and then put within the appropriate runlevel-numbered folder - by symbolic link.  There is a handy tool to do this for you, called {{Code|insserv}}:
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=bash>
  sudo insserv -d phidgetwebservice
</source>
</font>
</div>
 
The {{Code|insserv}} program is the program that makes use of the {{Code|### BEGIN INIT INFO...### END INIT INFO}} that appears at the top of the {{Code|phidgetwebservice}} script.  Use {{Code|man insserv}} for more information.  The {{Code|insserv}} tool handles the mess of finding the right runlevel folders (i.e. the {{Code|rc.d}} numbered folders) and making the appropriate links. You can see what links would be updated by running {{Code|insserv}} with the {{Code|-n}} option, for a dry run.
 
'''Note:''' When you run {{Code|insserv}}, all of the dependencies for the boot order are re-written.  This means that all of the initialization scripts in {{Code|/etc/init.d}} are re-examined.  So, you'll probably get a lot of output when you run the command.
 
Then, you can check that '''{{Code|phidgetwebservice}}''' is on the service list with:
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=bash>
  service --status-all
</source>
</font>
</div>
 
And you can start it right now without rebooting like this:
 
[[Image:linux_system_service_start.png]]
 
The {{Code|service}} command has many options to start and stop services like the phidgetwebservice, try {{Code|man service}} for more information.
 
At this point, you can follow the client instructions on [[#Using the Webservice|using the webservice]] above to create a loopback test for the new webservice service that should now be running.
 
The final piece, for future configuration changes, is that the {{Code|/etc/init.d}} script looks for the file {{Code|/etc/default/phidgetwebservice}} upon starting up.  The file is expected to contain the port, server ID, and password for the server side of the webservice.  These are also set in the {{Code|phidgetwebservice}} script in {{Code|init.d}}, as you can see from reading the code above, but if you want to change them a lot, you can edit the configuration file rather than changing the {{Code|phidgetwebservice}} script and re-installing by {{Code|insserv}} every time.  The configuration file in {{Code|/etc/default/}} should contain the same syntax as that used in the script source above:
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=bash>
  pws_port="5001"
  pws_serverid=""
  pws_password=""
</source>
</font>
</div>
 
===Cross-Compiling with a Custom Toolchain===
 
This would allow you to have the Phidget libraries compiled to include in code for an embedded device.  When developing for an embedded device, you will often write code for it on your 'normal' computer, and then build the code to binary with a different target than the processor in your computer.  Many microcontrollers do not have the ability to run a full operating system, and hence cannot compile code natively. 
 
The collection of tools used to create binary code for a separate system is called a ''toolchain''.  Compiling the Phidget libraries specifically for an embedded system, and placing them into the path for writing code on top of the libraries is like adding another link in this chain.
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=bash>
  sudo apt-get install gcc-arm-linux-gnueabi
</source>
</font>
</div>
 
You can use the typical ./configure setup for custom build targets:
 
'''<code><font size=3>./configure --prefix=toolchain_location --build=this_system --host=target_system</font></code>'''
 
For the Phidget libraries, the '''{{Code|./configure}}''' tool works this way as well. For example, let's say you're building the libraries to develop code for the [[SBC|Phidget Single Board Computer (SBC)]] as a target.  Your system is a 32 bit system (i686-pc-linux-gnu) and the target system for the [[SBC]] is {{Code|arm-linux-gnueabi}}.  Download the Phidget libraries [[#Getting Started (Libraries and Drivers)|above]] and unpack them into a folder '''{{Code|phidget_libraries}}'''.  If {{Code|/usr/arm-linux-gnueabi}} is the location of your ARM toolchain (downloaded above in '''{{Code|gcc-arm-linux-gnueabi}}'''), type:
 
<div style="background-color: #f3f3f3; border-color: #1c9edb; border-width:1px; border-style: dashed;">
<font size="3">
<source lang=bash>
 
  ~/phidget_libraries $> ./configure --prefix=/usr/arm-linux-gnueabi --build=i686-pc-linux-gnu --host=arm-linux-gnueabi
 
</source>
</font>
</div>


==Common Problems and Solutions==
{{Programming_Languages_Table}}


{{ProblemSolution|Low Speed Phidgets (Max of 8):|Linux will only schedule one low-speed interrupt transfer per millisecond.}}
==Older Versions==
If you need older versions of the Phidget22 Linux libraries, [{{SERVER}}/downloads/phidget22/libraries/linux/libphidget22/ click here].


You can find out the type of your Phidget by attaching it and then running '''<code><font size=3>dmesg | tail</font></code>''', which will display the type of Phidget from your kernel logs, as described above in the [[#Hardware|hardware section]]. The practical consequence of this is if your system has many low speed Phidgets attached, they will each be throttled down.  Low speed Phidgets require an interrupt transfer as often as every 8 milliseconds.  A Linux system could only have up to 8 of these Phidgets attached.
If you need Phidget21 Linux Libraries, [{{SERVER}}/downloads/phidget21/libraries/linux/libphidget/ click here].

Latest revision as of 15:45, 9 September 2024

Getting Started with Linux

Welcome to using Phidgets with Linux!

If you are ready to go, the first step in creating Linux applications with Phidgets is installing our libraries.

Install

The first step to using Phidgets with Linux is installing the Phidget22 libraries.

Supported Distros / Archs
Debian 6 (Squeeze) i386 armel
Debian 7 (Wheezy)
Debian 8 (Jessie) armhf
Debian 9 (Stretch)
Debian 10 (Buster) amd64 arm64
Debian 11 (Bullseye)
Debian 12 (Bookworm)
Ubuntu Xenial 16.04 LTS i386 armhf
Ubuntu Bionic 18.04 LTS amd64 arm64
Ubuntu Focal 20.04 LTS
Ubuntu Jammy 22.04 LTS
Ubuntu Noble 24.04 LTS

If you're running one of the supported distros, we recommend using the Package Install. For other systems, you can use the Source Install.

Install Script

To run the install script and install phidget22, enter the following command in the terminal: 

curl -fsSL https://www.phidgets.com/downloads/setup_linux | bash -
apt-get install -y libphidget22


curl -fsSL https://www.phidgets.com/downloads/setup_linux | sudo -E bash -
sudo apt-get install -y libphidget22

Manual Install

To install our package repository manually, enter the following command in the terminal, replacing distro with your distro codename: 

wget -qO /usr/share/keyrings/phidgets.gpg \
  https://www.phidgets.com/gpgkey/pubring.gpg
echo deb [signed-by=/usr/share/keyrings/phidgets.gpg] \
  http://www.phidgets.com/debian distro main \
  > /etc/apt/sources.list.d/phidgets.list


sudo wget -qO /usr/share/keyrings/phidgets.gpg \
  https://www.phidgets.com/gpgkey/pubring.gpg
echo deb [signed-by=/usr/share/keyrings/phidgets.gpg] \
  http://www.phidgets.com/debian distro main | sudo tee \
  /etc/apt/sources.list.d/phidgets.list > /dev/null

We support Debian releases from 6 to current, and Ubuntu LTS releases from 14.04 to current. If you are using another flavour of Linux (such as Mint), which is based on Ubuntu or Debian, use the corresponding Ubuntu or Debian codename.

Update your package lists: 

apt-get update


sudo apt-get update

Finally, install the Phidget package by entering the command below: 

apt-get install libphidget22


sudo apt-get install libphidget22

Additional Packages

You may also want to apt-get install the following optional packages:

  • libphidget22-dev: The C development libraries for Phidget22
  • libphidget22extra: Extra runtime library required for the Network Server and Admin tools
  • phidget22networkserver: The Phidget Network Server, which enables use of Phidgets over your network
  • libphidget22java: The Java libraries for Phidget22
  • phidget22admin: An administrator utility for listing Phidgets and upgrading firmware
  • phidget22wwwjs: The JavaScript libraries for Phidget22. This package also installs the HTML examples which can be accessed through the web interface


The libraries are now installed on your machine. Next, set up the UDev rules below.

Source Install

To install our libraries, first install libusb-1.0 development libraries. The exact command and package name will vary depending on distribution. For Debian based distributions, including Ubuntu and Mint, the command would be: 

apt-get install libusb-1.0-0-dev


Next, download and unpack the following files:

Open the README file that is included at the top of each directory. This file will give you important information about how to properly install the files.


Libraries are installed in /usr/local/lib by default. If you run into trouble finding the libraries during linking or at runtime, this probably means that /usr/local/lib is not on the library path for your distribution.

You can handle this in a number of ways:

Specify a different install folder during compile 

./configure --prefix=/usr && make && sudo make install

OR Add /usr/local/lib to the system-wide library path 

echo /usr/local/lib >> /etc/ld.so.conf && sudo ldconfig

OR Add /usr/local/lib in your local shell every time 

export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib

The libraries are now installed on your machine. Next, you should set the UDev Rules.

Setting UDev Rules

By default, Linux will not grant permission to regular users to access physical hardware as a security feature. This means that in order to run Phidgets code from user space you must grant yourself root privileges via sudo. For example:

sudo ./HelloWorld

You can grant access manually or, more commonly, set up a rules file to do it automatically keying off of the vendor code for Phidget USB devices. To do this, create a text file called "99-libphidget22.rules" with the following contents:

  1. All current and future Phidgets - Vendor = 0x06c2, Product = 0x0030 - 0x00af

SUBSYSTEMS=="usb", ACTION=="add", ATTRS{idVendor}=="06c2", ATTRS{idProduct}=="00[3-a][0-f]", MODE="666"

Where mode 666 means every user has permission to read and write to the specified file/device. You need to then move this file to "/etc/udev/rules.d". Now you can run Phidget related code as a regular user without the OS denying permission.

Verify

The best way to verify that your libraries are working properly is to compile and run an example program.


First, download and unpack this C example:

Note: If using the Debian intallation methods, you will need to install the libphidget22-dev package to use the C libraries for Phidget22

Next, open the terminal at the example location. Compile the example by entering the following command: 

 gcc HelloWorld.c -o HelloWorld -lphidget22


Run the HelloWorld example: 

./HelloWorld


Your terminal should look something like this:

Linux helloworld.PNG


The HelloWorld program will simply communicate when a Phidget has been attached or detached, as can be seen in the image above.


Your Phidget is now able to communicate with your development machine. The next step is selecting a programming language so you can start to write some code!

Programming

Ready to write some code? Select one of the programming languages below:

Core Languages Mobile Languages Other Languages
C Sharp C# Objective C Objective C LabVIEW LabVIEW
C/C++ C/C++ Swift Swift Max/MSP Max/MSP
Python Python Android Android Java
Java Java
Visual Basic .NET Visual Basic .NET
JavaScript JavaScript

Older Versions

If you need older versions of the Phidget22 Linux libraries, click here.

If you need Phidget21 Linux Libraries, click here.

Retrieved from "https://www.phidgets.com/docs/index.php?title=OS_-_Linux&oldid=34500"