OS - Phidget SBC

On 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)

The SBC is a unique Phidget. It is a computer with a Linux operating system. It can compile code, save files, manage background jobs, host information over the web, and more.

To learn the basics about the SBC, we have a handy web interface to interact with the SBC. This is covered in detail on the Getting Started Guide for the SBC. So before reading this page on how to use the operating system, you should have done the following via the Getting Started Guide:

• Set up networking on your SBC, via either Ethernet or wireless
• Set up a password
• Learned the IP address or link local address of the SBC

Conceivably, you could simply use the SBC like any Linux computer, and do all of your development and compiling of Phidget code on the SBC itself. In practice this is quite complicated as the SBC does not have a keyboard or screen. So usually, you will want to develop your code on an external computer and copy files and settings over to the SBC via a network. This makes this Getting Started section unique, in that we show you how to set up both computers:

• Your External Development Computer, usually your main desktop or laptop which will transfer files and settings to and from the SBC
• The SBC itself, which needs programming language libraries to use Phidgets.

Getting Started - External Computer

The simplest way to transfer files and commands to and from the SBC is via a program called ssh. The ssh program provides command line text access over a network into the SBC. Using it, you can run programs and give the SBC commands. The ssh program has a companion program called scp which can copy files back and forth. For Linux users, this will be familiar territory. If you are using Windows or Mac OS, and are unfamiliar with ssh, you can think of it like the command line or a Mac terminal.

Before connecting over ssh, you will need:

• The IP address (such as 168.254.3.0) or link local address (such as phidgetsbc.local) of the SBC
• The admin password for the SBC

Both of these items can be found by following the steps in the Getting Started Guide for the SBC.

SSH on Windows

The ssh program is not installed on Windows by default. But, there are a variety of SSH programs available for free, one simple and commonly used program being [PuTTY].

With PuTTY, when you first run the program it will ask you what to connect to. Enter the IP address or link local address of the SBC, and then click the SSH radio button right below the address, which will change the port to 22. Then click open, and you'll have an ssh connection to the SBC open in a terminal. It will prompt you for a user name (root) and password (the admin password).

To copy files back and forth, there is an SCP component to PuTTY, called PSCP, which is available from the same [PuTTY download page].

SSH on Linux and Mac OS

Linux and Mac OS already have ssh installed by default. To run ssh simply open a terminal...

• Ctrl-Alt-T on Linux
• Applications → Utilities → Terminal on Mac OS

...and type:

ssh root@phidgetsbc.local

If you have re-named your SBC, include that name instead of the phidgetsbc.local link address. Or, you can use the SBC's IP address, e.g. ssh root@168.254.3.0.

To copy files back and forth, the command follows the form of: scp from to

So, to copy a file /root/data.txt from the SBC to your local machine, type:

scp root@phidgetsbc.local:/root/data.txt .

Note the use of the dot . to indicate that scp should put the file in the current local directory. If you're not sure what folder the terminal is operating in type pwd to print the working directory. Terminals usually start by default in your home folder.

Getting Started - The SBC (Debian Linux)

The SBC comes with the following Phidget functionality installed:

• The Phidget C libraries libphidget21.so

Installing C/C++

The most simple way to install C/C++ on the SBC

Installing Python

Installing Python has two steps. First, you'll need to install the basic ability to run python, and then you'll need to install the Phidget Python module.

Basic Python

apt-get install python

Install Phidget Python Method 1: Use a USB Key

Copy the | Python Libraries onto a USB key. Unpack the zip file into a folder on the USB key. Insert the key into the SBC.

Install Phidget Python Method 2: Use the Internet

Rather than using a USB key to transfer the file, the SBC can download it directly from the internet. You will need wget and unzip installed, both of which are small:

apt-get install wget
apt-get install unzip

Copy the web link address for the | Python Libraries.

In an SSH terminal to the SBC, type: wget http://www.python_library_link where instead of http://www.python_library_link you insert the link you just copied.

This will download the Phidget python libraries to the folder you ran the wget command in. Unzip the file using the command unzip.

Using SBC Linux

Now that you've set up communication with the SBC, and installed whichever programming language support you need, you're probably ready for a short tour of useful tools on the SBC's version of Linux.

First, unless you set up another user, you will be running on the SBC as root, which is the super-user. For experienced Linux users, this probably makes you nervous because you know you can overwrite important system files without the system asking for additional permission. Even as a Windows or Mac OS user - although you may usually run your computer as an administrator - the system usually prompts you to confirm before you do anything really dangerous, and this will not happen as root.

Some Useful Commands

find

The find program does what it says - it finds things.

Unfortunately for the casual user, the find program is very flexible and powerful, and thus not especially intuitive to use. But, here are some examples:

SSH Command	What it Does	Example
find folder -name file.txt	Looks for all files in a folder (/ for root - or all - folders) with a certain name (* for wildcard)	find / -name *.jpg
find folder -mtime +X	Looks for all files in a folder modified less than X days ago	find /root -mtime +30

apt

The apt program allows you to install, uninstall, upgrade, and search software available for the SBC. For a non-Linux user, the apt framework may be daunting at first, but it actually allows you to keep your system up to date

SSH Command	What it Does	Example
apt-cache search term	Looks for all programs that have term in the title or description	apt-cache search opencv
apt-get update	Gets the most recent listing of available software	apt-get update (No options)
apt-get install program	Installs program from the internet	apt-get install python

which

The program which tells you if and where a program is installed.

For example, on a default SBC, typing which python will return no results. But after successfully installing python, it will return /usr/bin/python as the location of the python program/binary/executable.

Some Useful Commands to Install

gcc

less

wget

unzip

python

Using USB Data Keys

After plugging the USB key in, it won't just appear on your desktop, so to speak, so you'll need to figure out where you can read and write to it within the SSH directory structure.

The web access program can help with this. After you plug a USB key in, it will show up under Status → System. Or, the USB key and all other attached devices can be seen at Status → USB:

In the screenshot above, you can see that the USB key is located in /media/usb0.

Alternately, you can use the SSH command mount, and the searching program grep which will filter the response of mount and only return the lines with your search term (usb):

root@phidgetsbc:~# mount | grep usb
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)

In this case, the USB key can be written to and read from using the /media/usb0 directory. Copying a file to /media/usb0 will copy a file to the USB key. The same goes for removing, renaming, opening files within your program, etc.

Note: Mount points like /media/usb0 should not be hard-coded into any of your programs. (See the Common Problems and Solutions section for more information.) If you need to obtain the mount point for a freshly mounted USB key within your code, have your code obtain the mount tables and search on the device (e.g. /dev/sda1 or /dev/sdb1) and obtain the corresponding mounted /media/usbN location, where N is a number 0-9.

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:

• C/C++
• Java
• Python

Advanced Uses

Taking Pictures With the Webcam

Probably the most straightforward way to use a webcam for pictures rather than video is to use the opencv library. You can get it by:

apt-get install opencv

The opencv libraries can also be used within Python, by installing the link between them:

apt-get install python-opencv

Then taking pictures from within code becomes quite simple. For example, in Python, taking and saving an image is four lines:

#! /usr/bin/python

import cv

# The webcam is located at /dev/video0 
# OpenCV only needs the number after video
webcam = cv.CaptureFromCAM(0)

frame = cv.QueryFrame(webcam)

cv.SaveImage("image.jpg", frame)

For the complete OpenCV documentation, see The OpenCV Reference, and specifically the section on Reading and Writing Images.

Common Problems and Solutions

USB Memory Key mounting: Sometimes USB Memory Keys mount at more than one location

When you insert a memory key, the SBC will load it as a device (e.g. /dev/sda1) and it will also mount the key for reading and writing within the /media/ directory. The /media/ directory version will be called something like usb0. At times, an inserted memory key will get mounted in more than one location. You can observe if this occurs by checking the currently mounted devices with the command mount:

root@phidgetsbc:~# mount
tmpfs on /lib/init/rw type tmpfs (rw,nosuid,mode=0755)
proc on /proc type proc (rw,noexec,nosuid,nodev)
sysfs on /sys type sysfs (rw,noexec,nosuid,nodev)
udev on /dev type tmpfs (rw,mode=0755)
tmpfs on /dev/shm type tmpfs (rw,nosuid,nodev)
devpts on /dev/pts type devpts (rw,noexec,nosuid,gid=5,mode=620)
rootfs on / type rootfs (rw)
procbususb on /proc/bus/usb type usbfs (rw)
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
/dev/sda1 on /media/usb1 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)

You will note that the same device (/dev/sda1) is now mounted at both /media/usb0 and /media/usb1. To fix this problem as it occurs, you can use umount (notice there is no letter 'n') to unmount the second instance:

root@phidgetsbc:~# umount /media/usb1

In practice, this should not be a problem, because writing to or reading from either usb0 or usb1 will have the same effect on the memory key. However, if you hard-code a media location into your program (i.e. expecting /media/usb0 to be the first USB key you insert and /media/usb1 to be the second key) your program will sometimes work and sometimes fail.

To get around this within code, find the mount point for each device as it appears. The devices, such as /dev/sda1 will always refer to the actual memory key. But, they cannot be written to directly without being mounted, so you will have to parse the mount table (what is returned from mount) within your code to find the device and its corresponding mount point.

This is a problem with the standard embedded Debian automount program, and we have no known fix.