OS - Phidget SBC: Difference between revisions

Latest revision as of 22:02, 17 October 2023

Quick Downloads

Already know what you're doing? Here you go:

For PhidgetSBC (1070):

For PhidgetSBC2 (1072):

For PhidgetSBC3 (1073) kernel version 3.6.3:

For PhidgetSBC3 (1073) kernel version 3.14.27:

For PhidgetSBC4 (SBC3003):

changelog
SBC4 SD Card Image | md5 (After reflashing the SD card, be sure to expand the filesystem)
SBC4 Kernel/Bootloader Upgrade Package

If you need to access older versions of the libraries, click here.

Getting Started With the Phidget SBC

Welcome to using the Phidget SBC. If you haven't already, check out the user guide in order to set up the following:

Networking
Administrator password

If you are ready to go, the first step will be deciding how you will use the SBC:

Use the SBC like any other Linux computer, simply connect a monitor and a keyboard and begin your development.
Use a more powerful external computer to develop your code, and then simply copy the files to the SBC.

If you are using an external computer, there are videos available to help you get started, here is a video for Java:

We also have videos for Python and C.

If you will not be using an external computer, jump ahead to learn about installing packages for development, otherwise, keep reading!

Developing with an External Computer

There are two main ways in which you can access your SBC from an external computer:

SBC Web Interface
Secure Shell (SSH)

The user guide covers the SBC Web Interface in detail, so we will review SSH below.

SSH

If you are unfamiliar with SSH, it is a simple yet powerful tool that allows you to log into a remote machine in order to execute commands. You can also transfer files using the associated SCP tool.

In order to use SSH, you need to know the following things about the SBC:

IP address (e.g. 192.168.3.195) or the link local address (e.g. phidgetsbc.local)
The administrator password

You must also enable SSH on the SBC. You can do this via the SBC Web Interface which is shown in the image below:

SSH on Windows

To use SSH on Windows, we recommend PuTTY. Use the images below as a guide for configuring PuTTY (use the IP address or the link local address interchangeably):

After clicking open, simply login as root and provide the administrator password:

To transfer files between your SBC and Windows machine, we recommend either of these programs:

You will follow a similar process to access the SBC as described for SSH.

SSH on Linux and macOS

SSH is available on Linux and macOS by default. To run SSH, simply open the terminal and type the following:

ssh root@phidgetsbc.local

Or, something like this (you will need to know the IP address of your SBC):

ssh root@192.168.3.195

You will then be prompted for the password in order to gain access to the SBC:

To copy a file from the SBC to your development machine using SCP, simply open the terminal and type the following:

scp root@phidgetsbc.local:/path/to/source /path/to/destination

You can reverse this if you want to transfer a file from your development machine to your SBC:

scp  /path/to/source root@phidgetsbc.local:/path/to/destination

Installing Packages for Development

At this point you have connected to the SBC through one or more these three options:

SBC Web Interface
SSH
Directly via monitor and keyboard

Now that you are connected, you may want to start developing on/for the SBC. Before you do this, you need to install some packages. Let's start with C and Java.

C and Java

The simplest way to install C and Java support on the SBC is via the install buttons on located on the SBC Web Interface (System->Packages). Check Include full Debian Package Repository before installing.

When developing for Java, ensure your development machine and your SBC have the same version of Java. Check your Java version by entering this command:

Java -version

If you need to update the version of Java on your SBC, use the following commands:

apt-get install default-jre-headless
su
update-alternatives --config java

You're now ready to begin programming! Continue through this guide for code examples and directions on where to go next.

Installing Python

Installing support for Python has three steps:

Ensure Include full Debian Package Repository is checked on the SBC Web Interface (System->Packages)
Install Python
Install Phidget Python module

You will need to run commands on the SBC to install support for Python. You can either use SSH to issue the commands, or you can connect directly to the SBC via a monitor and keyboard.

Basic Python

If you're using the SBC3 or older, in order to install Python using the repository, you need to update the apt file, since Debian 7 has been archived. Go to /etc/apt/sources.list.d/multistrap-debian.list and add the following lines:

#     DO NOT EDIT THIS FILE BY HAND -- YOUR CHANGES WILL BE OVERWRITTEN
deb http://archive.debian.org/debian wheezy main contrib non-free

Then, run the following commands:

apt-get update
apt-get install python

If you're using the Phidget SBC4 you can just apt-get install python without changing the apt file.

Next, install the Phidget Python module.

Method 1: Use the Internet

First, install wget and unzip:

apt-get install wget
apt-get install unzip

Next, copy the web link address for the Python Libraries and use it in the following command (right click to copy into a terminal):

wget http://copied_link

The Phidget Python libraries should now be downloaded in the folder you ran the previous command in. The next step is to unzip the file:

unzip filename

Finally, change directories to the unzipped folder:

cd /path/to/unzipped/folder

and install the Phidget Python libraries:

python setup.py install

You're now ready to begin programming! Continue through this guide for code examples and directions on where to go next.

Method 2: 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.

You will have to figure out where the USB key (and the Phidget Python library folder) is now located. We describe how in the general Using USB Data Keys section. Next, run the following commands (be sure to modify the usb directory number if necessary):

cd /media/usb0/
python setup.py install

You're now ready to begin programming! Continue through this guide for code examples and directions on where to go next.

Developing Applications

If you are interested in developing on an external computer, keep reading. If you are planning on developing directly on the SBC, you can jump ahead to developing directly on the SBC.

Developing with an External Computer

When developing on an external computer, you will write, compile, and test your programs on that machine. When you are ready, you will then upload your programs to the SBC to run them. To demonstrate, we will use the Hello World example for Java. Download the following on your development machine before we get started:

Next, follow these steps:

1. Place phidget22.jar on your development machine in a directory that you will use to compile your Java files.

2. Copy the HelloWorld.java file from the example package to the same directory.

3. Compile the HelloWorld.java file. If you are using a Windows machine, type the following into the command prompt:

javac -classpath .;phidget22.jar HelloWorldExample.java

If you are using a Linux or macOS machine, type the following into the terminal:

javac -classpath .:phidget22.jar HelloWorldExample.java

You should now have the following class file:

HelloWorldExample.class

4. Using the SBC Web Interface, create a new project called HelloWorld:

5. On the next screen, you will be prompted to upload your files. We will upload the Java class file, and then click the Start button:

6. You'll note that as it runs, there are two links below the Stop button:

stdout: view the program output like you would in a terminal or command prompt
stderr: view the program error output

Success! The HelloWorld example is running on your SBC. If you aren't interested in developing directly on the Phidget SBC, jump ahead to running a program automatically.

Developing Directly on the Phidget SBC

When developing directly on the SBC, you will do so in one of the following ways:

Access the terminal by connecting directly to the SBC using a keyboard and monitor.
Access the terminal by using SSH.

Regardless of how you choose to access the terminal, the process is the same. First, you will need to pick a terminal editor in order to write and edit your files. Here are some options we recommend:

nano - recommended for beginners, already installed
vi - advanced, already installed
emacs - advanced, needs to be installed

Next, follow these steps:

1. If you haven't already, connect to the SBC using SSH or a keyboard and monitor.

2. Download the Phidget Java HelloWorld Example to the SBC.

wget http://examples_link

3. Unpack the examples

unzip examples_filename

4. Compile the HelloWorldExample.java example:

javac -classpath .:/usr/share/java/phidget22.jar HelloWorldExample.java

5.Run the HelloWorldExampleprogram:

java -classpath .:/usr/share/java/phidget22.jar HelloWorldExample

Success! The HelloWorld example is running on your SBC. Now that you have a program running on your SBC, you may be interested in having it run automatically when the SBC boots, or maybe even on a schedule. Keep reading for more information.

Running a Program Automatically

After testing your program, you will likely want it to run on boot, or on a schedule, without your input.

Run on Boot

Running on boot ensures that your program will never miss an event. As long as the SBC is running, your code will be running. This section assumes you have written and compiled your program on an external computer, and have uploaded it to the SBC Web Interface. If you are not using the SBC Web Interface, jump ahead to using a boot script.

To have your program run on boot, navigate to Projects->ProjectName->Startup Settings in the SBC Web Interface. After selecting your project, copy the settings from the image below:

We will review some of the options that are shown in the image above:

Startup Order: lower numbers boot first. Booting later means more programs are available for use, booting earlier means other programs can use your program.
Run as a daemon: starts the program as a daemon. Unless you have explicitly written your program as a daemon, leave this checked, or else your SBC may hang on boot.
Executable/Class name: your main Java class or C file.
Arguments: any command line arguments the program needs.

After saving your changes, your program will run automatically whenever your SBC boots.

Automatically Running Python Code

To run a Python script as a standalone application, you will need to add a line called a "shebang" to the top of the script, with the path to your Python executable. If you have followed the steps in this guide, the line will be:

#!/usr/bin/python

Run on a Schedule

Running your program on a schedule allows you to perform your task once a week, or once a minute without worrying about memory management issues or instability problems that may arise. It executes, and then gets cleaned up. To run your program on a schedule, we recommend using Cron. Cron can automatically schedule programs (known as jobs, or cron jobs). Cron simply reads a crontab file and runs whatever programs are listed, with whatever timing they are listed with. Cron runs continuously in the background, but the cron jobs only run as long as they naturally would, and then they exit.

Let`s set up your first cron job. We will use nano to edit the crontab file, but feel free to use whatever editor you prefer.

First, set your editor to nano:

export EDITOR=nano

Next, edit your crontab file:

crontab -e

Finally, schedule your cron job:

#cron job that will run at 5AM every week:
0 5 * * 1 /root/code/myprogram argument1

After entering your task, simply save and exit the file.

Run Using a Boot Script

If you want your program to run on boot, you can install your program into the boot order using a script. This process is covered here.

Programming

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

Phidget Network Server

The Phidget Network Server is an extremely useful feature of Phidgets that allows you to remotely control Phidgets over your network. If you haven't already, check out the Phidget Network Server page for a complete overview.

Try it Out!

The Phidget SBC comes with the Phidget Network Server installed, and the SBC automatically starts the Network Server on boot. In order to change any of this default behaviour, navigate to Phidgets->phidget22NetworkServer using the SBC Web Interface:

In order to try the Phidget Network Server out, you will need a host computer, and a client computer:

Host computer: the computer that is physically connected to the Phidgets via USB and is running the Phidget Network Server.
Client computer: a computer running a Phidgets application that accesses Phidgets connected to the host computer.

For this example, we will use the Phidget SBC as the host computer. The next step is setting up your client computer. If you are using a Windows computer as your client, keep reading, otherwise, you can jump ahead here:

macOS Client
Linux Client

Windows Client

In order to remotely access Phidgets on your SBC, you should get your client computer set up. Follow the Getting Started guide for Windows below before continuing:

Getting started with Windows

Now that you have Phidget drivers and libraries installed on your client computer, we can test the Phidget Network Server by following the steps below:

1. Open the Phidget Control Panel on your client computer. You will see something like this:

2. You now have access to the Phidgets that are connected to your Phidget SBC. Try double-clicking one of them to bring up an example.

macOS Client

In order to remotely access Phidgets on your SBC, you should get your client computer set up. Follow the Getting Started guide for macOS below before continuing:

Getting started with macOS

Now that you have Phidget drivers and libraries installed on your client computer, we can test the Phidget Network Server by following the steps below:

1. Open the Phidget Control Panel on your client computer. You will see something like this:

2. You now have access to the Phidgets that are connected to your Phidget SBC. Try double-clicking one of them to bring up an example.

Linux Client

In order to remotely access Phidgets on your SBC, you should get your client computer set up. Follow the Getting Started guide for Linux below before continuing:

Getting started with Linux

Now that you have Phidget drivers and libraries installed on your client computer, we can test the Phidget Network Server by following the steps below:

1. From the terminal, type in the following command:

 phidget22admin -s

You will now see something like this:

As shown in the image above, the server running on your SBC can now be seen over the network. You will now be able to remotely access any Phidgets connected to your SBC.

What's Next?

Now that you have seen the Network Server in action, you may be interested in implementing an application that takes advantage of all it's features. Luckily, every programming language we support comes with example code on how to do this! Jump to programming languages above.

Advanced Information

Writing Image to SD Card

If you would like to reflash your micro SD card, your first step will be to download the SBC4 SD Card Image. After downloading, unzip to get the .img file.

The next step is to flash your card. We recommend Etcher for flashing - this supports Windows, macOS, and Linux. It's also possible to flash from the command line on macOS and Linux, but this is not recommended as it does not verify the image (See Command Line).

Download and run Etcher. Plug in the MicroSD card using a card reader. Etcher will probably pick up the card automatically - otherwise, chose the card. Select the .img file using the select image button. :

Next, press the Flash! button. After writing and verifying, you will see:

The next step is to plug the SD card back into the SBC and expand the file system. Jump ahead to expanding your file system.

Command Line

NOTE: Flashing from command line is not recommended. Please consider using Etcher on Windows, macOS or Linux.

macOS

You should have already completed the first step, which is downloading the SD card image:

Next, make sure your SD card is plugged in, and enter the following into your terminal:

diskutil list

This will list all of the devices currently mounted on your system:

After verifying which device is your SD card, unmount it using the following command:

diskutil unmountDisk /dev/diskX

Warning: Ensure you are writing to the correct disk

Next, we can write the image file to the SD card:

if= path to your image file
of = where to write output (note using rdisk instead of disk will result in faster write times)

After writing, you are almost done. The next step is to plug the SD card back into the SBC and expand the file system. Jump ahead to expanding your file system.

Linux

You should have already completed the first step, which is downloading the SD card image:

Next, make sure your SD card is plugged in, and enter the following into your terminal:

dh -f

This will list all of the devices currently mounted on your system:

After verifying which device is your SD card, unmount it using the following command:

umount /dev/sdXX

Next, we can write the image file to the SD card:

if= path to your image file
of = where to write output (note: do not include partition number)

Warning: Ensure you are writing to the correct disk

After writing, you are almost done. The next step is to plug the SD card back into the SBC and expand the file system.

Expanding your File System

Note: PhidgetSBC4 SD card image version 3.0.0+ automatically expands the filesystem on first boot. For older SD card images, continue reading.

After writing the image file to your SD card, you will need to expand the file system size in order to take advantage of the full capacity of your card. In order to do this, you must run the expandfs.sh script which can be accessed at the / directory as shown here:

Note: if you plan on using SSH in order to run this script, you will need to enable SSH first (as it is turned off by default). Enabling SSH was covered above in the SSH section.

Next, simply run the script:

The SBC will automatically reboot, and your file system will be expanded. You can confirm that it has expanded by checking the file system size report.

Checking System Logs

The SBC maintains two logs: a kernel log and a system log.

The kernel log is for low-level occurrences, such as devices attaching and leaving the USB hub, recording what drivers are being used, and so on.

The system log (syslog) is for normal chatter from the operating system. Any program with the right permissions can use it (though you need to know the method to write to it, information all around the Internet can help) and it contains everything from the Ethernet going up and down, to webserver requests, and so on. If you don't run many programs or services on the SBC, the syslog will essentially be a mirror of the kernel log, because the kernel is the only thing talking.

You can check these logs by using the web interface in the System → Logs tab.

Or you can perform more powerful filtering and displaying via an SSH terminal. For example, dmesg is the command to display the kernel log, and tail prints the last ten lines of input. So, if you are trying to see if you can get a device to be detected on USB, you can run dmesg | tail to print the latest ten lines of kernel log data.

The actual locations of the log files (for filtering and reading) are:

/var/log/syslog
/var/log/dmesg

But don't edit them directly! Always follow the advice and procedures around the Internet on how to properly log items to syslog.

Personal tools

Views

More

Tools

OS - Phidget SBC: Difference between revisions

Latest revision as of 22:02, 17 October 2023

Contents

Quick Downloads

Getting Started With the Phidget SBC

Developing with an External Computer

SSH

Installing Packages for Development

C and Java

Installing Python

Developing Applications

Developing with an External Computer

Developing Directly on the Phidget SBC

Running a Program Automatically

Run on Boot

Run on a Schedule

Run Using a Boot Script

Programming

Phidget Network Server

Try it Out!

Windows Client

macOS Client

Linux Client

What's Next?

Advanced Information

Writing Image to SD Card

Command Line

Expanding your File System

Checking System Logs

Navigation menu

@@ Line 1: / Line 1: @@
+<metadesc>Communicate with sensors, controllers and relays with the PhidgetSBC! It uses Debian Linux and can run autonomous programs in C, Java, and Python.</metadesc>
 [[Category:OS]]
-[[File:icon-Linux.png|64x64px|link=OS - Linux]]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 | Webservice]].
 __TOC__
-==Getting Started (Libraries and Drivers)==
+==Quick Downloads==
+Already know what you're doing? Here you go:
-Linux has complete support for all Phidgets and their software APIs; the only thing it lacks when compared to Windows and Mac OSX is a graphical user interface.  We walk you through all steps for download,  installation, checking, and starting to write code below.
+'''For PhidgetSBC (1070):'''
+*[{{SERVER}}/downloads/phidgetsbc/1070/changelog.txt changelog]
+*[https://cdn.phidgets.com/downloads/phidgetsbc/1070/phidgetsbc-minimal.bin Minimal Firmware]
+*[https://cdn.phidgets.com/downloads/phidgetsbc/1070/phidgetsbc-full.bin Full Firmware]
+*[https://cdn.phidgets.com/downloads/phidgetsbc/1070/buildroot-phidgetsbc.tar.gz Buildroot/Kernel Sources]
+'''For PhidgetSBC2 (1072):'''
+*[{{SERVER}}/downloads/phidgetsbc/1072/changelog.txt changelog]
+*[https://cdn.phidgets.com/downloads/phidgetsbc/1072/phidgetsbc2.bin SBC2 Firmware]
+*[https://cdn.phidgets.com/downloads/phidgetsbc/1072/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package]
+'''For PhidgetSBC3 (1073) kernel version 3.6.3:'''
+*[{{SERVER}}/downloads/phidgetsbc/1073/changelog.txt changelog]
+*[https://cdn.phidgets.com/downloads/phidgetsbc/1073/linux-3.6.3/phidgetsbc3.bin SBC3 Firmware]
+*[https://cdn.phidgets.com/downloads/phidgetsbc/1073/linux-3.6.3/phidgetsbc3-kerneldev.tar.gz SBC3 Kernel Development Package]
+*[https://cdn.phidgets.com/downloads/phidgetsbc/1073/linux-3.6.3/phidgetsbc3-upgrade_3.6.3_3.14.27.tar.gz SBC3 Kernel upgrade package (3.6.3 -> 3.14.27)]
+'''For PhidgetSBC3 (1073) kernel version 3.14.27:'''
+*[{{SERVER}}/downloads/phidgetsbc/1073/changelog.txt changelog]
+*[https://cdn.phidgets.com/downloads/phidgetsbc/1073/linux-3.14.27/phidgetsbc3.bin SBC3 Firmware]
+*[https://cdn.phidgets.com/downloads/phidgetsbc/1073/linux-3.14.27/phidgetsbc3-update_3.14.27.tar.gz SBC3 Kernel update package (3.14.27)]
+*[https://cdn.phidgets.com/downloads/phidgetsbc/1073/linux-3.14.27/phidgetsbc3-kerneldev.tar.gz SBC3 Kernel Development Package]
+'''For PhidgetSBC4 (SBC3003):'''
+*[{{SERVER}}/downloads/phidgetsbc/SBC3003/changelog.txt changelog]
+*[https://cdn.phidgets.com/downloads/phidgetsbc/SBC3003/phidgetsbc4.zip SBC4 SD Card Image] | [https://cdn.phidgets.com/downloads/phidgetsbc/SBC3003/phidgetsbc4.md5 md5] (After reflashing the SD card, be sure to [[#Expanding_your_File_System|expand the filesystem]])
+*[https://cdn.phidgets.com/downloads/phidgetsbc/SBC3003/SBC3003_upgrade.tar.gz SBC4 Kernel/Bootloader Upgrade Package]
-If you are already a pro, and just want the downloads:
+If you need to access older versions of the libraries, [https://www.phidgets.com/downloads/phidgetsbc/ click here].
-*[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===
+==Getting Started With the Phidget SBC==
+Welcome to using the Phidget SBC. If you haven't already, check out the [[SBC3003 User Guide#Getting Started | user guide]] in order to set up the following:
+* Networking
+* Administrator password
-To install the libraries, follow these steps:
-#Download '''libusb-0.1''' and its development libraries
+If you are ready to go, the first step will be deciding how you will use the SBC:
-#*Try {{Code|apt-cache search libusb}} in a terminal to find current packages
+*Use the SBC like any other Linux computer, simply connect a monitor and a keyboard and begin your development.
-#*Or install [http://www.libusb.org/ from source], which includes the libusb development libraries by default
+*Use a more powerful external computer to develop your code, and then simply copy the files to the SBC.
-#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 these libraries are written in C, the additional libraries for Python, Java, and most other Phidget-supported languages depend on them.
-===Checking===
+If you are using an external computer, there are videos available to help you get started, here is a video for Java:
-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.
+<center>{{#ev:youtube|gZmWvWXICIA|||||rel=0}}</center>
+We also have videos for [https://www.youtube.com/watch?v=OhFbGzalBFw Python] and [https://www.youtube.com/watch?v=2hTlVexctqY C].
-====Software====
-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].
+If you will not be using an external computer, jump ahead to learn about [[#Installing packages for development|installing packages for development]], otherwise, keep reading!
-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.
+===Developing with an External Computer===
+There are two main ways in which you can access your SBC from an external computer:
+*SBC Web Interface
+*Secure Shell (SSH)
-To compile and run the basic C example for checking your installation:
+The [[SBC3003 User Guide#Getting Started | user guide]] covers the SBC Web Interface in detail, so we will review SSH below.
-. Unpack the [http://www.phidgets.com/downloads/examples/phidget21-c-examples_2.1.8.20111028.tar.gz Phidget Generic C Examples]<br>
+====SSH====
-. Open a terminal (often Ctrl-Alt-T) and go to the directory where the examples are unpacked<br>
+If you are unfamiliar with SSH, it is a simple yet powerful tool that allows you to log into a remote machine in order to execute commands. You can also transfer files using the associated SCP tool.
-. Compile the {{Code|HelloWorld.c}} example:<br>
-<div class="source">
-<syntaxhighlight lang=bash>
- gcc HelloWorld.c -o HelloWorld -lphidget21
+In order to use SSH, you need to know the following things about the SBC:
+*IP address (e.g. 192.168.3.195) or the link local address (e.g. phidgetsbc.local)
+*The administrator password
-</syntaxhighlight>
+You must also enable SSH on the SBC. You can do this via the SBC Web Interface which is shown in the image below:
-</div>
+[[File:phidgetsbc_enableSSH.PNG|link=|alt=|center]]
-. Run the {{Code|HelloWorld}} example:<br>
-<div class="source">
-<syntaxhighlight lang=bash>
- sudo ./HelloWorld
+{{hiddenh5|SSH on Windows}}
+To use SSH on Windows, we recommend [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY]. Use the images below as a guide for configuring PuTTY (use the IP address or the link local address interchangeably):
+[[File:Windows_PuttyIP.PNG|link=|alt=|left|425x411px|class=notpageimage]]
+[[File:Windows_PuttyLL.PNG|link=|alt=|425x411px|class=notpageimage]]
-</syntaxhighlight>
-</div>
-(The sudo is needed for USB access for now, see the [[#Setting udev Rules|Setting udev Rules]] section for how to change this)
-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.  These files are automatically put in the library location during the {{Code|make install}} step of [[#Installing | installing the libraries]].
+After clicking open, simply login as root and provide the administrator password:
+[[File:Windows_PuttyLogin.PNG|link=|alt=|center|class=notpageimage]]
-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 class="source">
+To transfer files between your SBC and Windows machine, we recommend either of these programs:
-<syntaxhighlight lang=bash>
+* [https://winscp.net/eng/download.php WinSCP]
+* [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY PSCP]
- $ sudo ./HelloWorld
+You will follow a similar process to access the SBC as described for SSH.
- Opening...
- Press Enter to end
- Hello to Device Phidget InterfaceKit 8/8/8, Serial Number: 37299
- Goodbye Device Phidget InterfaceKit 8/8/8, Serial Number: 37299
- Closing...
+{{hiddenh5|SSH on Linux and macOS}}
+SSH is available on Linux and macOS by default. To run SSH, simply open the terminal and type the following:
+<syntaxhighlight lang=bash>
+ssh root@phidgetsbc.local
+</syntaxhighlight>
+Or, something like this (you will need to know the IP address of your SBC):
+<syntaxhighlight lang=bash>
+ssh root@192.168.3.195
 </syntaxhighlight>
-</div>
-====Hardware====
+You will then be prompted for the password in order to gain access to the SBC:
+[[File:macOS_SSH.png|link=|alt=|center]]
-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 read the last ten lines of the log:
-<div class="source">
+To copy a file from the SBC to your development machine using SCP, simply open the terminal and type the following:
 <syntaxhighlight lang=bash>
+scp root@phidgetsbc.local:/path/to/source /path/to/destination
- $> dmesg | tail
- ....(9 lines)....
- [24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd
 </syntaxhighlight>
-</div>
+You can reverse this if you want to transfer a file from your development machine to your SBC:
-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 [[#Common Problems and Solutions | common problems 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:
-<div class="source">
 <syntaxhighlight lang=bash>
+scp  /path/to/source root@phidgetsbc.local:/path/to/destination
+</syntaxhighlight>
- $> dmesg | tail
+===Installing Packages for Development===
- ....(8 lines)....
+At this point you have connected to the SBC through one or more these three options:
- [24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd
+*SBC Web Interface
- [25094.809328] usb 2-1.2: USB disconnect, device number 5
+*SSH
+*Directly via monitor and keyboard
-</syntaxhighlight>
+Now that you are connected, you may want to start developing on/for the SBC. Before you do this, you need to install some packages. Let's start with C and Java.
-</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]].
+====C and Java====
+The simplest way to install C and Java support on the SBC is via the install buttons on located on the SBC Web Interface (System->Packages). Check ''Include full Debian Package Repository'' before installing.
-====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:
+[[File:phidgetsbc_installpackages.PNG|link=|alt=|center]]
-* 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]] 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 [[#Common Problems and Solutions|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|general troubleshooting guide]]).  If you are still having problems after the troubleshooting guide, please [[Contact Information|ask us]]!
+When developing for Java, ensure your development machine and your SBC have the same version of Java. Check your Java version by entering this command:
+<syntaxhighlight lang=bash>
+Java -version
+</syntaxhighlight>
-==Programming Languages==
+If you need to update the version of Java on your SBC, use the following commands:
+<syntaxhighlight lang=bash>
+apt-get install default-jre-headless
+su
+update-alternatives --config java
+</syntaxhighlight>
-Now that you have the basic libraries installed, you can pick your language and begin programming!
+You're now ready to begin programming! Continue through this guide for code examples and directions on where to go next.
-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.
+====Installing Python====
+Installing support for Python has three steps:
+#Ensure ''Include full Debian Package Repository'' is checked on the SBC Web Interface (System->Packages)
+#Install Python
+#Install Phidget Python module
-On Linux, we recommend the following languages:
+You will need to run commands on the SBC to install support for Python. You can either use SSH to issue the commands, or you can connect directly to the SBC via a monitor and keyboard.
-*[[Language - C/C++|C/C++]]
+{{hiddenh5|Basic Python}}
-*[[Language - Java | Java]]
+If you're using the SBC3 or older, in order to install Python using the repository, you need to update the apt file, since Debian 7 has been archived. Go to {{Code|/etc/apt/sources.list.d/multistrap-debian.list}} and add the following lines:
-*[[Language - Python | Python]]
-*[[Language - Ruby | Ruby]]
-*[[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:
+<syntaxhighlight lang=bash>
+#     DO NOT EDIT THIS FILE BY HAND -- YOUR CHANGES WILL BE OVERWRITTEN
+deb http://archive.debian.org/debian wheezy main contrib non-free
+</syntaxhighlight>
-*[[Language - MATLAB|MATLAB]]
+Then, run the following commands:
-==Webservice==
+<syntaxhighlight lang=bash>
+apt-get update
+apt-get install python
+</syntaxhighlight>
-The Phidget Webservice allows you to remotely control a Phidget over a network.<br>This section helps you install, check, and use the Webservice on Linux, but we also have an overview of the [[Phidget Webservice]] in general.
+If you're using the Phidget SBC4 you can just {{Code|apt-get install python}} without changing the apt file.
-===Installing the Webservice===
+Next, install the Phidget Python module.
-To install the webservice, you must first have the [[#Installing|Phidget libraries installed]].  Then, follow these steps:
+{{hiddenh5|Method 1: Use the Internet}}
+First, install wget and unzip:
+<syntaxhighlight lang=bash>
+apt-get install wget
+apt-get install unzip
+</syntaxhighlight>
-#Download '''avahi''' and its development libraries (mdnsresponder/bonjour is also an option, see the [[#Webservice with mDNSResponder|webservice with mDNSResponder]] section)
+Next, copy the web link address for the [https://cdn.phidgets.com/downloads/phidget22/libraries/any/Phidget22Python.zip Python Libraries] and use it in the following command (right click to copy into a terminal):
-#*Try {{Code|apt-cache search avahi}} in a terminal to find current packages
+<syntaxhighlight lang=bash>
-#*Often, this is installed in a default system, you may already have it
+wget http://copied_link
-#Unpack and install the [http://www.phidgets.com/downloads/libraries/phidgetwebservice_2.1.8.20111028.tar.gz Phidgets Webservice] source code tarball for Linux
+</syntaxhighlight>
-#*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====
+The Phidget Python libraries should now be downloaded in the folder you ran the previous command in. The next step is to unzip the file:
+<syntaxhighlight lang=bash>
+unzip filename
+</syntaxhighlight>
-For '''BSD''', the webservice has been found to work (BSD 8+) but requires a special configuration at the {{Code|./configure}} step:
+Finally, change directories to the unzipped folder:
+<syntaxhighlight lang=bash>
-<div class="source">
+cd /path/to/unzipped/folder
+</syntaxhighlight>
+and install the Phidget Python libraries:
 <syntaxhighlight lang=bash>
- ./configure LIBS=/usr/lib/libphidget21.so CFLAGS=-pthread
+python setup.py install
 </syntaxhighlight>
-</div>
-Then {{Code|make}} and {{Code|sudo make install}} are the same.
+You're now ready to begin programming! Continue through this guide for code examples and directions on where to go next.
-<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====
+{{hiddenh5|Method 2: Use a USB Key}}
-To use '''mdnsresponder''' instead of avahi, change the configure script to be:
+Copy the [https://cdn.phidgets.com/downloads/phidget22/libraries/any/Phidget22Python.zip Python Libraries] onto a USB key.  Unpack the zip file into a folder on the USB key.  Insert the key into the SBC.
-<div class="source">
+You will have to figure out where the USB key (and the Phidget Python library folder) is now located.  We describe how in the general [[#Using USB Data Keys | Using USB Data Keys]] section. Next, run the following commands (be sure to modify the usb directory number if necessary):
 <syntaxhighlight lang=bash>
- ./configure --enable-zeroconf=bonjour
+cd /media/usb0/
+python setup.py install
 </syntaxhighlight>
-</div>
-(To see all options, use {{Code|./configure --help}} like you would any configure script)
+You're now ready to begin programming! Continue through this guide for code examples and directions on where to go next.
+==Developing Applications==
+If you are interested in developing on an external computer, keep reading. If you are planning on developing directly on the SBC, you can jump ahead to [[#Developing directly on the Phidget SBC | developing directly on the SBC]].
-===Setting Up the Webservice===
+===Developing with an External Computer===
+When developing on an external computer, you will write, compile, and test your programs on that machine. When you are ready, you will then upload your programs to the SBC to run them. To demonstrate, we will use the Hello World example for Java. Download the following on your development machine before we get started:
+*[https://cdn.phidgets.com/downloads/phidget22/examples/java/Manager/Phidget22_HelloWorld_Java_Ex.zip Java HelloWorld Example]
+*[https://cdn.phidgets.com/downloads/phidget22/libraries/any/Phidget22Java.zip phidget22.jar]
-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:
+Next, follow these steps:
-<div class="source">
+. Place phidget22.jar on your development machine in a directory that you will use to compile your Java files.
-<syntaxhighlight lang=bash>
-$ phidgetwebservice21 -h
-</syntaxhighlight>
-<syntaxhighlight lang=text>
+. Copy the HelloWorld.java file from the example package to the same directory.
-'phidgetwebservice21' is a Phidget and Dictionary server from Phidgets Inc. See www.phidgets.com for more information.
-Usage: phidgetwebservice21 [OPTION]
-All parameters are optional. The default parameters are: port=5001, ServerName=(Computer Name) and no password
-Options:
+. Compile the HelloWorld.java file. If you are using a Windows machine, type the following into the command prompt:
-  -p      Port
+<syntaxhighlight lang=bash>
-  -n      Server Name
+javac -classpath .;phidget22.jar HelloWorldExample.java
-  -P      Password
-  -v      Debug mode
-  -h      Display this help
 </syntaxhighlight>
-</div>
+If you are using a Linux or macOS machine, type the following into the terminal:
-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 class="source">
 <syntaxhighlight lang=bash>
-  ./configure --disable-zeroconf
+javac -classpath .:phidget22.jar HelloWorldExample.java
 </syntaxhighlight>
-</div>
-(To see all options, use {{Code|./configure --help}} like you would any configure script)
+You should now have the following class file:
+*HelloWorldExample.class
-To find the defaults used by {{Code|phidget21webservice}}, 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 a server name to connect would not be an option without avahi or some other mDNS service; in this case you would only have the option to use an IP address.
+. Using the SBC Web Interface, create a new project called HelloWorld:
-===Using the Webservice===
-To use a Phidget over the webservice, you'll want to:
+[[File:Phidgetsbc_createproject.PNG|link=|alt=|center]]
-* 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, using the loopback interface.  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:
+. On the next screen, you will be prompted to upload your files. We will upload the Java class file, and then click the Start button:
-{{Code|CPhidget_open((CPhidgetHandle) device, -1)}}
-and change it to be:
+[[File:Phidgetsbc_runprogram.PNG|link=|alt=|center]]
-<div class="source">
-<syntaxhighlight lang=bash>
- int serial_number = 37299
- CPhidget_openRemoteIP ((CPhidgetHandle) device, serial_number, "127.0.0.1", 5001, NULL)
-</syntaxhighlight>
-</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 [[#Checking|ran the HelloWorld example code]].  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}} in [[#Setting Up the Webservice|the Setting Up the Webservice]] section.  The NULL is used to not specify a password.
+. You'll note that as it runs, there are two links below the Stop button:
+*stdout: view the program output like you would in a terminal or command prompt
+*stderr: view the program error output
-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 our {{Code|InterfaceKitRemote.c}} case, this would be by:
+Success! The HelloWorld example is running on your SBC. If you aren't interested in developing directly on the Phidget SBC, jump ahead to [[#Running a program automatically|running a program automatically]].
-<div class="source">
+===Developing Directly on the Phidget SBC===
-<syntaxhighlight lang=bash>
+When developing directly on the SBC, you will do so in one of the following ways:
- gcc InterfaceKitRemote.c -o InterfaceKitRemote -lphidget21
+*Access the terminal by connecting directly to the SBC using a keyboard and monitor.
-</syntaxhighlight>
+*Access the terminal by using SSH.
-</div>
-. 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:
+Regardless of how you choose to access the terminal, the process is the same. First, you will need to pick a terminal editor in order to write and edit your files. Here are some options we recommend:
+*nano - ''recommended for beginners, already installed''
+*vi  - ''advanced, already installed''
+*emacs - ''advanced, needs to be installed''
-[[Image:Linux_ws_start.png]]
-This will broadcast any Phidget events, and receive any Phidget requests, both over the network.
+Next, follow these steps:
-. Start the InterfaceKitRemote program that you just compiled which will open the remote Phidget.  In this case, it is {{Code|InterfaceKitRemote}}:
+. If you haven't already, connect to the SBC using SSH or a keyboard and monitor.
-[[Image:Linux_ws_step2.png]]
+. Download the [https://cdn.phidgets.com/downloads/phidget22/examples/java/Manager/Phidget22_HelloWorld_Java_Ex.zip Phidget Java HelloWorld Example] to the SBC.
+<syntaxhighlight lang=bash>
+wget http://examples_link
+</syntaxhighlight>
-. 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:
+. Unpack the examples
+<syntaxhighlight lang=bash>
+unzip examples_filename
+</syntaxhighlight>
-[[Image:Linux_ws_step3.png]]
+. Compile the HelloWorldExample.java example:
+<syntaxhighlight lang=bash>
+javac -classpath .:/usr/share/java/phidget22.jar HelloWorldExample.java
+</syntaxhighlight>
-. You can confirm that the webservice was indeed behind this exchange by killing the webservice process while still allowing the remote program to run:
+.Run the HelloWorldExampleprogram:
+<syntaxhighlight lang=bash>
+java -classpath .:/usr/share/java/phidget22.jar HelloWorldExample
+</syntaxhighlight>
-[[Image:Linux_ws_step4.png]]
+Success! The HelloWorld example is running on your SBC. Now that you have a program running on your SBC, you may be interested in having it run automatically when the SBC boots, or maybe even on a schedule. Keep reading for more information.
-===Debugging the Webservice===
+===Running a Program Automatically===
+After testing your program, you will likely want it to run on boot, or on a schedule, without your input.
-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 webservice source code directory, do:
+====Run on Boot====
+Running on boot ensures that your program will never miss an event. As long as the SBC is running, your code will be running. This section assumes you have written and compiled your program on an external computer, and have uploaded it to the SBC Web Interface. If you are not using the SBC Web Interface, jump ahead to [[#Via a Boot Script|using a boot script]].
-<div class="source">
-<syntaxhighlight lang=bash>
- make clean
- ./configure --enable-debug
+To have your program run on boot, navigate to Projects->ProjectName->Startup Settings in the SBC Web Interface. After selecting your project, copy the settings from the image below:
- make
- sudo make install
+[[File:phidgetsbc_runonboot.PNG|link=|alt=|center]]
-</syntaxhighlight>
-</div>
-If you suspect multicast DNS (mDNS) may be the problem, you can:
-* Try compiling the webservice with mDNSResponder, as described in [[#Installing the Webservice|Installing the Webservice]], or
-* Try compiling the webservice completely without mDNS, as described in [[#Setting Up the Webservice|Setting Up the Webservice]]
-==Advanced Uses==
+We will review some of the options that are shown in the image above:
+*Startup Order: lower numbers boot first. Booting later means more programs are available for use, booting earlier means other programs can use your program.
+*Run as a daemon: starts the program as a daemon. Unless you have explicitly written your program as a daemon, leave this checked, or else your SBC may hang on boot.
+*Executable/Class name: your main Java class or C file.
+*Arguments: any command line arguments the program needs.
-===Setting udev Rules===
+After saving your changes, your program will run automatically whenever your SBC boots.
-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.
+{{hiddenh5|Automatically Running Python Code}}
-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}}:
+To run a Python script as a standalone application, you will need to add a line called a "shebang" to the top of the script, with the path to your Python executable. If you have followed the steps in this guide, the line will be:
-<div class="source">
+<syntaxhighlight lang=python>
-<syntaxhighlight lang=bash>
+#!/usr/bin/python
- $> 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'''.
+====Run on a Schedule====
+Running your program on a schedule allows you to perform your task once a week, or once a minute without worrying about memory management issues or instability problems that may arise. It executes, and then gets cleaned up. To run your program on a schedule, we recommend using Cron. Cron can automatically schedule programs (known as ''jobs'', or ''cron jobs''). Cron simply reads a ''crontab file'' and runs whatever programs are listed, with whatever timing they are listed with. Cron runs continuously in the background, but the cron jobs only run as long as they naturally would, and then they exit.
-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.
+Let`s set up your first cron job. We will use nano to edit the crontab file, but feel free to use whatever editor you prefer.
-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">
+First, set your editor to nano:
 <syntaxhighlight lang=bash>
- SUBSYSTEM=="usb", ATTRS{idVendor}=="06c2", MODE="0666", OWNER="user"
+export EDITOR=nano
 </syntaxhighlight>
-</div>
+Next, edit your crontab file:
-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
+crontab -e
 </syntaxhighlight>
-</div>
+Finally, schedule your cron job:
+<syntaxhighlight lang=text>
-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:
+#cron job that will run at 5AM every week:
+5 * * 1 /root/code/myprogram argument1
-<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.
+[[File:phidgetsbc_cronjob.PNG|link=|alt=|center]]
-===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.
+After entering your task, simply save and exit the file.
-====User Space====
+====Run Using a Boot Script====
+If you want your program to run on boot, you can install your program into the boot order using a script. This process is covered [[OS - Linux#As A Service|here]].
-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.
+===Programming===
+Ready to write some code? Select one of the programming languages below:
+*[[Language - C|C]]
+*[[Language - Java | Java]]
+*[[Language - Python | Python]]
+*[[Language - JavaScript | JavaScript]]
+*[[Language - C_Sharp | C#]]
-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.
+==Phidget Network Server==
+The Phidget Network Server is an extremely useful feature of Phidgets that allows you to remotely control Phidgets over your network. If you haven't already, check out the  [[Phidget Network Server]] page for a complete overview.
-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:
+===Try it Out!===
+The Phidget SBC comes with the Phidget Network Server installed, and the SBC automatically starts the Network Server on boot. In order to change any of this default behaviour, navigate to Phidgets->phidget22NetworkServer using the SBC Web Interface:
-[[Image:linux_ws_boot.png|400px]]
-====As A Service====
+[[File:phidgetsbc_networkserver.PNG|link=|alt=|center]]
-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.
+In order to try the Phidget Network Server out, you will need a host computer, and a client computer:
+*Host computer: the computer that is physically connected to the Phidgets via USB and is running the Phidget Network Server.
+*Client computer: a computer running a Phidgets application that accesses Phidgets connected to the host computer.
-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:
+For this example, we will use the Phidget SBC as the host computer. The next step is setting up your client computer. If you are using a Windows computer as your client, keep reading, otherwise, you can jump ahead here:
-# A script that tells the boot process how to start and handle the webservice (i.e. by using {{Code|start-stop-daemon}})
+*[[#macOS Client | macOS Client]]
-# A link from that script to the boot list
+*[[#Linux Client | Linux Client]]
-# 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:
+====Windows Client====
-* Runlevels that the service should be present on
+In order to remotely access Phidgets on your SBC, you should get your client computer set up. Follow the Getting Started guide for Windows below before continuing:
-* Dependencies of the service
+*[[OS - Windows#Getting started with Windows| Getting started with Windows]]
-* 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">
+Now that you have Phidget drivers and libraries installed on your client computer, we can test the Phidget Network Server by following the steps below:
-<syntaxhighlight lang=bash>
-#!/bin/sh
+. Open the Phidget Control Panel on your client computer. You will see something like this:
-### 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"
+[[File:Phidgetsbc_networkserver_windows.PNG|link=|alt=|center|]]
-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
+. You now have access to the Phidgets that are connected to your Phidget SBC. Try double-clicking one of them to bring up an example.
-pws_port="5001"
-pws_serverid=""
-pws_password=""
-[ -f $CFG ] && . $CFG
-start() {
+====macOS Client====
-	[ -z "$pws_port" ] || OPTIONS="-p $pws_port "
+In order to remotely access Phidgets on your SBC, you should get your client computer set up. Follow the Getting Started guide for macOS below before continuing:
-	[ -z "$pws_password" ] || OPTIONS="$OPTIONS-P $pws_password "
+*[[OS - macOS#Getting started with macOS| Getting started with macOS]]
-	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() {
+Now that you have Phidget drivers and libraries installed on your client computer, we can test the Phidget Network Server by following the steps below:
-	echo -n "Stopping $DESC: "
-	start-stop-daemon -K -q -p $PIDFILE -x $DAEMON && echo "OK" || echo "NOT RUNNING"
-}
-case "$1" in
+. Open the Phidget Control Panel on your client computer. You will see something like this:
-  start)
-	start
-	;;
-  stop)
-	stop
-	;;
-  restart|force-reload)
-	stop
-	sleep 1
-	start
-	;;
-  *)
-	echo "Usage: $0 {start|stop|restart}"
-esac
-exit 0
+[[File:Phidgetsbc_networkserver_macos.PNG|link=|alt=|center|]]
-</syntaxhighlight>
-</div>
+. You now have access to the Phidgets that are connected to your Phidget SBC. Try double-clicking one of them to bring up an example.
-Save the script into a file called {{Code|phidgetwebservice}}, and use {{Code|chmod 755}} to make it executable.
+====Linux Client====
+In order to remotely access Phidgets on your SBC, you should get your client computer set up. Follow the Getting Started guide for Linux below before continuing:
+*[[OS - Linux#Getting started with Linux| Getting started with Linux]]
-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">
+Now that you have Phidget drivers and libraries installed on your client computer, we can test the Phidget Network Server by following the steps below:
-<syntaxhighlight lang=bash>
- sudo insserv -d phidgetwebservice
-</syntaxhighlight>
-</div>
+. From the terminal, type in the following command:
-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
+  phidget22admin -s
 </syntaxhighlight>
-</div>
+You will now see something like this:
-And you can start it right now without rebooting like this:
-[[Image:linux_system_service_start.png]]
+[[File:Phidgetsbc_linuxphidgetadmin.PNG|link=|alt=|center|]]
-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.
+As shown in the image above, the server running on your SBC can now be seen over the network. You will now be able to remotely access any Phidgets connected to your SBC.
-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">
+===What's Next?===
-<syntaxhighlight lang=bash>
+Now that you have seen the Network Server in action, you may be interested in implementing an application that takes advantage of all it's features. Luckily, every programming language we support comes with example code on how to do this! Jump to [[#Programming|programming languages]] above.
- 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:
+==Advanced Information==
+===Writing Image to SD Card===
+{{SDCardImage}}
-'''<font size=3><code>./configure --prefix=toolchain_location --build=this_system --host=target_system</code></font>'''
+===Checking System Logs===
-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:
+The SBC maintains two logs: a kernel log and a system log.
-<div class="source">
+The kernel log is for low-level occurrences, such as devices attaching and leaving the USB hub, recording what drivers are being used, and so on.
-<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:
+The system log (syslog) is for normal chatter from the operating system.  Any program with the right permissions can use it (though you need to know the method to write to it, information all around the Internet can help) and it contains everything from the Ethernet going up and down, to webserver requests, and so on.  If you don't run many programs or services on the SBC, the syslog will essentially be a mirror of the kernel log, because the kernel is the only thing talking.
-<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==
+You can check these logs by using the web interface in the {{Code|System &rarr; Logs}} tab.
-{{ProblemSolution|Low Speed Phidgets (Max of 8)|Linux will only schedule one low-speed interrupt transfer per millisecond.}}
+Or you can perform more powerful filtering and displaying via an SSH terminal.  For example, {{Code|dmesg}} is the command to display the kernel log, and {{Code|tail}} prints the last ten lines of input.  So, if you are trying to see if you can get a device to be detected on USB, you can run <code>dmesg | tail</code> to print the latest ten lines of kernel log data.
-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.
+The actual locations of the log files (for filtering and reading) are:
+* {{Code|/var/log/syslog}}
+* {{Code|/var/log/dmesg}}
+But don't edit them directly!  Always follow the advice and procedures around the Internet on how to properly log items to syslog.