OS - Phidget SBC: Difference between revisions

From Phidgets Support
Line 49: Line 49:


===Setting udev Rules===
===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 - it finds all devices that match a given set of rules, and applies new traits to them.  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 class="source">
<syntaxhighlight lang=bash>
$> lsusb
....Information about other devices...
Bus 002 Device 013: ID 06c2:0045 Phidgets Inc. (formerly GLAB) PhidgetInterface Kit 8-8-8
</syntaxhighlight>
</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 class="source">
<syntaxhighlight lang=bash>
SUBSYSTEM=="usb", ATTRS{idVendor}=="06c2", MODE="0666", OWNER="user"
</syntaxhighlight>
</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 class="source">
<syntaxhighlight lang=bash>
sudo chmod a+r /etc/udev/rules.d/10-persistent-usb.rules
</syntaxhighlight>
</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 class="source">
<syntaxhighlight lang=bash>
sudo udevadm control --reload-rules
</syntaxhighlight>
</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 class="source">
<syntaxhighlight 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
</syntaxhighlight>
</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 class="source">
<syntaxhighlight lang=bash>
sudo insserv -d phidgetwebservice
</syntaxhighlight>
</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 class="source">
<syntaxhighlight lang=bash>
service --status-all
</syntaxhighlight>
</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]] 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 class="source">
<syntaxhighlight lang=bash>
pws_port="5001"
pws_serverid=""
pws_password=""
</syntaxhighlight>
</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.
You can use the typical {{Code|./configure}} setup for custom build targets:
'''<font size=3><code>./configure --prefix=toolchain_location --build=this_system --host=target_system</code></font>'''
For the Phidget libraries, the {{Code|./configure}} tool works this way as well. You'd use this in the [[#Installing|install the libraries section]] setup. 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 standard Linux system (i686-pc-linux-gnu) and the target system for the [[SBC]] is {{Code|arm-linux-gnueabi}}.  For this target, you'll need the base of the GNU embedded Debian chain:
<div class="source">
<syntaxhighlight lang=bash>
sudo apt-get install gcc-arm-linux-gnueabi
</syntaxhighlight>
</div>
Then, 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 class="source">
<syntaxhighlight lang=bash>
~/phidget_libraries $> ./configure --prefix=/usr/arm-linux-gnueabi --build=i686-pc-linux-gnu --host=arm-linux-gnueabi
</syntaxhighlight>
</div>


==Common Problems and Solutions==
==Common Problems and Solutions==

Revision as of 23:14, 16 February 2012

Icon-Linux.pngOn the Single Board Computer (SBC), Phidgets can be either plugged directly into one of the USB ports or run over a network using the Webservice.

Getting Started (Libraries and Drivers)

Linux

To set up the SBC with Linux, you will need an Ethernet (i.e. wired) DHCP internet connection. If you intend to use the SBC wirelessly, you only need this wired Ethernet connection once, to set up the wireless connection.

You may have one of these at home, where you can plug the SBC right into the router. Alternatively, you might have this type of connection via the wall Ethernet at work, or at a University.

As another option, you can use a switch and plug your computer and the SBC into the switch, and enable the wired connection.

ifconfig


Troubleshooting

If the examples do not work but USB does work (i.e. your computer can consistently see the device in the hardware), take a moment to check the basics:

  • 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 /usr/lib)
  • The Phidget libraries are the latest version (visit the getting started section to download them)
  • Your Linux kernel version is 2.6 or later (type uname -r in a terminal to get your kernel version)
  • Check the common problems section below, some specific combinations can cause problems

If your problem doesn't seem to be fixed by these steps, make sure that the Phidget is seen consistently by USB (if it is erratic, try our general troubleshooting guide). If you are still having problems after the troubleshooting guide, please ask us!

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 (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:

Webservice

Advanced Uses

Setting udev Rules

Common Problems and Solutions

Low Speed Phidgets (Max of 8): Linux will only schedule one low-speed interrupt transfer per millisecond.

You can find out the type of your Phidget by attaching it and then running dmesg | tail, which will display the type of Phidget from your kernel logs, as described above in the 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.

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