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__
+==Quick Downloads==
+Already know what you're doing? Here you go:
-==Getting Started (Libraries and Drivers)==
+'''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]
-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.
+If you need to access older versions of the libraries, [https://www.phidgets.com/downloads/phidgetsbc/ click here].
-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  [[1072 0 - Getting Started | 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:
+==Getting Started With the Phidget SBC==
-* Set up networking on your SBC, via either Ethernet or wireless
+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:
-* Set up a password
+* Networking
-* Learned the IP address or link local address of the SBC
+* Administrator password
-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 [[#Getting Started - External Computer | External Development Computer]], usually your main desktop or laptop which will transfer files and settings to and from the SBC
-* The [[#Getting Started - The SBC (Debian Linux) | SBC]] itself, which needs programming language libraries to use Phidgets.
-===Getting Started - External Computer===
+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.
-You have two ways to connect to the SBC from an external computer: via the [[#SBC Web Interface|SBC Web Interface]] and over the more powerful but complex [[#SSH | Secure Shell (SSH)]].
-====SBC Web Interface====
+If you are using an external computer, there are videos available to help you get started, here is a video for Java:
-You have already worked extensively with the web interface in the [[1072 0 - Getting Started | Getting Started Guide for the SBC]].  This was the tool within a web browser which was opened either via the Phidget control panel on Windows, or by simply entering the IP or link local address into the browser.  It allowed you to set the password, set up internet connectivity, and so on.
+<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].
-We talk about the additional functionality of the web interface [[#Getting Started - The SBC (Debian Linux) | elsewhere in this document]].  This web interface will probably stay your initial go-to way to connect to the SBC, especially for tasks that benefit from graphical interaction, like setting up wireless or using the webcam.
-====SSH====
+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!
+===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 most flexible 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.
+The [[SBC3003 User Guide#Getting Started | user guide]] covers the SBC Web Interface in detail, so we will review SSH below.
-Before connecting over ssh, you will need:
+====SSH====
-* The '''IP address''' (such as 168.254.3.0) or '''link local address''' (such as phidgetsbc.local) of the SBC
+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.
-* The '''admin password''' for the SBC
-Both of these items can be found by following the steps in the [[1072 0 - Getting Started | Getting Started Guide for the SBC]].
-You will also need to enable SSH on the SBC side.  This can be done through the [[#SBC Web Interface| Web Interface]], under {{Code|Network &rarr; Settings}}, by changing the ''SSH Server'' radio button to ''Enabled'':
+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
-[[File:sbc_turn_on_ssh.png|link=|alt=]]
+You must also enable SSH on the SBC. You can do this via the SBC Web Interface which is shown in the image below:
+[[File:phidgetsbc_enableSSH.PNG|link=|alt=|center]]
-=====SSH on Windows=====
+{{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]]
-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 [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html 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 ({{Code|root}}) and password (the admin password).
+After clicking open, simply login as root and provide the administrator password:
+[[File:Windows_PuttyLogin.PNG|link=|alt=|center|class=notpageimage]]
-To copy files back and forth, there is an SCP component to PuTTY, called PSCP, which is available from the same [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY download page].
-=====SSH on Linux and Mac OS=====
+To transfer files between your SBC and Windows machine, we recommend either of these programs:
+* [https://winscp.net/eng/download.php WinSCP]
+* [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY PSCP]
-Linux and Mac OS already have ssh installed by default.  To run ssh simply open a terminal...
+You will follow a similar process to access the SBC as described for SSH.
-* {{Code|Ctrl-Alt-T}} on Linux
-* {{Code|Applications &rarr; Utilities &rarr; Terminal}} on Mac OS
-...and type:
-<div class="source">
+{{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>
-</div>
+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>
-If you have re-named your SBC, include that name instead of the {{Code|phidgetsbc.local}} link address.  Or, you can use the SBC's IP address, e.g. {{Code|ssh root@168.254.3.0}}.
+You will then be prompted for the password in order to gain access to the SBC:
+[[File:macOS_SSH.png|link=|alt=|center]]
-To copy files back and forth, the command follows the form of: {{Code|scp from to}}
-So, to copy a file {{Code|/root/data.txt}} from the SBC to your local machine, type:
+To copy a file from the SBC to your development machine using SCP, simply open the terminal and type the following:
+<syntaxhighlight lang=bash>
-<div class="source">
+scp root@phidgetsbc.local:/path/to/source /path/to/destination
+</syntaxhighlight>
+You can reverse this if you want to transfer a file from your development machine to your SBC:
 <syntaxhighlight lang=bash>
-scp root@phidgetsbc.local:/root/data.txt .
+scp  /path/to/source root@phidgetsbc.local:/path/to/destination
 </syntaxhighlight>
-</div>
-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 {{Code|pwd}} to print the working directory.  Terminals usually start by default in your home folder.
+===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
-===Getting Started - The SBC (Debian Linux)===
+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.
-The SBC comes with the following Phidget functionality installed:
-* The Phidget C libraries {{Code|libphidget21.so}}
-* The Phidget [[#Webservice | Webservice]]
-These packages can be seen via the SBC web interface
+[[File:phidgetsbc_installpackages.PNG|link=|alt=|center]]
-====Installing C/C++ and Java====
+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>
-The simplest way to install C/C++  and Java on the SBC is via the web interface.  There is a button under {{Code|System &rarr; Packages}} to install C support (including {{Code|gcc}}) and another button to install Java support.  Clicking the Java button will also install C support, as Java depends on the C libraries:
+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>
-[[File:sbc_packages_web.png|link-|alt=]]
+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
-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.
+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=====
+{{hiddenh5|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 {{Code|/etc/apt/sources.list.d/multistrap-debian.list}} and add the following lines:
-<div class="source">
 <syntaxhighlight lang=bash>
-apt-get install python
+#     DO NOT EDIT THIS FILE BY HAND -- YOUR CHANGES WILL BE OVERWRITTEN
+deb http://archive.debian.org/debian wheezy main contrib non-free
 </syntaxhighlight>
-</div>
-=====Install Phidget Python Method 1: Use a USB Key=====
-Copy the [http://www.phidgets.com/downloads/libraries/PhidgetsPython_2.1.8.20120216.zip 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 | Using USB Data Keys]] section.
-After you know the place where the USB key is mounted, go to that directory (e.g. {{Code|cd /media/usb0/}}, enter the unpacked Phidget Python Library folder, and run:
+Then, run the following commands:
-<div class="source">
 <syntaxhighlight lang=bash>
- python setup.py install
+apt-get update
+apt-get install python
 </syntaxhighlight>
-</div>
-Now, you're ready to begin writing Python code for the SBC.  For more help on writing and using Python with Phidgets, we have an whole [[Language - Python | page on that topic]].
+If you're using the Phidget SBC4 you can just {{Code|apt-get install python}} without changing the apt file.
-=====Install Phidget Python Method 2: Use the Internet=====
+Next, install the Phidget Python module.
-Rather than using a USB key to transfer the file, the SBC can download it directly from the internet.  You will need {{Code|wget}} and {{Code|unzip}} installed, both of which are small:
+{{hiddenh5|Method 1: Use the Internet}}
+First, install wget and unzip:
-<div class="source">
 <syntaxhighlight lang=bash>
 apt-get install wget
 apt-get install unzip
 </syntaxhighlight>
-</div>
-Copy the web link address for the [http://www.phidgets.com/downloads/libraries/PhidgetsPython_2.1.8.20120216.zip | Python Libraries].
+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):
+<syntaxhighlight lang=bash>
+wget http://copied_link
+</syntaxhighlight>
-In an SSH terminal to the SBC, type: {{Code|wget http://www.python_library_link}} where instead of http://www.python_library_link you insert the link you just copied.
+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>
-This will download the Phidget python libraries to the folder you ran the {{Code|wget}} command in.  Unzip the file using the command {{Code|unzip}}.
+Finally, change directories to the unzipped folder:
+<syntaxhighlight lang=bash>
+cd /path/to/unzipped/folder
+</syntaxhighlight>
+and install the Phidget Python libraries:
+<syntaxhighlight lang=bash>
+python setup.py install
+</syntaxhighlight>
-==Using SBC Linux==
+You're now ready to begin programming! Continue through this guide for code examples and directions on where to go next.
-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.
+{{hiddenh5|Method 2: Use a USB Key}}
-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.
+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.
-===Some Useful Commands===
+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>
+cd /media/usb0/
+python setup.py install
+</syntaxhighlight>
-====ls====
+You're now ready to begin programming! Continue through this guide for code examples and directions on where to go next.
-The '''ls''' program lists the contents of a directory.
+==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]].
-It will show both files and folders, but not files that start with a "." (these are hidden files on Linux).
+===Developing with an External Computer===
-*If you also want to show hidden files, use {{Code|ls -a}}
+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:
-*If you want more information, such as size and date modified, use {{Code|ls -l}}
+*[https://cdn.phidgets.com/downloads/phidget22/examples/java/Manager/Phidget22_HelloWorld_Java_Ex.zip Java HelloWorld Example]
-*Commands can be combined, like {{Code|ls -al}}
+*[https://cdn.phidgets.com/downloads/phidget22/libraries/any/Phidget22Java.zip phidget22.jar]
-====cd====
-The '''cd''' program changes to a new directory.
+Next, follow these steps:
-For example, {{Code|cd /root}} changes into the directory at the base of the file tree called ''root''.
+. Place phidget22.jar on your development machine in a directory that you will use to compile your Java files.
-Note:
+. Copy the HelloWorld.java file from the example package to the same directory.
-* Linux uses forward slashes
-* The base of all directories is "/" (not "C:\")
-* The tilde symbol (~) is short for your home directory (i.e. when you are root, this is short for "/root")
-* The double dot ".." means move one directory higher (for example from {{Code|/root/data/}} to {{Code|/root/}})
-====pwd====
+. Compile the HelloWorld.java file. If you are using a Windows machine, type the following into the command prompt:
+<syntaxhighlight lang=bash>
+javac -classpath .;phidget22.jar HelloWorldExample.java
+</syntaxhighlight>
+If you are using a Linux or macOS machine, type the following into the terminal:
+<syntaxhighlight lang=bash>
+javac -classpath .:phidget22.jar HelloWorldExample.java
+</syntaxhighlight>
-The '''pwd''' program prints the current directory you are working in.  ('P'rint 'W'orking 'D'irectory)
+You should now have the following class file:
+*HelloWorldExample.class
-For example:
-:{{Code|root@phidgetsbc:~# pwd}}
-:{{Code|/root}}
-====find====
+. Using the SBC Web Interface, create a new project called HelloWorld:
-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:
+[[File:Phidgetsbc_createproject.PNG|link=|alt=|center]]
-{| style="border:1px solid darkgray;" cellpadding="15px;"
-|-
-! SSH Command
-! What it Does
-! Example
-|-
-| {{Code|find folder -name file.txt}}
-| Looks for all files in a folder (/ for root - or all - folders) with a certain name (* for wildcard)
-| {{Code|find / -name *.jpg}}
-|-
-| {{Code|find folder -mtime +X}}
-| Looks for all files in a folder modified less than X days ago
-| {{Code|find /root -mtime +30}}
-|}
+. 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:
-====grep====
-The '''grep''' program takes text input and searches for a term.
+[[File:Phidgetsbc_runprogram.PNG|link=|alt=|center]]
-For example, if you type {{Code|mount}} to view what devices are mounted (e.g. loaded) on your SBC, you will see:
-<div class="source">
+. You'll note that as it runs, there are two links below the Stop button:
-<syntaxhighlight lang=text>
+*stdout: view the program output like you would in a terminal or command prompt
-root@phidgetsbc:~# mount
+*stderr: view the program error output
-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)
-</syntaxhighlight>
-</div>
-This may be a lot of information you don't need.  If you are only interested in a USB key attachment (as described in the [[#Using USB Data Keys|Using USB Data Keys]] section), you can use grep to filter that one response:
-<div class="source">
+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]].
-<syntaxhighlight lang=text>
-root@phidgetsbc:~# mount | grep sda1
-/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
-</syntaxhighlight>
-</div>
-====nano====
+===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.
-The '''nano''' program is a small text editor that you can use within an SSH terminal.
+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''
-Nano can be surprisingly useful for writing short lengths of code right on the SBC, so there is no need to transfer files and keep track of different file versions on different computers.
-Nano has all keyboard commands which are listed at the bottom of the screen at all times as a reminder (Ctrl-O to save, Ctrl-X to exit, these expand with a larger terminal window).  And, nano provides what is called 'syntax highlighting', which colours reserved keywords, comments, strings, and so on as appropriate to the programming language you are using.  Nano detects the programming language via the extension of the file ({{Code|.java}} for Java, {{Code|.c}} for C/C++, and {{Code|.py}} for Python).
+Next, follow these steps:
-Typing {{Code|nano test.py}} on an SSH command line and then entering a few lines of Python into the new empty file results in:
+. If you haven't already, connect to the SBC using SSH or a keyboard and monitor.
-[[File:sbc_nano_python.png|link=|alt=]]
+. 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>
-====apt====
+. Unpack the examples
+<syntaxhighlight lang=bash>
+unzip examples_filename
+</syntaxhighlight>
-The '''apt''' program allows you to install, uninstall, upgrade, and search software available for the SBC.
+. Compile the HelloWorldExample.java example:
-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
+<syntaxhighlight lang=bash>
+javac -classpath .:/usr/share/java/phidget22.jar HelloWorldExample.java
+</syntaxhighlight>
-{| style="border:1px solid darkgray;" cellpadding="15px;"
+.Run the HelloWorldExampleprogram:
-|-
+<syntaxhighlight lang=bash>
-! SSH Command
+java -classpath .:/usr/share/java/phidget22.jar HelloWorldExample
-! What it Does
+</syntaxhighlight>
-! Example
-|-
-| {{Code|apt-cache search term}}
-| Looks for all programs (packages) that have {{Code|term}} in the title or description
-| {{Code|apt-cache search opencv}}
-|-
-| {{Code|apt-cache show package}}
-| Shows a lot of data about {{Code|package}} including size, version, etc
-| {{Code|apt-cache show unzip}}
-|-
-| {{Code|apt-get update}}
-| Gets the most recent listing of available software
-| {{Code|apt-get update}}  (No options)
-|-
-| {{Code|apt-get install program}}
-| Installs {{Code|program}} from the internet
-| {{Code|apt-get install python}}
-|-
-|}
-====which====
+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.
-The program {{Code|which}} tells you if and where a program is installed.
+===Running a Program Automatically===
+After testing your program, you will likely want it to run on boot, or on a schedule, without your input.
-For example, on a default SBC, typing {{Code|which python}} will return no results.  But after successfully [[#Installing Python | installing python]], it will return {{Code|/usr/bin/python}} as the location of the python program/binary/executable.
+====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]].
-===Some Useful Commands to Install===
+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:
-====gcc====
-The '''gcc''' program is the C compiler for Linux.
+[[File:phidgetsbc_runonboot.PNG|link=|alt=|center]]
-If you are an experienced C/C++ user on Mac or Linux, or if you've already read our [[Language - C/C++ | C Language page]], you might think you need to install gcc via {{Code|apt-get}} to compile C code.  However, gcc is not in the package repository for the SBC, so {{Code|apt-get install gcc}} will fail.  Rather, to install gcc, you can do it via the web interface, as described in the [[#Installing C/C++ and Java|Installing C/C++ and Java]] section.
-After installing it via the SBC web interface, you can use {{Code|gcc}} normally.
+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.
-====less====
+After saving your changes, your program will run automatically whenever your SBC boots.
-The '''less''' program displays the contents of a text or source code file.  When displaying the file, {{Code|less}} allows you to scroll up and down to read it.
+{{hiddenh5|Automatically Running Python Code}}
-This is useful if you are writing your sensor readings to a data file, and you want to read the data file while it is being written by your main code.  If your data file is called {{Code|data.txt}}, you can type {{Code|less data.txt}} and see the lines in the file, and what they are.
+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:
-The {{Code|less}} program output can also be piped into another program.  For example, you can use {{Code|less}} and the word search program {{Code|grep}} to find lines within a file with a search term.  For instance, if you have a C source code file {{Code|Program.c}} on the SBC, and you want to see all the lines in {{Code|Program.c}} that contain a variable name {{Code|var}}, you can type:
+<syntaxhighlight lang=python>
-:<code>less Program.c | grep var</code>
+#!/usr/bin/python
+</syntaxhighlight>
+====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.
-====wget====
-The '''wget''' program allows you to get an online file (over http) and download it to the SBC.
+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.
-For example, to get the source file (HTML) from the Phidgets home page, you can type:
-<div class="source">
+First, set your editor to nano:
 <syntaxhighlight lang=bash>
-wget http://www.phidgets.com
+export EDITOR=nano
 </syntaxhighlight>
-</div>
+Next, edit your crontab file:
-This is most useful for downloading libraries, drivers, or anything (zip, tar, etc) you need from the web which is not available by [[#apt|using apt]].
-====unzip====
-===Writing a Phidget Program===
-===Running a Program Automatically===
-===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 {{Code|Status &rarr; System}}.  Or, the USB key and all other attached devices can be seen at {{Code|Status &rarr; USB}}:
-[[File:sbc_mounted_devices.png|link=|alt=]]
-In the screenshot above, you can see that the USB key is located in {{Code|/media/usb0}}.
-Alternately, you can use the SSH command {{Code|mount}}, and the searching program {{Code|grep}} which will filter the response of {{Code|mount}} and only return the lines with your search term ({{Code|usb}}):
-<div class="source">
 <syntaxhighlight lang=bash>
-root@phidgetsbc:~# mount | grep usb
+crontab -e
-/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
+</syntaxhighlight>
+Finally, schedule your cron job:
+<syntaxhighlight lang=text>
+#cron job that will run at 5AM every week:
+5 * * 1 /root/code/myprogram argument1
 </syntaxhighlight>
-</div>
-In this case, the USB key can be written to and read from using the {{Code|/media/usb0}} directory.  Copying a file to {{Code|/media/usb0}} will copy a file to the USB key.  The same goes for removing, renaming, opening files within your program, etc.
+[[File:phidgetsbc_cronjob.PNG|link=|alt=|center]]
-'''Note:''' Mount points like {{Code|/media/usb0}} should not be hard-coded into any of your programs.  (See the [[#Common Problems and Solutions | 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. {{Code|/dev/sda1}} or {{Code|/dev/sdb1}}) and obtain the corresponding mounted {{Code|/media/usbN}} location, where N is a number 0-9.
-===Saving and Retrieving Data===
+After entering your task, simply save and exit the file.
-====Over the Web (an SBC Webserver)====
+====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]].
-==Troubleshooting==
+===Programming===
+Ready to write some code? Select one of the programming languages below:
-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:
+*[[Language - C|C]]
-* No other programs, drivers, or processes are using that USB port in software
+*[[Language - Java | Java]]
-* You are running the example program as root (or your udev rules have been set properly)
+*[[Language - Python | Python]]
-* You are using libusb 0.1 (not 1.0 or later)
+*[[Language - JavaScript | JavaScript]]
-* You have compiled versions of libphidget21.a and libphidget21.so in your system library location (usually {{Code|/usr/lib}})
+*[[Language - C_Sharp | C#]]
-* 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]]!
+==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:
-===Initial Internet Setup===
-To set up the SBC, you need a ''wired'' Ethernet connection with DHCP, and without a firewall.  Even if you do not have this type of a connection at home, these types of connections are very common at both offices and universities.
+[[File:phidgetsbc_networkserver.PNG|link=|alt=|center]]
-Sometimes it can work to plug the SBC, using Ethernet, directly into an Ethernet port on your home router.  This is a very picky process, however, and can fail because:
-* Some home and office routers place a firewall between wireless connections (clients) and wired connections (the local area network)
-* Some home and office routers do not by default allow both Ethernet DHCP and wireless DHCP.
-* Some routers and DHCP hubs only provide access to an internet connection, and do not provide local area network inter-connections (this is common on mobile device tethering hubs)
-Routers are quite complex, and even with admin privileges it can be a painstaking process to find all the right firewall settings to turn off in order to allow two computers on the network to talk to one another, rather than just connect to the internet.  This is why university or office networks are often ideal for the purpose of setting up the SBC, because these institutions depend on computers on a local network being able to talk together.  Covering all of the different router configuration possibilities, and how to change them to make the SBC work, is essentially impossible.
+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 good news is that if you can find an Ethernet DHCP connection a single time, you can use that connection to set up as many wireless DHCP connections (with passwords) that you need on the SBC.  Once wireless is enabled, and allowed wireless network names are set up with passwords if needed, the SBC will automatically seek out and connect to the networks on the list as they appear.  It is rare for home or office routers to put a firewall between wired and wireless connections, and so connecting over wireless only will allow your external control computer and the SBC to connect easily.  At that point, you can also use wireless to modify all settings, including wireless and other Internet settings.
-If you have a wired DHCP connection, no firewall, and ''no link local addressing'' (e.g. bonjour or avahi is not installed) then you will need access to the router logs.
+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 | macOS Client]]
+*[[#Linux Client | Linux Client]]
-===Recovery / Upgrade System===
-The recovery / upgrade system is a small system from which the main system can be reset/upgraded, or recovered.
+====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:
+*[[OS - Windows#Getting started with Windows| Getting started with Windows]]
-====Entering the Recovery System====
-The recovery system can be entered in two ways.
-# From the 'System: Backup & Restore' web interface page.
+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:
-# By holding down the reset button for 20+ seconds - until the green light has switched from flashing slowly to flashing quickly.
-====Upgrades====
+. Open the Phidget Control Panel on your client computer. You will see something like this:
-Generally, you should not need to do a full system upgrade. Upgrades are meant to be performed via the package
-system, and Phidgets maintains it’s own package repository from which to push out updates.
-Occasionally, you may wish to go back to a clean install and upgrade to the latest rootfs/kernel from Phidgets.
-Phidgets will not be creating these images with every release of phidget21 as we did with PhidgetSBC1, rather they
-will be released several times a year, as needed for major changes not easy to push out via packages.
-You can also flash your own custom kernel or root filesystem image.
-====Factory Reset====
-This restores the kernel and root filesystem from backup, overwriting any changes that may have been made. This is
-equivalent to holding down the reset button for 10 seconds.
-====Recovery====
+[[File:Phidgetsbc_networkserver_windows.PNG|link=|alt=|center|]]
-If the main filesystem has been damaged/misconfigured in such a way that it won’t boot, you may be able to fix the
-issue / recovery important files before running a reset. The recovery system runs an SSH server that you can login
-to for console access. Username/password is: root/root.
-You can mount the main root filesystem with the following commands (assuming it’s not damaged):
-# ubiattach /dev/ubi_ctrl -m 6
-# mount -t ubifs /dev/ubi0_0 /mnt
-==Programming Languages==
-Now that you have the basic libraries installed, you can pick your language and begin programming!
+. 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.
-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.
+====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:
+*[[OS - macOS#Getting started with macOS| Getting started with macOS]]
-On Linux, we recommend the following languages:
-*[[Language - C/C++|C/C++]]
+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:
-*[[Language - Java | Java]]
-*[[Language - Python | Python]]
-Also check the following languages:
+. Open the Phidget Control Panel on your client computer. You will see something like this:
-* Ruby
+[[File:Phidgetsbc_networkserver_macos.PNG|link=|alt=|center|]]
-* C Sharp over Mono
-==Webservice==
+. 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.
-==Advanced Uses==
+====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]]
-===Using a Different Wireless Adapter===
+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:
-===Using a Different Webcam===
+. From the terminal, type in the following command:
-===Taking Pictures With the Webcam===
-Probably the most straightforward way to use a webcam for pictures rather than video is to use the {{Code|opencv}} library.  You can get it by:
-<div class="source">
 <syntaxhighlight lang=bash>
-apt-get install opencv
+ phidget22admin -s
 </syntaxhighlight>
-</div>
-The opencv libraries can also be used within Python, by installing the link between them:
-<div class="source">
+You will now see something like this:
-<syntaxhighlight lang=bash>
-apt-get install python-opencv
-</syntaxhighlight>
-</div>
-Then taking pictures from within code becomes quite simple.  For example, in Python, taking and saving an image is four lines:
-<div class="source">
+[[File:Phidgetsbc_linuxphidgetadmin.PNG|link=|alt=|center|]]
-<syntaxhighlight lang=bash>
-#! /usr/bin/python
-import cv
-# The webcam is located at /dev/video0
+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.
-# OpenCV only needs the number after video
-webcam = cv.CaptureFromCAM(0)
-frame = cv.QueryFrame(webcam)
-cv.SaveImage("image.jpg", frame)
+===What's Next?===
-</syntaxhighlight>
+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.
-</div>
-For the complete OpenCV documentation, see [http://opencv.willowgarage.com/documentation/index.html The OpenCV Reference], and specifically the section on [http://opencv.willowgarage.com/documentation/reading_and_writing_images_and_video.html Reading and Writing Images].
+==Advanced Information==
+===Writing Image to SD Card===
+{{SDCardImage}}
 ===Checking System Logs===
-===Custom Kernel and Filesystem===
+The SBC maintains two logs: a kernel log and a system log.
-You can compile your own Kernel and flash it to the board. Phidgets Inc. provides our kernel patches on phidgets.
-com. It is left up to the user to configure an appropriate cross-compiler for kernel development. You may also be
-able to compile a new kernel on-board.
-Installing a new kernel involves erasing the old kernel, flashing the new kernel, installing the new kernel modules,
-and rebooting:
-# 'make uImage; make modules' in the kernel directory
-# 'flash-eraseall /dev/mtd3'
-# 'nandwrite -p /dev/mtd3 arch/arm/boot/uImage'
-# 'make modules-install'
-# 'reboot'
-Custom kernels can also be flashed from the Recovery/Upgrade system.
+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.
-Custom filesystem can be flashed from the Recovery/Upgrade system. The creation of custom filesystems is not
+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.
-documented, as the Debian package repository should provide enough flexibility for most users. However, if you
-need to create a root filesystem image, use the following settings:
-Filesystem type is: UBIFS
-Commands to create it:
-# 'mkfs.ubifs -m 2KiB -e 126KiB -c 4050 -r $ROOTFS/ system_ubifs.img'
-# 'ubinize -o system_ubi.img -m 2KiB -p 128KiB -s 512 ubinize.cfg'
-<div class="source">
-<syntaxhighlight lang=bash>
-Where ‘ubinize.cfg contains:
-# Section header
-[rootfs]
-# Volume mode (other option is static)
-mode=ubi
-# Source image
-image=system_ubifs.img
-# Volume ID in UBI image
-vol_id=0
-# Volume size
-vol_size=64128KiB
-# Allow for dynamic resize
-vol_type=dynamic
-# Volume name
-vol_name=rootfs
-# Autoresize volume at first mount
-vol_flags=autoresize
-You then flash ‘system_ubi.img’ (not ‘system_ubifs.img’) from the recovery system.
-</syntaxhighlight>
-</div>
-==Common Problems and Solutions==
-{{ProblemSolution|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. {{Code|/dev/sda1}}) and it will also ''mount'' the key for reading and writing within the {{Code|/media/}} directory.  The {{Code|/media/}} directory version will be called something like {{Code|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 {{Code|mount}}:
-<div class="source">
-<syntaxhighlight lang="text">
-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)
-</syntaxhighlight>
-</div>
-You will note that the same device ({{Code|/dev/sda1}}) is now mounted at ''both'' {{Code|/media/usb0}} and {{Code|/media/usb1}}.  To fix this problem as it occurs, you can use {{Code|umount}} (notice there is no letter 'n') to unmount the second instance:
-<div class="source">
-<syntaxhighlight lang="text">
-root@phidgetsbc:~# umount /media/usb1
-</syntaxhighlight>
-</div>
-In practice, this should not be a problem, because writing to or reading from either {{Code|usb0}} or {{Code|usb1}} will have the same effect on the memory key.  However, if you hard-code a media location into your program (i.e. expecting {{Code|/media/usb0}} to be the first USB key you insert and {{Code|/media/usb1}} to be the second key) your program will sometimes work and sometimes fail.
+You can check these logs by using the web interface in the {{Code|System &rarr; Logs}} tab.
-To get around this within code, find the mount point for each device as it appears.  The devices, such as {{Code|/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 {{Code|mount}}) within your code to find the device and its corresponding mount point.
+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.
-This is a problem with the standard embedded Debian automount program, and we have no known fix.
+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.