Difference between revisions of "OS - Phidget SBC"

From Phidgets Support
Jump to: navigation, search
(Run on Boot)
 
(127 intermediate revisions by 6 users not shown)
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]]
 
[[Category:OS]]
{{OSLang|[[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__
 
__TOC__
  
 
==Quick Downloads==
 
==Quick Downloads==
 +
Already know what you're doing? Here you go:
  
Unlike our other supported operating systems, the SBC '''does not require downloads''' unless you are doing something advanced like loading the firmware or developing your own kernel. You will know if you need these downloads, otherwise, the SBC should work as described on the [[1072_-_Getting_Started|SBC2 Getting Started Guide]] right out of the box.
+
'''For PhidgetSBC (1070):'''
 +
*[{{SERVER}}/downloads/phidgetsbc/1070/changelog.txt changelog]
 +
*[{{SERVER}}/downloads/phidgetsbc/1070/phidgetsbc-minimal.bin Minimal Firmware]
 +
*[{{SERVER}}/downloads/phidgetsbc/1070/phidgetsbc-full.bin Full Firmware]
 +
*[{{SERVER}}/downloads/phidgetsbc/1070/buildroot-phidgetsbc.tar.gz Buildroot/Kernel Sources]
 +
'''For PhidgetSBC2 (1072):'''
 +
*[{{SERVER}}/downloads/phidgetsbc/1072/changelog.txt changelog]
 +
*[{{SERVER}}/downloads/phidgetsbc/1072/phidgetsbc2.bin SBC2 Firmware]
 +
*[{{SERVER}}/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]
 +
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.6.3/phidgetsbc3.bin SBC3 Firmware]
 +
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.6.3/phidgetsbc3-kerneldev.tar.gz SBC3 Kernel Development Package]
 +
*[{{SERVER}}/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]
 +
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.14.27/phidgetsbc3.bin SBC3 Firmware]
 +
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.14.27/phidgetsbc3-update_3.14.27.tar.gz SBC3 Kernel update package (3.14.27)]
 +
*[{{SERVER}}/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]
 +
*[{{SERVER}}/downloads/phidgetsbc/SBC3003/phidgetsbc4.zip SBC4 SD Card Image] | [{{SERVER}}/downloads/phidgetsbc/SBC3003/phidgetsbc4.md5 md5]
 +
*[{{SERVER}}/downloads/phidgetsbc/SBC3003/SBC3003_upgrade.tar.gz SBC4 Kernel/Bootloader Upgrade Package]
  
*[{{SERVER}}/downloads/libraries/phidgetsbc2.bin SBC2 Firmware]
+
==Getting Started With the Phidget SBC==
*[{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package] (How-to and patch file)
+
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:
*[{{SERVER}}/Drivers_Info.html#SBC2 License]
+
* Networking
 +
* Administrator password
  
Note that, instead of using the firmware to update your SBC, updates should normally be done via the System -> Packages page on your SBC2 web interface. It is rarely necessary to completely re-flash your device.
 
  
==Getting Started with the Phidget SBC Debian Linux==
+
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.
  
The Single Board Computer (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 this is your first time''' using the Phidget SBC, you will want to start with the [[1072 - Getting Started | Getting Started Guide for the SBC]].  After that, here we will get you started on topics beyond those in the getting started guide, including how to write Phidget code to run on the SBC.  You '''do not need this page''' if you are simply using the SBC to broadcast data from Phidgets over the network - it does that automatically.  We describe how to verify and use this in the [[1072 - Getting Started | Getting Started Guide]].
+
If you are using an external computer, there are videos available to help you get started, here is a video for Java:
  
This page will show you how to:
+
<center>{{#ev:youtube|InbY-Ui1tg0|||||rel=0}}</center>
* Install the ability to write and develop code on the SBC itself
+
We also have videos for [https://www.youtube.com/watch?v=y7XhShmhiEU&list=PLwPK-C9lEEc0iciKTiWSWZ74tQysd2lsS&index=4 Python] and [https://www.youtube.com/watch?v=8vv8kx4743c&list=PLwPK-C9lEEc0iciKTiWSWZ74tQysd2lsS&index=2 C].
* Use the command line for basic coding tasks
+
* Troubleshoot the SBC's network
+
It will also give additional specifications, which are useful for doing more advanced things with the SBC hardware and software.
+
  
Before reading this page, you should have done the following via the Getting Started Guide:
 
* Set up networking on your SBC, via either Ethernet or wireless
 
* Set up an admin password
 
* Learned the IP address or link local address of the SBC
 
We will use this information in setting up the libraries and drivers to use the SBC for writing and running code.
 
  
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 gets complicated as the SBC does not have a keyboard or screen.  So usually, you will want to develop your code 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:
+
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!
* 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===
+
===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)
  
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)]].
+
The [[SBC3003 User Guide#Getting Started | user guide]] covers the SBC Web Interface in detail, so we will review SSH below.
 
+
====SBC Web Interface====
+
 
+
You have already worked extensively with the web interface in the [[1072 - 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 an internet browser.  It allowed you to set the password, set up internet connectivity, and so on. 
+
 
+
This section doesn't have more information on the interface; rather, it simply serves as a reminder that you have the web interface as an available tool.  Examples, including screenshots, are placed where appropriate in this document.  The 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====
 
====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.
  
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. If you are unfamiliar with ssh, you can think of it like the command line or a Mac terminal, but with a remote connection to a different computer. It is a minimal yet effective way to interact with a remote computer.
+
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
  
Before connecting over ssh, you will need:
+
You must also enable SSH on the SBC. You can do this via the SBC Web Interface which is shown in the image below:
* The '''IP address''' (such as 168.254.3.0) or '''link local address''' (such as phidgetsbc.local) of the SBC
+
[[File:phidgetsbc_enableSSH.PNG|link=|alt=|center]]
* The '''admin password''' for the SBC
+
Both of these items can be found by following the steps in the [[1072 - 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'' and saving your changes:
+
{{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]]
 +
[[File:Windows_PuttyLL.PNG|link=|alt=|425x411px]]
  
[[File:sbc_turn_on_ssh.png|link=|alt=]]
 
  
=====SSH on Windows=====
+
After clicking open, simply login as root and provide the administrator password:
 +
[[File:Windows_PuttyLogin.PNG|link=|alt=|center]]
  
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 is [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY], and it has the advantage that the executable doesn't need to install, it just runs.
 
  
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).
+
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]
  
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].  Use of PSCP will be similar with the address, username, and password, except that you will be transferring files instead of sending commands.
+
You will follow a similar process to access the SBC as described for SSH.
  
=====SSH on Linux and Mac OS=====
+
{{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:
Linux and Mac OS already have ssh installed by default. To run ssh simply open a terminal...
+
* {{Code|Ctrl-Alt-T}} on Linux
+
* {{Code|Applications &rarr; Utilities &rarr; Terminal}} on Mac OS
+
...and type:
+
 
+
<div class="source">
+
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
 
ssh root@phidgetsbc.local
 
ssh root@phidgetsbc.local
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
+
Or, something like this (you will need to know the IP address of your SBC):
 
+
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. something like {{Code|ssh root@168.254.3.0}}
+
 
+
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:
+
 
+
<div class="source">
+
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
scp root@phidgetsbc.local:/root/data.txt .
+
ssh root@192.168.3.195
 
</syntaxhighlight>
 
</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.
+
You will then be prompted for the password in order to gain access to the SBC:
 +
[[File:macOS_SSH.png|link=|alt=|center]]
  
===Getting Started - The SBC (Debian Linux)===
 
  
The SBC runs Linux, which is a full operating system. It is stripped down compared to a full desktop release of Linux, but you can compile code on it, run programs, schedule tasks, create and manage files, run a web server, and much, much more.
+
To copy a file from the SBC to your development machine using SCP, simply open the terminal and type the following:
 
+
At this point you have connected to the SBC via the [[#SBC Web Interface|web interface]], and probably also through [[#SSH|SSH]].  This section will help you install libraries and drivers that you probably want - i.e. support for C, Java, and Python.  After this section, you'll be well into the depths of using the SBC as a computer, and so you'll probably want to keep the [[#Using SBC Linux|Using SBC Linux section]] open for reference while you work if you are not already familiar with Linux.
+
 
+
The SBC comes with the following Phidget functionality installed:
+
* The Phidget C libraries {{Code|libphidget21.so}}
+
* The Phidget [[#WebService | WebService]]
+
(If you are simply curious what these are and how they get installed, we describe the process on the [[OS - Linux | general Linux page]].)
+
 
+
But to compile C programs, or run Java programs, or use Python, you will need to install these languages onto the SBC. 
+
 
+
Before installing anything on the SBC, however, (even via a button on the web interface) make sure that the ''Include full Debian Package Repository'' option is checked in the web interface under {{Code|System &rarr; Packages}}.
+
 
+
====Installing C/C++ and Java====
+
 
+
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:
+
 
+
[[File:sbc_packages_web.png|link-|alt=]]
+
 
+
Now you're ready to begin programming.  We have programming pages for both [[Language - C/C++|C/C++]] and for [[Language - Java|Java]].  Remember that if you're unfamiliar with Linux, we have help on using files and running programs automatically in the [[#Using SBC Linux|Using SBC Linux section]]. 
+
 
+
If you want to avoid using the [[#SSH|SSH]] interface on the SBC entirely, and you want to write your program in Java and run it continuously from boot (which is the only option if you want to avoid [[#SSH|SSH]]), we have a [[#Program in Java with the Web Interface|very in-depth section]] on that topic.
+
 
+
====Installing Python====
+
 
+
Installing Python has two steps.  First, you'll need to install the basic ability to run python, and then you'll need to install the Phidget Python module.  Both steps (and both options) require that you issue the relevant commands through an [[#SSH|SSH terminal]].
+
 
+
=====Basic Python=====
+
 
+
The base Python functionality can be downloaded and installed in one step with [[#apt|apt]] (i.e. in a terminal, type):
+
 
+
<div class="source">
+
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
apt-get install python
+
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  /path/to/source root@phidgetsbc.local:/path/to/destination
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
 
  
This will give you Python, and now you just have to install the Phidget Python module to gain Phidget functionality.
+
===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
  
=====Install Phidget Python Method 1: Use a USB Key=====
+
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.
  
Copy the [{{SERVER}}/downloads/libraries/PhidgetsPython.zip Python Libraries] onto a USB key.  Unpack the zip file into a folder on the USB key. Insert the key into the SBC.
+
====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.
  
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, in a terminal go to that directory (e.g. type {{Code|cd /media/usb0/}}), enter the unpacked Phidget Python Library folder, and run:
+
[[File:phidgetsbc_installpackages.PNG|link=|alt=|center]]
  
<div class="source">
+
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>
 
<syntaxhighlight lang=bash>
python setup.py install
+
Java -version
 
</syntaxhighlight>
 
</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]].  Remember that if you're unfamiliar with Linux, we have help on using files and running programs automatically in the [[#Using SBC Linux|Using SBC Linux section]].
+
If you need to update the version of Java on your SBC, use the following commands:
 
+
=====Install Phidget Python Method 2: Use the Internet=====
+
 
+
Rather than using a USB key to transfer the file, the SBC can download it directly from the internet.  You will need {{Code|wget}} and {{Code|unzip}} installed, both of which are small:
+
 
+
<div class="source">
+
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
apt-get install wget
+
apt-get install default-jre-headless
apt-get install unzip
+
su
 +
update-alternatives --config java
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
 
  
Copy the web link address for the [{{SERVER}}/downloads/libraries/PhidgetsPython.zip Python Libraries].
+
You're now ready to begin programming! Continue through this guide for code examples and directions on where to go next.
  
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. Copying into a terminal can usually be done via the right-click menu.
+
====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
  
This will download the Phidget python libraries to the folder you ran the {{Code|wget}} command in. Unzip the downloaded file using the command {{Code|unzip file}}, where file is the filename from {{Code|wget}}. Or try typing {{Code|ls}} to list the names of a file in the directory, which should include the unzipped folder. Enter the unzipped folder (e.g. use {{Code|cd}} to change directory), and install the Phidget Python libraries:
+
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.
  
<div class="source">
+
{{hiddenh5|Basic Python}}
 +
The base Python functionality can be downloaded and installed in one step:
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
python setup.py install
+
apt-get install python
 
</syntaxhighlight>
 
</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 a whole [[Language - Python | page on that topic]].  Remember that if you're unfamiliar with Linux, we have help on using files and running programs automatically in the [[#Using SBC Linux|Using SBC Linux section]].
+
Next, install the Phidget Python module.
  
====Installing Other Languages====
+
{{hiddenh5|Method 1: Use the Internet}}
 
+
First, install wget and unzip:
You may also be able to program on the SBC using [[Language - Ruby|Ruby]] and [[Language - C Sharp|C# under Mono]], though we do not offer in-depth support for these languages on the SBC.  The installation procedures should more or less follow that of [[#Installing Python|installing python]] on the SBC, except you will be installing Ruby or Mono.  Performing package searches using [[#apt|apt cache search]] can help you find the relevant software.
+
 
+
For C#, as of 2012 the {{Code|mono-complete}} package is broken on the Debian Squeeze repository.  Rather, you have to install the Mono runtime and Mono compiler separately.
+
 
+
To install the runtime package (and its dependencies), use [[#apt|apt]]:
+
 
+
<div class="source">
+
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
apt-get install mono-runtime
+
apt-get install wget
 +
apt-get install unzip
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
 
 
Then, to install the C# compiler:
 
  
<div class="source">
+
Next, copy the web link address for the [{{SERVER}}/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>
 
<syntaxhighlight lang=bash>
apt-get install mono-gmcs
+
wget http://copied_link
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
 
  
Or the Visual Basic compiler:
+
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:
 
+
<div class="source">
+
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
apt-get install mono-vbnc
+
unzip filename
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
 
  
Then, the system and library packages do not link correctly for the version 2.0 of Mono.  If this is the case, your code will compile fine, but when you try to run it, you will get an error like:
+
Finally, change directories to the unzipped folder:
 
+
:{{Code|The assembly mscorlib.dll was not found or could not be loaded.}}
+
:{{Code|It should have been installed in the `/usr/lib/mono/1.0/mscorlib.dll' directory.}}
+
 
+
In this case, you need to install these two packages:
+
 
+
<div class="source">
+
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
apt-get install libmono-corlib1.0-cil
+
cd /path/to/unzipped/folder
apt-get install libmono-system1.0-cil
+
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
+
and install the Phidget Python libraries:
 
+
Here we found these packages to work by working through the tree structure.  As a general rule, you can find these dependencies by using install (here, {{Code|apt-get install mono-complete}}) to get a sense of the package tree structure.  This will possibly tell you that the packages are broken, but at the same time this will list the dependencies of the packages.  Trying to install individual dependencies will show you that although a root-package fails, the sub-packages will sometimes succeed, and install what you need.
+
 
+
If you want to use a specific dll or library that is not available in this reduced version of mono, you can install mono complete by switching from Emdebian+Debian to just Debian.  To do this:
+
 
+
In {{Code|/etc/apt/preferences}} make the following changes:
+
:{{Code|Package: *}}
+
:{{Code|<nowiki>Pin: release a=stable</nowiki>}}
+
:{{Code|Pin-Priority: 1010}}
+
+
In {{Code|/etc/apt/sources.list/mutistrap-debian.list}} remove the emdebian line.
+
 
+
Apply the changes:
+
 
+
<div class="source">
+
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
apt-get update
+
python setup.py install
apt-get dist-upgrade
+
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
 
  
Many packages will be 'downgraded' from the emdebian to debian versions.  Delete the {{Code|<nowiki>/etc/apt/preferences</nowiki>}} file and install mono-complete:
+
You're now ready to begin programming! Continue through this guide for code examples and directions on where to go next.
  
<div class="source">
+
{{hiddenh5|Method 2: Use a USB Key}}
<syntaxhighlight lang=bash>
+
apt-get install monodoc-http mono-complete
+
</syntaxhighlight>
+
</div>
+
  
Choose monodoc-http explicitly, because otherwise the install fails on monodoc-browser.
+
Copy the [{{SERVER}}/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.
  
After this process, you can compile your C# Code.cs Phidget source file the same way as on a generic [[Language - C Sharp#Linux|Linux with Mono]] system. Please refer to that page on how to obtain the *.dll Phidget resource file and compile your code.  On the SBC, however, because you are already running as root (the Super User), you do not need 'sudo' and indeed the SBC will give you an error if you use it.  Instead, compiling and running will look like:
+
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):  
 
+
<div class="source">
+
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
gmcs Code.cs -r:Phidget21.NET.dll
+
cd /media/usb0/
mono Code.exe
+
python setup.py install
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
 
  
==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.
+
==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]].
  
First, you will by default be running on the SBC as '''root''', which is the super-user.  For Linux users, this probably makes you nervous because you know you can overwrite important system files without the system asking for additional permission. As a Windows or Mac OS user - although you may usually run your computer as an administrator - your familiar system usually prompts you to confirm before you do anything really dangerous, and this will '''not''' happen on the SBC as the root user.
+
===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:
 +
*[{{SERVER}}/downloads/phidget22/examples/java/Manager/Phidget22_HelloWorld_Java_Ex.zip Java HelloWorld Example]
 +
*[{{SERVER}}/downloads/phidget22/libraries/any/Phidget22Java.zip phidget22.jar]
  
Next, there is no installed help on the SBC.  Help on Linux is usually called 'man pages' which is short for 'the manual pages'.  On a full Linux system, usually if you need help with any command you can type, for example, {{Code|man ls}} and it will give you help with the program [[#ls|ls]].  But these help pages take up significant space, and they are widely available online.  So, if you need more help with a certain command, you can always type {{Code|man command}} into your favourite search engine.
 
  
Finally, the SBC has no windowing system.  For Linux users, this means no X-windows (Gnome, KDE, etc).  And as a Windows or Mac user, you can think of it as running all of your programs and commands through the terminal or DOS prompt command line.  The SBC provides all of the functionality of an operating system (e.g. process scheduling, file management, etc) but without any graphical interface.  The only exception is the [[#SBC Web Interface|web interface]], which gives graphical access to a limited part of what the SBC can do.
+
Next, follow these steps:
  
===Some Useful Commands===
+
1. Place phidget22.jar on your development machine in a directory that you will use to compile your Java files.
  
If you are doing more with the SBC than simply running pre-written programs [[#Writing a Phidget Program|in Java to run continuously from boot]], you will be interacting with the SBC's Linux operating system over the command line by using [[#SSH|SSH]].  This section discusses useful programs already installed on the SBC, and how to run them on the command line.
+
2. Copy the HelloWorld.java file from the example package to the same directory.
  
====ls====
+
3. Compile the HelloWorld.java file. If you are using a Windows machine, type the following into the command prompt:
 
+
<syntaxhighlight lang=bash>
The '''ls''' program lists the contents of a directory.
+
javac -classpath .;phidget22.jar HelloWorldExample.java
 
+
It will show both files and folders, but not files that start with a "." (these are hidden files on Linux).
+
*If you also want to show hidden files, use {{Code|ls -a}}
+
*If you want more information, such as size and date modified, use {{Code|ls -l}}
+
*Commands can be combined, like {{Code|ls -al}}
+
 
+
====cd====
+
 
+
The '''cd''' program changes to a new directory.
+
 
+
For example, {{Code|cd /root}} changes into the directory at the base of the file tree called ''root''.
+
 
+
Note:
+
* 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====
+
 
+
The '''pwd''' program prints the current directory you are working in.  ('P'rint 'W'orking 'D'irectory)
+
 
+
For example:
+
:{{Code|root@phidgetsbc:~# pwd}}
+
:{{Code|/root}}
+
 
+
====cp, mv, and rm====
+
 
+
These programs are copy ('''cp'''), move ('''mv'''), and remove ('''rm''').
+
 
+
Copy copies a file from one location and pastes it to another.
+
 
+
For example, if you have a file {{Code|data.txt}}, typing {{Code|cp data.txt data_backup.txt}} will put a copy of the file {{Code|data.txt}} into {{Code|data_backup.txt}}
+
 
+
Move moves a file (this is also useful for renaming files) to a new destination.
+
 
+
For example, if you have a file {{Code|data.txt}}, typing {{Code|mv data.txt data_backup.txt}} will put the contents of {{Code|data.txt}} into {{Code|data_backup.txt}}, and then will remove {{Code|data.txt}}.
+
 
+
Remove deletes a file.
+
 
+
For example, typing {{Code|rm data.txt}} will delete {{Code|data.txt}}.
+
 
+
Note that '''rm''' is final.  Once you remove a file using {{Code|rm}}, it is gone forever.  There is no recycle bin, no temporary trash, nothing other than backups you may have personally created in the past!
+
 
+
Directories can only be removed with {{Code|rmdir}}, and then only if they are empty.  If you want to remove a directory and all the files in it, use {{Code|rm -rf directory}} but be '''very, very careful''' with this command.  Trying to remove everything within a directory (e.g. {{Code|rm -rf *}}) is one of the most dangerous commands you can run on a Linux system, as running it from the wrong directory will result in Linux happily removing everything under that directory -- which could be your entire filesystem.
+
 
+
====find====
+
 
+
The '''find''' program does what it says - it finds things.
+
 
+
Unfortunately for the casual user, the find program is very flexible and powerful, and thus not especially intuitive to use.  But, here are some examples:
+
 
+
{| 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}}
+
|}
+
 
+
====grep====
+
 
+
The '''grep''' program takes text input and searches for a term.
+
 
+
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">
+
<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)
+
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
+
If you are using a Linux or macOS machine, type the following into the terminal:
 
+
<syntaxhighlight lang=bash>
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:
+
javac -classpath .:phidget22.jar HelloWorldExample.java
 
+
<div class="source">
+
<syntaxhighlight lang=text>
+
root@phidgetsbc:~# mount | grep sda1
+
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
+
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
 
 
====nano====
 
 
The '''nano''' program is a small text editor that you can use within an SSH terminal.
 
 
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).
 
 
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:
 
 
[[File:sbc_nano_python.png|link=|alt=]]
 
 
====apt====
 
 
The '''apt''' program allows you to install, uninstall, upgrade, and search software available for the SBC.
 
For a non-Linux user, the apt framework may be daunting at first, but it actually allows you to keep your system up to date and install and manage software quickly, easily, and for free.
 
 
'''Note:''' Before installing anything on the SBC, make sure that the ''Include full Debian Package Repository'' option is checked in the web interface under {{Code|System &rarr; Packages}}.
 
 
{| style="border:1px solid darkgray;" cellpadding="15px;"
 
|-
 
! SSH Command
 
! What it Does
 
! 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}}
 
|-
 
|}
 
 
====mount====
 
 
The program {{Code|mount}} shows you all of the mounted devices on your SBC. 
 
 
For example:
 
 
<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)
 
</syntaxhighlight>
 
</div>
 
 
For the non-Linux user, the concept of a device may be quite strange.  To give a short summary, everything on Linux that you can read or write is a file.  Webcams are files (i.e. you can 'read' photos from them), USB keys are files, and each filesystem (tmp storage, the kernel portion, the main filesystem) are also themselves files.  These files specify what and how something can be written.  These are not necessarily linear, for example, you can see above that the USB key ({{Code|/media/usb0}} is mounted ''within'' the root file system {{Code|rootfs}} which is /. 
 
  
So mount gives you an idea of what devices have been 'mounted' for reading or writing, and how you can read and write to them.  More information on mount (and its various forms, like {{Code|umount}}) is available widely around the Internet.
+
You should now have the following class file:
 +
*HelloWorldExample.class
  
====which====
 
  
The program {{Code|which}} tells you if and where a program is installed.
+
4. Using the SBC Web Interface, create a new project called HelloWorld:
  
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.
 
  
===Some Useful Commands to Install===
+
[[File:Phidgetsbc_createproject.PNG|link=|alt=|center]]
  
These are other programs you may find useful on the command line.  Although they are not on the SBC by default, these and other programs can usually be installed simply by using [[#apt|apt-get install]], with the exception of gcc.  For example, {{Code|apt-get install wget}} will download and install [[#wget|wget]]. 
 
  
'''Note:''' This section and the section on [[#Some Useful Commands|pre-installed commands]] can hardly cover all of the complexities and power of the Linux operating system.  There are many excellent tutorials online, and between them and using [[#apt|apt]] to find and install programs you should be able to learn a lot and perform any number of complex useful tasks.
+
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:
  
====gcc====
 
  
The '''gcc''' program is the C compiler for Linux.
+
[[File:Phidgetsbc_runprogram.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.
+
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
  
====less====
 
  
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.
+
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]].
  
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.
+
===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 {{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:  
+
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:
:<code>less Program.c | grep var</code>
+
*nano - ''recommended for beginners, already installed''
 +
*vi  - ''advanced, already installed''
 +
*emacs - ''advanced, needs to be installed''
  
====wget====
 
  
The '''wget''' program allows you to get an online file (over http) and download it to the SBC.
+
Next, follow these steps:
  
For example, to get the source file (HTML) from the Phidgets home page, you can type:
+
1. If you haven't already, connect to the SBC using SSH or a keyboard and monitor.
  
<div class="source">
+
2. Download the [{{SERVER}}/downloads/phidget22/examples/java/Manager/Phidget22_HelloWorld_Java_Ex.zip Phidget Java HelloWorld Example] to the SBC.
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
wget http://www.phidgets.com
+
wget http://examples_link
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
 
  
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]].
+
3. Unpack the examples
 
+
===Writing a Phidget Program===
+
 
+
We provide two ways to write and upload a Phidget Program:
+
# The [[#SBC Web Interface|web interface]]:
+
#* This is useful for simple projects written in Java that you want to start only at boot
+
#* You can also use C projects, but they must be compiled off the SBC for an ARM processor
+
# Over [[#SSH|SSH]], which will allow you to write or transfer source code directly to and from the SBC
+
#* This is useful for all other projects, such as:
+
#** Projects that run at scheduled times (e.g. once per minute)
+
#** Projects that use languages other than Java or ARM-compiled C
+
Note that you can still run an [[#SSH|SSH]] project at boot, you just have to write and install a startup script.  This is a bit complex, but we do have an example that starts the program {{Code|phidgetwebservice21}} [[OS - Linux#As A Service|at boot using a script]].
+
 
+
Once you know which method you'd like to use, you can continue on to learn how to [[#Program in Java with the Web Interface|Program in Java with the Web Interface]], or how to [[#Program with SSH|Program with SSH]] using Java, C, or Python.  If you are actually typing in source code on the SBC, you'll find our [[#Developing Code on the SBC|developing code on the SBC section]] useful.
+
 
+
====Program in Java with the Web Interface====
+
 
+
To show how to write, compile, and install Java programs on the SBC, we'll use the [[Language - Java|Java Hello World]] example code.  You can download the HelloWorld example by downloading the whole [{{SERVER}}/downloads/examples/JavaJNI.zip Java example package].  Make sure you have [[#Installing C/C++ and Java|Java installed on the SBC]].
+
 
+
Here's how to get the HelloWorld code running on the SBC.  On your external computer:
+
 
+
1. Download the SBC version of the Phidget Java libraries ({{Code|phidget21.jar}}).  You can download this from the [[#SBC Web Interface|web interface]], on the page under {{Code|Projects &rarr; Projects}}, under the '''Notes''' section.
+
 
+
2. Place the SBC version of {{Code|phidget21.jar}} into a directory on your external computer.  This will be your working directory that you will use to compile the Java files.
+
 
+
3. Also copy the {{Code|HelloWorld.java}} file into that working directory.
+
 
+
4. Compile the {{Code|HelloWorld.java}} file from within that working directory.  From the command line prompt on Windows, this will be:
+
<div class="source">
+
<syntaxhighlight lang=bash>
+
javac -classpath .;phidget21.jar HelloWorld.java
+
</syntaxhighlight>
+
</div>
+
In a terminal on Linux or Mac OS, this will be:
+
<div class="source">
+
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
javac -classpath .:phidget21.jar HelloWorld.java
+
unzip examples_filename
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
 
  
5. You should now have three compiled class files: {{Code|HelloWorld.class}}, {{Code|HelloWorld$1.class}}, and {{Code|HelloWorld$2.class}}.  You don't need to try and run them, and if you do you may encounter an error because the SBC {{Code|phidget21.jar}} may be slightly different than the Phidget support you have installed on your external computer.
+
4. Compile the HelloWorldExample.java example:
 
+
Now we move onto the SBC:
+
 
+
6. Create a new project on the SBC, in the web interface under {{Code|Projects &rarr; Projects}}.  Call it HelloWorld:
+
 
+
[[File:sbc_create_project.png|link=|alt=]]
+
 
+
7. On the next screen, you will be prompted to upload your files.  We will upload the three Java class files, and then click the {{Code|Start}} button:
+
 
+
[[File:sbc_web_run_project.png|link=|alt=]]
+
 
+
8. You'll note that as it runs, there are two links below the {{Code|Stop}} button: One called {{Code|stdout}}, which is ''Standard Output'', and one called {{Code|stderr}}, which is ''Standard Error''.  Usually, when you run a program on the command line, you see both standard out and standard error at the same time - i.e. you get all program output right there in your terminal or command prompt.  But when running a program in the background, Linux splits the output up into normal output and error output as this is very useful for debugging (i.e. you can check if standard error is empty). 
+
 
+
Here, however, if you're not sure whether the program will run correctly, you should first check {{Code|stderr}} to see if any errors were generated, and then check {{Code|stdout}} to see if the output looks as expected.
+
 
+
To write your own Java program, follow the same process but use your own source code instead of the {{Code|HelloWorld.java}} example.
+
 
+
Now that you have a running program, we offer additional help on [[#Via the Web Interface|running a program automatically using the web interface]].
+
 
+
====Program with SSH====
+
 
+
Similarly to starting a program via the [[#Program in Java with the Web Interface|web interface]], we use the Phidget Java {{Code|HelloWorld}} example here.
+
 
+
Make sure you have [[#Installing C/C++ and Java|Java installed on the SBC]].  To compile and run the {{Code|HelloWorld}} example:
+
 
+
1. Open an [[#SSH|SSH terminal]] to the SBC
+
 
+
2. Download the [{{SERVER}}/downloads/examples/JavaJNI.zip Phidget Java Examples] to the SBC, using [[#wget|wget]] (you may need to install {{Code|wget}} using [[#apt|apt]].)
+
 
+
3. Unpack the examples using [[#unzip|unzip]] (you may need to install {{Code|unzip}} using [[#apt|apt]].)
+
 
+
4. The location of {{Code|phidget21.jar}} on the SBC is {{Code|/usr/share/java/phidget21.jar}}.  Within the unzipped example directory, compile the {{Code|HelloWorld.java}} example:
+
 
+
<div class="source">
+
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
javac -classpath .:/usr/share/java/phidget21.jar HelloWorld.java
+
javac -classpath .:/usr/share/java/phidget22.jar HelloWorldExample.java
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
 
  
5. To run the {{Code|HelloWorld}} program, use:
+
5.Run the HelloWorldExampleprogram:
 
+
<div class="source">
+
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
java -classpath .:/usr/share/java/phidget21.jar HelloWorld
+
java -classpath .:/usr/share/java/phidget22.jar HelloWorldExample
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
 
  
Now that you have a running program, you'll probably want to learn to [[#Running a Program Automatically|run this Java program automatically]].
+
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.
  
'''Permissions Note:''' If you're used to using Linux with Phidgets already, you'll probably notice that you don't need to switch into root using {{Code|sudo}} on the SBC in order to run programs.  This is because you already are running as root, not because the [[OS - Linux#Setting udev Rules|udev rules are set up]].  So if you set up another user, or [[#Via Cron|run a cron job]] as anything other than root or system, you'll need to add permission for the Phidget program to run in your [[OS - Linux#Setting udev Rules|udev rules]].
+
===Running a Program Automatically===
 +
After testing your program, you will likely want it to run on boot, or on a schedule, without your input.  
  
====Developing Code on the SBC====
+
====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]].
  
When you're not just using pre-written source code, and you're writing code actually on the SBC itself, you'll probably want to use [[#nano|nano]].  Other terminal editors on the SBC include {{Code|vi}} which is already installed, and {{Code|emacs}}, which you can install using [[#apt|apt]].  Both {{Code|vi}} and {{Code|emacs}} are much more efficient for the experienced user, but they contain modes and keyboard shortcuts that can seem strange or almost hindering to the casual user.
 
  
Regardless of which editor you choose to use, some of your keyboard habits may not transfer well.  For example, in the Linux command line, the command {{Code|Ctrl-C}} means ''stop the currently running program'', (i.e. your open editor) not copy.  Within most SSH terminals, you can copy and paste using the right-mouse button, and on some terminals (and all native Linux terminals) you can copy by simply highlighting text, and you can paste it using the middle (scroll) mouse button.  On the other hand, if you write a program that hangs on the command line, {{Code|Ctrl-C}} can actually be useful to terminate it.
+
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:
  
Also {{Code|Ctrl-Z}} does not mean ''undo'', rather it means ''run the current program in the background''.  This is useful because running a program in an SSH terminal simply hangs your SSH input until the program is done.  So typing {{Code|Ctrl-Z}} while the program is running frees up the command line for more input.  But if you accidentally hit {{Code|Ctrl-Z}} while running an editor like [[#nano|nano]], the editor will immediately exit to the command line.  Don't worry though, it will not stop or lose your work.  You can bring it back up by using the {{Code|fg}} (e.g. 'foreground') command, like {{Code|fg nano}}, and this will automatically bring your nano process back to the front.
 
  
===Running a Program Automatically===
+
[[File:phidgetsbc_runonboot.PNG|link=|alt=|center]]
  
For testing your program, you will certainly want to run it via [[#SSH|SSH]] or via the {{Code|Start}} button on the project page on the web interface until you are quite sure it runs well.  However, eventually you will probably want the program to run without your input, either [[#Via the Web Interface|continuously, and starting at boot]], or via a task scheduled to [[#Via Cron|run to completion at certain times]].
 
  
Both have their advantages and disadvantages.  Usually, you would want to use the continuous, from-boot methods for event driven code that has to handle a wide variety of user input that could occur at any time.  You would want to use the scheduled method when the SBC needs to perform a repeated task (e.g. reading sensor data) again and againThe main difference is:
+
We will review some of the options that are shown in the image above:
* With the continuous (boot) method you can have any Phidgets (including sensors, LEDs, input switches, etc) attached and giving events to your code all the time, and
+
*Startup Order: lower numbers boot first. Booting later means more programs are available for use, booting earlier means other programs can use your program.   
* With the scheduled (cron) method you have much less of a chance to run into long-term memory management and instability problems with any code you write, because your program runs for only a short time before exiting and getting cleaned up.
+
*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.
  
====Via the Web Interface====
+
After saving your changes, your program will run automatically whenever your SBC boots.
  
To use this method, you must have created the program you want to run as [[#Program in Java with the Web Interface | a Java or ARM-compiled C project in the web interface]].  If you would like to use another language, or another way of uploading your project, but you still want to start at boot and run continuously, you will need to use a [[#Via a Boot Script|boot script]].
+
{{hiddenh5|Automatically Running Python Code}}
  
In the web interface, go to the {{Code|Projects}} tab, and click on the project you would like to run.  Near the bottom of the project page (the one with the {{Code|Start}} and {{Code|Stop}} buttons at the top), there will be a section called {{Code|Startup Settings}}.  You can see a screenshot of the whole project page, including these settings, in the [[#Program in Java with the Web Interface | web interface project section]].
+
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:
  
Select the {{Code|Enabled}} radio button.  The other defaults should be fine, unless you specifically know otherwise:
+
<syntaxhighlight lang=python>
* For ''Boot Order'', lower numbers boot first.  Booting later means more programs are available for use, booting earlier means other programs can use your program. 
+
#!/usr/bin/python
* ''Run as a daemon'' starts the program as a daemon, which is a program that runs in the background.  Unless you have ''explicitly'' written your program as a daemon, leave this checked.  (If you don't know what a daemon is, don't worry, you haven't written one, so leave it checked.)  ''Un''checking this when your program is a normal program will cause the SBC to hang while booting.
+
</syntaxhighlight>
* The ''Executable or Class'' name should be automatically sensed to be your main Java class
+
* ''Arguments'' are any command line arguments you need, just as you would type them into the command line
+
  
'''Note:''' Your program must be very, very stable to run properly via the web interface.  Imagine your program running continuously for days, or months on end.  Any memory leaks, over time, will render your program (and the SBC) unusable until a reboot. Counts or other variables that increase within your program and never reset may create a segmentation fault eventually.
+
====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.
  
If, for stability purposes, you want your program to start, run for a little while, and then exit so that the SBC operating system can clean up the memory each time, you'll probably want to use [[#Via Cron|Cron]] to run your program instead.
 
  
====Via Cron====
+
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.
  
Cron can automatically schedule programs - known as 'jobs', or 'cron jobs' - at most once per minute.  Less often than that, it is very flexible, allowing you to run it on certain months, weekdays, hours, etc.  Cron simply reads a special file (your {{Code|crontab}}) and runs whatever programs are listed, with whatever timing they are listed with.  The cron program runs all the time in the background, making it what is known as a Linux ''daemon'', but the programs it starts as jobs run only as long as they naturally would, and then they exit.
 
  
If you need your program to run more often than once per minute, have the program schedule itself while still running.  For example, to run every five seconds, run a fast loop,  and sleep for five seconds. Do this twenty times and exit.  Then schedule this once per minute using cron, and your program will in essence run every five seconds.
+
First, set your editor to nano:  
 
+
Setting up a cron job simply entails editing your {{Code|crontab}} file.
+
 
+
First, you'll probably want to specify your default editor to be [[#nano|nano]]. Otherwise it will default to {{Code|vi}} and you'll have to figure out {{Code|vi}} in order to add lines to your crontab:
+
 
+
<div class="source">
+
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
 
export EDITOR=nano
 
export EDITOR=nano
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
+
Next, edit your crontab file:
 
+
Then, to edit your crontab file, simply type:
+
 
+
<div class="source">
+
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
 
crontab -e
 
crontab -e
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
+
Finally, schedule your cron job:
 
+
Each line of the crontab file is one scheduled job.  Lines that start with a hash "#" are comments and are ignored.  There is an example line in the crontab, and a reminder line at the very end.  Essentially, each line should contain:
+
 
+
<div class="source">
+
 
<syntaxhighlight lang=text>
 
<syntaxhighlight lang=text>
minute hour dayOfMonth month dayOfWeek  command
+
#cron job that will run at 5AM every week:
 +
0 5 * * 1 /root/code/myprogram argument1
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
 
  
Where:
+
[[File:phidgetsbc_cronjob.PNG|link=|alt=|center]]
*{{Code|command}} is the program you want to run (with absolute path, and arguments)
+
** For example, {{Code|./myprogram argument1}} won't work, but {{Code|/root/code/myprogram argument1}} will
+
* Each time argument is either a number, a list of numbers separated by commas, or an asterisk
+
** For example, * * * * * means every minute for all days and months, 0,30 * * * * means every thirty minutes (i.e. at the top of the hour and at 30 minutes in) for all days and months
+
  
If you already have jobs scheduled, you'll see them in the file that comes up.  You can edit, add, or delete. 
 
  
After you save, you'll see a little message back in the terminal that says the new crontab file was installed, and it is now scheduled!  Cron always starts every boot, and so if you have edited and installed your crontab as above, the scheduling of your program will start properly even after a reboot of the SBC.  However, if you are having strange scheduling problems, you may want to familiarize yourself with the [[#Software Details|software details]] of how the SBC as a whole determines the current date and time.
+
After entering your task, simply save and exit the file.
  
=====My Cron Job Doesn't Work!=====
+
====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]].
  
It is actually very common for a script or program to work on the command line but then ''not'' work as a cron job.  The most common reason for this, by far, is that you specify ''relative'' paths in your program to access files rather than ''absolute'' paths.  For example:
+
===Programming===
* {{Code|code/project.c}} is a relative path (bad for cron)
+
Ready to write some code? Select one of the programming languages below:
* {{Code|/root/code/project.c}} is an absolute path (good for cron)
+
*[[Language - C|C]]
The cron jobs are ''not'' executed from your home directory, or your code directory, so they will not be using the same location you may be using to test your code.  So always use absolute paths.
+
*[[Language - Java | Java]]
 +
*[[Language - Python | Python]]
 +
*[[Language - JavaScript | JavaScript]]
 +
*[[Language - C_Sharp | C#]]
  
Another common reason is you may be using environment variables or other settings that are true in a terminal but are ''not'' true by default in the raw system.  You can end up taking many things for granted in a shell, for example the shortcut "~" means home directory in a shell, but not by default in the raw system. The things that get loaded for a shell (but which are not present in the raw system) are:
+
==Phidget Network Server==
* The settings loaded by {{Code|/etc/profile}}
+
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.
* Any settings in {{Code|~/.bashrc}}, which is nothing by default on the SBC
+
  
On a full Linux operating system, you would use the logs written to by cron to find the error output and debug it.  On the SBC, however, cron does not write logs (otherwise, these logs would eat up the SBC memory very quickly even for routine jobs). For short-term debugging, you can write output from your program to a file, and read that file afterwards to figure out what your program is doing.
+
===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:
  
====Via a Boot Script====
 
  
If you want to run your program constantly and for it to start at boot like the [[#Via the Web Interface|web interface would do]], you can install your program into the boot order using a script. This is a somewhat involved process, and you should be familiar with shell programming in Linux.  For this process, we only offer a [[OS - Linux#As A Service|similar example]] which installs and runs the program {{Code|phidgetwebservice21}} within the boot sequence.
+
[[File:phidgetsbc_networkserver.PNG|link=|alt=|center]]
  
===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.
+
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 web interface 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=]]
+
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]]
  
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}}):
+
====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]]
  
<div class="source">
 
<syntaxhighlight lang=bash>
 
root@phidgetsbc:~# mount | grep usb
 
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
 
</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.
+
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:
  
'''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.
+
1. Open the Phidget Control Panel on your client computer. You will see something like this:
  
===Saving and Retrieving Data===
 
  
This section covers getting data on and off of the SBC.  There are two main methods of simply moving data on and off the SBC - via a [[#Via a USB Key|USB key]], and via [[#Over the Network (SCP)|copy over the network]] - and a third method for moving and installing data when it concerns [[#Backing Up Your Data|backing up lower level system data]].
+
[[File:Phidgetsbc_networkserver_windows.PNG|link=|alt=|center|]]
  
====Via a USB Key====
 
  
After plugging in a USB data key, first you need to [[#Using USB Data Keys | find out the location]] where that data key was mounted.
+
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.
  
Let's say the location of the USB key is {{Code|/media/usb0/}}, and we want to copy the file {{Code|data.txt}} to the USB key.  Your SSH session might look something like this, using [[#ls|ls]] and [[#mount|mount]]:
+
====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]]
  
<div class="source">
 
<syntaxhighlight lang=bash>
 
root@phidgetsbc:~# ls
 
data.txt
 
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)
 
root@phidgetsbc:~# cp data.txt /media/usb0/
 
</syntaxhighlight>
 
</div>
 
  
The '''cp''' program copies data from a source to a destination.  The syntax is {{Code|cp from to}}, where here we are copying from {{Code|data.txt}} to {{Code|/media/usb0/}}.
+
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:
  
'''Caution:''' Even if there is no USB key mounted at {{Code|/media/usb0/}}, this use of {{Code|cp}} will still work ''with no errors''!  This is because there is still a file called {{Code|/media/usb0/}}, there is just no USB key file system ''mounted'' to that point. So be sure to run [[#mount|mount]] or use some other method of determining that there is, in fact, a USB data key attached and where it is mounted to.
+
1. Open the Phidget Control Panel on your client computer. You will see something like this:
  
====Over the Network (SCP)====
+
[[File:Phidgetsbc_networkserver_macos.PNG|link=|alt=|center|]]
  
SCP is a command line program already installed on Linux and Mac OS, and downloadable for free on Windows. We discuss it and give examples in the [[#SSH|SSH]] section, but remember it here when you're trying to get data on and off of the SBC. With SSH or a terminal already open, you'll probably find it to be much faster and easier than dealing with a USB key.
+
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.
  
====Backing Up Your Data====
+
====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]]
  
For the web interface, you can save and restore all web interface settings under the {{Code|System &rarr; Backup & Restore}} tab.
 
  
To save the settings of what packages are installed for later re-installation, you can type:
+
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:
 
+
<div class="source">
+
<syntaxhighlight lang=bash>
+
dpkg --get-selections > installedPrograms.txt
+
</syntaxhighlight>
+
</div>
+
  
Then save the file {{Code|installedPrograms.txt}} externally.  If you have to completely wipe the SBC, you can just reinstall the whole list by moving the {{Code|installedPrograms.txt}} file back onto the SBC, and then typing:
+
1. From the terminal, type in the following command:
  
<div class="source">
 
 
<syntaxhighlight lang=bash>
 
<syntaxhighlight lang=bash>
dpkg –set-selections < installedPrograms.txt
+
phidget22admin -s
apt-get dselect-upgrade
+
 
</syntaxhighlight>
 
</syntaxhighlight>
</div>
 
  
Also remember to externally save:
+
You will now see something like this:
* Your {{Code|~/.bashrc}} settings file if you've changed it
+
* Your {{Code|crontab}} file if [[#Via Cron|you've edited it]]
+
* Any data files or code you've created
+
  
It is important to save these settings often, and at points where you know the system is running well.  It may be tempting to create a backup right before you [[#Recovery System|wipe the SBC and start from scratch]], but often the reason you are having problems then is some setting or change, and backing these up and reinstalling them will only reinstall the problem.
 
  
To truly back the files up, you must copy them to an external computer or location using either a [[#Via a USB Key|USB Key]] or [[#Over the Network (SCP) | over the network]].  Then they can be copied back if needed later.
+
[[File:Phidgetsbc_linuxphidgetadmin.PNG|link=|alt=|center|]]
  
If you are looking to restore data on an SBC that will not boot properly, you'll want to be in the [[#Partial Recovery|partial recovery]] portion of our Troubleshooting section.
 
  
==Troubleshooting==
+
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 SBC can be quite tricky to debug, because it is a complex and flexible computer.  Common problems and solutions include:
 
* You can't find the SBC on the network at all - refer to the [[#Initial Internet Setup|Initial Internet Setup]] section
 
* You have changed some setting or file such that the SBC doesn't run anymore, or doesn't run as expected - refer to the [[#Recovery|Recovery]] section
 
  
If you are having trouble using Phidgets on the SBC, you should go through the [[OS - Linux#Troubleshooting | Troubleshooting section on the general Linux page]]. Some of the problems on the Linux page (such as library problems) are easier to fix by simply working through the [[#Recovery|Recovery]] section when they occur on the 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|programming languages]] above.
  
Namely, it often helps to simply perform a [[#Factory Reset|factory reset]] on the SBC (save your files and installed program list first, as [[#Backing Up Your Data|described here]]).  Sometimes you change a file or setting within the operating system when you are trying to get something up and running, and this unintentionally affects other programs too.  Performing a factory reset starts you with a clean slate.
+
==Advanced Information==
 
+
===Writing Image to SD Card===
If your problem doesn't seem to be fixed by these steps, or the information within this guide, please [[Contact Us|ask us]]!
+
{{SDCardImage}}
 
+
===Initial Internet Setup===
+
 
+
To set up the SBC, you almost always need a ''wired'' Ethernet connection with DHCP (Dynamic Host Configuration Protocol), and without a firewall.  This connection should be to a ''router'', not directly plugged in to your computer.
+
 
+
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.  On a Windows or Mac OS computer, you can bring up the Phidget Control Panel as described in the SBC's [[1072 - Getting Started|Getting Started Page]].  Failing this, or on a Linux computer, we discuss some alternate setup methods in this section.  Keep in mind that without a wired, open DHCP connection these setup methods can be difficult and fickle.
+
 
+
====No Wired-Only Connection====
+
 
+
Sometimes it can work to plug the SBC, using Ethernet, directly into an Ethernet port on your home wireless router.  Do not plug it directly into your computer!  (Although in some instances, a direct connection can be made to work on Linux, see the [[#No DHCP|No DHCP]] section below)
+
 
+
This direct-router method 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.  University libraries in particular can be a good source of wired DHCP connection ports. 
+
 
+
Covering all of the different router configuration possibilities here, and how to change them to make the SBC work, is essentially impossible.  If you try using the SBC at home or at work, the SBC does not work on the first try when plugged directly into the router via Ethernet, and you want to make that connection work rather than seeking out an alternate for the initial setup, you should find documentation specific to your router (usually available online) and properly configure it.
+
 
+
The good news is that if you can find an Ethernet DHCP connection ''just once'' for a short time, you can use that connection to configure the SBC to work on your home wireless network.  During that initial connection, you can enable wireless and set up as many wireless DHCP connections (with passwords) that you need.  Once wireless is enabled and set up, you can take the SBC home to your wireless router and the SBC will automatically seek out and connect to its remembered networks as they appear.  At that point, you can also use wireless like a normal internet, web interface, and SSH connection.
+
 
+
====No Link Local Addressing====
+
 
+
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 DHCP router logs.  From the router logs, you should see the connection (or attempted connection) by the SBC within the logs.  From that log entry, you should either be able to determine the IP address for the SBC, or see what happens when the router blocks access.  The IP address can be used in place of the link local address for both the web interface and for SSH.
+
 
+
====No DHCP====
+
 
+
The SBC will first try to use DHCP, but then it will revert to responding to a link local address under bonjour and avahi.  If you are depending on this, please wait '''at least three minutes''' after the SBC boots for the SBC to fail in obtaining a DHCP connection and properly revert to link local addressing.
+
 
+
If you have a static IP setup, and want to use link local addressing rather than accessing the router logs, this should usually work by default on Windows and Mac OS (e.g. type the address such as {{Code|phidgetsbc.local}} into a web browser).  If it doesn't work automatically, there is not much you can do and you should seek out a wired DHCP connection elsewhere.
+
 
+
On Linux, it also should work by default, but you have the additional option of explicitly adding routes that look within the default network settings for the SBC.  From a terminal (as root), type:
+
* {{Code|route add -net 169.254.0.0 netmask 255.255.0.0 dev eth0 metric 99}}
+
* {{Code|route add default dev eth0 metric 99}}
+
You can also compile and use the {{Code|phidgetsbclist.c}} example (use the provided Makefile, don't use gcc) in the [{{SERVER}}/downloads/libraries/libphidget.tar.gz Phidget Linux Libraries] package, under the {{Code|examples}} folder.  This will allow you to see if the SBC is detected on the network at all.  Note that to use this option you must have the Phidget Libraries and the Phidget WebService installed on your Linux computer - in-depth instructions to do this are on the [[OS - Linux|main Linux page]].
+
 
+
===Recovery System===
+
 
+
You can either boot the SBC into recovery mode and attempt to recover files and settings, or you can completely wipe the SBC by performing a factory reset.  If the LEDs do not turn on normally (red on constantly, green on at first start, then off, then on when fully booted) then you'll want to read the [[#Hardware Issues|hardware issues]] section.
+
 
+
====Partial Recovery====
+
 
+
The recovery system can be entered in two ways:
+
# From the {{Code|System &rarr; Backup & Restore}} web interface page.
+
# By holding down the reset button for 20+ seconds - until the green light has switched from flashing slowly to flashing quickly.
+
 
+
The recovery system runs an [[#SSH|SSH]] server where the username and password both are {{Code|root}}.
+
 
+
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 or recover important files before running a full factory reset. From an SSH connection to the recovery system, you can mount the main root filesystem with the following commands (assuming it’s not damaged):
+
 
+
<div class="source">
+
<syntaxhighlight lang=bash>
+
ubiattach /dev/ubi_ctrl -m 6
+
mount -t ubifs /dev/ubi0_0 /mnt
+
</syntaxhighlight>
+
</div>
+
 
+
====Factory Reset====
+
 
+
This restores the kernel and root filesystem from backup, overwriting any changes that may have been made and ''completely wiping the system'' to the state that it got shipped in. (You can save your files and installed program list first, as [[#Backing Up Your Data|described here]].)  This can be enacted one of two ways.
+
# Use the reset button:
+
##Enter the recovery mode by holding down the reset button for 20+ seconds as above (until fast flashing)
+
##Wait for a full boot (i.e. you can see it on the Phidget control panel, or can SSH with username and password as {{Code|root}})
+
##Hold down the reset button again, but this time for only 10 seconds (until slow flashing)
+
##Wait for the SBC to fully reset and reboot (at least three minutes) - the LED will turn off and on again when this occurs
+
##*Note that after a factory reboot the SSH server will be disabled
+
##*Also note that after a factory reboot the SBC creates new SSH keys, and reverts to the {{Code|phidgetsbc.local}} address
+
# Via the web interface, under {{Code|System &rarr; Backup & Restore &rarr; Go button}}, where you can follow the instructions
+
 
+
====Hardware Issues====
+
 
+
The LEDs are an indicator of the hardware working properly.  The normal boot process is:
+
* Red LED: Turns on from moment of power being applied.
+
* Green LED: Turns on momentarily when power applied, then turns off momentarily, then turns on and stays on when booted.
+
 
+
If the green status LED never turns on (or fails to turn on the second time), the boot process is failing somewhere.  This could be due to:
+
* A damaged OS - Try performing a [[#Factory Reset|Factory Reset]]
+
* If this fails, it is likely hardware damage (very difficult to diagnose, please [[Contact Us|contact us]])
+
 
+
If neither LED turns on, hardware damage is even more likely.  Unless the path to the red LED is the one thing that has been damaged, the device is likely not receiving and using power.
+
* Try performing a [[#Factory Reset|Factory Reset]], and if that does not work please [[Contact Us|contact us]]
+
 
+
=====USB Issues=====
+
 
+
On the Phidget SBC2, there is a hardware issue that is unrelated to the LEDs.  It is a USB problem, and manifests in many ways:
+
* Strange behaviour when some devices but not others are plugged in to the SBC
+
* Strange behaviour with combinations of devices
+
* Failure (or intermittent failure) to see Phidgets on the USB hub, or USB keys on the hub
+
 
+
This problem is fixable, either on your own or by sending your SBC back to Phidgets.  For an in-depth solution, see the [[SBC2_USB_Hub_Fix | SBC2 Hub Fix Page]].
+
 
+
===Updating Your SBC===
+
 
+
If you've owned your SBC for a while and want to update your packages, you can run:
+
 
+
<div class="source">
+
<syntaxhighlight lang=bash>
+
apt-get update
+
apt-get upgrade
+
</syntaxhighlight>
+
</div>
+
 
+
...to ''update'' your software source list and then ''upgrade'' to the latest version of all installed software.  If you are used to Mac OS or Windows, note that this does not just update the non-kernel parts of the operating system, it updates every additional piece of software you have installed.
+
 
+
To update the SBC software itself (e.g. the kernel), it is easiest to use the web interface, under {{Code|System &rarr; Backup & Restore &rarr; Go button}}, to enter a page that will give you the option to update.  You will need to have an update file on a USB key inserted into the SBC, of type:
+
* UBI Image (system_ubi.img), or
+
* Kernel image (uImage), or
+
* Phidget Upgrade package containing both UBI and Kernel images (phidgetsbc*.bin)
+
 
+
These are either obtained from the Phidgets website, or are a custom kernel / filesystem that you can create yourself, if you are experienced.
+
 
+
The reason why this information is in troubleshooting is that you should certainly [[#Backing Up Your Data|back up your system]] before trying this.  And, it is quite rare to need to upgrade the kernel or filesystem on the SBC, so something serious should be going on before you attempt it.  Try using the [[#Recovery System|recovery system]] first.
+
 
+
==Programming Languages==
+
 
+
Now that you have the basic libraries installed, you can pick your language and begin programming! 
+
 
+
If you are not using the [[#WebService | webservice]] to control a Phidget over a network, your next step will be to delve into the use of your specific language.  Each page has its own set of specific libraries, code examples, and setup instructions. 
+
 
+
On SBC Linux, we recommend the following languages:
+
 
+
*[[Language - C/C++|C/C++]]
+
*[[Language - Java | Java]]
+
*[[Language - Python | Python]]
+
 
+
These languages may also run on the SBC, but we do not yet directly offer SBC support for them:
+
* [[Language - Ruby|Ruby]]
+
* [[Language - C Sharp|C#]] (using Mono)
+
 
+
You can probably figure out how to install and use them by a combination of the language pages linked above, and the section on [[#Installing Other Languages|installing other languages on the SBC]].
+
 
+
==WebService==
+
 
+
The SBC comes with the [[Phidget WebService]] installed, and the SBC automatically starts the WebService at boot.
+
 
+
To practice using the WebService, and to learn more about it, we have hands-on examples on the [[OS - Linux|general Linux page]], starting in the [[OS - Linux#Using the WebService|using the WebService section]].
+
 
+
==Advanced Uses==
+
 
+
===Using a Different Wireless Adapter===
+
 
+
The support for the wireless adaptor that Phidgets sells is written into the SBC kernel.  Hence, we do not support using other adaptors.
+
 
+
However, Linux is very flexible, and it is possible (though not easy) to write a custom kernel for the SBC and add support for a new wireless adaptor.  We can't help you with this, but we do provide some basic guidelines for [[#Custom Kernel and Filesystem|building your own kernel]].
+
 
+
===Using a Different Webcam===
+
 
+
In addition to the webcam that Phidgets sells, you have the option to use many different webcams with the SBC.  There is a [http://www.ideasonboard.org/uvc/#devices long list] of compatible webcams.
+
 
+
The common thread for these webcams is that they use UVC - the USB Video Class - drivers for Linux.  You can then use [[#mount|mount]] to find out what video device your webcam is mounted under.
+
 
+
===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 libcv2.1
+
</syntaxhighlight>
+
</div>
+
 
+
If there is no {{Code|libcv2.1}} package, you can perform {{Code|apt-cache search libcv}} to find the current version.
+
 
+
The opencv libraries can also be used within Python, by installing the link between them:
+
 
+
<div class="source">
+
<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">
+
<syntaxhighlight lang=bash>
+
#! /usr/bin/python
+
 
+
import cv
+
 
+
# The webcam is located at /dev/video0
+
# OpenCV only needs the number after video
+
webcam = cv.CaptureFromCAM(0)
+
 
+
frame = cv.QueryFrame(webcam)
+
 
+
cv.SaveImage("image.jpg", frame)
+
</syntaxhighlight>
+
</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].
+
 
+
'''Note:''' The SBC is probably not as powerful for image processing and transport when compared to your desktop computer.  Try running your image processing code on the SBC from an early point in development.  During those test runs, you can visit the first System page of the [[#SBC Web Interface|SBC Web Interface]] to check the processor and memory use.  For more information on processor power, check the specification for your SBC (on the product page on [{{SERVER}} our main website]) as well as our discussion of [[#Pushing Processor Limits|pushing processor limits]] below.
+
  
 
===Checking System Logs===
 
===Checking System Logs===
Line 977: Line 432:
 
* {{Code|/var/log/dmesg}}
 
* {{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.
 
But don't edit them directly!  Always follow the advice and procedures around the Internet on how to properly log items to syslog.
 
===X Forwarding===
 
 
Although most tasks can be done using the [[#SBC Web Interface|SBC Web Interface]] or [[#SSH|SSH]], you can also set up X11 forwarding on the SBC.  X11 is the window manager base, which provides a graphical windowing system on the SBC.  Although you probably won't connect directly to the X11 manager (i.e. by plugging a screen directly into the SBC), X11 also gives a user the ability to forward graphical windows over SSH.  You will need the following packages installed:
 
* {{Code|x11-common}}
 
* {{Code|xbase-clients}}
 
After installing, make sure that the line in {{Code|/etc/ssh/sshd_config}} has a line that says:
 
:{{Code|X11Forwarding yes}}
 
Then log out and log back into the SBC.  This second time you log in, use the {{Code|-X}} switch to turn on X forwarding for that connection:
 
:{{Code|ssh -X root@phidgetsbc.local}}
 
Then you should be able to run programs that launch a window, and it will launch remotely and appear on the computer you have the SSH connection from.
 
 
===Pushing Processor Limits===
 
 
The SBC, though more powerful than many embedded computers out there, is probably about as powerful as your smartphone.  If you hook up 1 ms Phidget sampling devices to all six of its USB ports, events and packets will probably get lost.  The exact data rates you can accomplish depend on:
 
* What else is running on the SBC
 
* How efficient your code is for external operations (like File I/O)
 
* Other minor details (e.g. the temperature of the SBC, etc)
 
 
If you want to achieve data rates as fast as possible, try these tips:
 
* Program in C, not in an interpreted language (Python, Java, .NET)
 
* Perform file I/O as little as possible.  Locally cache data, manage your writing to a file in a separate thread, and use low-level write calls.
 
* Change the [[#Custom Kernel and Filesystem|filesystem]] to a faster, non-compressed file system.
 
** Alternatively, use a high-data-rate USB key.
 
* Keep other running processes to a minimum.
 
** If you are running code locally right on the SBC, turn off the Phidget WebService.
 
 
===Custom Kernel and Filesystem===
 
 
You can compile your own kernel and flash it to the board. 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.  We have a kernel development kit, complete with patch file and README:
 
* [{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC Kernel Development Package]
 
 
Compiling a new, custom kernel is somewhat complex.  If the SBC is your first experience with Linux, writing a custom kernel will be difficult.  However, it will probably also be very rewarding because you can put whatever you like into it.  We might be able to offer additional suggestions, but ultimately you're on your own here.
 
 
You may be able to write a custom kernel right on the SBC, but the easiest way is to develop the kernel on an external computer.  And the easiest way to develop on an external computer is for that computer to also be Linux, even just in a Virtual Machine.  The time spent loading a copy of Linux into a virtual machine (such as VirtualBox, which is free) onto your computer will probably be less time than setting up a standard compiler on Windows to cross-compile.
 
 
On your external Linux system, you will need:
 
* A cross-compiling toolchain for the ARM processor, which we briefly describe on the [[OS - Linux#Cross-Compiling with a Custom Toolchain | main Linux page]], and
 
* The [{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC Kernel Development Package] from the Phidgets website. 
 
The kernel development kit has a brief README file which describes how to obtain the proper kernel and patch, configure, customize, and build it.
 
 
We have an application guide in progress, which walks through building a custom kernel to add Bluetooth support to the SBC.  Please contact us if you would like more information.  Even if you are trying to add support for hardware other than a bluetooth modem, or wondering if support even exists in the kernel for your modem (3G, alternate wireless, etc) you will probably find the application guide helpful.  Follow it up to the point where you run the program {{Code|menuconfig}} (you don't need an SBC to do this), which will give you a menu of all drivers you can enable in the SBC kernel.
 
 
After making your new kernel, you should have a uImage and modules target for your Makefile.  At this point you can transfer your kernel files onto the SBC, make their targets, and transfer them into the nand memory.  This involves erasing the old kernel, flashing the new kernel, installing the new kernel modules, and rebooting.  From the SBC, in the kernel directory:
 
 
<div class="source">
 
<syntaxhighlight lang=bash>
 
make uImage; make modules
 
flash-eraseall /dev/mtd3
 
nandwrite -p /dev/mtd3 arch/arm/boot/uImage
 
make modules-install
 
reboot
 
</syntaxhighlight>
 
</div>
 
 
Custom kernels can also be flashed from the [[#Recovery System | Recovery System]].
 
 
If you need to create a root filesystem image, the filesystem type is UBIFS, and the commands to create it are:
 
 
<div class="source">
 
<syntaxhighlight lang=bash>
 
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
 
</syntaxhighlight>
 
</div>
 
 
Where {{Code|ubinize.cfg}} contains:
 
 
<div class="source">
 
<syntaxhighlight lang=bash>
 
# 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
 
</syntaxhighlight>
 
</div>
 
 
You then flash ‘system_ubi.img’ (not ‘system_ubifs.img’) from the recovery system.
 
 
Again, like the custom kernel creation, the need to create a custom root filesystem is essentially non-existent except for those advanced users who already know they need it... and furthermore, you are almost entirely on your own.
 
 
==Software Details==
 
 
For even more advanced uses of the SBC, it may help to know the gritty details of the SBC software system.
 
 
;Operating System
 
:Debian/GNU Linux
 
:Kernel 2.6.X or higher (generally kept up to date with latest releases, use {{Code|uname -r}} to check the kernel version)
 
 
;Main Filesystem (rootfs)
 
:UBIFS (a raw flash type of file system)
 
:Mounted in a 460 MB Nand partition (in Read/Write mode)
 
 
;Kernel
 
:uImage format
 
:Has its own 3MiB partition on bare Nand
 
 
;Web Interface Scripts and Configuration Data
 
:Located in {{Code|/etc/webif}}
 
:Modifying these scripts can be done; however, it is very easy to enter invalid data that could cause the system to behave unexpectedly or not boot.
 
 
;User Applications uploaded through Web Interface
 
:Located in {{Code|/usr/userapps}}
 
 
;Webcam Device Location
 
:{{Code|/dev/video0}}
 
:Numbers increase with more webcams
 
 
;Date and Time
 
:Set using ntp (network time protocol) at boot
 
:The ntp daemon continues to run in the background and will periodically update the clock
 
:The network keeps the SBC very close to real time
 
:Also there is a real-time clock with battery backup which will preserve date/time across reboots, power removal
 
:The real-time clock is synced to system time during reboot/shutdown
 
:If power is unplugged suddenly, and the network not restored, the real-time clock may not have the correct time
 
 
;Wireless Networking System
 
:Wireless adapter support for the wireless adapter that Phidgets sells is written into the kernel
 
:It supports WEP and WPA
 
:It is best configured through the configuration interface.
 
 
;Nand Layout
 
:The board contains 512MiB on Nand. This nand is split into 7 partitions as follows:
 
:0: u-boot size: 256K Read Only
 
:1: u-boot_env size: 128K Read Only
 
:2: recovery_kernel size: 2M Read Only
 
:3: kernel size: 3M Writable
 
:4: flashfs size: ~3.625M Read Only
 
:5: recovery_fs size: ~ 43M Read Only
 
:6: rootfs size: ~ 460M Writable
 
: The final size of flashfs/recovery_fs/rootfs depends on the image size at production, and on the number/location of bad blocks in the NAND.
 
: '''Note''': U-Boot and recovery kernel and filesystem cannot be written from Linux - this is a safety measure.
 
 
;Boot Loader
 
:U-Boot is used for setting up the processor and booting Linux, and is only accessible via a serial connection.
 
:Normal users will not need to use or modify it.
 
:Be very careful when modifying the u-boot partition. If it is damaged or overwritten, it is difficult to fix.
 
:When using U-Boot, a prompt will appear via serial shortly after power on. 
 
:The environment variables will help you determine how to boot Linux on the SBC
 
:You can also refer to the [http://www.denx.de/wiki/DULG/Manual U-Boot documentation]
 
 
;Boot Process
 
:From power on...
 
:1. Processor loads first 4 bytes from NAND into Steppingstone and runs it.
 
:2. Steppingstone sets up RAM, copies u-boot from NAND into RAM and runs U-Boot.
 
:3. U-Boot initializes the processor, sets GPIO state, etc., copies the linux kernel into RAM, sets up the kernel command line arguments, checks that the kernel image is valid, and boots it.
 
:4. Linux boots, bringing up USB, Networking, NAND, etc. and then mounts the rootfs NAND partition on /.
 
:5. init gets run as the parents of all processes, as uses the /etc/inittab script to bring up the system. This includes mounting other filesystems, settings the hostname, and running the scripts in /etc/init.d, among other things.
 
:6. inittab then turns the green LED on.
 
:7. inittab then sets up a getty on the first serial port, ready for interfacing using the debug board.
 
 
==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. 
 
 
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.
 
 
This is a problem with the standard embedded Debian automount program, and we have no known fix.
 
 
{{ProblemSolution|Perl Locale Errors on SSH|No Locales Installed}}
 
 
By default, no locales are installed on the SBC.  If you use [[#apt|apt]] a lot to install and manage your software on the SBC, you will get messages like this:
 
 
<div class="source">
 
<syntaxhighlight lang="text">
 
perl: warning: Setting locale failed.
 
perl: warning: Please check that your locale settings:
 
LANGUAGE = (unset),
 
LC_ALL = (unset),
 
LANG = "en_CA.UTF-8"
 
    are supported and installed on your system.
 
perl: warning: Falling back to the standard locale ("C").
 
locale: Cannot set LC_CTYPE to default locale: No such file or directory
 
locale: Cannot set LC_MESSAGES to default locale: No such file or directory
 
locale: Cannot set LC_ALL to default locale: No such file or directory
 
</syntaxhighlight>
 
</div>
 
 
To squelch these messages, you should install and reconfigure your locale like this:
 
 
<div class="source">
 
<syntaxhighlight lang="bash">
 
apt-get install locales
 
dpkg-reconfigure locales
 
</syntaxhighlight>
 
</div>
 
 
The last command will show you a long list from which you should pick your location, by language.  For example, en_CA is english_Canada.  Here in Calgary, we use en_CA.UTF-8 and so for the first question we would input locale "114" and for the second (system) question we would input {{Code|en_CA}} for the locale.
 
 
This might give you a locale undefined error, in which case you can generate the locale (for us, again, it is en_CA):
 
 
<div class="source">
 
<syntaxhighlight lang="bash">
 
locale-gen en_CA
 
</syntaxhighlight>
 
</div>
 

Latest revision as of 19:22, 27 February 2020

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

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:

  1. Ensure Include full Debian Package Repository is checked on the SBC Web Interface (System->Packages)
  2. Install Python
  3. 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

The base Python functionality can be downloaded and installed in one step:

apt-get install python

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:


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:


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:


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:


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

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.