Phidgets Legacy Support - User contributions [en]

File:Midi-Tracks.zip

2015-02-12T15:08:28Z

Kat: Midi tracks for the tutorial on playing midi songs with stepper motors.

Midi tracks for the tutorial on playing midi songs with stepper motors.

File:StepperMidi.zip

2015-02-12T14:58:46Z

Kat: Visual Basic files for running stepper motors as midi instruments

Visual Basic files for running stepper motors as midi instruments

Template:APbox

2015-01-13T17:47:01Z

Kat:

{|
|- valign="top"
|{{{1}}}
|style="width: 10%"|
|{{{2}}}
|style="width: 10%"|
|{{{3}}}
|- valign="top"
|{{{4}}}
|style="width: 10%"|
|{{{5}}}
|style="width: 10%"|
|{{{6}}}
|- valign="top"
|{{{7}}}
|style="width: 10%"|
|{{{8}}}
|style="width: 10%"|
|{{{9}}}
|- valign="top"
|{{{10}}}
|style="width: 10%"|
|{{{11}}}
|style="width: 10%"|
|{{{12}}}
|}

File:MoreInfo.png

2015-01-12T21:12:37Z

Kat:

File:200px-BuyNow.png

2015-01-12T20:42:18Z

Kat:

File:200px-BuyNowII.png

2015-01-12T20:39:36Z

Kat:

Category:Application Guides

2014-12-04T16:11:47Z

Kat: Added a link for people to share their own projects.

These are a selection of in-house projects (and descriptions on how to do them) that we have found useful, or interesting, or both. Be sure to check back from time to time and more will be added in the future.

For more ideas on how you can use Phidgets, read our [http://phidgets.wordpress.com/category/how-tos/ blog's how-to guides] and check out our [http://www.pinterest.com/phidgets/phidgets/ map of Phidgets projects].

Have you got a project? Share it in the [http://phidgets.com/phorum/viewforum.php?f=35 Phidgets Phorums].

Main Page

2014-12-04T16:09:18Z

Kat:

[[Category:Administrative]]__NOTOC__
{| cellpadding="25" cellspacing="20" style="border:0;"
|- valign="top"
| cellpadding="25" style="border:1px solid darkgray;" |
{|
|- valign="center"
| rowspan="2" | [[Image:App_guide_sbcweb_sbc_image.jpg|250px|link=Category:Primer|alt=]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Hardware</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Get extensive hardware information on topics like:
* '''[[Stepper Motor and Controller Primer | Stepper Motors]]''',
* Digital '''[[Digital Input Primer|Inputs]]''' and '''[[Digital Output Primer|Outputs]]''',
* '''[[Solid State Relay Primer|Solid State Relays]]''',
and much, much more in our '''[[:Category:Primer|Primers]]'''<br>

Specifications, photos, and the like can be found back on our '''[{{SERVER}} main website]'''<br>
|}
| style="border:1px solid darkgray;" cellpadding="25px" |
{|
|- valign="center"
| rowspan="2" | [[Image:Manag-inheritedobject.png|200px|link=Software Overview|alt=]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Software</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Compare our supported '''[[Software Overview#Language Support|languages]]''' and '''[[Software Overview#Operating System Support|operating systems]]''' <br>
Learn our method of '''[[General Phidget Programming]]'''<br>
Download the specific API for your language of choice '''[[Software Overview#Language Support|on its wiki page]]'''<br>
Run and modify the software examples '''[[Software Overview#Language Support|for your language]]''' <br>
Use Phidgets over a network with our '''[[Phidget WebService|WebService]]''' and '''[[Phidget Dictionary|Dictionary]]'''<br>
|}
|- valign="top"
| style="border:1px solid darkgray;" cellpadding="25px" |
{|
|- valign="center"
| rowspan="2" | [[Image:fire.png|250px|link=:Category:Application Guides|alt=]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Inspiration</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Read our '''[[:Category:Application Guides|application notes]]''' showing cool projects <br>
View a list of '''[http://www.pinterest.com/phidgets/phidgets/ customer projects]''' that have been submitted <br>
Visit our '''[http://www.phidgets.com/phorum/ forums]''' for more customer projects and to share your ideas <br>
|}
| style="border:1px solid darkgray;" cellpadding="25px" |
{|
|- valign="center"
| rowspan="2" | [[Contact Us|<font style="font-size:150pt;line-height:170pt;color:blue;">?</font>]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Help</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Learn '''[[What is a Phidget?|what a Phidget is]]''' <br>
Start with the ''Getting Started'' guide for your Phidget in its '''[[:Category:UserGuide|user guide]]''' <br>
Visit our '''[{{SERVER}}/phorum/ forums]''' and connect with others <br>
Try out our '''[[General Troubleshooting]]''' guide <br>
Access our '''[{{SERVER}}/content_display.php?content=Policies policies]''' for shipping and return information<br>
Keep your language and operating system '''[[Software Overview|libraries]]''' up-to-date <br>
Discover how '''[[About Phidgets Inc.|Phidgets Inc.]]''' was founded <br>
'''[[Contact Us|Contact us]]''' for support <br>
|}
|}

About Phidgets Inc.

2014-11-26T21:11:45Z

Kat:

'''Quick''': We want you to get your problem solved or your project finished as quickly as possible. The drivers are easy to install, and the Phidgets easy to set up. With a [http://www.phidgets.com/docs/Programming_Resources comprehensive API with code examples] for nearly every device it's easy to write code and have something working in less than an hour. We always have products in stock and we ship fast so you won't have to wait long before you can put your plan into action.

'''Easy''': Phidgets offers a [http://www.phidgets.com/docs/Programming_Resources robust API], making it easy to write a program in your favourite language and have Phidgets working right away. There's no propriety software that you have to download. Applications can be developed in over a dozen languages. Phidgets devices are also easy to set up. These devices are meant for people without an extensive electrical background, so you don’t need to mess around with circuits, just plug in a device and go!

'''Supportive''': Plenty of [http://www.phidgets.com/docs/Category:Primer primers], [http://www.phidgets.com/docs/Main_Page documentation], [http://phidgets.wordpress.com/category/how-tos/ how to’s] and [http://www.phidgets.com/docs/Category:Application_Guides examples] are provided online to help you get your project going. Can’t find the answers? Phidget engineers are available by phone and email, and our [http://phidgets.com/phorum/ Phorums] are a great place to post questions to the community.

'''Cost Effective''': You won’t be able to find higher quality sensors at the price of Phidgets. We focus on making well-engineered devices with affordable components, so you don’t have to break the bank to get something that works. Given Phidgets’ reliability, you won’t need to replace them anytime soon. Basically, you’re getting industrial quality devices at a hobbyist price.

==How it all Started==

[[File:Saul.jpg|link=|left]]

The original idea for [[What_is_a_Phidget%3F|Phidgets]] came from Saul Greenberg, a computer science professor at the University of Calgary, who was researching Human-Computer Interfaces.
His research involved the design and creation of customized computer interfaces that interact with the physical world- for example, a sensor that could detect when someone was working at a computer, causing a physical indicator like a light or a motor to activate. Computer science students do not typically have experience with designing and building electronics, so Saul would enlist electrical engineers to complete research projects by building the electronics and interfacing them with the computers. While this was a reasonable short-term solution, the projects were not self-sustaining. Once the project was complete, the engineer would move on with their studies and the project would inevitably fall into disarray.

To solve this problem, Saul decided to focus his designing and building efforts into specialized modules with a programming interface that would feel comfortable to any software developer. This solution had already been applied previously, particularly with graphical user interfaces (GUIs). The software behind a GUI is extremely complex, but each component (menus, sliders, buttons) is presented to the programmer as a simple, well-documented software object, sometimes called a '''"Widget"'''. Saul's solution mirrored this concept with physical electronics- hiding complexity within a simple package. Any programmer could then build a customized system without having to worry about the minutiae of circuit design and low-level computer interfacing. Because of this similarity, these devices were called "Physical Widgets", or '''"Phidgets"''' for short.

<br clear=all>

[[File:Chester-Mug-shot.jpg‎|right|link=]]

Chester Fitchett started working on Phidgets as an undergrad in the Human-Computer Interface program. The first Phidgets were built by hand, with software written exclusively in Visual Basic 6 for Windows. Students from several universities used these early Phidgets in their academic projects. You can watch videos demonstrating some of these projects [http://grouplab.cpsc.ucalgary.ca/Videos/Phidgets here]. After university, Chester founded '''Phidgets Inc.''', believing that there was a market for Phidgets beyond academic research. The main challenge was adapting the Phidgets concept from something that was "good enough" for a research setting to a finished product that was reliable, user-friendly, and programmable using the most popular [[Software_Overview#Operating_System_Support|operating systems]] and [[Software_Overview#Language_Support|programming languages]].

<br clear=all>

==Who uses Phidgets?==

Today, [[What_is_a_Phidget%3F|Phidgets]] are bought by a wide variety of customers, each with a unique set of goals.

{|
|- valign="top"
|[[File:1018.jpg|link=|left|260px]]
|

'''Schools''' use Phidgets to introduce their students to programming, electronics, and robotics as early as grade eight.

'''Hobbyists''' use Phidgets to build fun projects in their spare time- for example, a sound system that loads different songs based on which [[RFID Primer|RFID tag]] is placed on the surface of the coffee table.

'''Businesses''' use Phidgets to automate company processes, or monitor company machinery.

'''Researchers''' use Phidgets to aid in highly customized experiments- for example, a network of [[1044 User Guide|Spatial Sensors]] to monitor earthquake activity across a city.

'''Entrepreneurs''' use Phidgets to prototype their product ideas.
|}

File:Chester-Mug-shot.jpg

2014-11-26T21:10:52Z

Kat:

File:Phidgetsheader.jpg

2014-09-10T15:14:43Z

Kat: A phidgets header for landing pages and newsletters.

A phidgets header for landing pages and newsletters.

File:Temperaturelog.c

2014-08-11T19:07:19Z

Kat: For the logging to usb flash drive on SBC post: http://wp.me/p4iBI4-lV

For the logging to usb flash drive on SBC post: http://wp.me/p4iBI4-lV

Weather Station

2014-06-05T13:38:33Z

Kat:

[[Category:batteryPower]]
[[Category:solarPower]]
[[Category:phidgetsSBC]]
[[Category:fileIO]]
[[Category:removableStorage]]
[[Category:scheduler]]
[[Category:weatherproofing]]
[[Category:mounting]]
[[Category:Application Guides]]
The project described here is a simple weather station that measures air temperature, humidity, and surface temperature of the ground below the weather station.
{|
|Practical concepts covered are (click on links to see other projects on that topic):
* Powering your Phidget
** [[:Category:BatteryPower|Battery power]]
** [[:Category:SolarPower|Solar power]]
* [[:Category:PhidgetsSBC|Using the SBC]]
** Using analog sensors
** Using LEDs
** Using USB sensors
* Data Logging
** Recording samples at a certain time
** [[:Category:FileIO|Writing to a text file]]
** [[:Category:RemovableStorage|Writing to a removable USB key]]
** [[:Category:Scheduler|Using the SBC cron scheduler]]
** Using Phidgets with Python
* Fixed Structures
** [[:Category:Weatherproofing|Weather resistance]]
** [[:Category:Mounting|General planning and assembly]]
|width="45px"| 
|[[Image:app_guide_weatherstn_introphoto.jpg|500px|link=|alt=]]
|}

{| style="border:1px solid darkgray;" cellpadding="5px;"
|'''Time:'''
| About 6 full days of work, including gathering components, writing code, and drilling/assembling
|-
|'''Special Needed Tools:'''
|Drill, soldering iron, small screwdriver, socket and wrench set
|-
|'''Other Useful Tools:'''
|Hammer, tin snips for pipe strapping
|-
|'''Materials and Phidgets:'''
|Extensive lists are provided in this guide
|}

As with any of our [[:Category:Application Guides|described projects]], Phidgets takes care of the electrical component design. Still, a project of this magnitude require a time investment in addition to a monetary investment. Designing projects like these is hard.

But the reward is deep - and very real. A full, functional outdoor sensor system that you can build to whatever specifications you like... ask any hobbyist and you may see their eyes light up remembering their latest project. Building such things is a special kind of freedom!

__TOC__

==Introduction==

A remote station project can monitor and log weather and other environmental conditions using Phidgets.

On this page, we describe this particular setup to get you started:

[[File:app_guide_weatherstn_station.png|900px|link=|alt=]]

We start with all of the pieces (the Phidgets, the power supply, the main structure, and the code) and then put it all together.

==Phidgets==

At the core of this weather logging station is the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer (SBC2)]. The sensors and other attachments from Phidgets could include:

{| style="border:1px solid darkgray;" cellpadding="5px;"
|- style="background: #c0c0c0;"
!Task
!Phidget
|- style="background: #efefef;"
|
* Schedule the samples
* Split and Provide power to devices
* Control the USB Phidget (IR sensor)
* Run the code
|[{{SERVER}}/products.php?product_id=1072 1072 - PhidgetSBC2]
|- style="background: #efefef;"
|
* Read surface temperature of ground, without touching it
* Provide ambient air temperature at board location
|[{{SERVER}}/products.php?product_id=1045 1045 - PhidgetTemperatureSensor IR]
|- style="background: #efefef;"
|
* Measure ambient air temperature
* Measure ambient air humidity
|[{{SERVER}}/products.php?product_id=1125 1125 - Humidity/Temperature Sensor]
|- style="background: #efefef;"
|
* Read the analog-in [{{SERVER}}/products.php?product_id=1125 Humidity/Temperature Sensor]
* Control LEDs to display status
|
[{{SERVER}}/products.php?product_id=1018 PhidgetInterfaceKit 8/8/8] <br>
(included on-board with the [{{SERVER}}/products.php?product_id=1072 1072 PhidgetSBC2])
|- style="background: #efefef;"
|
* Take pictures
|[{{SERVER}}/products.php?product_id=3402 3402 USB Webcam]
|- style="background: #efefef;"
|
* Display Status
| [{{SERVER}}/products.php?product_id=3601 3601 - 10mm Green LED] / [{{SERVER}}/products.php?product_id=3600 3600 - 10mm Red LED]
|- style="background: #efefef;"
|
* Allow for far sensor placement
| 3004 - Sensor Cable 350cm
|}

The SBC has the ability to run both USB-based Phidgets (such as the [{{SERVER}}/products.php?product_id=1045 1045 - PhidgetTemperatureSensor IR]) and analog-based Phidgets (such as the [{{SERVER}}/products.php?product_id=1125 1125 - Humidity/Temperature Sensor]). But we have a variety of different environmental sensors that you could use on your system. The included [{{SERVER}}/products.php?product_id=1018 1018 - PhidgetInterfaceKit 8/8/8] on board the SBC can handle up to 8 analog sensors, and 8 digital in sensors like switches.

Take note that the rated temperature range for the SBC is 0-70°C. You will also notice that it looks substantially colder in most of the pictures than 0°C! There are a few reasons for this. The first is that the SBC is being kept in a sealed container with some (admittedly minor) insulation. Also keep in mind that the SBC will generate heat just like any electronics that have power flowing through them; the SBC is essentially a 1W heater all by itself which, when inside the case, keeps the temperature up significantly above the outside temperature. That said the temperature inside the case is still below 0 on a fairly regular basis. This just goes to show you that the temperature range is not a hard limit and the board will function below it, however there are no guarantees at this point, the SBC could stop functioning at basically any time. It would start up again as the temperature increased but it is very likely that the board seizes up and remains inoperable for long periods of time if it is not being monitored. This was a risk we took and luckily we didn't run into any issues. For the record the coldest temperatures we recorded during the operation of this weather station were between -10 and -15°C. I would not recommend attempting to run it in a colder environment than that without steps being taken to actively heat the board.

Using these components requires a bit of care, so the next sections give some suggestions on how to use each Phidget.

===Phidget Infrared Temperature Sensor (IR Sensor)===

Measuring the temperature of the ground is useful for things such as highway temperature in the summer, or snow surface temperature in the winter. The IR board can face downward to do this without contacting the surface itself.

The IR board should be:
* Encased and sealed (such as with a Phidget Enclosure and low-temperature caulk) against the weather
* Suspended at the right height for the sample size of ground needed (see the [{{SERVER}}/products.php?product_id=1045 1045 - PhidgetTemperatureSensor IR] specifications for the degrees of view you have)
* Suspended far enough away from the station that it is measuring only ground, and not measuring the base of the station
* Reasonably protected from solar heating (having a large station arm above it and shading it will probably do it)

Note that you will need to calibrate the data received from this sensor. When you can control all of the variables around what you are using the IR board to measure, you can get very accurate measurements. But in the out-of-doors with a weather station, you will use the board temperature, any shaded temperatures you get from the [[#Phidget Temperature and Humidity Sensor|second temperature sensor]], and thermal measurement theory to correct the value the sensor receives. Error includes:
* Warming of the IR board itself (i.e. you may need corrections based on board temperature)
* Emissivity of your subject being less than 1.0 (for more information on emissivity, see the [{{SERVER}}/products.php?product_id=1045 1045 - PhidgetTemperatureSensor IR] product page)
* Measurement of any reflected heat in addition to emitted heat (this also depends on the emissivity)

These concepts and terms should help you get started in your research on how to correct the data specific to your needs - or if you need to do so at all - but a full course in correction is beyond our scope here.

===Phidget Temperature and Humidity Sensor===

Temperature sensors need to be protected from heating by the sun. Both humidity and temperature sensors need to be protected from snow accumulating on them so that they can interact with the ambient air.

A standard, suspended, white plastic Stephenson-type screen can provide this kind of protection. Plastic ones are inexpensive, and available from specialized weather stores. The photo in the [[#Introduction|Introduction]] shows a typical shield screen of this type.

===Webcam===

Whatever webcam you choose, you should test it outside to properly set the exposure and focus. Most webcams are not weatherproof. Your webcam can either be housed in a weather resistant housing such as those designed for outdoor floodlights, or sealed directly (except the lens) with thick, low-temperature caulk.

===Communication===

Because of the power requirements (as discussed further in the [[#Power|power]] section), we chose not to include a wireless connection to transfer data and check on status. Rather, this task can be split up into two parts:
* LEDs can provide visible status
* USB keys can store and transfer data
Performing both of these tasks during normal field operation is covered in the [[#Code|code section]]. However, for development and debugging, we did use a wireless connection:

[[File:app_guide_weatherstn_table_devel.jpg|800px|link=|alt=]]

==Power==

From the Phidget documentation, we know that the Single Board Computer (SBC) will run at 1.2 watts with no power consumed by devices in its USB ports, and 2.5 watts maximum if all USB port devices are drawing power to maximum specification. Because the power to all sensors and USB devices is included in this estimate, this is what we use to pick a battery and a solar panel.

Although we chose our Phidgets first, and are now designing a power system to support them, the Phidget selection also included some power concerns. With a little forethought, we can guess that the wireless internet adaptor is probably the most power hungry thing that we can plug into a Phidget SBC. A wireless adaptor has two important benefits:
# You can download data over the network
# You can change code, settings, and scheduling of data gathering as the station is operating
You don't necessarily need an internet connection to use the wireless, as you can connect to it via its {{Code|phidgetsbc.local}} local link address.

On the other hand, without a wireless adaptor, the SBC is essentially running autonomously. You can save a lot of power this way, but if the SBC gets into an undesirable state (extreme weather causes it to reboot, a USB Phidget wiggles loose and doesn't properly attach in software, etc) your only options are to either reboot, or add a network connection to log in and change things.

As we do not use wireless here, but do use a webcam, we use an estimate of 2.0 watts to run the SBC.

===Solar Panel===

We would like to have a power setup that will operate continuously, rather than having to replace the battery. This involves solar power, and it also involves knowing something about the expected weather (namely, the sunshine) in the installation location. Your solar watt capacity should be big enough that in periods of sun it can recharge the battery much faster than the SBC will drain it.

To take an example as to why this matters, imagine installing a 2.0 watt solar panel into your system. If there were sunshine 100% of the time, this would be a closed, self-refreshing system because the SBC would draw 2.0 watts from the battery, and the solar panel would put 2.0 watts back in. But with only a short period of dark, the battery will be drained slightly and never refreshed. So we need to consider all of the factors that could cause darkness (or relative darkness) and determine from them how big a solar panel we need.

We start with choosing amorphous solar panels because of their low cost, and (more importantly) their ability to charge a battery in low or indirect light conditions.

Then, we account for nightfall. This at least doubles our solar needs, especially in winter when nights are long. We assume 3/5 dark time, as twilight conditions are poor for power generation, and the station will be installed in a valley with high ridges blocking the sun for morning and evening. So even assuming every day is sunny, we will only receive 2/5 charge time, and will need 5/2 (5 watts) of power via the solar cell simply due to location and season.

Then, we account for weather. An average long storm for the interior Rocky mountains is about two weeks. Although we chose amorphous solar panels for their low-light performance, the conservative assumption is that the battery will get little recharge during such a storm. Therefore, we want to recharge quickly between storms. In late winter, the mountain sky is cloudy about 2/3 of the time, leaving us one week to top off the battery after two weeks of drain. From our [[Electricity Primer#Power Needs|more general power needs section]], we can learn that our 2.0 watt SBC will draw 0.17 amps if [[#Battery|we use a 12 V battery]]. So our drain - at worst - will be:
*Two weeks = 24 hours per day x 14 days = 336 hours
*336 hours at 0.17 amps = 57 amp-hours

To recharge 57 amps at 12 V, with a 10 watt panel this would take (the concepts are from the [[Electricity Primer#Power Needs|more general power needs section]]):
* 57 amps * N hours = 10 watts / 12 V
* N = 68
...68 hours. At 2/5 charge time from the nightfall calculation (giving ten hours a day of charge), a 10 watt panel would recharge in the expected week (6.8 days). This gives us an idea of what class of solar panel we are looking for, and from here we can examine 10 watt and larger panels with respect to cost and size.

After examining cost, a 10-watt panel was nearly the same size and cost as an 18-watt panel ($80), and so an 18-watt panel was used here. The 18-watt panel also would help add a buffer when - even on non-storm days - high mountain clouds form and further reduce the available sun.

Whatever you choose for your solar panel, you should include a charge limiter, and a way to reliably attach the wires to a battery (clips are for testing only, the post clamps are a more permanent install). The cable on the right is outdoor grade power hookup wire:

[[File:app_guide_weatherstn_battery_wires.jpg|800px|link=|alt=]]

===Battery===

Your battery amp capacity should be big enough that the SBC can run continuously, with reserves, in times of cloudy weather. Even with a proper type of battery, if your SBC completely drains your battery, depending on the battery type it has a chance of dying completely (which is called ''bricking'') and will lose its capacity to recharge.

We have an in-depth description of how to choose batteries [[Electricity Primer#Power Needs|in a more general power needs section]]. From the information in that section, we can determine that we will probably be using a 12 V battery, and that the SBC will draw 0.17 amps with a 12 V battery.

Using this in the [[#Solar Panel|solar power section]], we calculated that the drain on the battery during a long storm would be, at worst, 57 amp-hours, and so this is the minimum usable capacity we need for the battery.

At more than about 30 amp-hours, the [[Electricity Primer#Power Needs|battery that makes the most sense]] is the large car-battery type lead acid battery. However, typical car batteries won't work as they are not ''deep cycle'' that is, they are designed to stay fully charged most of the time. Drawing current from this type of battery continuously will only damage and eventually destroy it. Batteries for RVs, boats, electric golf carts, and the like are designed to be used up through most of their amperage capacity, recharged, and used again and again - these batteries are deep cycle batteries.

Most batteries list this usable capacity for their specification, but if not, consider only 60% of the capacity to be usable. Some example specifications are:
* ''70 Amp-hours (110 reserve)'' - this battery has 70 usable amp hours
* ''70 Amp hours'' - this battery probably only has 42 amp hours, but you can call the manufacturer to make sure

The battery will probably be a higher cost than the solar panel. A 60-70 usable amp-hour lead acid battery will be about $100 and 50 lbs. When choosing a battery, the 'buy in bulk' philosophy can come into play. For example, this station ended up using a 110 amp-hour battery, which was $115 and 65 lbs. This is not much weight or price difference for nearly double the power capacity. And extra power capacity will give you extra buffer when you are testing your system at the beginning.

There are many different types of deep cycle batteries - not just lead acid - and they vary in price significantly. There are resources all over the Internet about different battery types to use with solar panels (as well as [[Electricity Primer#Battery Power|a primer that we have]]), so we will not describe them here. The key deciding factor is how long the installation is designed to last. Lead acid batteries have a lifespan of about three years. Longer than that, and you will need to purchase a more expensive battery.

[[File:app_guide_weatherstn_battery.jpg|800px|link=|alt=]]

==Structural System==

The list of major components for this weather station is:

{| style="border:1px solid darkgray;" cellpadding="5px;"
|- style="background: #c0c0c0;"
! Components
|-
| Station Tripod
|- style="background: #efefef;"
| Commercial lightweight tripod
|- style="background: #efefef;"
| Extension masts
|- style="background: #efefef;"
| Protective screen for temperature and humidity sensor
|-
| Wires
|- style="background: #efefef;"
| Exterior-grade power cable
|- style="background: #efefef;"
| Hookup wire for LEDs and Long Phidget Sensor wires
|- style="background: #efefef;"
| Solder and heatshrink
|-
| Misc Hardware
|- style="background: #efefef;"
| Horizontal arm for measuring surface temperature (Pipe plus U-bolts and pipe strapping)
|- style="background: #efefef;"
| Solar panel and SBC case mounting (Metal frame or wide clamps with locks, with U-bolts)
|- style="background: #efefef;"
| Battery box to keep snow off the terminals
|- style="background: #efefef;"
| Pelican 1200 waterproof case for SBC
|- style="background: #efefef;"
| Battery post mounts, protectors, and charge limiter
|}

Although most of these components individually are inexpensive, put them together and the Phidgets are only a small portion of the overall system cost.

With these types of projects, it is easy to lose track of all the little details. Even in something contained like a weather station there are lots, including:
* Zip ties (black exterior type) for cable management
* Cold weather silicone caulk for sealing the case wire holes
* Silica gel packets for desiccant within the SBC case
* Penetrating oil (WD-40) and a hammer for working with the tripod and masts
* Foam to pad the U-bolt ends from the solar panel
* Bolts and angle brackets for the Pelican case mounting
And so on. So plan to spend a while working your particular system out with diagrams, lists, or whatever works for you.

The details of each major connecting part (e.g. mounting the solar panel on the mast, mounting the SBC within the case and to the mast, mounting the horizontal arm, etc) will depend on many different details specific to your application, such as:
* Snow depth, expected winds, and primary weather
* Length of the horizontal arm and any sensors also on the end
We found U-bolts to be sufficient for most mounting needs, and quick grip clamps to be sufficient for the solar panel (a person could hang on them), which made the station easier to maintain. This station was designed to be run for a few months and then moved or taken down; a more permanent installation may have a different design.

Depending on your expected forces, you can enhance this basic system design. For example, adding some stakes and plastic coated galvanized guy wires can enable your weather station masts to withstand winds of 70 kph with minimal vibration:

[[File:app_guide_weatherstn_guyhardware.jpg|800px|link=|alt=]]

==Code==

We will be writing our Phidget code in Python. This code will then be scheduled to run - via [[OS - Phidget SBC#Via Cron|cron]] on the SBC - to sample data once per minute and take a webcam photo once every thirty minutes.

Since the weather station runs autonomously - on its own, in the wild - you will need to write code that runs on the SBC itself, as you will have no external computer to control the SBC. This depends on the SBC being set up as described in the [[1072 User Guide]] page, and then additionally as described in the [[OS - Phidget SBC]] page. Namely, to follow along with this particular station design, you will need:
* [[OS - Phidget SBC#SSH|SSH]] enabled
* [[OS - Phidget SBC#Installing Python|Python installed]]

Of course, there are many, many other ways to design this code - in Java, to run at boot rather than as a cron job, and so on - and many of these alternatives are outlined on the [[OS - Phidget SBC]] page.

For this example, we have two [[Language - Python|Python scripts]]: {{Code|station.py}} which runs the sensors once per minute and saves the data, and {{Code|webcam.py}} which saves a webcam picture once per minute. You can download the files [http://www.instructables.com/files/orig/FZF/K2QV/HW1M9HIP/FZFK2QVHW1M9HIP.zip here].

===Station===

The station code in {{Code|station.py}} has three jobs:
* Reading data, which is the gathering and saving of the weather data,
* Displaying status via the Interface Kit and LEDs, and
* Moving data onto a second USB key (optional)

====Reading and Recording Data====

This station handles two USB Phidgets (the Interface Kit on the SBC board, and the IR Temperature sensor), and two analog Phidgets (air temperature, and humidity).

We have code snippets for using more than one USB Phidget on the [[General Phidget Programming#Using Multiple Phidgets|General Phidget Programming page]]. To use more than one analog sensor, you simply use the port number it is plugged in to. As shown on the general programming page, you can automatically detect which USB Phidgets are attached, without knowing their serial number. But you cannot detect which analog ports are being used, unless create an ad-hoc method, such as assuming a value of 0 means no sensor is attached, and any other value indicates an attached sensor.

After we read the data from the Phidgets, we want to save it on the USB data key. We can either hard-code the location or automatically detect where the key is plugged in. Using USB keys with the SBC is discussed in detail on the [[OS - Phidget SBC#Using USB Data Keys|SBC operating system page]]. We will hard-code the location in this section's code, but we show how to automatically detect a USB key in the [[#Moving USB Data|Moving USB Data]] section.

Here we open the two USB Phidgets, read the IR temperature state, read the two analog in sensors, write the data to an existing file on the USB data key, and turn on and off an LED looks like:

<div class="source">
<syntaxhighlight lang=python>
#! /usr/bin/python

from Phidgets.PhidgetException import *
from Phidgets.Events.Events import *
from Phidgets.Devices.InterfaceKit import *
from Phidgets.Devices.TemperatureSensor import *
from time import sleep
from datetime import *

errors = ""
fileLocation = "/media/usb0/data.txt"
weatherLED = 0 # Digital out port position

def close():
global interfaceKit
global temperatureSensor
global errors
try:
interfaceKit.setOutputState(weatherLED,0)
except PhidgetException as e:
errors = errors + "Phidget Exception on turning off LED\n"
temperatureSensor.closePhidget()
interfaceKit.closePhidget()

try:
temperatureSensor = TemperatureSensor()
interfaceKit = InterfaceKit()
except RuntimeError as e:
errors = errors + "Runtime Exception on object creation\n"

try:
# Replace these serial numbers with your own
temperatureSensor.openPhidget(142768)
interfaceKit.openPhidget(48498)
except PhidgetException as e:
errors = errors + "Phidget Exception on Open\n"

try:
interfaceKit.waitForAttach(1000)
temperatureSensor.waitForAttach(1000)
except PhidgetException as e:
errors = errors + "Phidget Exception on Attach\n"

try:
# Turn the LED on
interfaceKit.setOutputState(weatherLED,1)
# Temperature and humidity are both ratiometric
interfaceKit.setRatiometric(1)
except PhidgetException as e:
errors = errors + "Phidget Exception on Ratiometric turn on\n"

# To let the LED stay on for a visually detectable amount of time
sleep(0.5)

try:
# These conversions are in the product manual
currentTemp = (interfaceKit.getSensorValue(0) * 0.22222) - 61.11
currentRH = (interfaceKit.getSensorValue(1) * 0.1906) - 40.2
except PhidgetException as e:
errors = errors + "Phidget Exception on reading Temperature and RH\n"

try:
currentIRTemp = temperatureSensor.getTemperature(0)
boardTemp = temperatureSensor.getAmbientTemperature()
except PhidgetException as e:
errors = errors + "Phidget Exception on reading IR Temperature"

outputLine = ""
outputLine = outputLine + str(datetime.now()) + ","
outputLine = outputLine + "T=" + str(currentTemp) + ","
outputLine = outputLine + "RH=" + str(currentRH) + ","
outputLine = outputLine + "IR-T=" + str(currentIRTemp) + ","
outputLine = outputLine + "IR-Brd=" + str(boardTemp) + "\n"

appendFile = open(fileLocation, 'a')
appendFile.write(outputLine)
if errors is not "":
appendFile.write(str(datetime.now()) + ":\n" + errors)
appendFile.close()

close()
exit(0)
</syntaxhighlight>
</div>

This code snippet shows only one LED in use to show status, attached to digital output port 0 (short LED wire goes into the ground '''G''' terminal). For ideas on using other LEDs to display the status of the SBC and your program, see the [[#Status|status section]].

After running this a number of times, you will have a file {{Code|data.txt}} full of lines that look like this:

<div class="source">
<syntaxhighlight lang=text>
2012-03-10 08:37:02.776500,T=-1.77726,RH=40.2,IR-T=-1.01,IR-Brd=-1.09
</syntaxhighlight>
</div>

This can be written differently to start with, or parsed later into whatever data analysis program you want to use.

====Moving USB Data====

The station was visited once per week to obtain the data. On these visits, we would simply change out the old USB key for a new one on every visit, and reboot the SBC.

We also considered the alternative of writing some extra code to detect when a second USB key is plugged in and copy all of the latest data to it.

After experimenting with both, it turned out that the change-and-reboot option worked well and was the simplest. Rebooting the station at every visit was no problem because the cron job simply restarts as soon as the SBC restarts. Having only one key with the data on it for the week, and then installing a fresh one, created only one key to keep track of at a time.

However, the copy method may be useful in other instances. You can use the mount table to detect a second USB key and write to it like this (the mount and cp shell commands are discussed on the [[OS - Phidget SBC]] page):

<div class="source">
<syntaxhighlight lang=python>
#! /usr/bin/python
from time import sleep
from datetime import *
import shlex, subprocess

# If this code might start again via cron, we want to ensure only one process writing to the USB key
# The file contains a "1" to denote a process is using the second key, and "0" otherwise
lockFile = "/root/WeatherStation/semaphore.txt"

# The shell command to check the location of a second USB key
checkUSBcommand = "mount | grep sdb1"

# Spawn a command line process, and obtain the output (e.g. the lines from "mount" with "sdb1" in them)
checkUSBprocess = subprocess.Popen(checkUSBcommand, shell=True,
stdin=subprocess.PIPE, stdout=subprocess.PIPE)
output = checkUSBprocess.communicate()[0]

usbLocation = None # A default value

if len(output) > 3: # If we have more than a newline, key is attached
outputArray = output.split("usb")
usbLocation = outputArray[1][0] # Get the number right after "usb"

# If there is no usb key, remove any locks - especially useful for multiple cron processes
if usbLocation is None:
file = open(lockFile, "w")
file.write("0\n")
file.flush()
file.close
exit(0)

file = open(lockFile, "r")
lock = file.readline().rstrip()
if lock is not "0": # If another process is already writing
exit(0)

# If we've gotten this far, there is a key and we need to write to it.

# Lock the semaphore
file = open(lockFile, "w")
file.write("1\n")
file.flush()
file.close

usbLocation = "/media/usb" + usbLocation + "/"

# Copy the data file via a spawned shell process
copyDataCommand = "cp /media/usb0/data.txt " + usbLocation
dataProcess = subprocess.Popen(copyDataCommand,
shell=True, stdout=subprocess.PIPE)
# The copy might take a while, so check every so often and sleep until done
while dataProcess.poll() != 0:
sleep(0.1)

# Copy any webcam images via a spawned shell process
copyImagesCommand = "cp /media/usb0/*.jpg " + usbLocation
imageProcess = subprocess.Popen(copyImagesCommand,
shell=True, stdout=subprocess.PIPE)

# Again, the copy might take a while, so check every so often and sleep until done
while imageProcess.poll() != 0:
sleep(0.1)

# Unlock the semaphore
file = open(lockFile, "w")
file.write("0\n")
file.close

exit(0)

</syntaxhighlight>
</div>

====Status====

There are many ways to use LEDs to communicate status, but a key way is to have the LEDs turn on when reading data, and turn off when finished successfully. Then, if they remain on at your next visit, you will know an error was triggered.

This shows that an error occurred, but not what error. You can also consider writing the details of the error to your data file along with time and date information so you know what surrounding conditions may have caused it. But depending on your method of moving (or copying) the USB data off of the board, you may want to have many LEDs for different states:
* Data being measured
* Data being copied
* Error generated
* Program exited normally

If you use more than one LED, especially of the same colour, make sure to label them!

The LED setup that was used in this particular station turned an LED on for measurement, and then off on successful program exit. Then, when the station SBC was rebooted in the field, a briefly flashing LED once per minute means the reboot of the station and software was successful.

===Webcam===

There is a lot of information on the [[#OS - Phidget SBC#Taking Pictures With the Webcam|SBC operating system page]] on using UVC compatible webcams. That section describes how to install the {{Code|opencv}} supporting library, which was used to control the webcam.

The code {{Code|webcam.py}} run once every 30 minutes to take a picture was:

<div class="source">
<syntaxhighlight lang=python>
#! /usr/bin/python

import cv
from datetime import *

webcam = cv.CaptureFromCAM(0)

image = cv.QueryFrame(webcam)

# Compose a fixed-width date label for the file
now = datetime.now()
filename = str(now.year)
if len(str(now.month)) == 1:
filename += "0" + str(now.month)
else:
filename += str(now.month)
if len(str(now.day)) == 1:
filename += "0" + str(now.day)
else:
filename += str(now.day)
filename += "-" + str(now.hour) + "-" + str(now.minute) + ".jpg"

# This results in something like /media/usb0/20120224-30.jpg
filename = "/media/usb0/" + filename

if image:
cv.SaveImage(filename, image)
print filename
else:
# Throw an error, now just an empty placeholder
print ""

exit(0)
</syntaxhighlight>
</div>

===Scheduling===

You can schedule your Python scripts the same way we did - as cron jobs by following the [[OS - Phidget SBC#Via Cron|cron section]] on the SBC operating system page. Both files were saved in the default home directory {{Code|/root}}.

The line used to schedule the weather station every minute was:

<div class="source">
<syntaxhighlight lang="bash">
* * * * * /root/station.py
</syntaxhighlight>
</div>

The line used to schedule the webcam every thirty minutes was:

<div class="source">
<syntaxhighlight lang="bash">
0,30 * * * * /root/webcam.py
</syntaxhighlight>
</div>

===Data===

When visiting this weather station, we could perform any upkeep. Then, as above, we could get the data off the weather station by simply removing the USB key drive from the SBC and rebooting the SBC. As mentioned earlier, the reboot helped keep our code stable over time by resetting and fully cleaning out any script instances which had hung due to unforeseen circumstances. The USB key would then have a week of data on it at a time. Here is a week with air temperature in <span style="color:green;">green</span> and (partially corrected) snow surface temperature in <span style="color:blue;">blue</span>:

[[File:app_guide_weatherstn_plot.jpg|800px|link=|alt=]]

==Putting it All Together==

Field installation will always be harder than you think. But at the same time it will be fun, seeing your hard work come together. Make sure you have permission to set up your station in its new home if the land is not yours. Some day-of-assembly tips:
* Pick a day with reasonable weather for the installation, so you can slow down and do things carefully.
* Assemble the pieces for practice at home, or better yet run them in your backyard before installing elsewhere
* Bring basic tools into the field with you when you install (a solar setup tester, hammer, penetrating oil, some wrenches and sockets, caulk)

It is good to check your code very carefully before installing, but if something doesn't go right, you can always remove the SBC, transport it home, fix it, and reinstall relatively easily.

[[File:app_guide_weatherstn_sbc_box_lables.png|800px|link=|alt=]]

When you check on the station, things you may not expect can happen in the interim, so consider bringing a small repair kit each time as you work the bugs out.

[[File:app_guide_weatherstn_snow.jpg|500px|link=|alt=]]

==Extra Credit==

===Faster Sampling===

The ports can sample at any time interval up to the maximum data rate of the [{{SERVER}}/products.php?product_id=1018 Phidget Interface Kit] attached to the SBC. So you can also write fast-sampling code that runs constantly from [[OS - Phidget SBC#Via a Boot Script|the SBC boot time]] and samples very quickly. With fewer than four analog sensors, you can sample up to 1000 times per second.

===A Smarter Station===

The Single Board Computer is just that - a computer! So you could install something like the [http://www.r-project.org R Statistical Package] (you can do this by using [[OS - Phidget SBC#apt|apt-get install r-base]] over [[OS - Phidget SBC#SSH|SSH]] on the SBC) and do analysis on the data as it comes in.

[[File:app_guide_weatherstn_farshot.jpg|500px|link=|alt=]]

Thermocouple Primer

2014-06-02T16:28:31Z

Kat:

[[Category: Primer]]

==Introduction==
A thermocouple is a device consisting of 2 different conductors that produce a voltage proportional to a temperature difference between either end of the pair of conductors. There are many types of thermocouples, with varying types of conductors and probe designs.

Most thermocouples produce voltages of less than 50mV so very sensitive electronics are required to interface with them.

==Choosing a Thermocouple==

===Conductor Calibration Types===
J, K, E and T-Type thermocouples are the most common types of thermocouples. Each type has a different temperature range and resolution due to the metals used in the conductors.

{| style="border:1px solid darkgray;" cellpadding="7px;"
|+'''Calibration Type Temperature Ranges'''
|-style="background: #d1d1d1" align=center
! Type || Temperature Range °C || Notes
|-
|style="background: #f0f0f0" align=center| K
|style="background: #f0f0f0" align=center|-200 to +1250
|style="background: #f0f0f0" align=left |The most common sensor, wide range, good in oxidizing atmosphere
|-
|style="background: #f0f0f0" align=center| J
|style="background: #f0f0f0" align=center|0 to +750
|style="background: #f0f0f0" align=left |More Limited range, main application is with old equipment that cannot accept modern thermocouples
|-
|style="background: #f0f0f0" align=center| T
|style="background: #f0f0f0" align=center|-200 to +300
|style="background: #f0f0f0" align=left |Most Accurate base-metal thermocouple, non-magnetic, popular choice for strong magnetic fields and subzero environments
|-
|style="background: #f0f0f0" align=center| E
|style="background: #f0f0f0" align=center|-200 to +900
|style="background: #f0f0f0" align=left |Well suited to low temperature (cryogenic) use
|}

The insulation that surrounds the thermocouple is the limiting factor in the true temperature range. For example, a K-type thermocouple insulated with teflon is good up to +200°C. The same thermocouple using Fiberglass is good to 480°C. For short durations the thermocouples can be exposed to higher heat than they are rated for, however, they will degrade if exposed to very high heat for long periods of time.

====Using Other Thermocouple Types with Phidgets====

You can interface with other thermocouple types using Phidgets Inc. thermocouple interfaces, with some minor calculations:

# First, visit [http://instrumentation-central.com/pages/thermocouple_reference_table.htm this website] and open the conversion table for the desired thermocouple type.
# Take the '''ambient temperature''' value measured by the board and use the ones digit to select the column, and the other digits to select the row. Record this thermoelectric voltage value.
# Use the '''getPotential''' call in your program in order to get the thermocouple's current thermoelectric voltage value.
# Add the two voltage values from the previous steps and use the table to convert back into temperature.

===Junction Type===

[[File:Thermocouple.jpg|350px|thumb|link=|'''Junction Types'''<br/>A cross-sectional view of the three most common junction types.<br/>[[Media:Thermocouple.jpg|Full-sized Image]]]]

An important feature to consider when choosing a thermocouple is the junction type. This describes the degree to which the sensing end of the thermocouple is exposed to the environment it's measuring. There are three main types of junctions: Grounded, Ungrounded, and Exposed.

====Ungrounded====

A thermocouple with an ungrounded junction has a metallic outer sheath, usually made of a corrosion-resistant material such as stainless steel. The junction where the two conductors meet is suspended inside this sheath, such that the end of the junction is not in contact with the sheath. As a result, it will take longer for the thermocouple to react to temperature changes in the environment, because the inside of the sheath must reach thermal equilibrium before the conductors can detect the change. Ungrounded thermocouples can be used with a Phidgets Inc. thermocouple interface with no issues as long as the [[#Conductor Calibration Types|type]] is also supported.

'''Advantages:'''
* The conductors are protected from the environment, enabling the sensor to be used in a wider range of applications.
* Since the conductors are not grounded, the thermocouple will not introduce a [[Electricity Primer#Multiple Powered Phidgets|ground loop]] into the system.

'''Disadvantages:'''
* It takes longer for the thermocouple to react to temperature changes in the environment because it is not in direct contact with it.

====Grounded====

A thermocouple with a grounded junction has an outer sheath just like the ungrounded design, but the junction where the two conductors meet is welded to the inside of the sheath. This allows for a shorter reaction time to temperature changes, but is likely to introduce a [[Electricity Primer#Multiple Powered Phidgets|ground loop]] into the system. In order to use a grounded thermocouple with a Phidgets Inc. thermocouple interface, you need a USB isolator to ensure system stability.

'''Advantages:'''
* The conductors are protected from the environment, enabling the sensor to be used in a wider range of applications.
* Reacts more quickly to temperature changes in the environment.

'''Disadvantages:'''
* Special care must be taken to protect your system's stability from ground loops.

====Exposed====

A thermocouple with an exposed junction has no protective sheath, allowing the junction where the two conductors meet to be in direct contact with the environment it's measuring. As a result, an exposed thermocouple will have the fastest reaction time, but can only be used in non-corrosive, non-pressurized applications (While it is possible to use exposed thermocouples in high pressure applications, it is difficult to make a proper seal. Many enclosed thermocouples will have special hardware for this sort of application). Exposed thermocouples can be used with a Phidgets Inc. thermocouple interface with no issues as long as the [[#Conductor Calibration Types|type]] is also supported.

'''Advantages:'''
* Exhibits the fastest reaction to temperature changes in the environment due to direct contact.
* Since the conductors are not grounded, the thermocouple will not introduce a [[Electricity Primer#Multiple Powered Phidgets|ground loop]] into the system.

'''Disadvantages:'''
* Limited to non-corrosive, non-pressurized applications.
* The thermocouple has no protection from physical contact.

==Things to Watch For==
===Grounding===
A “ground loop” happens when two points in a circuit are at different potentials, when they are expected to be the same. This difference in electrical potentials causes a build up of static electricity that can give electrical shocks to people and electronics. In the case of thermocouples and thermocouple boards, the negative terminal on the 1051 1-input thermocouple boards is USB ground, as is the ground terminal on the 1048 4-input board. So, if you ground the junction of your thermocouple when using these boards and the material it’s affixed to has a different voltage than the ground on the computer, you’ve created a circuit with two points at different potentials.

More information about how to avoid ground loops in thermocouples can be found [http://phidgets.wordpress.com/2014/06/02/how-to-avoid-grounding-a-thermocouple/ here, on the Phidgets blog].

===Interference===
When measuring from a thermocouple, each thermocouple is compared to adapter's internal ground. If your thermocouple is measuring a conductive device which cannot equalize to the ground of the adapter, you should isolate the thermocouple wire using thermally conductive epoxy. Thermocouples are conductive, and are very good at shorting electrical systems together. If in doubt, do not allow the thermocouple wire to contact other metal parts.

Since a thermocouple is essentially just two long wires, it could act like an antenna and pick up electromagnetic interference from other nearby electronics or appliances. See the [[Addressing_Electromagnetic_Interference_with_Phidgets|Addressing EMI]] page for more information on how to deal with this problem.

===Wire Size===
The maximum temperature varies with the diameter of the wire used in the thermocouple. Although the type of thermocouple dictates the temperature range, the maximum range is also limited by the diameter of the
thermocouple wire. That is, a very thin thermocouple may not reach the full temperature range. On the other hand, a thinner thermocouple does reduce the amount of thermal distortion introduced.

Selecting the wire gauge used in the thermocouple sensor depends upon your application. Generally, when longer life is required for the higher temperatures, the larger size gauges should be chosen. When sensitivity is the prime concern, the smaller sizes should be used.

===Wire Length===
Very long thermocouples are okay (even 100m), but if there are measurement stability issues or USB resets, ferrite beads can be added to the thermocouple wire close to the adapter. See our tutorial on [[Addressing_Electromagnetic_Interference_with_Phidgets|Addressing EMI issues]] for more information.

Note that thermocouples use special wires. This means that if you want to extend the length of your thermocouple you need to use thermocouple wire of the same letter type, not just generic wire. Often, thermocouple extension wire will be rated for a narrower temperature range, since it isn't intended to be used in the sensing end of the application.

Since a thermocouple works due to the interaction at the junction of two different metals, it isn't advisable attach two pieces of thermocouple wire simply by soldering them- This would create an additional junction that would interfere with the measurement signal. The best way to connect two thermocouple wires is to buy a connector of the same letter type that clamps onto either end, such as [http://www.omega.com/pptst/SMPW-CC.html this K-type connector] from Omega.

On the flip side, you can cut thermocouples down to a shorter length if you require that as well. Just make sure to cut the size you want out of the side with the actual sensing area on it. The junction between the 2 metals is what allows the device to measure temperature so you need to have the end with the junction on the length you will be using or the thermocouple won't do anything.

==How to connect your Thermocouple==
===Stripped Wire===
Most thermocouples come with the leads just stripped and otherwise unaltered. We recommend a 5 to 6mm wire strip length; the terminal blocks on the majority of adapters will accept wires between 16 - 26 AWG. When using thin wires, make sure that you have a solid connection after tightening the terminal screw.

===Connectors===
[[image:Thermocouple.png|thumb|link=|300px]]
Many K-Type thermocouples are designed to mate with the Subminiature (flat pin) female connector.
Listed below are examples of compatible thermocouples from popular sensor manufacturers using this connector.

{| style="border:1px solid darkgray;" cellpadding="7px;"
|+'''Compatible Thermocouples'''
|-style="background: #d1d1d1" align=center
! Manufacturer|| Part Number || Description
|-
|style="background: #f0f0f0" align=center|Omega
|style="background: #f0f0f0" align=center|TC-PVC-K-24-180
|style="background: #f0f0f0" align=left |PVC-insulated 4.5m epoxy-coated tip k-type
|-
|style="background: #f0f0f0" align=center|Omega
|style="background: #f0f0f0" align=center|88202K
|style="background: #f0f0f0" align=left |Moving-surface swivel-head handle k-type
|-
|style="background: #f0f0f0" align=center|Omega
|style="background: #f0f0f0" align=center|88402K
|style="background: #f0f0f0" align=left |Flat-leaf magnetized k-type
|-
|style="background: #f0f0f0" align=center|Nanmac
|style="background: #f0f0f0" align=center|B8-10
|style="background: #f0f0f0" align=left |Handheld trident-style ribbon k-type
|-
|style="background: #f0f0f0" align=center|Cole-Parmer
|style="background: #f0f0f0" align=center|WU-93631-11
|style="background: #f0f0f0" align=left |ICONEL-sheathed high-temp 12” k-type
|}

Category:Application Guides

2014-05-21T15:13:35Z

Kat: added link for the how-to guides on the blog

Access Control

2014-05-12T21:16:14Z

Kat:

[[Category: cabling]]
[[Category: Weatherproofing]]
[[Category: mounting]]
[[Category: PhidgetsSBC]]
[[Category: Application Guides]]
This project will help you set up a keyless entry system for any door in your house, specifically we want to create a system that will unlock a door when a recognized RFID tag is detected.
{|
|Practical concepts covered are (click on links to see other projects on that topic):
* [[:Category:cabling|Cabling]]
* [[:Category:Weatherproofing|Weatherproofing]]
* [[:Category:mounting|Hardware Mounting]]
* [[:Category:PhidgetSBC|Using the Phidget SBC]]
|width="45px"| 
|[[File:doorunlockfull.png|500px|link=|alt=]]
|}

{| style="border:1px solid darkgray;" cellpadding="5px;"
|'''Time:'''
| About a full day of work, including gathering components, writing code, and drilling/assembling.<br> The challenge will be mounting, wiring, weather proofing, and running power to your system - the code is relatively easy.
|-
|'''Special Needed Tools:'''
|A selection of screwdrivers, Drill with a large bore drill bit, Fish tape, Exterior Caulk
|-
|'''Phidgets Needed:'''
|A [{{SERVER}}/products.php?product_id=1024 1024 - PhidgetRFID Read/Write], a [{{SERVER}}/products.php?product_id=1072 1072 - PhidgetSBC2] or [{{SERVER}}/products.php?product_id=1073 1073 - PhidgetSBC3], and a [{{SERVER}}/products.php?product_id=3052 3052 - SSR Relay Board]
|-
|'''Materials Needed:'''
| A Double gang electrical box, and faceplate for the box
|}

As with any of our [[:Category:Application Guides|described projects]], Phidgets takes care of the electrical component design. Here, we walk you through the code and hardware connections to create a system out of our ready made boards.

'''''Warning: '''''Before you begin this project note that we will be '''drilling holes in an exterior wall''', so make sure to check with local building codes to ensure the modifications you are making are legal.

==Introduction==

Keyless entry systems have been in use in large facilities for years so why not your house too? At the flash of a card or key-chain your door will automatically unlock, no need to fumble around in the dark with a set of keys to find the right key which inevitably takes a few tries.

==Setting it up==
The most difficult part with this project is installing all the components. We are trying to mount hardware on both the exterior and interior of the wall; this can be tricky as cables will need to be run through the wall. Since exterior walls have insulation in them, feeding wires through can be difficult.
#The first step is to cut a hole in the exterior wall that is large enough to fit the box you have gotten.
#You will need to drill a hole through the interior side of the wall inline with this large hole.
#Use your fish tape to feed the USB cable through the hole and then fish it through the electrical box.
#Insert the box into the hole you created and screw it in place.
#Use the exterior caulk to create a seal between the box and the wall.
#The easiest thing to do now is to fasten the RFID reader to the faceplate via glue or foam tape.
#Attach the faceplate to the electrical box and this part is finished.
Depending on where you install the box it may also be a good idea to use some foam weather stripping to enhance the seal of the faceplate to the box.

On the inside you will need to mount the SBC. This can be done many ways though the obvious choice is to do the same thing as you did for the RFID reader. Since the location of the SBC is less important you could even put it down at foot level, out of sight. Alternatively you could mount it in an enclosure directly on the wall. If you have a basement or crawlspace underneath your front door you could also mount it on the rafters below the door. Having the SBC be connected to the internet will help debug issues, keep maintenance easy, and allow for easier addition of new tags

Next we need to have a method for actually unlocking the door. For this project we will be using an electric strike. An electric strike is a device that replaces the hardware on the jamb of the door. Electric strikes can be difficult to install, usually they are used in metal frame doors since the jambs tend to be hollow in these cases which makes running wires much easier. However, there are strikes made specifically for wooden doors. In general, you should follow the instructions that come with the strike for installation.
{|
|[[File:metaldoorjamb.jpg|thumb|left|310px|link={{SERVER}}/wiki/images/3/3d/Metaldoorjamb.jpg|Metal door jamb with precut hole for a strike plate. Note that since the frame is hollow wiring can be run through it fairly easily.]]||[[File:wooddoorjamb.jpg|thumb|right|310px|link={{SERVER}}/wiki/images/a/af/Wooddoorjamb.jpg|Wood door jamb with traditional strike plate installed. This needs to be removed, and a large hole cut out for the electric strike.]]
|}
While installing the strike keep in mind what you are going to need to do with the wires. You need to run wires from the power supply to the relay and from the relay to the strike.

This is the functional schematic for the components of this project:<br />
[[File:doorlockblockdiagram.png|600px|link={{SERVER}}/wiki/images/5/54/Doorlockblockdiagram.png]]<br />
This is how it would look in real life<br />
[[File:doorunlockfull.png|600px|link={{SERVER}}/wiki/images/a/aa/Doorunlockfull.png]]

==Software==
We want the program to have the following process flow:

[[File:Gliffyflowchart.png|link=|alt=|900px]]

We need to have code that checks RFID tag events against a list or database of accepted tags and if the tag is a recognized tag, switch power on to the electric strike.

<div class="source">
<syntaxhighlight lang=java>
rfid.addTagGainListener(new TagGainListener()
{
public void tagGained(TagGainEvent oe)
{
String line = null;
try{
reader = new Scanner(inFile); // set the scanner to read in from the appropriate file
}
catch(Exception e){}
while(reader.hasNextLine()){ // read through the entire file
try{
line = reader.nextLine(); //read in the current tag data
if(line.equals(oe.toString())){ //does the active tag match this entry?
ik.setOutputState(0,true); //if so activate the relay.
}
}
catch(Exception e){}
}
reader.close();
}
});
</syntaxhighlight>
</div>

Where ''inFile'' is a File object set to the file in which the tag data is stored. The tags can be read into a file off-line prior to normal operation, or at will with the push of a button depending on what you prefer. You can download the full code [{{SERVER}}/wiki/images/c/c9/DoorUnlocker.java here]. Note that this code has a mechanism for reading tags into a file though it is for demonstration purposes. In practice you would want the tag reading system to be a bit more robust. Perhaps by using a database of some kind so you could also log who specifically was accessing the door etc...

When the tag is no longer detected the door should relock, though we want to have a window in which the user can still open the door before it locks. This can be handled in our tag loss handler:

<div class="source">
<syntaxhighlight lang=java>
delay = new javax.swing.Timer(SHORTDELAY, new ActionListener(){ //SHORTDELAY is an arbitrary number of milliseconds
public void actionPerformed(ActionEvent evt){
try{
ik.setOutputState(0,false);
}
catch(Exception e){}
delay.stop();
}
});

rfid.addTagLossListener(new TagLossListener()
{
public void tagLost(TagLossEvent oe)
{
try{
if(ik.getOutputState(0) == true){
delay.start(); //add a short delay so the user has time to open the door
}
}
catch(Exception e){}
}
});
</syntaxhighlight>
</div>

1045 User Guide

2014-05-09T19:28:48Z

Kat:

[[Category:UserGuide]]
{{UserguideTOC|1045.jpg|1045}}
==Getting Started==

===Checking the Contents===
{{UGbox|
'''You should have received:'''
* A PhidgetTemperatureSensor IR
* A Mini-USB cable
|
'''In order to test your new Phidget you will also need:'''
* A source of heat
||}}

===Connecting the Pieces===
{{UGbox|
Connect the PhidgetTemperatureSensor IR to your computer using the Mini-USB cable.
|
[[File:1045_0_Connecting_The_Hardware.jpg|400px|link=]]
||}}

===Testing Using Windows 2000 / XP / Vista / 7===

{{UGwin}}

===Running Phidgets Sample Program===

{{UGwin2|'''TemperatureSensor-full'''}}

{{UGbox|
Double Click on the [[File:Ph.jpg|link=]] icon to activate the Phidget Control Panel and make sure that the Phidget Temperature Sensor IR is properly attached to your PC.
|[[File:1045_0_ControlPanel.jpg|400px|link=]]
|
# Double Click on Phidget Temperature Sensor IR in the Phidget Control Panel to bring up TemperatureSensor-full and check that the box labelled Attached contains the word True.
# Place a source of heat in front of the sensor. The object temperature is displayed in degrees centigrade.
# You can adjust the temperature sensitivity by moving the slider. We have set the sensitivity at 0.5 degree.
# The board temperature is displayed in this box
|[[File:1045_0_TemperatureSensor_Screen.jpg|400px|link=]]

}}

===Testing Using Mac OS X===

{{UGmac|Phidget Temperature Sensor IR|TemperatureSensor-full}}

===Using Linux===

{{UGlinux}}

===Using Windows Mobile / CE 5.0 / CE 6.0===

{{UGce}}

==Technical Details==

===Measured Temperatures===

The 1045 is factory calibrated in wide temperature ranges: -40 to 125 °C for the ambient temperature and -70 to 382.2 °C for the object temperature.

To get an accurate reading, it is important that the object being measured occupies the full field of view of the sensor while not making physical contact with the sensor. Since an infra-red sensor measures temperature based on what the object is emitting, there is theoretically no limit to the range of such a sensor, except that the further away from the sensor the object is, the larger the area of detection is. If the object being measured doesn't occupy the full area, the emissions of other objects could reduce the accuracy of the reading. In addition, the temperature of the object and of the environment also affect the overall accuracy. The highest degree of accuracy is +/- 0.5 degrees Celsius when both the ambient temperature and the object temperature are between 0 and 50 degrees Celsius. As either temperature changes, the accuracy can decrease to up to +/- 4 degrees Celsius.

The measured value is the average temperature of all objects in the 10° Field Of View of the sensor.

The sensor is configured to continuously transmit the temperature of the measured object every 32ms.

===Board Temperature===

It is very important to understand that these accuracies are only guaranteed and achievable when the sensor is in thermal equilibrium and under isothermal conditions (there are no temperature differences across the sensor package board. The accuracy of the thermometer can be influenced by temperature differences in the board induced by causes like (among others): Hot electronics behind the sensor, heaters/coolers behind or beside the sensor or by a hot/cold object very close to the sensor that not only heats the sensing element in the thermometer but also the 1045 board.

The 1045 assumes that the ambient temperature has settled to a constant temperature. If the surrounding temperature is constantly changing, or if there is a difference of temperature across the sensor package, additional infra-red radiation will be sensed which can result in temperature errors outside of the calibrated errors.

===Emissivity===

In order to measure temperature using infrared radiation, it is absolutely essential to know the emissivity of the surface being measured. Emissivity is a measure of how effective a surface is at radiating energy. An emissivity of 1 is the most effective radiator - for a given temperature, it will radiate the most heat. The 1045 assumes that the surface being measured has an emissivity of 1. If the 1045 is used to measure a surface with an emissivity of 0.5, the measured temperature will be 50% of the difference in temperature between the board and object.

A few examples of some materials with a large difference in emissivity are aluminum, with a typical value of 0.18, and plastics, which can have a value ranging from 0.85 to 0.95. The visible colour of the object does not necessarily mean it has a higher emissivity value. A heavily oxidized aluminum object has an emissivity value of around 0.3, even though it looks very dark. The closer the value is to 1, the better the object is at emitting radiation.

The 1045 is calibrated for an object emissivity of 1.

For an arbitrary emissivity, the measured temperature can be converted to the surface temperature using this formula:

Surface Temperature = (Sensor Temperature - Ambient Temperature) * Emissivity + Ambient Temperature

A good resource of emissivity values of different materials can be found on [http://www.monarchinstrument.com/pdfs/TableofEmissivity.pdf this site].

Emissivity is a complicated topic, as it can vary depending on the temperature of the material. For precise measurements, you may have to calculate the emissivity of your material by comparing the reported Sensor Temperature to the actual surface temperature measured with a contact thermocouple.

IR measurements are true surface temperature measurements. For example, when measuring the temperature of a person, the actual temperature measured by an IR thermometer will be temperature of the clothing and not the skin temperature. Emissivity of the clothes is another issue that has to be considered.

===Sunlight Immunity===

The Temperature Sensor also contains a built-in optical filter to cut off the visible spectra and increase immunity against errors introduced by any surrounding light sources.

The wavelength pass band of this optical filter is from 5.5 to 14μm.

==API==
{{UGapih}}

===Functions===

{{UGapi|int TemperatureInputCount () [get] : Constant <nowiki>=</nowiki> 1
|Returns the number of temperature inputs (IR Sensors) that can be read by the PhidgetTemperatureSensor.
}}

{{UGapi|double Temperature (int Index) [get] : °C
|Returns the temperature measured by the IR sensor. This value is returned in degrees Celsius but can easily be converted into other units. This value will always be between TemperatureMin and TemperatureMax. Please refer to the device specifications for noise and accuracy details.
}}

{{UGapi|double TemperatureMax (int Index) [get] : Constant <nowiki>=</nowiki> 380°C
|Returns the maximum temperature that can be returned by an IR Sensor input.
}}

{{UGapi|double TemperatureMin (int Index) [get] : Constant, <nowiki>=</nowiki> -70°C
|Returns the minimum temperature that can be returned by an IR Sensor input.
}}

{{UGapi|double TemperatureChangeTrigger(int Index) [get,set] : °C
|Sets / gets the change trigger for an input. This is the amount by which the sensed temperature must change between TemperatureChangeEvents. By default this is set to 0.1. Setting TemperatureChangeTrigger to 0 will cause all temperature updates to fire events. This is helpful for applications that are implementing their own filtering.
}}

{{UGapi|double AmbientTemperature () [get] : °C
|Returns the temperature of the 1045 board, measured at the base of the IR Sensor. This temperature is used as a reference for IR sensor temperature measurement. This value will always be between getAmbientTemperatureMin and getAmbientTemperatureMax.
}}

{{UGapi|double AmbientTemperatureMax () [get] : Constant <nowiki>=</nowiki> 125°C
|Returns the maximum temperature that can be returned by the ambient sensor.
}}

{{UGapi|double AmbientTemperatureMin () [get] : Constant <nowiki>=</nowiki> -40°C
|Returns the minimum temperature that can be returned by the ambient sensor.
}}

===Events===

{{UGapi|OnTemperatureChange(int ProbeIndex, double Temperature) [event]
|Event that fires whenever the temperature measured by the IR sensor changes by more than the TemperatureChangeTrigger.
}}

{{UGapi|OnError(int code, String description) [event]
|PhidgetTemperatureSensor returns EEPHIDGET_OUTOFRANGE when an input goes out of the range specified by TemperatureMin-TemperatureMax. The event is reported once per input per out-of-range type, until the value has gone back into range. The description specifies the input, the type of out-of-range error and the out of range value that was read.
}}

==Product History==
{{UGhist}}
{{UGrow2|1045_0|February 2011 |0|100|Product Release}}
{{UGrow2|1045_0|May 2011 |0|101|getLabelString fix for lables > 7 characters}}
{{UGrow2|1045_1|September 2012|1|101|ICs put on reverse side to reduce error from self-heating}}

1135 User Guide

2014-05-09T17:59:46Z

Kat:

[[Category:UserGuide]]
{{UserguideTOC|1135.jpg|1135}}
==Getting Started==

===Checking the Contents===
{{UGbox|
'''You should have received:'''
* A Precision Voltage sensor
* A sensor cable
|
'''In order to test your new Phidget you will also need:'''
* A PhidgetInterfaceKit 8/8/8
* A USB cable
* A 9V battery
||}}

===Connecting the Pieces===
{{UGbox|
#Connect the Precision Voltage Sensor to an Analog Input on the PhidgetInterfaceKit 8/8/8 board using the sensor cable.
#Connect the voltage source to the terminal block. It is possible to connect the leads of the voltage source to either terminal - the reported voltage may just be of the opposite polarity.
#Connect the InterfaceKit board to your PC using the USB cable.
|
[[File:1135_0_Connecting_The_Hardware.jpg|400px|link=]]
||}}

===Testing Using Windows 2000 / XP / Vista / 7===

{{UGwin}}

===Running Phidgets Sample Program===

{{UGwin2|'''InterfaceKit-full'''}}

{{UGbox6|
Double Click on the [[File:Ph.jpg|link=]] icon to activate the Phidget Control Panel and make sure that the '''Phidget InterfaceKit 8/8/8''' is properly attached to your PC.
|[[File:1018_2_Control_Panel_Screen.jpg|400px|link=]]
|
#Double Click on '''Phidget InterfaceKit 8/8/8''' in the Phidget Control Panel to bring up InterfaceKit-full and check that the box labelled Attached contains the word True.
#Make sure that the Ratiometric box is not Ticked.
#With no connections on the input terminal blocks, the Analog In value should be approximately 500. The value displayed shows the 9V battery actual voltage when the battery’s + wire is connected to the VIN+ terminal block.
#You can adjust the input sensitivity by moving the slider pointer.
#Click on the Sensors button to bring up the Advanced Sensor Form.
|
[[File:1135 0 InterfaceKit Screen.jpg|link=|400px]]
|
#In the Advanced Sensor Form, select the 1135 - Voltage Sensor from the drop down menu.
#The differential voltage measured by the sensor is shown here.
#Formula used to convert the analog input SensorValue into voltage.
|
[[File:1135 0 Advanced Sensor Form Screen.jpg|link=|400px]]
}}

===Testing Using Mac OS X===

{{UGmac| | }}

===Using Linux===

{{UGlinux}}

===Using Windows Mobile / CE 5.0 / CE 6.0===

{{UGce}}

==Technical Details==
===General===
The Voltage Sensor measures the differential voltage between the input terminals and outputs the difference proportionally. The maximum differential voltage that can be measured accurately is +/-30V. When the positive and negative inputs are equal, the analog output value is 2.5V. When the positive input is 30V greater than the negative input, the analog output is 4.5V and when the positive input is 30V less than the negative input, the analog output is 0.5V.

When measuring voltage levels below 5V, you'll have more accuracy if you connect the leads directly to the [[Analog Input Primer|analog input]] of an interface kit.

Since the 1135 Voltage Sensor can measure a differential voltage, the common mode rejection (CMR) is an important specification. CMR refers to the amount of voltage that both input terminals of a differential amplifier can be offset without affecting the output gain. For example, if the positive terminal sees a voltage of 7V and the negative terminal sees a voltage of 5V, then the CMR would be 5V and would output a value of 2V at unity gain. For the 1135 Voltage Sensor, it is able to measure the differential voltage of +/-10V with a CMR of 40V while keeping the accuracy within 2%. Please note that the error specifications do not include the error introduced by the Analog to Digital Conversion on the Analog Input. (if you are using the 1135 with a PhidgetInterfaceKit) The majority of error introduced by the Analog to Digital conversion is from the error in the voltage reference (0.5% max), and the limitation of resolution in the SensorValue property. The best accuracy can be achieved by using a 2 or more point calibration of your
system - effectively calibrating the 1135 and the PhidgetInterfaceKit in a single step. If you are calibrating, be sure to use a good quality multimeter to determine the voltage being applied.

Using RawSensorValue in the formula will increase the resolution, which is limited by SensorValue to about 67mV.

===Formulas===
The Formula to translate SensorValue into differential voltage is:

::<math>V_{diff} = \frac{\frac{SensorValue}{200} - 2.5}{0.0681}</math>

where V<sub>diff</sub> is defined as V<sub>positive</sub> - V<sub>negative</sub>.

{{UGotherint}}

===Analog Input Cable Connectors===
Each Analog Input uses a 3-pin, 0.100 inch pitch locking connector. Pictured here is a plug with the connections labeled. The connectors are commonly available - refer to the [[Analog Input Primer]] for manufacturer part numbers.

==API==
{{SensorAPI}}

==Product History==
{{UGhist}}
{{UGrow|March 2010 |0 |N/A |Product Release }}

1073 User Guide

2014-05-06T20:05:45Z

Kat: added the getting started SBC video

[[Category:UserGuide]]
{{UserguideTOC|1073.jpg|1073}}

==Getting Started==

{{#ev:youtube|09Z61tf-JA4}}

===Checking the Contents===
{{UGbox|
'''You should have received:'''
* A Power Supply
* A Cat-5e network cable
* A Mounting kit (4 nuts & bolts, 4 plastic spacers)
* A PhidgetSBC3 Board

'''In order to test your new Phidget you will also need:'''
* A short length of wire to test the digital inputs
* An LED to test the digital outputs
* An Analog Sensor to test the analog inputs
* A UVC compatible Webcam

|[[File:1072_0_Package_Contents.jpg|400px|link=]]
||}}

===Connecting the Pieces===
{{UGbox|
# Connect the analog sensor to the analog input port 4 using a Phidgets sensor cable. The analog input ports are numbered from 0 to 7 starting from the left.
# Connect one end of a wire to digital input port 0 and the other end to ground (labelled ‘G’ on the underside of the board).
# Connect the LED by inserting the long LED wire into the digital output 7 and the shorter wire into Ground.
# Connect the power supply to the PhidgetSBC3 using the barrel connector.
# Connect the PhidgetSBC3 to your network with an Ethernet cable. Plug the wall adapter into an appropriate outlet. The red status indicator light located near the USB ports should be lit if the unit is receiving power. The green LED located above the red LED indicates boot status. The green LED will turn on and off once during boot and then turn back on when everything is running.
# Other Phidgets can also be connected to the 1073 using a USB cable.
|
[[File:1072_0_Connecting_The_Hardware.jpg|400px|link=]]
||}}

===Testing Using Windows 2000 / XP / Vista / 7===

{{UGwin}}

===Running Phidgets Sample Program===

Double clicking on the [[File:Ph.jpg|link=]] icon loads Phidget Control Panel; we will use this program to ensure that your new Phidget works properly.

{{UGbox|
*Make sure that the PhidgetSBC3 is powered and properly connected to your network.
* Click the '''PhidgetSBC3''' tab in the Phidget Control Panel.
* Double click on the PhidgetSBC3 device to bring up the PhidgetSBC3 configuration panel in your default web browser.
* You can differentiate multiple PhidgetSBC3s by their MAC address, which is printed on the sticker on the back of your board.

This control panel view will tell you (at the bottom):
* The '''link local''' address of the SBC (called the mDNS address), here it is {{Code|phidgetsbc.local}}
** The name {{Code|phidgetsbc.local}} is the default link local address
** Although there is a period after the link local address in the Phidget Control panel, the address itself does not include that final period
* The '''IP (Internet Protocol)''' address of the SBC, here it is 192.168.2.181
** There is no default for the IP address
** The SBC will only have an IP address if it successfully gained one through DHCP (Dynamic Host Configuration Protocol) over Ethernet

You will need one of these two pieces of information when you start working directly with the [[OS - Phidget SBC | SBC Operating System]] for tasks such as writing and running code on the SBC, so write these down somewhere while you work through the rest of this Getting Started page.

|[[File:1073_0_Control_Panel_Screen.jpg|400px|link=]]
||}}

{{UGsbc1}}

{{UGsbc2}}

{{UGsbc3}}

{{UGsbc4}}

==Technical Details==

===Rebooting/Resetting the PhidgetSBC===
To reboot the device, quickly press the black reset button found between the USB connectors and the power terminals. Both Ethernet Port LEDs (yellow-connectivity, green-activity), and the green status LED will turn off. The reboot is done when all LEDs come back on in about 25 seconds.

To reset the firmware, press and hold the button for 10 seconds until the green status LED begins to blink, then release. Both Ethernet Port LEDs will turn off (yellow-connectivity, green-activity) for 80 seconds; the green status LED will then turn off; then all LEDs will come back on in 20 seconds. All data will be lost and the operating system will be reset to a factory state.

To boot into the Recovery / Upgrade system, hold the button for 20 seconds until the green status LED switches from blinking slowly to blinking quickly, then release. The recovery system allows for factory reset, full system upgrades and recovery of the main system.

===Recovery / Upgrade System===
The recovery / upgrade system is a small system from which the main system can be reset/upgraded, or recovered.

====Entering the Recovery System====
The recovery system can be entered in two ways.
# From the ‘System: 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.

====Upgrades====
Generally, you should not need to do a full system upgrade. Upgrades are meant to be performed via the package system, and Phidgets maintains it’s own package repository from which to push out updates.

Occasionally, you may wish to go back to a clean install and upgrade to the latest rootfs/kernel from Phidgets. Phidgets will not be creating these images with every release of phidget21 as we did with PhidgetSBC1, rather they will be released several times a year, as needed for major changes not easy to push out via packages.

You can also flash your own custom kernel or root filesystem image.

====Factory Reset====
This restores the kernel and root filesystem from backup, overwriting any changes that may have been made. This is equivalent to holding down the reset button for 10 seconds.

====Recovery====
If the main filesystem has been damaged/misconfigured in such a way that it won’t boot, you may be able to fix the issue / recovery important files before running a reset. The recovery system runs an SSH server that you can loginto for console access. Username/password is: root/root.

You can mount the main root filesystem with the following commands (assuming it’s not damaged):
# ubiattach /dev/ubi_ctrl -m 6
# mount -t ubifs /dev/ubi0_0 /mnt

===Ports and Connectors===

{{UGbox|
Numbered in the circles on the diagram:
# 10/100baseT Ethernet
# Six USB High-Speed Ports
# Indicator LEDs
# Reboot / Reset Button
# Power input terminal
# Power input jack
# Eight Interface Kit Digital Inputs (Indexed 0 to 7)
# Eight Interface Kit Digital Outputs (Indexed 0 to 7)
# Eight Interface Kit Analog Inputs (Indexed 0 to 7)
:A. JTAG connector, for internal testing purposes only
|[[File:1073_0_Layout_Top.jpg|400px|link=]]
||}}

[[File:1072_0_Layout_Front.jpg|500px|link=]]

:1. This Ethernet port is used for network connectivity to the PhidgetSBC. This enables access to the PhidgetSBC as well as any connected Phidgets through the webservice. Alternatively, the USB Wireless adapter can be used for network connectivity.
:2. These USB ports can be used for connecting Phidgets, Wi-Fi adapters, flash drives, webcams, USB hubs, etc.
:3. These LEDs indicate the status of the PhidgetSBC. The Red LED indicates that the power supply is on and running properly. The green LED indicates boot status. The green LED will turn on and off once during boot and then turn back on when everything is running.
:4. This will reboot the board if pressed once. Note that this is a forced reboot. Any user programs that were running may leave their data in a inconsistent state, but this is safe for the base system. A soft reboot can be performed remotely from the configuration interface.If held for more then 10 seconds, the red LED will start to blink and enter emergency Reset mode. Once the button is released, the onboard memory will revert to a factory-fresh state. This includes overwriting the kernel and root file system, and erasing all configuration, user data, and applications. If held for more then 20 seconds, the Recovery/Upgrade system will be booted, from which a Factory Reset/Full filesystem upgrade can be performed.
:5,6. The PhidgetSBC can be powered from either the terminals or the barrel connector.
:7,8,9. The Interface Kit I/O is explained in the Interface Kit section of the manual.

===Power Distribution===

The 12V power supply is stepped down to 5V and distributed in the following way:

* Each USB port has 500 mA available
* All analog inputs share a total of 500 mA
* The digital outputs, +5V terminals, USB controller, and pull-ups all share a total of 500 mA

===Power Over Ethernet===
Power over Ethernet can be used to provide both a network connection and power to a device when a power outlet is not available. This means that with the proper adapters, you can run the PhidgetSBC entirely off an Ethernet source. The PhidgetSBC does not draw power directly from a powered Ethernet line, but instead can use a setup where the power is split to a separate line again near the PhidgetSBC. The board has been tested and will work with Power Sourcing Equipment that can output 6-12VDC.

===Hardware Layout===
The PhidgetSBC is based around the i.MX28 processor. This is an ARM926EJ-S based microprocessor from Freescale, which runs at 454MHz. Connected to this is 128 MiB of DDR2 SDRAM, 1 GiB of very large page NAND and a 10/100baseT Ethernet controller. The microprocessors USB Host port is connected to a 7-port USB 2.0 High Speed Hub chip. The integrated PhidgetInterfaceKit 8/8/8 is connected to one of the hub ports, with the other 6 ports being brought out to the user.

===Software Layout===
The PhidgetSBC runs Debian/GNU Linux 7.0 as its operating system and gets booted with U-Boot. The kernel is 3.6.3 and generally kept up to date with the latest releases. The root filesystem is created using debootstrap and is mounted in a ~924MiB nand partition using the UBIFS filesystem, in Read-Write mode.

Configuration data is located at ‘/etc/webif’. This is where all configuration that can be set through the website is located.

User applications are stored in ‘/usr/userapps’, each is their own directory.

The kernel is stored on bare Nand in it own 4MiB partition, in the uImage format.

===Date and Time===
The date and time are set using ntp (network time protocol) at boot. The ntp daemon continues to run in the background and will periodically update the clock, keeping it very close to real time.

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, the real-time clock may not have the correct time.

===Wireless Networking System===
Wireless networking is supported using the available adapter and is configured through the configuration interface.

===Configuration System===
The configuration system used by the website is stored in ‘/etc/webif’. These files should generally not be changed manually, but there is no reason why they could not be. It’s very easy to enter invalid data that could cause the system to behave unexpectedly or not boot.

===Nand Layout===
The board contains 1GiB of Nand. This nand is split into 8 partitions as follows:
{|
|-
|0: bootloader || size: 4MiB || Read Only
|-
|1: environment || size: 512KiB || Read Only
|-
|2: device_tree || size: 512KiB || Read Only
|-
|3: recovery_system || size: 4MiB || Read Only
|-
|4: recovery_kernel || size: 4MiB || Read Only
|-
|5: recovery_fs || size: 83MiB || Read Only
|-
|6: kernel || size: 4MiB || Writable
|-
|7: rootfs || size: 924MiB || Writable
|}

U-Boot and recovery kernel and filesystem cannot be written from Linux - this is a safety measure.

===Boot Process===
This describes the boot process from power on.
# CPU loads the bootstream from Nand
# Bootstream initializes memory, power and GPIO, then runs u-boot from Nand
# u-boot turns the green LED on and then checks to see if the reset button is being held down
# if the reset button is held, u-boot either restores the kernel/filesystem, or boot into the recovery system, depending on the hold time
# u-boot then loads the device tree and Linux kernel into Ram and then runs the kernel
# Linux reads in the device tree from ram, and turns off the green LED
# Linux then boots, bringing up usb, ethernet, etc.
# init gets run as the parents of all processes, and uses the /etc/inittab script to bring up the system. This includes mounting other filesystems, settings the hostname, running the scripts in /etc/init.d, and running user applications
# inittab then turns the green LED on. The system has finished booting

===Drivers for USB to Serial adapters===
The SBC kernel contains driver support for the following USB to Serial Adapters. Please consult the kernel documentation for details into the driver support for the USB to Serial adapters.

{| style="border:1px solid darkgray;" cellpadding="7px;" width="40%"
|-style="background: #e9e9e9" align=center
! Company || Product
|-
|style="width: 10%; background: #f0f0f0" align=left| ConnectTech
|style="width: 10%; background: #f0f0f0" align=left| WhiteHEAT
|-
|style="width: 10%; background: #f0f0f0" align=left| Keyspan
|style="width: 10%; background: #f0f0f0" align=left| USA-18X, USA-28, USA-28X, USA-28XA, USA-28XB, USA-19, USA-19W, USA-19QW, USA-19QI, USA-49W, USA-49WLC
|-
|style="width: 10%; background: #f0f0f0" align=left| FTDI
|style="width: 10%; background: #f0f0f0" align=left| Single Port Serial Adapter
|-
|style="width: 10%; background: #f0f0f0" align=left| Cypress
|style="width: 10%; background: #f0f0f0" align=left| M8 CY4601 Family
|-
|style="width: 10%; background: #f0f0f0" align=left| Digi International
|style="width: 10%; background: #f0f0f0" align=left| AccelePort USB Serial
|-
|style="width: 10%; background: #f0f0f0" align=left| Belkin
|style="width: 10%; background: #f0f0f0" align=left| USB Serial Adapter F5U103
|-
|style="width: 10%; background: #f0f0f0" align=left| MCT
|style="width: 10%; background: #f0f0f0" align=left| USB Single Port Serial Adapter U232
|-
|style="width: 10%; background: #f0f0f0" align=left| Inside Out Networks
|style="width: 10%; background: #f0f0f0" align=left| Edgeport Serial Adapter
|-
|style="width: 10%; background: #f0f0f0" align=left| Prolific
|style="width: 10%; background: #f0f0f0" align=left| PL2303
|-
|}

===Drivers for USB Wifi Adapters===
The SBC kernel contains driver support for the following USB Wireless Adapters. Please consult the kernel documentation for more details.

{| style="border:1px solid darkgray;" cellpadding="7px;" width="60%"
|-style="background: #e9e9e9" align=center
! Company || Module || Chipsets
|-
|style="width: 10%; background: #f0f0f0" align=left| Atheros
|style="width: 10%; background: #f0f0f0" align=left| ath9k_htc
|style="width: 10%; background: #f0f0f0" align=left| AR9271, AR7010
|-
|style="width: 10%; background: #f0f0f0" align=left| Atheros
|style="width: 10%; background: #f0f0f0" align=left| carl9170
|style="width: 10%; background: #f0f0f0" align=left| AR9170
|-
|style="width: 10%; background: #f0f0f0" align=left| Intersil
|style="width: 10%; background: #f0f0f0" align=left| r8712u
|style="width: 10%; background: #f0f0f0" align=left| ISL3877, ISL3880, ISL3886, ISL3887, ISL3890
|-
|style="width: 10%; background: #f0f0f0" align=left| Realtek
|style="width: 10%; background: #f0f0f0" align=left| r8712u
|style="width: 10%; background: #f0f0f0" align=left| RTL8188SU, RTL8191SU, RTL8192SU
|-
|style="width: 10%; background: #f0f0f0" align=left| Ralink
|style="width: 10%; background: #f0f0f0" align=left| rt2500usb
|style="width: 10%; background: #f0f0f0" align=left| RT2500USB/RT2571
|-
|style="width: 10%; background: #f0f0f0" align=left| Ralink
|style="width: 10%; background: #f0f0f0" align=left| rt2800usb
|style="width: 10%; background: #f0f0f0" align=left| RT2070, RT2770, RT2870, RT3070, RT3071, RT3072, RT3370, RT3572, RT5370, RT5372
|-
|style="width: 10%; background: #f0f0f0" align=left| Ralink
|style="width: 10%; background: #f0f0f0" align=left| rt73usb
|style="width: 10%; background: #f0f0f0" align=left| RT2501USB/RT2571W
|-
|style="width: 10%; background: #f0f0f0" align=left| Realtek
|style="width: 10%; background: #f0f0f0" align=left| rtl8187
|style="width: 10%; background: #f0f0f0" align=left| RTL8187L, RTL8187B
|-
|style="width: 10%; background: #f0f0f0" align=left| Realtek
|style="width: 10%; background: #f0f0f0" align=left| rtl8192cu
|style="width: 10%; background: #f0f0f0" align=left| RTL8188CUS, RTL8192CU
|-
|style="width: 10%; background: #f0f0f0" align=left| ZyDAS / Atheros
|style="width: 10%; background: #f0f0f0" align=left| zd1211rw
|style="width: 10%; background: #f0f0f0" align=left| ZD1211/ZD1211B, AR5007UG
|-
|}

===U-Boot===
U-Boot is used for setting up the processor and booting Linux, and is only accessible by the serial port. Normal users will not need to use it. If you are connected to the serial port, you will see the U-Boot prompt shortly after power up. You can view the environment variables for information on how to properly boot Linux on the PhidgetSBC.

Be very careful when modifying the u-boot partition. If it is damaged or overwritten, it is difficult to fix.

Refer to U-Boot documentation here: [http://www.denx.de/wiki/DULG/Manual www.denix.de/wiki/DULG/Manual] for more information on using U-Boot.

===Ad-hoc Networks===

The SBC can be configured as a device in an ad-hoc network.

For more information, visit the [[Ad-Hoc_Networks_on_the_SBC|Ad-Hoc Networks]] page.

===Further Reading===

Check the [[OS - Phidget SBC|Phidget SBC]] page for more details about using the Phidget SBC.

Check the [[1018 User Guide]] for more information about the InterfaceKit on this board.

==API==

The Phidget SBC has the same API functions and events as the PhidgetInterfaceKit.

Check the [[1018 User Guide]] for API details.

==Product History==
{{UGhist}}
{{UGrow|January 2013|0|300|Product Release}}

OS - Linux

2014-05-06T20:01:47Z

Kat: added a getting started on Linux video.

[[Category:OS]]
{{OSLang|[[File:icon-Linux.png|64x64px|link=OS - Linux]]|On Linux, Phidgets can be either plugged directly into a USB Port or run over a network using the [[#WebService | WebService]].}}
__TOC__

You need kernel '''version 2.6''' (released in 2003) or later.

==Quick Downloads==

Linux has complete support for all Phidgets and their software APIs; the only thing it lacks when compared to Windows and OS X is a graphical user interface. We walk you through all steps for download, installation, checking, and starting to write code below.

If you are already a pro, and just want the downloads:
*[{{SERVER}}/downloads/libraries/libphidget.tar.gz Phidget Libraries for Linux]
*[{{SERVER}}/downloads/libraries/phidgetwebservice.tar.gz Phidget WebService for Linux]
*[[Software License]]

==Getting Started with Linux==

{{#ev:youtube|6pXWhGzX4Fg}}

===Installing===

To install the libraries, follow these steps:

#Install libusb-1.0 development libraries - {{Code|libusb-1.0-0-dev}}.
#*Note that libusb-1.0 may be already on your system, but the development libraries probably aren't.
#*Search for {{Code|libusb-1.0-0-dev}} or similar in your distribution package directory.
#*Or install [http://www.libusb.org/ from source].
#Unpack and install the [{{SERVER}}/downloads/libraries/libphidget.tar.gz Phidget Libraries]
#*From the main unpacked libraries directory, run:
#*:{{Code|./configure}}
#*:{{Code|make}}
#*:{{Code|sudo make install}}
#*This will compile phidget21.h and place the library into your gcc path

'''Note:''' Although these libraries are written in C, the additional libraries for Python, Java, and most other Phidget-supported languages depend on them.

===Checking===

To confirm the libraries were installed and work correctly, you can check both the hardware and software sides of the interface. It is worth checking the software side first, because if it works then you know the hardware side is also okay.

====Software====

To confirm that the libraries were installed correctly and can be used in code, you can use the [{{SERVER}}/downloads/examples/phidget21-c-examples.tar.gz Phidget Generic C Examples].

The easiest way to confirm correct installation will be to compile and run the {{Code|HelloWorld}} C example, included in the examples download. This does not involve writing any C code, but it does involve compiling the example and running it, which is a quick process as we show below. If you feel more comfortable running the {{Code|HelloWorld}} example for your specific language, you can skip below and pick your language, but keep in mind that any problems could be with the C library installation and not necessarily with your language.

To compile and run the basic C example for checking your installation:

1. Unpack the Phidget Generic C Examples<br>
2. Open a terminal (often Ctrl-Alt-T) and go to the directory where the examples are unpacked<br>
3. Compile the {{Code|HelloWorld.c}} example:<br>
<div class="source">
<syntaxhighlight lang=bash>

gcc HelloWorld.c -o HelloWorld -lphidget21

</syntaxhighlight>
</div>
4. Run the {{Code|HelloWorld}} example:<br>
<div class="source">
<syntaxhighlight lang=bash>

sudo ./HelloWorld

</syntaxhighlight>
</div>
(The sudo is needed for USB access for now, see the [[#Setting udev Rules|Setting udev Rules]] section for how to change this)

The {{Code|-lphidget21}} will look in the standard library location for your Linux distribution (usually {{Code|/usr/lib/}}) for the Phidget 21 library file. Generally, libraries to be linked on Linux through {{Code|gcc}} have a naming convention. For example, {{Code|-lphidget21}} looks for the binary files '''{{Code|libphidget21.a}}''' and '''{{Code|libphidget21.so}}''' in the library location. These files are automatically put in the library location during the {{Code|make install}} step of [[#Installing | installing the libraries]].

The HelloWorld program will simply print out basic information for any device you plug in, and print a message upon unplugging the device. For example, starting the program, plugging in an Interface Kit Phidget, unplugging the Interface Kit, and pressing Enter displays:

<div class="source">
<syntaxhighlight lang=bash>

$ sudo ./HelloWorld

Opening...
Press Enter to end

Hello to Device Phidget InterfaceKit 8/8/8, Serial Number: 37299
Goodbye Device Phidget InterfaceKit 8/8/8, Serial Number: 37299

Closing...

</syntaxhighlight>
</div>

====Hardware====

If the out-of-the-box examples do not work, make sure the Phidget is seen by your USB interface. To check this, you can use the kernel log reader {{Code|dmesg}}. Pipe the output of {{Code|dmesg}} into the utility {{Code|tail}} to read the last ten lines of the log:

<div class="source">
<syntaxhighlight lang=bash>

$> dmesg | tail
....(9 lines)....
[24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd

</syntaxhighlight>
</div>

The number between the [ ] is the system time in seconds since the last boot up, so you can tell whether the event was recent or not. (This will also tell you the interrupt type of Phidget that is registered by the USB interface, see the [[#Common Problems and Solutions | common problems section below]] for more information on what this means.)

The Phidget should both connect and disconnect properly, so unplugging it should result in an additional line at the tail:

<div class="source">
<syntaxhighlight lang=bash>

$> dmesg | tail
....(8 lines)....
[24344.013638] usb 2-1.2: new low speed USB device number 5 using ehci_hcd
[25094.809328] usb 2-1.2: USB disconnect, device number 5

</syntaxhighlight>
</div>

If you don't see similar lines to these at the tail of your kernel log, take a look at the [[#Troubleshooting|troubleshooting]] section below, as well as the '''Communications''' section of our [[General Troubleshooting#Communications Troubleshooting|general troubleshooting page]].

====Troubleshooting====

If the examples '''do not''' work but USB '''does''' work (i.e. your computer can consistently see the device in the [[#Hardware|hardware]]), take a moment to check the basics:
* No other programs, drivers, or processes are using that USB port in software
* You are running the example program as root (or your udev rules have been set properly)
* You are using libusb 1.0 (not the older 0.1 release)
* You have compiled versions of libphidget21.a and libphidget21.so in your system library location (usually {{Code|/usr/lib}})
* The Phidget libraries are the latest version (visit the [[#Quick Downloads| quick downloads section]] to download them)
* Your Linux kernel version is 2.6 or later (type {{Code|uname -r}} in a terminal to get your kernel version)
* Check the [[#Common Problems and Solutions|common problems]] section below, some specific combinations can cause problems

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

==Programming Languages==

Now that you have the basic libraries installed, you can pick your language and begin programming!

If you are not using the [[#WebService | webservice]] (discussed below) to control a Phidget over a network, your next step will be to delve into the use of your specific language. Each page has its own set of specific libraries, code examples, and setup instructions.

On Linux, we recommend the following languages:

*[[Language - C/C++|C/C++]]
*[[Language - Java | Java]]
*[[Language - Python | Python]]
*[[Language - Ruby | Ruby]]
*[[Language - C Sharp | C#]] (Using [[Language - C Sharp#Mono|Mono]])
*[[Language - Flash AS3 | Flash AS3]]

You can also use these languages, but they do not support [[General Phidget Programming#Event Driven Code | event driven code]], and must use [[General Phidget Programming#Logic Code | logic code]] only:

*[[Language - MATLAB|MATLAB]]
*[[Language - Simulink|Simulink]]

==WebService==

The Phidget WebService allows you to remotely control a Phidget over a network.<br>This section helps you install, check, and use the WebService on Linux, but we also have an overview of the [[Phidget WebService]] in general.

===Installing the WebService===

To install the webservice, you must first have the [[#Installing|Phidget libraries installed]]. Then, follow these steps:

#Download '''avahi''' and its development libraries (mdnsresponder/bonjour is also an option, see the [[#WebService with mDNSResponder|webservice with mDNSResponder]] section)
#*Try {{Code|apt-cache search avahi}} in a terminal to find current packages
#*Often, this is installed in a default system, you may already have it
#Unpack and install the [{{SERVER}}/downloads/libraries/phidgetwebservice.tar.gz Phidgets WebService] source code tarball for Linux
#*From the unpacked WebService source code directory, run:
#*:{{Code|./configure}}
#*:{{Code|make}}
#*:{{Code|sudo make install}}
#*This will compile the executable {{Code|phidgetwebservice21}} and place it into {{Code|/usr/bin/phidgetwebservice21}}

====WebService with BSD====

For '''BSD''', the webservice has been found to work (BSD 8+) but requires a special configuration at the {{Code|./configure}} step:

<div class="source">
<syntaxhighlight lang=bash>
./configure LIBS=/usr/lib/libphidget21.so CFLAGS=-pthread
</syntaxhighlight>
</div>

Then {{Code|make}} and {{Code|sudo make install}} are the same.
<br>
The {{Code|LIBS}} argument may not be necessary, but sometimes BSD has trouble finding the library install location. The {{Code|CFLAGS}} argument is needed because BSD needs explicit linking for using threads.

====WebService with mDNSResponder====

To use '''mdnsresponder''' instead of avahi, change the configure script to be:

<div class="source">
<syntaxhighlight lang=bash>
./configure --enable-zeroconf=bonjour
</syntaxhighlight>
</div>

(To see all options, use {{Code|./configure --help}} like you would any configure script)

===Setting Up the WebService===

To set up and use the webservice, it helps to have [[#Setting udev Rules|set your udev rules]]. Otherwise, you must run the webservice as root.

You can get command line help with {{Code|phidgetwebservice21}} by using the {{Code|-h}} option:

<div class="source">
<syntaxhighlight lang=bash>
$ phidgetwebservice21 -h
</syntaxhighlight>

<syntaxhighlight lang=text>
'phidgetwebservice21' is a Phidget and Dictionary server from Phidgets Inc. See www.phidgets.com for more information.
Usage: phidgetwebservice21 [OPTION]
All parameters are optional. The default parameters are: port=5001, ServerName=(Computer Name) and no password

Options:
-p Port
-n Server Name
-P Password
-v Debug mode
-h Display this help
</syntaxhighlight>
</div>

You will see this help regardless of whether the webservice was correctly hooked in to avahi. In fact, you will see it even if you explicitly disabled mDNS in the {{Code|./configure}} step at compile:

<div class="source">
<syntaxhighlight lang=bash>
./configure --disable-zeroconf
</syntaxhighlight>
</div>

(To see all options, use {{Code|./configure --help}} like you would any configure script)

To find the defaults used by {{Code|phidget21webservice}}, the command line is the fastest way to learn the default server name and IP address of your computer:
*For the default server name, use {{Code|hostname}} on the command line.
*For your IP address, use {{Code|ifconfig -a}} on the command line.
**A line in the return text, under your main internet connection (usually {{Code|eth0}}) will say something like {{Code|inet addr:192.168.3.178}}, which is your IP.

Using a server name to connect would not be an option without avahi or some other mDNS service; in this case you would only have the option to use an IP address.

===Using the WebService===

To use a Phidget over the webservice, you'll want to:
* Obtain code you can use to open a Phidget remotely
* Start the webservice on the computer that directly connects to the Phidget
* Run your program on the remote computer that will control the Phidget over the network

The easiest way to test these steps on Linux is simply to set up the webservice and run the Phidget program on the same computer, using the loopback interface. Later, you can replace one of the two ends with a different computer and/or operating system.

To quickly create code to run remotely, in our examples we include commented out lines with openRemote() function calls of different types. In the C example for your device, find the line that says:

{{Code|CPhidget_open((CPhidgetHandle) device, -1)}}

and change it to be:

<div class="source">
<syntaxhighlight lang=bash>
int serial_number = 37299
CPhidget_openRemoteIP ((CPhidgetHandle) device, serial_number, "127.0.0.1", 5001, NULL)
</syntaxhighlight>
</div>

Except that you should replace '''37299''' with the serial number of your Phidget, which you can obtain from either the Phidget board itself, or from when you [[#Checking|ran the HelloWorld example code]]. The IP address "127.0.0.1" simply loops back to the same computer, and 5001 is the default port as found from using {{Code|phidget21webservice -h}} in [[#Setting Up the WebService|the Setting Up the WebService]] section. The NULL is used to not specify a password.

Save the changed example under a different filename. In the walkthrough here, we are using the {{Code|InterfaceKit.c}} example, and we rename it to be {{Code|InterfaceKitRemote.c}}

Compile your new C file. In our {{Code|InterfaceKitRemote.c}} case, this would be by:

<div class="source">
<syntaxhighlight lang=bash>
gcc InterfaceKitRemote.c -o InterfaceKitRemote -lphidget21
</syntaxhighlight>
</div>

1. Start two terminals to run this test, usually opened via Ctrl-Alt-T. Your [[#Setting udev Rules|udev rules]] need to be set up or you should use sudo for every command. First, start the webservice in Terminal #1:

[[Image:Linux_ws_start.png|link=]]

This will broadcast any Phidget events, and receive any Phidget requests, both over the network.

2. Start the InterfaceKitRemote program that you just compiled which will open the remote Phidget. In this case, it is {{Code|InterfaceKitRemote}}:

[[Image:Linux_ws_step2.png|link=]]

3. Now, plug in the Phidget! The {{Code|phidget21webservice}} program captures the attach and other events and sends them out over the network (in the background in Terminal #1) and the Phidget software objected opened with openRemote in Terminal #2 receives them:

[[Image:Linux_ws_step3.png|link=]]

4. You can confirm that the webservice was indeed behind this exchange by killing the webservice process while still allowing the remote program to run:

[[Image:Linux_ws_step4.png|link=]]

===Debugging the WebService===

In addition to enabling [[General Phidget Programming#Logging|logging]] in your Phidget code, you can get additional debugging information from the WebService itself. This additional debugging is enabled via a re-compile of the webservice. From the webservice source code directory, do:

<div class="source">
<syntaxhighlight lang=bash>
make clean

./configure --enable-debug

make

sudo make install
</syntaxhighlight>
</div>

If you suspect multicast DNS (mDNS) may be the problem, you can:
* Try compiling the webservice with mDNSResponder, as described in [[#Installing the WebService|Installing the WebService]], or
* Try compiling the webservice completely without mDNS, as described in [[#Setting Up the WebService|Setting Up the WebService]]

==Advanced Uses==

===Setting udev Rules===

If you don't want to be using {{Code|sudo}} to run Phidget programs (including the webservice) forever, you will want to create a {{Code|udev}} rule to allow yourself access to the Phidget when you are not root.

Udev has an easy way to set the owner and permissions of the USB interface of the Phidget - it finds all devices that match a given set of rules, and applies new traits to them. But you need to give udev something to match in order to apply the new settings. Here, we will tell udev to match the vendor code for Phidgets, Inc.

We recommend that you use the rules file included in the library download you have already installed. Check the README file included in that download for information on how exactly to install it.

The rules for udev are kept in files in {{Code|/etc/udev/rules.d/}} and are traditionally grouped into order of running (10 runs before 20, 30, etc) and device type (cd, network, etc). There should be one or more files in there already - if this is your first time editing udev rules take a look at them to see the syntax to use:
* Commas separate each pair with == or =
* One rule on each line, no line breaks
* Quotes around the value to be matched or changed
* Comments can be added on lines starting with #

Strictly speaking, the files run in lexical order (i.e. the order they're listed when you use {{Code|ls}}). A device can match many rules, and all will apply (if possible). If conflicting rules are found, the first rule found is followed.

===Starting the WebService at Boot===

If you are tired of starting the webservice on the command line all the time, you can have the webservice start when your system starts, every time.

====User Space====

If you are running a standard Linux machine with an X-server (Unity, KDE) the easiest way to do this is to have the Phidget WebService start when your x server starts.

In this case, the webservice will be running in user space, so your [[#Setting udev Rules|udev rules need to be set up]] for the your user permissions to be able to access the USB ports using libusb.

Within the X-windowing system, there is usually some sort of {{Code|System → Settings/Preferences → Startup}} that you can choose to add programs that start when a user session starts. On Ubuntu you can use Unity to find programs listing "startup" in their names to accomplish the same thing. This will eventually lead you to a graphical tool like this to simply add the {{Code|/usr/bin/phidgetwebservice21}} program:

[[Image:linux_ws_boot.png|400px|link=]]

====As A Service====

You would want to set the boot start of {{Code|phidgetwebservice21}} to be a service if you are running a server, or a headless machine. It is handy any time you need the webservice to be started as a booted, respawning service with a presence in different run levels and for all users.

A service is essentially a program that hangs out in the background, waiting to be used by some incoming task. When the service is needed, the service forks a program to handle that need. Most services that run on your Linux computer already have the ability to fork themselves.

The webservice, however, is just a binary on Linux - {{Code|phidgetwebservice21}} - and so we need a program that handles the forking for us. For this, we use the {{Code|start-stop-daemon}} program to spawn a standalone process for us, or kill it, based on our service-like start, stop, and restart commands.

To do this, we need:
# A script that tells the boot process how to start and handle the webservice (i.e. by using {{Code|start-stop-daemon}})
# A link from that script to the boot list
# An initialization file for the script

First, the script. We will walk through Debian here, both because it is such a common distribution and because it is the distribution that our [{{SERVER}}products.php?product_id=1073 Single Board Computer] runs. But {{Code|init}} is surprisingly diverse on Linux, including everything from a different boot order, to different initialization programs and structure, and even different runlevels.

On Debian (including Ubuntu), the initialization script covers:
* Runlevels that the service should be present on
* Dependencies of the service
* Name of the service and other informative data
* The location of the PIDFILE, which stores the process ID (pid) for later dealing with a spawned instance
* Any configuration file locations
* What to do when the service is given instructions to '''start''', '''stop''', or '''reload'''.

The Debian script we use to start the webservice on the [{{SERVER}}products.php?product_id=1073 Single Board Computer]:

<div class="source">
<syntaxhighlight line start="1" lang=bash>

#!/bin/sh

### BEGIN INIT INFO
# Provides: phidgetwebservice
# Required-Start: $network $remote_fs
# Required-Stop: $network $remote_fs
# Should-Start: avahi
# Should-Stop: avahi
# Default-Start: 2 3 4 5
# Default-Stop: 0 1 6
# Short-Description: Phidget WebService
# Description: Phidget WebService for controlling Phidgets over the network.
### END INIT INFO

DESC="Phidget WebService"
NAME=phidgetwebservice
BIN=phidgetwebservice21
DAEMON=/usr/bin/$BIN
PIDFILE=/var/run/$NAME.pid
CFG=/etc/default/$NAME

# Gracefully exit if the package has been removed.
test -x $DAEMON || exit 0

# load config
pws_port="5001"
pws_serverid=""
pws_password=""
[ -f $CFG ] && . $CFG

start() {
[ -z "$pws_port" ] || OPTIONS="-p $pws_port "
[ -z "$pws_password" ] || OPTIONS="$OPTIONS-P $pws_password "

if [ -z "$pws_serverid" ]; then
OPTIONS="$OPTIONS -n $( hostname )"
else
OPTIONS="$OPTIONS -n $pws_serverid"
fi

echo -n "Starting $DESC: "
start-stop-daemon -S -b -q -p $PIDFILE -m -x $DAEMON -- $OPTIONS && echo "OK" || echo "ALREADY RUNNING"
}

stop() {
echo -n "Stopping $DESC: "
start-stop-daemon -K -q -p $PIDFILE -x $DAEMON && echo "OK" || echo "NOT RUNNING"
}

case "$1" in
start)
start
;;
stop)
stop
;;
restart|force-reload)
stop
sleep 1
start
;;
*)
echo "Usage: $0 {start|stop|restart}"
esac

exit 0
</syntaxhighlight>
</div>

Save the script into a file called {{Code|phidgetwebservice}}, and use {{Code|chmod 755}} to make it executable.

Also on Debian, startup service scripts should go in {{Code|/etc/init.d}}, and then put within the appropriate runlevel-numbered folder - by symbolic link. There is a handy tool to do this for you, called {{Code|insserv}}:

<div class="source">
<syntaxhighlight lang=bash>
sudo insserv -d phidgetwebservice
</syntaxhighlight>
</div>

The {{Code|insserv}} program is the program that makes use of the {{Code|### BEGIN INIT INFO...### END INIT INFO}} that appears at the top of the {{Code|phidgetwebservice}} script. Use {{Code|man insserv}} for more information. The {{Code|insserv}} tool handles the mess of finding the right runlevel folders (i.e. the {{Code|rc.d}} numbered folders) and making the appropriate links. You can see what links would be updated by running {{Code|insserv}} with the {{Code|-n}} option, for a dry run.

'''Note:''' When you run {{Code|insserv}}, all of the dependencies for the boot order are re-written. This means that all of the initialization scripts in {{Code|/etc/init.d}} are re-examined. So, you'll probably get a lot of output when you run the command.

Then, you can check that {{Code|phidgetwebservice}} is on the service list with:

<div class="source">
<syntaxhighlight lang=bash>
service --status-all
</syntaxhighlight>
</div>

And you can start it right now without rebooting like this:

[[Image:linux_system_service_start.png|link=]]

The {{Code|service}} command has many options to start and stop services like the phidgetwebservice, try {{Code|man service}} for more information.

At this point, you can follow the client instructions on [[#Using the WebService|using the webservice]] to create a loopback test for the new webservice service that should now be running.

The final piece, for future configuration changes, is that the {{Code|/etc/init.d}} script looks for the file {{Code|/etc/default/phidgetwebservice}} upon starting up. The file is expected to contain the port, server ID, and password for the server side of the webservice. These are also set in the {{Code|phidgetwebservice}} script in {{Code|init.d}}, as you can see from reading the code above, but if you want to change them a lot, you can edit the configuration file rather than changing the {{Code|phidgetwebservice}} script and re-installing by {{Code|insserv}} every time. The configuration file in {{Code|/etc/default/}} should contain the same syntax as that used in the script source above:

<div class="source">
<syntaxhighlight lang=bash>
pws_port="5001"
pws_serverid=""
pws_password=""
</syntaxhighlight>
</div>

===Cross-Compiling with a Custom Toolchain===

This would allow you to have the Phidget libraries compiled to include in code for an embedded device. When developing for an embedded device, you will often write code for it on your 'normal' computer, and then build the code to binary with a different target than the processor in your computer. Many microcontrollers do not have the ability to run a full operating system, and hence cannot compile code natively.

The collection of tools used to create binary code for a separate system is called a ''toolchain''. Compiling the Phidget libraries specifically for an embedded system, and placing them into the path for writing code on top of the libraries is like adding another link in this chain.

You can use the typical {{Code|./configure}} setup for custom build targets:

<div class="source">
<syntaxhighlight lang=bash>
./configure --prefix=toolchain_location --build=this_system --host=target_system
</syntaxhighlight>
</div>

For the Phidget libraries, the {{Code|./configure}} tool works this way as well. You'd use this in the [[#Installing|install the libraries section]] setup. For example, let's say you're building the libraries to develop code for the [{{SERVER}}products.php?product_id=1073 Single Board Computer] as a target. Your system is a standard Linux system (i686-pc-linux-gnu) and the target system for the SBC is {{Code|arm-linux-gnueabi}}. For this target, you'll need the base of the GNU embedded Debian chain:

<div class="source">
<syntaxhighlight lang=bash>
sudo apt-get install gcc-arm-linux-gnueabi
</syntaxhighlight>
</div>

Then, download the Phidget libraries [[#Quick Downloads|above]] and unpack them into a folder {{Code|phidget_libraries}}. If {{Code|/usr/arm-linux-gnueabi}} is the location of your ARM toolchain (downloaded above in {{Code|gcc-arm-linux-gnueabi}}), type:

<div class="source">
<syntaxhighlight lang=bash>
~/phidget_libraries $> ./configure --prefix=/usr/arm-linux-gnueabi --build=i686-pc-linux-gnu --host=arm-linux-gnueabi
</syntaxhighlight>
</div>

===Linux on Non-Standard Systems===

We occasionally get requests to use Phidgets on Linux systems other than a standard laptop or desktop. One example is the Raspberry Pi system. Often these systems include USB ports, so the combination makes sense.

Our libraries are installed by building from source, and their main dependency is the {{Code|libusb-1.0-0-dev}} library, so if you can get gcc on your machine (or set up a cross compiler for it) and you can also install the libusb-1.0 development headers, you can probably get Phidgets to work. Of course, we don't offer much support for these systems, so - depending on your system - expect to spend some raw time getting it up and going.

If you're new to the embedded computer thing, keep in mind that for these super basic systems, once you've gotten a power supply, and storage, and put the kernel you want on it, and then spent a couple of days of time getting things working, and more time getting your drivers going, costs add up pretty quickly. If you want a compact system that works right out of the box (and which can use all of our analog sensors in addition to our USB Phidgets), check out our [{{SERVER}}products.php?product_id=1073 Single Board Computer]. Our SBC3:
* Has many more USB ports than super-stripped devices, and also has digital and analog ports
* Includes a power supply and can run on batteries easily
* Has a nice amount of RAM, a decent embedded processor, and built-in onboard storage (we've run R, GRASS, and X11 on it)
* Includes installed Debian, working Phidget drivers, and [[Phidget WebService|networked Phidget drivers]] from the moment it ships
* Has access to the full Debian repository including Python, Mono .NET, Ruby, and gcc
* Has a kernel development kit with patch file and instructions for adding new drivers (bluetooth, wireless, and so on)
* Comes with very in-depth documentation and technical support by phone and email
* Etc, etc.
The [[Phidget WebService|networked support]] in particular allows it to work with your cell phone and more.

But if you really do want a raw hobbyist system to tinker with, go for it! We're all nerds here - we've been there too and we certainly understand!

==Common Problems and Solutions==

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

You can find out the type of your Phidget by attaching it and then running <code><font size=3>dmesg | tail</font></code>, which will display the type of Phidget from your kernel logs, as described above in the [[#Hardware|hardware section]]. The practical consequence of this is if your system has many low speed Phidgets attached, they will each be throttled down. Low speed Phidgets require an interrupt transfer as often as every 8 milliseconds. A Linux system could only have up to 8 of these Phidgets attached.

{{ProblemSolution|Sample Overrun Error|The data read from a program, or the first packet on the WebService, can give a sample overrun error (EEPHIDGET_OVERRUN).}}

Linux only polls data from the analog inputs on Phidgets when you ask it to. So there is some delay between when you open the device and when it actually attaches when data from those inputs are accumulating...and overrunning the buffer. This is simply in the nature of how Linux polls USB - we recommend catching (but ignoring) this one-time initial error.

{{ProblemSolution|Raspberry Pi USB Current|Your device doesn't seem to run as expected on a Raspberry Pi.}}

The USB ports on the standard Raspberry Pi are only capable of supplying around 100mA reliably. Since USB specification dictates 500mA of current maximum, many USB devices require several hundred mA to run smoothly. Since the Pi cannot supply this much current it is common to see buggy performance or complete failure to run at all. The get around this you should use a USB hub connected to the Pi that has it's own external power supply. This will allow the devices connected to have as much power as they require.

OS - OS X

2014-05-06T20:00:59Z

Kat: added a getting started on Mac video

[[Category:OS]]
{{OSLang|[[File:Icon-Mac-OS.png‎|64x64px|link=]]|On OS X, Phidgets can be either plugged directly into a USB Port or run over a network using the [[#WebService|WebService]].}}
__TOC__
Phidgets are designed to run on '''OS X 10.4 Tiger or newer''', and can run on PPC, 32-bit, and 64-bit systems.

==Quick Downloads==

If this is your first Phidget, we highly recommend working through the Getting Started guide for your specific Phidget device, which may be found in its [[:Category:UserGuide|user guide]]. If you already have the Preference Pane Installed and know how to use it, then you've already followed the guide and are ready to learn more about the workings behind the Preference Pane, the Phidget WebService, and more - all specific to OS X.

If you are already a pro, and just want the drivers:

*[{{SERVER}}/downloads/libraries/Phidget.dmg OS X Installer Download]
*[[Software License]]

==Getting Started with OS X==

{{#ev:youtube|o2P580PvjCg}}

===Installing===

The Phidget installer will install the core Phidget files onto your system.

To install the libraries, follow these steps:

1. Download the Phidget installer for your system:
*[{{SERVER}}/downloads/libraries/Phidget.dmg OS X Installer]

2. Open up the installer, and double click on {{Code|Phidgets.mpkg}} to install the libraries.

[[File:OSX Install 1.png|link=|alt=OS X Install]]

3. Proceed through the wizard.

[[File:OSX Install 2.png|link=|alt=OS X Install]]

4. Once the installation is complete, you are ready to program with Phidgets. To find out what files got installed, please see [[#Description of Installer files | Description of Installer files]] in the Appendix section.

Proceed onto to the [[#Phidget Preference Pane | next]] section where the Phidget Preference Pane will be discussed.

====Phidget Preference Pane====

The Phidget Preference Pane is a tool to quickly determine whether your system is able to communicate with Phidgets, and also act as a debugging tool.

Once the Phidget libraries are installed using the installer, open up the {{Code|System Preferences}} window.

[[File:OSX System Preferences.png|link=|alt=OS X System Preferences]]

Click on the {{Code|Phidgets}} icon in the {{Code|Other}} section to bring up the Phidgets Preference Pane.

[[File:OSX PreferencePane General.png|link=|alt=OS X PreferencePane General]]

The Phidget Preference Pane can:
* Access and test Phidgets connected to your computer
* Update device firmware
* Access other Phidgets over the webservice, and make your local Phidgets accessible over the webservice
* Make use of the [[Phidget Dictionary]]
* Manage the labels of connected Phidgets
* View all [[OS_-_Phidget_SBC|SBCs]] on the network and view their webpages

'''For more information, visit the [[Phidget Control Panel#OS X|Phidget Preference Pane]] page.'''

===Checking===

To confirm the libraries were installed and work correctly, you can check both the hardware and software components of the interface. It is worth checking the software side first, because if it works then you know the hardware side is also okay.

====Software====

If you have the Phidgets library installed on your system, you can verify that the software component is working by seeing if the Phidget device is listed in the General tab of the Phidget Preference Pane.

[[File:OSX PreferencePane General.png ‎|link=|alt=OS X Preference Pane General]]

The above screenshot shows that a PhidgetRFID and a PhidgetInterfaceKit are attached to the computer. If you see your Phidget in the list, you can continue to the [[#Programming Languages | programming languages]] section to learn more. If you are not able to see that the Phidget is in the list, there may be a hardware issue. Please see the [[#Hardware| hardware]] section for more details.

====Hardware====

You can verify that your computer detects that the Phidget is plugged in through a USB connection by going to the OS X System Profiler. You can access the System Profiler by selecting {{Code|About This Mac}} under the Apple icon.

[[File:OSX About This Mac.png‎|link=|alt=OS X About This Mac]]

The new window will open up.

[[File:OSX More Info.png|link=|alt=OS X More Info]]

Select {{Code|More Info}}. The System Profiler will show up. In the USB section, you will be able to find all connected USB devices.

[[File:OSX USB Devices.png ‎|link=|alt=OS X Attached USB Devices]]

In the above screenshot, The PhidgetInterfaceKit and PhidgetRFID are connected to the USB ports.

If you don't see the Phidget in the list, then take a look at the [[#Troubleshooting|troubleshooting]] section below, as well as the '''Communications''' section of our [[General Troubleshooting#Communications Troubleshooting|general troubleshooting page]].

====Troubleshooting====

If the example programs '''do not''' work but USB '''does''' work (i.e. your computer can consistently see the device in the [[#Hardware|hardware]]), take a moment to check the basics:
* You are using OS X 10.4 or newer.
* No other programs, drivers, or processes are using that USB port in software
* The Phidget libraries are the latest version (visit the [[#Quick Downloads| quick downloads section]] to download them)

* Check the [[#Common Problems and Solutions|common problems]] section below, some specific combinations can cause problems

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

==Programming Languages==
Phidgets’ philosophy is that you do not have to be an electrical engineer in order to do projects that use devices like sensors, motors, motor controllers, and interface boards. All you need to know is how to program.

After you have installed the drivers above, you should pick a programming language, install libraries, and run the examples for that specific language. You can learn more about what is needed to program in a particular language by choosing the language of your preference below. If you need help choosing a language, please look at the [[Software Overview#Language Support |language comparison table]].

We recommend the following languages for OS X:
* [[Language - Applescript|AppleScript]]
* [[Language - C/C++|C/C++]]
* [[Language - C Sharp|C# (Using Mono)]]
* [[Language - Cocoa | Cocoa]]
* [[Language - Flash AS3 | Flash AS3]]
* [[Language - Flex AS3 | Flex AS3]]
* [[Language - LiveCode | LiveCode]]
* [[Language - Java | Java]]
* [[Language - Max/MSP|Max/MSP]]
* [[Language - Python | Python]]
* [[Language - Ruby|Ruby]]

You can also use these languages, but they do not support [[General Phidget Programming#Event Driven Code | event driven code]], and must use [[General Phidget Programming#Logic Code | logic code]] only:

*[[Language - MATLAB|MATLAB]]
*[[Language - Simulink|Simulink]]

==WebService==

The Phidget WebService allows you to remotely control a Phidget over a network.

Drivers for the Phidget WebService on OS X are already included in the [[#Quick Downloads | Drivers]] above. If you see the Phidget Preference Pane in System Preferences, then you already have the WebService drivers installed.

There are two ways that you can connect to a Phidget hosted on another computer. The first method is by using the IP address/host name and port of the host computer. The second method makes the use of [http://en.wikipedia.org/wiki/Multicast_DNS mDNS], which allows Phidgets to be found and opened on the network by a server id instead of an IP address/host name. When using a server id, both the client and server will need to be running an implementation of zero configuration networking. The Phidget WebService takes advantage of [http://www.apple.com/support/downloads/bonjourforwindows.html Bonjour] software, which is built-in to OS X. It is a tool developed by Apple to locate devices, such as Phidgets, on a network.

This section helps you install, check, and use the WebService on Windows, but we also have an overview of the [[Phidget WebService]] in general.

===Turning the WebService On and Off===

There are two methods that can be used to turn the WebService on and off. The first method is through the Phidget Preference Pane. In the {{Code|WebService}} tab, you can start or stop the WebService. You can also choose to have the WebService start up automatically upon system boot up by selecting the {{Code|Start Automatically}} checkbox.

[[File:OSX PreferencePane Webservice Stopped.png|link=|alt=OS X PreferencePane WebService]]

The second method of turning the WebService on and off is through command line. After using our installer, the WebService utility is automatically installed in {{Code|/usr/bin/phidget21webservice}}.

You can get command line help with {{Code|phidgetwebservice21}} using the -h option:

<div class="source">
<syntaxhighlight lang=bash>
phidgetwebservice21 -h
</syntaxhighlight>

<syntaxhighlight lang=text>
'phidgetwebservice21' is a Phidget and Dictionary server from Phidgets Inc. See www.phidgets.com for more information.
Usage: phidgetwebservice21 [OPTION]
All parameters are optional. The default parameters are: port=5001, ServerName=(Computer Name) and no password

Options:
-p Port
-n Server Name
-P Password
-v Debug mode
-h Display this help
</syntaxhighlight>
</div>

Mapping out which command line options to which Phidget Preference Pane option is as follows:

-p: {{Code|Port}} field

-n: {{Code|ServerID}} field

-P: {{Code|Password}} field

-v: Not supported under the Phidget Preference Pane

To find the defaults used by {{Code|phidget21webservice}}, the command line is the fastest way to learn the default server name and IP address of your computer:
*For the default server name, use {{Code|hostname}} on the command line.
*For your IP address, use {{Code|ifconfig -a}} on the command line.
**A line in the return text, under your main internet connection (usually {{Code|eth0}}) will say something like {{Code|inet addr:192.168.3.178}}, which is your IP.

Here are some usage examples:

To start the WebService with default parameters:
<div class="source">
<syntaxhighlight lang=bash>
phidgetwebservice21
</syntaxhighlight>
</div>

To start the WebService with a server name of {{Code|myServer}}:
<div class="source">
<syntaxhighlight lang=bash>
phidgetwebservice21-n myServer
</syntaxhighlight>
</div>

To stop the WebService, simply close the command line window or press {{Code|Control}} and {{Code|c}} at the same time in the command line window.

===Using the WebService===

To use a Phidget over the WebService, you'll want to:
* Have two different computers connected to the same network. We will call the computer that has the Phidget directly connected to the USB port the host. The client will be the computer that runs a Phidget application to connect to the Phidget attached to the host. Please note that if you only have a single computer, you can also connect to the Phidget over the WebService. The computer will simply act as both a host and client. This will allow you to bypass the [[General Phidget Programming # Details for Open() | one application per Phidget limitation]].

* Start the WebService on the computer that directly connects to the Phidget
* Run your program on the remote computer that will control the Phidget over the network

The easiest way to test these steps on OS X is to set up the WebService and run the Phidget program on the client. Please follow these steps:

1. On the host, open up the Phidget Preference Pane and traverse to the {{Code|Web Service}} tab.

[[File:OSX PreferencePane Webservice Stopped.png |link=|alt=OS X Preference Pane WebService]]

2. Leave all fields the way they are, and click on {{Code|Start WebService}} to run the WebService.

3. You can determine that the WebService is running by looking at the status on the right side.

[[File:OSX PreferencePane Webservice Running.png|link=|alt=OS X PreferencePane WebService Running]]

4. Ensure that the Phidget is plugged in to the host.

5. On the client's Phidget Preference Pane, open up the {{Code|Bonjour}} tab. You will see the Phidget that is plugged into the host as one of the entries listed. Double click it to open the example application.

[[File:OSX PreferencePane Bonjour.png ‎‎ |link=|alt=OS X PreferencePane Bonjour.png ‎]]

6. The example application will open up, and you will be able to communicate with the Phidget over the WebService.

[[File:OSX PreferencePane Example.png ‎ |link=|alt=OS X PreferencePane Example]]

7. You can confirm that the WebService was indeed behind this exchange by terminating the WebService process while still allowing the remote program to run. On the host's Phidget Preference Pane, traverse to the {{Code|WebService}} tab. Hit {{Code|Stop WebService}} to terminate the WebService.

[[File:OSX PreferencePane Webservice Running.png|link=|alt=OS X PreferencePane WebService Running]]

8. Take a look at the example application on the client. Since the application can no longer connect to the WebService, there is nothing attached.

[[File:OSX PreferencePane Example Stopped.png |link=|alt=OS X PreferencePane Example Stopped]]

===Debugging the WebService===

In addition to enabling [[General Phidget Programming#Logging|logging]] in your Phidget code, you can get additional debugging information from the WebService itself. This additional debugging can only be enabled from the command line approach to start the WebService. Debug information is enabled by specifying the {{Code|-v}} option:

<div class="source">
<syntaxhighlight lang=bash>
phidgetwebservice21 -v -n "myServer"
</syntaxhighlight>
</div>

The debugging information will be shown as output in the command line console.

==Advanced Uses==

==Appendix==

===Description of Installer files===

Here is the list of files and their description for each file the installer puts onto your system.
===Description of Library files===

This section will explain the files that were placed onto your system as part of the installation process.
* <b>{{Code|Phidget21.framework}}</b> contains the actual Phidget library, which is used at run-time. It is placed into {{Code|/Library/Frameworks}}.
* <b>{{Code|Phidget.kext}}</b> is the kernel extension. It is placed into {{Code|/System/Library/Extensions}}.
* <b>{{Code|libphidget21.jnilib}}</b> is the JNI library for Java. It is placed into {{Code|/Library/Java/Extensions}}.
* <b>{{Code|Phidgets.prefpane}}</b> is the Phidgets Preference Pane. It is placed into {{Code|/Library/PreferencePanes}}.
* <b>{{Code|phidgetwebservice21}}</b> is the Phidget WebService. It is placed into {{Code|/usr/bin}}.
* <b>{{Code|PhidgetsOSA.app}}</b> is the the Phidgets agent for AppleScript. It is placed into {{Code|/Library/ScriptingAdditions}}.

==Common Problems and Solutions==

None, yet.

OS - Windows

2014-05-06T19:59:40Z

Kat: added video for getting started on windows.

[[Category:OS]]
{{OSLang|[[File:Icon-Windows.png|64x64px|link=OS - Windows]]|Windows, Phidgets can be either plugged directly into a USB Port or run over a network using the [[#WebService | WebService]].
}}
__TOC__

Phidgets are designed to run on '''Windows XP SP3 or newer''', on both 32 and 64-bit systems.

==Quick Downloads==

If this is your first Phidget, we highly recommend working through the ''Getting Started'' guide for your specific Phidget device, which may be found in its [[:Category:UserGuide|user guide]]. If you already have the [[File:Ph.jpg]] icon in your task bar and know how to use it, then you've already followed the guide and are ready to learn more about the control panel, the Phidget WebService, and more - all specific to Windows.

If you are already a pro, and just want the drivers:

*[{{SERVER}}/downloads/libraries/Phidget-x86.exe 32 Bit Installer Download]
*[{{SERVER}}/downloads/libraries/Phidget-x64.exe 64 Bit Installer Download]

For special cases where you want to install the Phidget libraries without the installer, please see the [[#Advanced Uses | Advanced Uses]] section.
*[{{SERVER}}/downloads/libraries/Phidget21-windevel.zip Phidget21 Libraries] (32-Bit and 64-Bit development files without an installer)
*[[Software License]]

==Getting Started with Windows==

{{#ev:youtube|DnMjarrgPrA}}

===Installing===

The Phidget installer requires that your system has .NET framework 2.0 or higher. The .NET framework can be downloaded from [http://www.microsoft.com/net Microsoft]. If you do not have the .NET framework 2.0 or later installed, you can still use Phidgets. However, you won't be able to use the installer, and will have to manually install the Phidget libraries. Please see the [[#Advanced Uses | Advanced Uses]] section.

To install the libraries, follow these steps:

1. Download one of the Phidget installer for your system, depending on whether your system is 32 or 64-bit.
*[{{SERVER}}/downloads/libraries/Phidget-x86.exe 32-bit]
*[{{SERVER}}/downloads/libraries/Phidget-x64.exe 64-bit]

2. Open up the installer, and proceed through the wizard.

[[image:Windows_Install.png|link=]]

Please note that by default, the installer places the [[#Description of Installer files | Phidget libraries]] in {{Code|C:\Program Files\Phidgets}}.

3. Once the installation is complete, you are ready to program with Phidgets. To find out what files got installed, please see [[#Description of Installer files | Description of Installer files]] in the Appendix section.

Next, the Phidget Control Panel will be discussed.

====Phidget Control Panel====

The Phidget Control Panel is a tool to quickly determine whether your system is able to communicate with Phidgets, and also act as a debugging tool.

Once the Phidget libraries are installed using the installer, you should see the [[File:Ph.jpg]] icon in the taskbar. Double click on it to bring up the Phidget Control Panel. If the icon does not appear, just find and open the Phidget Control Panel from the start menu.

[[File:Windows ControlPanel General.PNG|link=|alt=Windows Control Panel General]]

The Phidget Control Panel can:
* Access and test Phidgets connected to your computer
* Update device firmware
* Access other Phidgets over the webservice, and make your local Phidgets accessible over the webservice
* Make use of the [[Phidget Dictionary]]
* View all [[OS_-_Phidget_SBC|SBCs]] on the network and view their webpages

'''For more information, visit the [[Phidget Control Panel]] page.'''

===Checking===

To confirm the libraries were installed and work correctly, you can check both the hardware and software components of the interface. It is worth checking the software side first, because if it works then you know the hardware side is also okay.

====Software====

If you have the Phidgets library installed on your system, you can verify that the software side component is working by seeing if a Phidget device is listed in the {{Code|General}} tab of the Phidget Control Panel.

[[File:Windows_ControlPanel_General.PNG|link=|alt=Windows Control Panel General]]

The above screenshot shows that a PhidgetRFID and a PhidgetInterfaceKit are attached to the computer. If you see your Phidget in the list, you can continue to the [[#Programming Languages | programming languages]] section to learn more. If you are not able to see that the Phidget is in the list, there may be a hardware issue. Please see the [[#Hardware| hardware]] section for more details.

====Hardware====

You can verify that your computer detects that the Phidget is plugged in through a USB connection by going to the Windows Device Manager.
On Windows XP, you can access the Device Manager by accessing the start menu, right clicking on {{Code|Computer}} and selecting {{Code|Properties}}. Next, select {{Code|Advanced System Settings}} to open up a new Window. Here, open up the {{Code|Hardware}} tab and select {{Code|Device Manager}}. The Device Manager window will open.

[[File:Windows7_DeviceManager.PNG|link=|alt=Windows Device Manager]]

Under the {{Code|Human Interface Devices}} heading, you can view whether your computer detects that the Phidget is connected through the USB if it is in the list. There should be a {{Code|HID-compliant device}} and a {{Code|USB Input Device}} entry for every Phidget that is attached to the computer. Please note that there is currently no way of directly determining which entry belongs to which Phidget. A simple way of verifying which entry belongs to which Phidget is to simply connect or disconnect the Phidget from the USB port of the computer. The list will automatically refresh to show the updated list of all connected USB devices.

If you don't see the Phidget in the list, then take a look at the [[#Troubleshooting|troubleshooting]] section below, as well as the '''Communications''' section of our [[General Troubleshooting#Communications Troubleshooting|general troubleshooting page]].

====Troubleshooting====

If the examples '''do not''' work but USB '''does''' work (i.e. your computer can consistently see the device in the [[#Hardware|hardware]]), take a moment to check the basics:
* You are using Windows 2000 or newer.
* The Phidget Control Panel requires that you have .NET framework 2.0 or newer.
* No other programs, drivers, or processes are using that USB port in software. Some drivers or software will sometimes mistakenly claim Phidget devices when waiting on some hardware to be connected. Please see the section: [[#Issue: Some third party software prevents communications with Phidgets|third party software prevents communications with Phidgets]] for more information.
* The Phidget libraries are the latest version (visit the [[#Quick Downloads| getting started section]] to download them)
* Check the [[#Common Problems and Solutions|common problems]] section below, some specific combinations can cause problems

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

==Programming Languages==

Phidgets’ philosophy is that you do not have to be an electrical engineer in order to do projects that use devices like sensors, motors, motor controllers, and interface boards. All you need to know is how to program.

After you have installed the drivers above, you should pick a programming language, install libraries, and run the examples for that specific language. You can learn more about what is needed to program in a particular language by choosing the language of your preference below. If you need help choosing a language, please look at the [[Software Overview#Language Support |language comparison table]].

On Windows, we recommend the following languages:

*[[Language - C Sharp|C#]]
*[[Language - C/C++|C/C++]]
*[[Language - Flash AS3|Flash AS3]]
*[[Language - Java|Java]]
*[[Language - LabVIEW|LabView]]
*[[Language - Max/MSP|Max/MSP]]
*[[Language - Python|Python]]
*[[Language - Visual Basic .NET|Visual Basic .NET]]
*[[Language - Visual Basic 6.0|Visual Basic 6.0]]

You can also use these languages, but they do not support [[General Phidget Programming#Event Driven Code | event driven code]], and must use [[General Phidget Programming#Logic Code | logic code]] only:

*[[Language - MATLAB|MATLAB]]
*[[Language - Simulink|Simulink]]

The following languages are also supported, but due to a lack of demand, the full API is not implemented. Please refer to the specific language for more information on what features are unsupported.
*[[Language - Adobe Director|Adobe Director]]
*[[Language - AutoIt|AutoIt]]
*[[Language - Delphi|Delphi]]
*[[Language - LiveCode|LiveCode]]
*[[Language - Visual Basic for Applications|Visual Basic for Applications]]
*[[Language - Visual Basic Script|Visual Basic Script]]

==WebService==

The Phidget WebService allows you to remotely control a Phidget over a network. For more information, please see the [[Phidget WebService|Phidget WebService]] page.

Drivers for the Phidget WebService on Windows are already included in the [[#Quick Downloads | Drivers]] above. If you have a [[File:Ph.jpg]] icon in your taskbar, you already have the WebService drivers installed.

There are two ways that you can connect to a Phidget hosted on another computer. The first method is by using the IP address/host name and port of the host computer. The second method makes the use of [http://en.wikipedia.org/wiki/Multicast_DNS mDNS], which allows Phidgets to be found and opened on the network by a server id instead of an IP address/host name. When using a server id, both the client and server will need to be running an implementation of zero configuration networking. The Phidget WebService takes advantage of the [http://www.apple.com/support/downloads/bonjourforwindows.html Bonjour] software. It is a tool, developed by Apple to locate devices such as Phidgets, and printers. You will have to install Bonjour onto your system to use the second method.

This section helps you install, check, and use the WebService on Windows, but we also have an overview of the [[Phidget WebService]] in general.

===Turning the WebService On and Off===

There are two methods that can be used to turn the WebService on and off. The first method is through the Phidget Control Panel. In the {{Code|WebService}} tab, you can start, restart or stop the WebService. You can also choose to have the WebService start up automatically upon Windows boot up by selecting {{Code|Automatic}} as the {{Code|Startup Type}}. By leaving the {{Code|Startup Type}} as {{Code|Manual}}, you will have to manually turn the WebService on everytime you wish to use it.

[[File:Windows_ControlPanel_WebService_Setup_Stopped.PNG|link=|alt=Windows Control Panel WebService Setup]]

The second method of turning the WebService on and off is through command line. If you used our installer, the WebService utility is automatically installed in {{Code|C:\Program Files\Phidgets\PhidgetWebservice21.exe}}. Otherwise, if you wish to manually install the {{Code|PhidgetWebservice21.exe}}, you can place it anywhere on your system, and navigate to it in command line.

You can get command line help with {{Code|PhidgetWebservice21.exe}} using the {{Code|-h}} option:

<div class="source">
<syntaxhighlight lang=bash>
PhidgetWebservice21 -h
</syntaxhighlight>

<syntaxhighlight lang=text>
'phidgetwebservice21' is a Phidget and Dictionary server from Phidgets Inc. See www.phidgets.com for more information.
Usage: phidgetwebservice21 [OPTION]
All parameters are optional. The default parameters are: port=5001, ServerName=(Computer Name) and no password

Options:
-p Port
-n Server Name
-P Password
-v Debug mode
-h Display this help
</syntaxhighlight>
</div>

Mapping out which command line options to which Phidget Control Panel option is as follows:

-p: {{Code|Port}} field

-n: {{Code|ServerID}} field

-P: {{Code|Password}} field

-v: {{Code|Enable verbose output}} checkbox

To find the host name and IP address of your computer, open up the command line prompt.
*For the default server name, type {{Code|hostname}}.
*For your IP address, type {{Code|ipconfig -all}}.
**A line in the return text, will say something like {{Code|192.168.2.198}}, which is your IP.

Here are some usage examples. The Windows command line is used. Traverse to the Phidget installation directory(by default, it is located in {{Code|C:\Program Files\Phidgets}}).

To start the WebService with default parameters:
<div class="source">
<syntaxhighlight lang=bash>
PhidgetWebservice21.exe
</syntaxhighlight>
</div>

To start the WebService with a server name of {{Code|myServer}}:
<div class="source">
<syntaxhighlight lang=bash>
PhidgetWebservice21.exe -n myServer
</syntaxhighlight>
</div>

To stop the WebService, simply close the command line window or press {{Code|Ctrl}} and {{Code|c}} at the same time in the command line window.

===Using the WebService===

To use a Phidget over the WebService, you'll want to:
* Have two different computers connected to the same network. We will call the computer that has the Phidget directly connected to the USB port the host. The client will be the computer that runs a Phidget application to connect to the Phidget attached to the host. Please note that if you only have a single computer, you can also connect to the Phidget over the WebService. The computer will simply act as both a host and client. This will allow you to bypass the [[General Phidget Programming # Details for Open() | one application per Phidget limitation]].

* Start the WebService on the computer that directly connects to the Phidget
* Run your program on the remote computer that will control the Phidget over the network

The easiest way to test these steps on Windows is [http://www.apple.com/support/downloads/bonjourforwindows.html download] and install Bonjour onto both the host and client. Next, we will set up the WebService and run the Phidget program on the client. Please follow these steps:

1. On the host, open up the Phidget Control Panel and traverse to the {{Code|Setup}} tab of the {{Code|WebService}} section.

[[File:Windows_ControlPanel_WebService_Setup_Stopped.PNG|link=|alt=Windows Control Panel WebService Setup Stopped]]

2. Leave all fields the way they are, and click on {{Code|Start}} to run the WebService.

3. You can determine that the WebService is running by looking at the WebService status at the bottom of the window.

[[File:Windows_ControlPanel_WebService_Setup_Running.PNG|link=|alt=Windows Control Panel WebService Setup Running]]

4. Ensure that the Phidget is plugged in to the host.

5. On the client's Phidget Control Panel, open up the {{Code|Bonjour}} tab in the {{Code|WebService}} section. You will see the Phidget that is plugged into the host as one of the entries listed. Double click it to open the example application.

[[File:Windows_ControlPanel_WebService_Bonjour_Running.PNG|link=|alt=Windows Control Panel WebService Bonjour]]

6. The example application will open up, and you will be able to communicate with the Phidget over the WebService.

[[File:Windows_ControlPanel Example.PNG|link=|alt=Windows Control Panel Example]]

7. You can confirm that the WebService was indeed behind this exchange by terminating the WebService process while still allowing the remote program to run. On the host's Phidget Control Panel, traverse to the {{Code|Setup}} tab of the {{Code|WebService}} section. Hit {{Code|Stop}} to terminate the WebService.

[[File:Windows_ControlPanel_WebService_Setup_Running.PNG|link=|alt=Windows Control Panel WebService Setup Running]]

8. Take a look at the example application on the client. Since the application can no longer connect to the WebService, the attached state of the Phidget is false.

[[File:Windows_ControlPanel_WebService_Example_Disconnected.PNG|link=|alt=Windows Control Panel WebService Example while WebService Stopped]]

===Debugging the WebService===

In addition to enabling [[General Phidget Programming#Logging|logging]] in your Phidget code, you can get additional debugging information from the WebService itself. This additional debugging can be enabled from the {{Code|Enable verbose output}} checkbox in the Phidget Control Panel.

[[File:Windows_ControlPanel_WebService_Setup_Running.PNG|link=|alt=Windows Control Panel WebService Setup]]

The debugging information is shown in the {{Code|Output}} tab.

[[File:Windows_ControlPanel_WebService_Output_Running.PNG|link=|alt=Windows Control Panel WebService Output Running]]

If you are using the command line approach to start the WebService, debug information is enabled by specifying the {{Code|-v}} option:

<div class="source">
<syntaxhighlight lang=bash>
PhidgetWebservice21.exe -v -n "myServer"
</syntaxhighlight>
</div>

The debugging information is shown command line output. This will prove useful when debugging WebService problems.

==Advanced Uses==

===Manual File Installation===

The Phidget installer installs the most commonly used files onto your system. However, there may be special cases where you want to install the Phidget libraries without the installers. This section will describe the purpose of the most important files file and cover how to manually install and distribute the libraries with your code. You can get the files [{{SERVER}}/downloads/libraries/Phidget21-windevel.zip here].

====Description of Library files====

Here is the list of files and their description for each file the installer puts onto your system. You don't need to know this if you're just using our installer, but if you are looking to distribute our libraries with your code (without your clients having to use our installer) this list will help you pick and choose what you need:

* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. It is also placed in {{Code|C:\Windows\System32}}.
* <b>{{Code|PhidgetWebService21.exe}}</b> is used to control Phidgets remotely across a network using the [[#WebService | PhidgetWebservce]].
* <b>{{Code|PhidgetWindowsService21.exe}}</b> is a Windows service that controls {{Code|PhidgetWebService21.exe}}.
* <b>{{Code|phidget21.lib}}</b> is used by your compiler to link to the dll. Your compiler has to know where this file is, by default our installer puts {{Code|phidget21.lib}} into {{Code|C:\Program Files\Phidgets}}, so you can either point your compiler to that location, or copy and link to it in a directory for your project workspace. {{Code|phidget21.lib}} is written to be compatible with most compilers - but your specific compiler may need a different format. Check our documentation for your specific compiler for details. Please note that we provide versions of the {{Code|phidget21.lib}} that are specifically optimized for 32-bit or 64-bit systems. If you are using a 64 bit versions of Windows, the {{Code|phidget21.lib}} is placed in {{Code|C:\Program Files\Phidgets}}; The 32 bit version of {{Code|phidget21.lib}} is placed in {{Code|C:\Program Files\Phidgets\x86}}.
* <b>{{Code|phidget21.h}}</b> lists all the Phidget API function calls available to your code. Your compiler also has to know where this file is. By default, our installer puts {{Code|phidget21.h}} into {{Code|C:\Program Files\Phidgets}} so you can either point your compiler to that location, or copy and link to it in a directory for your project workspace.
* <b>{{Code|phidget21.jar}}</b> is an archive containing the Phidgets library, used by the [[Language - Java | Java]] programming language.
* <b>{{Code|Phidget21.NET.dll}}</b> is the Phidgets library for .NET framework 2.0 or greater. Any .NET language can be used, including [[Language - C Sharp | C#]] , and [[Language - Visual Basic .NET | Visual Basic .NET]].
* <b>{{Code|Phidget21.NET1.1.dll}}</b> is the Phidgets library for .NET framework 1.1. Any .NET language can be used, including [[Language - C Sharp | C#]] , and [[Language - Visual Basic .NET | Visual Basic .NET]]. This version of the dll should ''only'' be used for .NET 1.1 applications, not .NET 2.0 applications.
* <b>{{Code|Phidget21.NET.XML}}</b> provides the IntelliSense in-line documentation for the .NET library in Visual Studio.
* <b>{{Code|Phidget21COM.dll}}</b> is the Component Object Model(COM) library and provides your project access to the Phidget ActiveX objects. This libraries is used by the [[Language - Adobe Director|AdobeDirector]], [[Language - AutoIt|AutoIT]], [[Language - Delphi|Delphi]], [[Language - Visual Basic 6.0|Visual Basic 6.0]], [[Language - Visual Basic for Applications|Visual Basic for Applications]], [[Language - Visual Basic Script|Visual Basic Script]].
* <b>{{Code|Phidget21Manager.exe}}</b> is a tool to quickly determine whether your system is able to control Phidgets, and also act as a debugging tool.
* <b>{{Code|Examples}} folder</b> contain example applications that allows you to quickly see if your Phidget is properly configured.
* <b>{{Code|x86 folder}} folder</b> contain the 32 bit versions of {{Code|phidget21.dll}}, {{Code|phidget21.lib}}, {{Code|Phidget21COM.dll}}. These folder will only appear on 64 bit installations and is useful if you want to code against the 32 bit libraries.

=====Special Cases of Library Install=====

Regardless of what language you will be using to program Phidgets, you will need the {{Code|phidget21.dll}} placed in the {{Code|C:\WINDOWS\system32}} directory. Additional files are needed for the language that you choose. Please refer to the documentation provided by your [[Software Overview#Language Support|language]] to determine what files are needed and the steps needed to install them onto your system.

You can find the {{Code|phidget21.dll}} in the link below:

*[{{SERVER}}/downloads/libraries/Phidget21-windevel.zip Phidget21 Libraries] (32-Bit and 64-Bit development files without an installer)

{{Code|PhidgetWebService21.exe}} is also provided in the link above.

===Windows in a Virtual Machine===

Phidgets can also be used inside a virtual machine. Instructions for VMWare and VirtualBox are provided below. Virtual PC is not supported as USB Phidgets requires a virtual platform that supports HID USB Devices and since Virtual PC does not support HID USB devices, Phidgets may not be used.

As always, please ensure that you have the latest Phidget [[#Quick Downloads | drivers]] installed on the virtual machine and that you are using the latest version of your virtual software.

<b>VMWare:</b>

To enable USB Phidgets, select Virtual Machine -> Removable Devices -> and select the Phidget Input Device -> Connect.

<b>VirtualBox</b>

To enable USB Phidgets, VirtualBox Guest Additions(Devices -> Install Guest Additions) may need to be installed. Afterwards, click on Devices -> USB Devices and select the Phidget device to enable. The state should go from Busy to Captured. VirtualBox may bring up a new hardware wizard in the host operating system, which has to be installed. Please note that Phidgets with USB hubs (for example, the [{{SERVER}}/products.php?product_id=1019 1019 Interface Kit with 6-port hub]), are undetectable; Fortunately, Phidgets that are attached to such Phidgets are detectable.

Note that Windows XP "mode" in Windows 7 does '''not''' support Phidgets.

===Installing Without an Internet Connection===
When running the Phidgets installer it will check for other applications such as .NET. Part of this requires an active internet connection. The downside to this is that even if you have the applications installed already, if you do not have an internet connection you cannot complete the installation process. There is a way around this however which involves extracting the Phidget21.msi out of the .exe installer. To do this follow these steps:

*Run the installer.
[[image:Msi-1.png|400px|link=]]
*Once the installer has started up and you are at the first informational window, navigate to your {{Code|Local Disk\Users\"username"\AppData\Local\Temp}} folder.
*Look for the most recently modified folders. The Phidgets one will not have an obvious title, most likely a seemingly random string of numbers and characters.
[[image:Msi-2.png|500px|link=]]
*In this folder you will find the Phidget21.msi. This can be used to install the Phidgets libraries without needing an internet connection.

==Common Problems and Solutions==

===Issue: Projects are not working after a Phidget21 reinstall===
Affected Operating Systems: '''Windows'''

Solution: You need to reset your references and library paths. When you reinstall the Phidgets drivers all of the old paths can get broken. Make sure that you are including the right header files and that you have referenced the right libraries and that should fix the problem.

===Issue: Some third party software prevents communications with Phidgets===
Affected Operating Systems: '''Windows'''

Some drivers or software will sometimes mistakenly claim Phidget devices when waiting on some hardware to be connected.
This is caused by the drivers taking every HID (human interface device) on the USB bus, effectively stealing them from the Phidgets drivers.
When this happens, the device shows up in the Phidget Control Panel at start up but examples and programs are unable to make a connection to the Phidget.
This is known to occur with Logitech QuickCam, Force Feedback Mouse, Nike, Velleman K8055, and some SteelSeries drivers.

Solution: If you suspect this is a problem then try putting your machine in safe mode. If this fixes the problem you can be sure that this is the problem. Try shutting/uninstalling the offending driver/software down or kill its process in the task manager when using Phidgets.

===Issue: A corrupt installation fails on uninstall or repair===
Affected Operating Systems: '''Windows'''

Solution: If the normal uninstall fails, or for whatever reason, you can choose to remove the Phidget drivers manually.
Please perform the following:
# Shut down any programs using the Phidget libraries, including the WebService and the Phidget Control Panel.
# Delete {{Code|C:\Program Files\Phidgets\}}
# Remove the Phidgets key from the Registry {{Code|[-HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services PhidgetWebService21]}}.

In most cases this is enough to get the installer working again. If you need to remove all traces of the Phidgets libraries manually, perform the following additional steps:

# Unregister the COM library: {{Code|regsvr32 /u "C:\Program Files\Phidgets\Phidget21COM.dll"}}.
# Remove {{Code|Phidget21.NET}} and {{Code|Policy.2.1.Phidget21.NET}} from {{Code|C:\Windows\Assembly\}}.
# Delete {{Code|C:\Documents and Settings\All Users\Application Data\Phidgets}} if you are using WindowsXP or {{Code|C:\Users\All Users\Phidgets}} if you are using Windows Vista.
# Delete {{Code|C:\Windows\system32\phidget21.dll}}.
# Delete Phidgets from the start menu.
# Search for and remove keys mentioning Phidgets from the registry in the following locations:
#* {{Code|[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall\]}}
#* {{Code|[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Installer\Products\]}}
#* {{Code|[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\.NETFramework\AssemblyFolders\Phidgets Inc]}}
#* {{Code|[HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Run\Phidget21Manager]}}
#* {{Code|[HKEY_LOCAL_MACHINE\SOFTWARE\Classes\Installer\Assemblies\Global\]}}
# Reboot

'''NOTE:''' You can go through the registry and purge any other keys mentioning Phidgets if you still have problems, but at this point you should be able to reinstall under most cases. There will also be keys relating to the installer, the .NET library and the COM library, but they should not interfere with anything.

===Issue: Event data is sporadic/slow/clumped over the WebService===
Affected Operating Systems: '''Windows'''

Windows implements 200ms delayed ACKs for network traffic. When traffic is one-way only - as it is with event data, the data will all arrive in clumps every 200ms because of delayed ACKs.

This can be a great drawback for applications which rely on low latency event data over the network. (source: http://support.microsoft.com/kb/214397)

This delayed ACK behavior can be disabled in windows to decrease event latency as documented here: http://support.microsoft.com/kb/328890

In the future, the Phidgets library may implement this differently, but so far we have been unable to match the performance achieved by disabling delayed ACK.

===Issue: Windows XP "mode" in Windows 7 does not work with Phidgets===
Affected Operating Systems: '''Windows''' (running XP in included XP mode)

Although XP supports some USB devices, its overall device support is spotty. If you need to run XP within a virtual machine, Phidgets work under both VMWare and VirtualBox - the two main virtual machine programs. However, this means you will need to own a copy of Windows XP to install into the virtual machine.

File:GettingStartedSBCExamples.zip

2014-04-25T13:58:19Z

Kat: These examples go with the Getting Started on SBC video tutorial.

These examples go with the Getting Started on SBC video tutorial.

OS - Phidget SBC

2014-04-10T18:07:12Z

Kat: added advice for updating the version of Java on SBC

[[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__

==Quick Downloads==

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 [[1073 User Guide#Getting Started|SBC2 Getting Started Guide]] right out of the box.

*[{{SERVER}}/downloads/libraries/phidgetsbc2.bin SBC2 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package] (How-to and patch file)
*[[Software License]]
*[{{SERVER}}/downloads/libraries/phidgetsbc3_1.0.0.20121213.bin SBC3 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-kerneldev_1.0.0.20121213.tar.gz SBC3 Kernel Development Package]

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==

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 [[1073 User Guide#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 [[1073 User Guide#Getting Started | Getting Started Guide]].

This page will show you how to:
* Install the ability to write and develop code on the SBC itself
* 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:
* 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===

You have two ways to connect to the SBC from an external computer: via the [[#SBC Web Interface|SBC Web Interface]] and over the more powerful but complex [[#SSH | Secure Shell (SSH)]].

====SBC Web Interface====

You have already worked extensively with the web interface in the [[1073 User Guide#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====

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.

Before connecting over ssh, you will need:
* The '''IP address''' (such as 168.254.3.0) or '''link local address''' (such as phidgetsbc.local) of the SBC
* The '''admin password''' for the SBC
Both of these items can be found by following the steps in the [[1073 User Guide#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 → Settings}}, by changing the ''SSH Server'' radio button to ''Enabled'' and saving your changes:

[[File:sbc_turn_on_ssh.png|link=|alt=]]

=====SSH on Windows=====

The ssh program is not installed on Windows by default. But, there are a variety of SSH programs available for free. One simple and commonly used program 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 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.

=====SSH on Linux and Mac OS=====

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 → Utilities → Terminal}} on Mac OS
...and type:

<div class="source">
<syntaxhighlight lang=bash>
ssh root@phidgetsbc.local
</syntaxhighlight>
</div>

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>
scp root@phidgetsbc.local:/root/data.txt .
</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.

===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.

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 → 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 → Packages}} to install C support (including {{Code|gcc}}) and another button to install Java support:

[[File:sbc_packages_web.png|link=|alt=]]

You have to check that you are running the same version of Java on your development machine (where you plan on compiling the java programs) as the SBC is running. To do this type the following into the terminal on your computer and from ssh on the SBC:

<div class="source">
<syntaxhighlight lang=bash>
Java -version
</syntaxhighlight>
</div>

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

<div class="source">
<syntaxhighlight lang=bash>
apt-get install openjdk-7-jre-headless
su
update-alternatives --config java
</syntaxhighlight>
</div>

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>
apt-get install python
</syntaxhighlight>
</div>

This will give you Python, and now you just have to install the Phidget Python module to gain Phidget functionality.

=====Install Phidget Python Method 1: Use a USB Key=====

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.

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:

<div class="source">
<syntaxhighlight lang=bash>
python setup.py install
</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]].

=====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>
apt-get install wget
apt-get install unzip
</syntaxhighlight>
</div>

Copy the web link address for the [{{SERVER}}/downloads/libraries/PhidgetsPython.zip Python Libraries].

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.

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:

<div class="source">
<syntaxhighlight lang=bash>
python setup.py install
</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]].

====Installing Other Languages====

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>
apt-get install mono-runtime
</syntaxhighlight>
</div>

Then, to install the C# compiler:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install mono-gmcs
</syntaxhighlight>
</div>

Or the Visual Basic compiler:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install mono-vbnc
</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:

:{{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>
apt-get install libmono-corlib1.0-cil
apt-get install libmono-system1.0-cil
</syntaxhighlight>
</div>

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>
apt-get update
apt-get dist-upgrade
</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:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install monodoc-http mono-complete
</syntaxhighlight>
</div>

Choose monodoc-http explicitly, because otherwise the install fails on monodoc-browser.

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:

<div class="source">
<syntaxhighlight lang=bash>
gmcs Code.cs -r:Phidget21.NET.dll
mono Code.exe
</syntaxhighlight>
</div>

==Using SBC Linux==

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

First, 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.

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.

===Some Useful Commands===

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.

====ls====

The '''ls''' program lists the contents of a directory.

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>
</div>

This may be a lot of information you don't need. If you are only interested in a USB key attachment (as described in the [[#Using USB Data Keys|Using USB Data Keys]] section), you can use grep to filter that one response:

<div class="source">
<syntaxhighlight lang=text>
root@phidgetsbc:~# mount | grep sda1
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</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 → 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.

====which====

The program {{Code|which}} tells you if and where a program is installed.

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===

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.

====gcc====

The '''gcc''' program is the C compiler for Linux.

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.

====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.

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.

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:
:<code>less Program.c | grep var</code>

====wget====

The '''wget''' program allows you to get an online file (over http) and download it to the SBC.

For example, to get the source file (HTML) from the Phidgets home page, you can type:

<div class="source">
<syntaxhighlight lang=bash>
wget http://www.phidgets.com
</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]].

===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 the same version of [[#Installing C/C++ and Java|Java installed on the SBC]] as you have on your external development machine. Instruction for checking and updating are found on the [[#Installing C/C++ and Java|installation page]].

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 → 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>
javac -classpath .:phidget21.jar HelloWorld.java
</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.

Now we move onto the SBC:

6. Create a new project on the SBC, in the web interface under {{Code|Projects → 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>
javac -classpath .:/usr/share/java/phidget21.jar HelloWorld.java
</syntaxhighlight>
</div>

5. To run the {{Code|HelloWorld}} program, use:

<div class="source">
<syntaxhighlight lang=bash>
java -classpath .:/usr/share/java/phidget21.jar HelloWorld
</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]].

'''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]].

====Developing Code on the SBC====

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.

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===

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 again. The main difference is:
* 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
* 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.

====Via the Web Interface====

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]].

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]].

Select the {{Code|Enabled}} radio button. The other defaults should be fine, unless you specifically know otherwise:
* 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.
* ''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.
* 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.

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====

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.

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>
export EDITOR=nano
</syntaxhighlight>
</div>

Then, to edit your crontab file, simply type:

<div class="source">
<syntaxhighlight lang=bash>
crontab -e
</syntaxhighlight>
</div>

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>
minute hour dayOfMonth month dayOfWeek command
</syntaxhighlight>
</div>

Where:
*{{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.

=====My Cron Job Doesn't Work!=====

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:
* {{Code|code/project.c}} is a relative path (bad for cron)
* {{Code|/root/code/project.c}} is an absolute path (good for cron)
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.

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:
* The settings loaded by {{Code|/etc/profile}}
* 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.

====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.

===Using USB Data Keys===

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

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

[[File:sbc_mounted_devices.png|link=|alt=]]

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

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

<div class="source">
<syntaxhighlight lang=bash>
root@phidgetsbc:~# mount | grep usb
/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.

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

===Saving and Retrieving Data===

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]].

====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.

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

<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/}}.

'''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.

====Over the Network (SCP)====

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.

====Backing Up Your Data====

For the web interface, you can save and restore all web interface settings under the {{Code|System → Backup & Restore}} tab.

To save the settings of what packages are installed for later re-installation, you can type:

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

<div class="source">
<syntaxhighlight lang=bash>
dpkg –set-selections < installedPrograms.txt
apt-get dselect-upgrade
</syntaxhighlight>
</div>

Also remember to externally save:
* 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.

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==

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.

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.

If your problem doesn't seem to be fixed by these steps, or the information within this guide, please [[Contact Us|ask us]]!

===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 User Guide#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 → 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 → Backup & Restore → 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 → Backup & Restore → 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==

===Shutting off USB ports to save power===
The SBC3 has an on-board USB hub that can control power to the ports. To do this unbind and rebind the USB drivers.

To turn off the ports {{code|echo "1-1" >/sys/bus/usb/drivers/usb/unbind}}

To turn on the ports {{code|echo "1-1" >/sys/bus/usb/drivers/usb/bind}}

These will also cause detach and attach events for the Phidget devices, respectively. While the drivers are unbound, you will not get any hot plug events for any devices on USB.

===Using a Touchscreen===
Please note that this will ONLY work with an SBC3 since it has a USB 2.0 hub:

Using a touchscreen with the SBC is a great way to get user input and visual feedback from an SBC otherwise devoid of visual output. The SBC does not have any conventional display ports such as VGA, DVI, or HDMI but it does have a number of USB ports and USB displays do exist. With the upgrade to a USB 2.0 hub on the SBC3 from the earlier models which had USB 1 hubs the SBC now has enough capability to operate a screen over USB. We don't recommend running a standard desktop environment since the processor is too slow to really keep up with a typical desktop it does make for an excellent interface for a kiosk, instrumentation control panel or other, similar use case. This document is going to go through the process of enabling support for a typical USB display as well as installing a fairly compact desktop environment called xfce on the SBC.

The screen I will be using is from a company called [http://lilliputweb.net/ Lilliput]. Specifically a UM-70 model. Before you begin, please make sure that you have the screen plugged into the SBC, it will also be useful to have a spare USB keyboard and mouse handy as you will need them once you are no longer using an SSH terminal to communicate with the SBC.

[[File:lilliputoff.jpg|center|400px|link=]]

====Getting the display to function====
Begin by logging into the web configuration page for your SBC and upgrading all of the packages on the SBC. Be sure to include the full Debian package repository. For more information on how to do this refer to the [[OS - Phidget SBC#Getting Started - External Computer|getting started]] section of the Phidget SBC documentation. Once you are fully up to date open an SSH session with the SBC and navigate to the "/etc" folder. Open inittab with a terminal-based text editor such as nano and add the following to the bottom of the file, just above the {{code|T0:23:respawn:/sbin/getty -L ttyAMA0 115200 vt100}} line:

<div class="source">
<syntaxhighlight lang=bash>
1:2345:respawn:/sbin/getty 38400 tty1
2:23:respawn:/sbin/getty 38400 tty2
3:23:respawn:/sbin/getty 38400 tty3
4:23:respawn:/sbin/getty 38400 tty4
5:23:respawn:/sbin/getty 38400 tty5
6:23:respawn:/sbin/getty 38400 tty6
</syntaxhighlight>
</div>

Now reboot your system. After a few minutes you should see the LCD screen come up with a standard Linux terminal interface and a login prompt. This is all well and good but this isn't really appreciably better than simply using an SSH session to communicate with the SBC.

[[File:lilliputlogin.jpg|center|400px|link=]]

====Setting up Xfce====
In order to get a traditional windowing environment we still need to install a desktop manager as well as a number of supporting packages. Log in and make sure everything is still up to date with:

<div class="source">
<syntaxhighlight lang=bash>
apt-get update
</syntaxhighlight>
</div>

Then install the following packages:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install xserver-xorg lxde xfce4
</syntaxhighlight>
</div>

If the SBC asks you if you want to continue, just type "Y" and press enter.

This will install the xfce desktop environment and any other necessary programs on the SBC. When it's done, restart the SBC. When it boots back up it should boot directly to a login screen instead of the terminal interface. Log in, and you are good to go. It won't be particularly fast, but don't worry, the SBC does not have a dedicated video processor on it so it's perfectly normal for it to be slow. What's important is that it works.

[[File:lilliputdesktop.jpg|center|400px|link=]]

====Calibrating the touch screen====
Unfortunately, by default the screen is calibrated to believe the bottom of the screen is on the right hand side. This has the effect of making the touch functionality more or less useless until it has been properly calibrated. To do this, install the following package:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install xinput-calibrator
</syntaxhighlight>
</div>

Now use xinput calibrator to measure the parameters of your screen. Launch xinput calibrator (called Calibrate Touchscreen in the programs menu) and follow the instructions on the screen. The screen should now be functioning at full potential.

===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]]. You can also have a look at our thoughts on our own experience with choosing a Wifi adapter: [[Alternative Wi-Fi Adapters on the SBC]].

===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===

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 {{Code|System → Logs}} tab.

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

The actual locations of the log files (for filtering and reading) are:
* {{Code|/var/log/syslog}}
* {{Code|/var/log/dmesg}}
But don't edit them directly! Always follow the advice and procedures around the Internet on how to properly log items to syslog.

===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|PHP Curl|Curl doesn't install smoothly}}

There is an issue with the embedded version of PHP5.3, try forcing it to install the specific version that you need. This can be done with the following command:

{{Code|apt-get install php5-common<nowiki>=</nowiki>5.3.3-7+squeeze14}}

{{ProblemSolution|FTDI Errors|FTDI adapters do not appear to work with the SBC}}

The 3.1.6 version of the Linux kernel which is used on some versions of the SBC has a bug that causes issues with FTDI drivers and makes them malfunction. To solve this problem you must upgrade the kernel to a newer version. You can find the files [[#Quick Downloads| here]].

{{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>

OS - Phidget SBC

2014-04-10T17:57:51Z

Kat:

[[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__

==Quick Downloads==

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 [[1073 User Guide#Getting Started|SBC2 Getting Started Guide]] right out of the box.

*[{{SERVER}}/downloads/libraries/phidgetsbc2.bin SBC2 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package] (How-to and patch file)
*[[Software License]]
*[{{SERVER}}/downloads/libraries/phidgetsbc3_1.0.0.20121213.bin SBC3 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-kerneldev_1.0.0.20121213.tar.gz SBC3 Kernel Development Package]

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==

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 [[1073 User Guide#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 [[1073 User Guide#Getting Started | Getting Started Guide]].

This page will show you how to:
* Install the ability to write and develop code on the SBC itself
* 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:
* 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===

You have two ways to connect to the SBC from an external computer: via the [[#SBC Web Interface|SBC Web Interface]] and over the more powerful but complex [[#SSH | Secure Shell (SSH)]].

====SBC Web Interface====

You have already worked extensively with the web interface in the [[1073 User Guide#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====

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.

Before connecting over ssh, you will need:
* The '''IP address''' (such as 168.254.3.0) or '''link local address''' (such as phidgetsbc.local) of the SBC
* The '''admin password''' for the SBC
Both of these items can be found by following the steps in the [[1073 User Guide#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 → Settings}}, by changing the ''SSH Server'' radio button to ''Enabled'' and saving your changes:

[[File:sbc_turn_on_ssh.png|link=|alt=]]

=====SSH on Windows=====

The ssh program is not installed on Windows by default. But, there are a variety of SSH programs available for free. One simple and commonly used program 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 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.

=====SSH on Linux and Mac OS=====

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 → Utilities → Terminal}} on Mac OS
...and type:

<div class="source">
<syntaxhighlight lang=bash>
ssh root@phidgetsbc.local
</syntaxhighlight>
</div>

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>
scp root@phidgetsbc.local:/root/data.txt .
</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.

===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.

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 → 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 → 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>
apt-get install python
</syntaxhighlight>
</div>

This will give you Python, and now you just have to install the Phidget Python module to gain Phidget functionality.

=====Install Phidget Python Method 1: Use a USB Key=====

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.

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:

<div class="source">
<syntaxhighlight lang=bash>
python setup.py install
</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]].

=====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>
apt-get install wget
apt-get install unzip
</syntaxhighlight>
</div>

Copy the web link address for the [{{SERVER}}/downloads/libraries/PhidgetsPython.zip Python Libraries].

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.

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:

<div class="source">
<syntaxhighlight lang=bash>
python setup.py install
</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]].

====Installing Other Languages====

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>
apt-get install mono-runtime
</syntaxhighlight>
</div>

Then, to install the C# compiler:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install mono-gmcs
</syntaxhighlight>
</div>

Or the Visual Basic compiler:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install mono-vbnc
</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:

:{{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>
apt-get install libmono-corlib1.0-cil
apt-get install libmono-system1.0-cil
</syntaxhighlight>
</div>

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>
apt-get update
apt-get dist-upgrade
</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:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install monodoc-http mono-complete
</syntaxhighlight>
</div>

Choose monodoc-http explicitly, because otherwise the install fails on monodoc-browser.

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:

<div class="source">
<syntaxhighlight lang=bash>
gmcs Code.cs -r:Phidget21.NET.dll
mono Code.exe
</syntaxhighlight>
</div>

==Using SBC Linux==

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

First, 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.

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.

===Some Useful Commands===

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.

====ls====

The '''ls''' program lists the contents of a directory.

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>
</div>

This may be a lot of information you don't need. If you are only interested in a USB key attachment (as described in the [[#Using USB Data Keys|Using USB Data Keys]] section), you can use grep to filter that one response:

<div class="source">
<syntaxhighlight lang=text>
root@phidgetsbc:~# mount | grep sda1
/dev/sda1 on /media/usb0 type vfat (rw,noexec,nodev,sync,noatime,nodiratime)
</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 → 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.

====which====

The program {{Code|which}} tells you if and where a program is installed.

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===

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.

====gcc====

The '''gcc''' program is the C compiler for Linux.

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.

====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.

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.

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:
:<code>less Program.c | grep var</code>

====wget====

The '''wget''' program allows you to get an online file (over http) and download it to the SBC.

For example, to get the source file (HTML) from the Phidgets home page, you can type:

<div class="source">
<syntaxhighlight lang=bash>
wget http://www.phidgets.com
</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]].

===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 the same version of [[#Installing C/C++ and Java|Java installed on the SBC]] as you have on your external development machine. Instruction for checking and updating are found on the [[#Installing C/C++ and Java|installation page]].

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 → 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>
javac -classpath .:phidget21.jar HelloWorld.java
</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.

Now we move onto the SBC:

6. Create a new project on the SBC, in the web interface under {{Code|Projects → 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>
javac -classpath .:/usr/share/java/phidget21.jar HelloWorld.java
</syntaxhighlight>
</div>

5. To run the {{Code|HelloWorld}} program, use:

<div class="source">
<syntaxhighlight lang=bash>
java -classpath .:/usr/share/java/phidget21.jar HelloWorld
</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]].

'''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]].

====Developing Code on the SBC====

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.

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===

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 again. The main difference is:
* 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
* 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.

====Via the Web Interface====

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]].

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]].

Select the {{Code|Enabled}} radio button. The other defaults should be fine, unless you specifically know otherwise:
* 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.
* ''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.
* 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.

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====

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.

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>
export EDITOR=nano
</syntaxhighlight>
</div>

Then, to edit your crontab file, simply type:

<div class="source">
<syntaxhighlight lang=bash>
crontab -e
</syntaxhighlight>
</div>

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>
minute hour dayOfMonth month dayOfWeek command
</syntaxhighlight>
</div>

Where:
*{{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.

=====My Cron Job Doesn't Work!=====

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:
* {{Code|code/project.c}} is a relative path (bad for cron)
* {{Code|/root/code/project.c}} is an absolute path (good for cron)
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.

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:
* The settings loaded by {{Code|/etc/profile}}
* 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.

====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.

===Using USB Data Keys===

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

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

[[File:sbc_mounted_devices.png|link=|alt=]]

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

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

<div class="source">
<syntaxhighlight lang=bash>
root@phidgetsbc:~# mount | grep usb
/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.

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

===Saving and Retrieving Data===

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]].

====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.

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

<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/}}.

'''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.

====Over the Network (SCP)====

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.

====Backing Up Your Data====

For the web interface, you can save and restore all web interface settings under the {{Code|System → Backup & Restore}} tab.

To save the settings of what packages are installed for later re-installation, you can type:

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

<div class="source">
<syntaxhighlight lang=bash>
dpkg –set-selections < installedPrograms.txt
apt-get dselect-upgrade
</syntaxhighlight>
</div>

Also remember to externally save:
* 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.

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==

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.

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.

If your problem doesn't seem to be fixed by these steps, or the information within this guide, please [[Contact Us|ask us]]!

===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 User Guide#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 → 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 → Backup & Restore → 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 → Backup & Restore → 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==

===Shutting off USB ports to save power===
The SBC3 has an on-board USB hub that can control power to the ports. To do this unbind and rebind the USB drivers.

To turn off the ports {{code|echo "1-1" >/sys/bus/usb/drivers/usb/unbind}}

To turn on the ports {{code|echo "1-1" >/sys/bus/usb/drivers/usb/bind}}

These will also cause detach and attach events for the Phidget devices, respectively. While the drivers are unbound, you will not get any hot plug events for any devices on USB.

===Using a Touchscreen===
Please note that this will ONLY work with an SBC3 since it has a USB 2.0 hub:

Using a touchscreen with the SBC is a great way to get user input and visual feedback from an SBC otherwise devoid of visual output. The SBC does not have any conventional display ports such as VGA, DVI, or HDMI but it does have a number of USB ports and USB displays do exist. With the upgrade to a USB 2.0 hub on the SBC3 from the earlier models which had USB 1 hubs the SBC now has enough capability to operate a screen over USB. We don't recommend running a standard desktop environment since the processor is too slow to really keep up with a typical desktop it does make for an excellent interface for a kiosk, instrumentation control panel or other, similar use case. This document is going to go through the process of enabling support for a typical USB display as well as installing a fairly compact desktop environment called xfce on the SBC.

The screen I will be using is from a company called [http://lilliputweb.net/ Lilliput]. Specifically a UM-70 model. Before you begin, please make sure that you have the screen plugged into the SBC, it will also be useful to have a spare USB keyboard and mouse handy as you will need them once you are no longer using an SSH terminal to communicate with the SBC.

[[File:lilliputoff.jpg|center|400px|link=]]

====Getting the display to function====
Begin by logging into the web configuration page for your SBC and upgrading all of the packages on the SBC. Be sure to include the full Debian package repository. For more information on how to do this refer to the [[OS - Phidget SBC#Getting Started - External Computer|getting started]] section of the Phidget SBC documentation. Once you are fully up to date open an SSH session with the SBC and navigate to the "/etc" folder. Open inittab with a terminal-based text editor such as nano and add the following to the bottom of the file, just above the {{code|T0:23:respawn:/sbin/getty -L ttyAMA0 115200 vt100}} line:

<div class="source">
<syntaxhighlight lang=bash>
1:2345:respawn:/sbin/getty 38400 tty1
2:23:respawn:/sbin/getty 38400 tty2
3:23:respawn:/sbin/getty 38400 tty3
4:23:respawn:/sbin/getty 38400 tty4
5:23:respawn:/sbin/getty 38400 tty5
6:23:respawn:/sbin/getty 38400 tty6
</syntaxhighlight>
</div>

Now reboot your system. After a few minutes you should see the LCD screen come up with a standard Linux terminal interface and a login prompt. This is all well and good but this isn't really appreciably better than simply using an SSH session to communicate with the SBC.

[[File:lilliputlogin.jpg|center|400px|link=]]

====Setting up Xfce====
In order to get a traditional windowing environment we still need to install a desktop manager as well as a number of supporting packages. Log in and make sure everything is still up to date with:

<div class="source">
<syntaxhighlight lang=bash>
apt-get update
</syntaxhighlight>
</div>

Then install the following packages:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install xserver-xorg lxde xfce4
</syntaxhighlight>
</div>

If the SBC asks you if you want to continue, just type "Y" and press enter.

This will install the xfce desktop environment and any other necessary programs on the SBC. When it's done, restart the SBC. When it boots back up it should boot directly to a login screen instead of the terminal interface. Log in, and you are good to go. It won't be particularly fast, but don't worry, the SBC does not have a dedicated video processor on it so it's perfectly normal for it to be slow. What's important is that it works.

[[File:lilliputdesktop.jpg|center|400px|link=]]

====Calibrating the touch screen====
Unfortunately, by default the screen is calibrated to believe the bottom of the screen is on the right hand side. This has the effect of making the touch functionality more or less useless until it has been properly calibrated. To do this, install the following package:

<div class="source">
<syntaxhighlight lang=bash>
apt-get install xinput-calibrator
</syntaxhighlight>
</div>

Now use xinput calibrator to measure the parameters of your screen. Launch xinput calibrator (called Calibrate Touchscreen in the programs menu) and follow the instructions on the screen. The screen should now be functioning at full potential.

===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]]. You can also have a look at our thoughts on our own experience with choosing a Wifi adapter: [[Alternative Wi-Fi Adapters on the SBC]].

===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===

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 {{Code|System → Logs}} tab.

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

The actual locations of the log files (for filtering and reading) are:
* {{Code|/var/log/syslog}}
* {{Code|/var/log/dmesg}}
But don't edit them directly! Always follow the advice and procedures around the Internet on how to properly log items to syslog.

===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|PHP Curl|Curl doesn't install smoothly}}

There is an issue with the embedded version of PHP5.3, try forcing it to install the specific version that you need. This can be done with the following command:

{{Code|apt-get install php5-common<nowiki>=</nowiki>5.3.3-7+squeeze14}}

{{ProblemSolution|FTDI Errors|FTDI adapters do not appear to work with the SBC}}

The 3.1.6 version of the Linux kernel which is used on some versions of the SBC has a bug that causes issues with FTDI drivers and makes them malfunction. To solve this problem you must upgrade the kernel to a newer version. You can find the files [[#Quick Downloads| here]].

{{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>

Template:UGsbc4

2014-04-10T17:51:03Z

Kat: added a note about versions of java

==Advanced User's Guide==

This section describes use of the PhidgetSBC outside of the web configuration, and basic opening of Phidgets over the network. This includes custom applications, using the included gcc compiler, using SSH, customizing the system, and building your own filesystem and/or kernel from sources. It is recommended that you have some experience with Linux before trying some of these tasks.

===Custom Applications===

The PhidgetSBC supports custom user application written in either Java or C. Custom applications are set up and managed using the configuration interface. Alternatively applications can also be created using the command line tool ‘createapp’ - the tool will guide you through the set up process.

Custom applications are created under the /mnt/userspace/userapps/(application name) directory and contain all application files. This must include at least the executable file.

Java applications must be compiled on a separate development machine, where they can also be tested before deployment. When coding, make sure to include the correct version of phidget21.jar file as part of the environment and that the SBC and your development machine are running the same version of Java. You can use the link under Userspace: Applications page in the configuration interface to ensure that your Java program is synchronized with the version of phidget21 on the PhidgetSBC. When using Java packages, make sure to create the appropriate directory for them.

The PhidgetSBC also supports .jar files and you may find it easier to compile and upload a .jar instead of the all the necessary .class files. When your project is completed we recommend to compile the project as a .jar. This reduces the number of extra flies created into a single package that is easier to manage and can be executed from the command line, or even by double clicking the file if your operating system environment is configured properly.

Under the command line, you can use the jar utility from the Java SDK to package the .class and .java files. The process starts by going to the directory where your program is located and creating a manifest file. This manifest file tells the java jar compiler the version of the program and the name of the Main-Class which acts as the entry point for the application. The entry point is the class that contains the main method that is run when the program is started. You also want to add a line to specify the class-path which will point to the phidget21.jar file that contains the library for including into the jar.

Let’s assume we want to distribute our program MyProgram.java as an executable jar file. First, compile the program to generate the .class files. Now, create the manifest file MyProgram.mf which contains the following lines:

:Manifest-Version: 1.0
:Class-Path: phidget21.jar
:Main-Class: MyProgram

Save the file and close it. Create the jar by running the following command from the command line:
:jar cmf MyProgram.mf MyProgram.jar MyProgram.class MyProgram.java SupportClass.class SupportClass.java.
You should now have an executable jar file called MyProgram.jar that you can distribute easily as one package and run from anywhere very easily. To run the executable jar file you can either type the following into the command line:
:java -jar MyProgram.jar
Or, you can double click the file in a visual operating system if your environment is configured properly.

Note: Some IDEs, such as Eclipse and Netbeans, automatically create jar files when you build your project. Simply look in your build output folders for your .jar file. Java applications can also be directly executed through SSH using jamvm.

i.e.: jamvm –jar MyProgram.ja

C programs can be compiled on the PhidgetSBC itself, via the SSH interface, or off-board using a cross compiler. Use of a cross compiler is not strictly documented here, but it is possible to build one from the buildroot distribution available on our web site. When developing C applications on the PhidgetSBC, it is recommended that you log in using the ‘user’ account instead of ‘root’. If you need to log data from a custom application, you can either log directly to the application directory with the size limits of the userspace in mind, or to /tmp if the data should be erased on reboot. Alternatively, you can use a
flash drive, which are mounted automatically at /media/usb(0-9) when plugged in. Note that custom applications should not try to get user input, as stdin is closed before the application gets run.

===GCC===

The PhidgetSBC contains full GCC and associated build tools, as well as make and gdb for compiling C source. Use of these is the same as on full linux, just keep in mind that there is no swap space and userspace is limited. Compiling will also be slow for complicated programs. Simple programs are ideal for this environment. The C library used is uClibc. For most uses this should be similar to full libc, just much smaller. Also, when compiling a program that links with libphidget21.so, you need to add ‘-lphidget21 -ldl -lpthread -lm’ to the command line. Otherwise, you will get segfaults.

===Phidget Dictionary===

Communication between a custom application on the PhidgetSBC and the outside world can be facilitated by using the dictionary interface of the Phidget Webservice. The dictionary lets you set and listen for key/value pairs over the network, and take action accordingly. This could be used to post data or listen for commands over the network, while maintaining reliability and ultimate control on the PhidgetSBC itself in case of network failure. See the Phidget Programming manual for its use in your language of choice.

===SSH===
The built-in SSH Server can be enabled to allow console access to the PhidgetSBC. By default, this server is disabled. SSH access to the PhidgetSBC is enabled in the Network: Network configuration page on the PhidgetSBC. Projects on the PhidgetSBC should be stored in the user home directory (/home/user). Enabling the server for the first time can take several minutes as the encryption keys are generated. Once SSH is enabled, connect to the PhidgetSBC using its hostname or IP address (e.g. ‘ssh user@phidgetsbc.local’). You should login using the restricted ‘user’ account using the initial password set for the ‘root’ account. The password for the user account can be changed any time either through the unrestricted root account or directly through the user account. Files can be sent to the board using scp or by uploading through the web interface in Userspace: Userspace Browser. The SSH server does not support sftp. Text files (source code, etc.) can be edited using vi or with the web interface. On Windows, we recommend Putty for an SSH client. You can get this at http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html.

===Customization===

If you wish to customize the root filesystem, you have two options: customize locally on the board, or build a custom kernel and filesystem from source. If you mess up the firmware while customizing, you can always perform a board reset and start again. You may also want to to add new libraries or kernel extensions, add new Unix tools, update certain aspects, delete others, change the boot process, etc. All of this is possible, but it is also completely unsupported by Phidgets. In order to customize the root file system of a running PhidgetSBC, you will need to remount the filesystem as readwrite with the command: ‘mount -o remount,rw /’. At this point you can change any files in /, just keep in mind the amount of free space. Once the SBC is rebooted, / will again be mounted as read-only.

===Custom Kernels and Filesystem===

You can build the complete filesystem and kernel from the same codebase as Phidgets Inc. uses. The full Buildroot system can be downloaded from our website. Phidgets Inc. does not provide support for custom filesystems or kernels, nor do we provide advanced tutorials on the buildroot system. However, this basic information should be enough to get started. Buildroot works by building a full cross-compiler for the PhidgetSBC and then using that to build a full set of tools to create a root filesystem from scratch. It also handles building the kernel. You can use the cross compiler that it produces to build your own applications for the PhidgetSBC independently of the system, or integrate your code into the process. Buildroot downloads all of the source code it needs from open-source repositories, so the Buildroot distribution itself is fairly small. Buildroot needs to be run on Linux. Unpack the distribution and run the following commands to set everything up:

*`touch .config`
*`make BOARD=phidget_sbc getconfig`

You can build your filesystem by typing ‘make’ and change configuration options using ‘make menuconfig’. Output binaries are located in binaries/phidget_sbc - the .bin files are accepted by the PhidgetSBC upgrade system. Building the full filesystem relies on some packages which you will need to install into your Linux distribution, including but not limited to: libacl1-dev, zlib1g-dev, kaffe, liblzo2-dev. If you make changes to config files, source, etc., run ‘rm_root’ before running make, otherwise the filesystem may not be updated properly. Kernel patches are stored in: target/device/PhidgetSBC/. More information about Buildroot can be found here: http://buildroot.uclibc.org/docs.html

Main Page

2014-04-10T17:15:28Z

Kat:

[[Category:Administrative]]__NOTOC__
{| cellpadding="25" cellspacing="20" style="border:0;"
|- valign="top"
| cellpadding="25" style="border:1px solid darkgray;" |
{|
|- valign="center"
| rowspan="2" | [[Image:App_guide_sbcweb_sbc_image.jpg|250px|link=Category:Primer|alt=]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Hardware</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Get extensive hardware information on topics like:
* '''[[Stepper Motor and Controller Primer | Stepper Motors]]''',
* Digital '''[[Digital Input Primer|Inputs]]''' and '''[[Digital Output Primer|Outputs]]''',
* '''[[Solid State Relay Primer|Solid State Relays]]''',
and much, much more in our '''[[:Category:Primer|Primers]]'''<br>

Specifications, photos, and the like can be found back on our '''[{{SERVER}} main website]'''<br>
|}
| style="border:1px solid darkgray;" cellpadding="25px" |
{|
|- valign="center"
| rowspan="2" | [[Image:Manag-inheritedobject.png|200px|link=Software Overview|alt=]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Software</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Compare our supported '''[[Software Overview#Language Support|languages]]''' and '''[[Software Overview#Operating System Support|operating systems]]''' <br>
Learn our method of '''[[General Phidget Programming]]'''<br>
Download the specific API for your language of choice '''[[Software Overview#Language Support|on its wiki page]]'''<br>
Run and modify the software examples '''[[Software Overview#Language Support|for your language]]''' <br>
Use Phidgets over a network with our '''[[Phidget WebService|WebService]]''' and '''[[Phidget Dictionary|Dictionary]]'''<br>
|}
|- valign="top"
| style="border:1px solid darkgray;" cellpadding="25px" |
{|
|- valign="center"
| rowspan="2" | [[Image:fire.png|250px|link=:Category:Application Guides|alt=]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Inspiration</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Read our '''[[:Category:Application Guides|application notes]]''' showing cool projects <br>
View a list of '''[http://www.pinterest.com/phidgets/phidgets/ customer projects]''' that have been submitted <br>
Visit our '''[http://www.phidgets.com/phorum/ forums]''' for more customer projects and ideas <br>
|}
| style="border:1px solid darkgray;" cellpadding="25px" |
{|
|- valign="center"
| rowspan="2" | [[Contact Us|<font style="font-size:150pt;line-height:170pt;color:blue;">?</font>]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Help</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Learn '''[[What is a Phidget?|what a Phidget is]]''' <br>
Start with the ''Getting Started'' guide for your Phidget in its '''[[:Category:UserGuide|user guide]]''' <br>
Visit our '''[{{SERVER}}/phorum/ forums]''' and connect with others <br>
Try out our '''[[General Troubleshooting]]''' guide <br>
Access our '''[{{SERVER}}/content_display.php?content=Policies policies]''' for shipping and return information<br>
Keep your language and operating system '''[[Software Overview|libraries]]''' up-to-date <br>
Discover how '''[[About Phidgets Inc.|Phidgets Inc.]]''' was founded <br>
'''[[Contact Us|Contact us]]''' for support <br>
|}
|}

Main Page

2014-04-10T17:15:00Z

Kat:

[[Category:Administrative]]__NOTOC__
{| cellpadding="25" cellspacing="20" style="border:0;"
|- valign="top"
| cellpadding="25" style="border:1px solid darkgray;" |
{|
|- valign="center"
| rowspan="2" | [[Image:App_guide_sbcweb_sbc_image.jpg|250px|link=Category:Primer|alt=]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Hardware</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Get extensive hardware information on topics like:
* '''[[Stepper Motor and Controller Primer | Stepper Motors]]''',
* Digital '''[[Digital Input Primer|Inputs]]''' and '''[[Digital Output Primer|Outputs]]''',
* '''[[Solid State Relay Primer|Solid State Relays]]''',
and much, much more in our '''[[:Category:Primer|Primers]]'''<br>

Specifications, photos, and the like can be found back on our '''[{{SERVER}} main website]'''<br>
|}
| style="border:1px solid darkgray;" cellpadding="25px" |
{|
|- valign="center"
| rowspan="2" | [[Image:Manag-inheritedobject.png|200px|link=Software Overview|alt=]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Software</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Compare our supported '''[[Software Overview#Language Support|languages]]''' and '''[[Software Overview#Operating System Support|operating systems]]''' <br>
Learn our method of '''[[General Phidget Programming]]'''<br>
Download the specific API for your language of choice '''[[Software Overview#Language Support|on its wiki page]]'''<br>
Run and modify the software examples '''[[Software Overview#Language Support|for your language]]''' <br>
Use Phidgets over a network with our '''[[Phidget WebService|WebService]]''' and '''[[Phidget Dictionary|Dictionary]]'''<br>
|}
|- valign="top"
| style="border:1px solid darkgray;" cellpadding="25px" |
{|
|- valign="center"
| rowspan="2" | [[Image:fire.png|250px|link=:Category:Application Guides|alt=]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Inspiration</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Read our '''[[:Category:Application Guides|application notes]]''' showing cool projects <br>
View a list of '''[[User Projects|customer projects]]''' that have been submitted <br>
Visit our '''[http://www.phidgets.com/phorum/ forums]''' for more customer projects and ideas <br>
|}
| style="border:1px solid darkgray;" cellpadding="25px" |
{|
|- valign="center"
| rowspan="2" | [[Contact Us|<font style="font-size:150pt;line-height:170pt;color:blue;">?</font>]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Help</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Learn '''[[What is a Phidget?|what a Phidget is]]''' <br>
Start with the ''Getting Started'' guide for your Phidget in its '''[[:Category:UserGuide|user guide]]''' <br>
Visit our '''[{{SERVER}}/phorum/ forums]''' and connect with others <br>
Try out our '''[[General Troubleshooting]]''' guide <br>
Access our '''[{{SERVER}}/content_display.php?content=Policies policies]''' for shipping and return information<br>
Keep your language and operating system '''[[Software Overview|libraries]]''' up-to-date <br>
Discover how '''[[About Phidgets Inc.|Phidgets Inc.]]''' was founded <br>
'''[[Contact Us|Contact us]]''' for support <br>
|}
|}

User Projects

2014-04-10T17:14:01Z

Kat: cut down list and added the link.

A wide variety of projects can be completed with Phidgets. This list shows the breadth of applications, from drones to monitoring and control systems. We've only selected some of the most popular projects, but for a complete look and an up-to-date list of where Phidgets have been used, check out the '''[http://www.pinterest.com/phidgets/phidgets/ Phidgets Pinterest Board]'''.

For more project ideas, check out our [[:Category:Application Guides|Application Notes]].

If you'd like to share your project here, [[Contact_Us|contact us]].

<div class="nonumtoc">
__TOC__
</div>

==Phidgets Contests==

* [http://www.phidgets.com/phorum/viewforum.php?f=55 2013 Phidgets Contest Entries].

==RoboDose==

[[File:robodose.jpg|left]]

From their website: "he RoboDose uses an industry standard controller to automate the process of an everyday problem. We took the provided Phoenix Contact Nanoline PLC starter kit and their Nano-Navigator software and produced what we believe could be the answer to an everyday issue. Our team worked through numerous design sessions in order to arrive at this year’s solution. Our team of two boys and three girls made the decision to solve the problem of the elderly forgetting to take, remembering when to take, and trying to recall how many of each medication to take. Our device was designed to eliminate the need of weekly/daily pill organizers and caregivers having to individually dispense and monitor prescriptions we created a product that could safely and securely dispense the proper dosages, multiple times a day. The machine was designed to notify caregivers or family members if proper dosages were not taken in a timely manner."

[http://www.chrisandjimcim.com/index.php?option=com_content&view=article&id=334:nanoline-2014-robodose&catid=76:simulation-projects&Itemid=281 Website]

<br clear=all>

==Converse Canvas Experiment==

[[File:Converse.jpg|100px|left]]

Perfect Fools made a screen of converse shoes that rotate to show red, white or blue. Images are fed from a computer and the shows turn to create the 12' tall display.

[https://www.youtube.com/watch?v=fkIFbOJG_aM Website]

<br clear=all>

==Mapbot==

[[File:mapbot.jpg|left]]

Using Phidget servo motors, a ship is steered around a map, showing the trade routes that the Portuguese took in the 1500s.

[http://staceyrdevlin.wordpress.com/2014/04/02/my-adventures-with-the-mapbot-come-to-an-end-or-do-they/ Website]

<br clear=all>

==Falcon Robotics AUVSI==

[[File:Falconrobotics.JPG|left|100px]]

The team from Carl Hayden High School developed several underwater vehicles that have won several prizes.

[https://sites.google.com/site/falconroboticsfrcteam842/ Website]

<br clear=all>

==Planet Tree==

[[File:Planet tree.jpg|left|100px]]

The Planet Tree installation by Wit Pimkanchanapong uses 300 Phidgets servo motors to create the effect of leaves turning in the wind.

[https://vimeo.com/10626181 Website]

<br clear=all>

File:Converse.jpg

2014-04-10T17:05:48Z

Kat: Converse Canvas Experiment by Perfect Fools

Converse Canvas Experiment by Perfect Fools

File:Planet tree.jpg

2014-04-10T17:01:47Z

Kat: By Wit Pimkanchanapong

By Wit Pimkanchanapong

File:Falconrobotics.JPG

2014-04-10T16:57:25Z

Kat: Image supplied by the Falcon Robotics team.

Image supplied by the Falcon Robotics team.

File:Mapbot.jpg

2014-04-10T16:34:50Z

Kat: Photo by Stacey Devlin http://staceyrdevlin.wordpress.com/2014/04/02/my-adventures-with-the-mapbot-come-to-an-end-or-do-they/

Photo by Stacey Devlin http://staceyrdevlin.wordpress.com/2014/04/02/my-adventures-with-the-mapbot-come-to-an-end-or-do-they/

File:Robodose.jpg

2014-04-10T16:32:31Z

Kat:

Category:Application Guides

2014-04-10T16:10:32Z

Kat: changed link for user projects to the regularly updated pinterest board.

Main Page

2014-04-10T16:09:22Z

Kat: changed link for user projects to the regularly updated pinterest board.

[[Category:Administrative]]__NOTOC__
{| cellpadding="25" cellspacing="20" style="border:0;"
|- valign="top"
| cellpadding="25" style="border:1px solid darkgray;" |
{|
|- valign="center"
| rowspan="2" | [[Image:App_guide_sbcweb_sbc_image.jpg|250px|link=Category:Primer|alt=]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Hardware</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Get extensive hardware information on topics like:
* '''[[Stepper Motor and Controller Primer | Stepper Motors]]''',
* Digital '''[[Digital Input Primer|Inputs]]''' and '''[[Digital Output Primer|Outputs]]''',
* '''[[Solid State Relay Primer|Solid State Relays]]''',
and much, much more in our '''[[:Category:Primer|Primers]]'''<br>

Specifications, photos, and the like can be found back on our '''[{{SERVER}} main website]'''<br>
|}
| style="border:1px solid darkgray;" cellpadding="25px" |
{|
|- valign="center"
| rowspan="2" | [[Image:Manag-inheritedobject.png|200px|link=Software Overview|alt=]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Software</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Compare our supported '''[[Software Overview#Language Support|languages]]''' and '''[[Software Overview#Operating System Support|operating systems]]''' <br>
Learn our method of '''[[General Phidget Programming]]'''<br>
Download the specific API for your language of choice '''[[Software Overview#Language Support|on its wiki page]]'''<br>
Run and modify the software examples '''[[Software Overview#Language Support|for your language]]''' <br>
Use Phidgets over a network with our '''[[Phidget WebService|WebService]]''' and '''[[Phidget Dictionary|Dictionary]]'''<br>
|}
|- valign="top"
| style="border:1px solid darkgray;" cellpadding="25px" |
{|
|- valign="center"
| rowspan="2" | [[Image:fire.png|250px|link=:Category:Application Guides|alt=]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Inspiration</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Read our '''[[:Category:Application Guides|application notes]]''' showing cool projects <br>
View a list of '''[http://www.pinterest.com/phidgets/phidgets/ User Projects|customer projects]''' that have been submitted <br>
Visit our '''[http://www.phidgets.com/phorum/ forums]''' for more customer projects and ideas <br>
|}
| style="border:1px solid darkgray;" cellpadding="25px" |
{|
|- valign="center"
| rowspan="2" | [[Contact Us|<font style="font-size:150pt;line-height:170pt;color:blue;">?</font>]]
| style="padding-top:12px;padding-left:20px;padding-right:20px;" | <h2>Help</h2>
|- valign="top"
| style="padding-bottom:12px;padding-left:20px;padding-right:20px;" |
Learn '''[[What is a Phidget?|what a Phidget is]]''' <br>
Start with the ''Getting Started'' guide for your Phidget in its '''[[:Category:UserGuide|user guide]]''' <br>
Visit our '''[{{SERVER}}/phorum/ forums]''' and connect with others <br>
Try out our '''[[General Troubleshooting]]''' guide <br>
Access our '''[{{SERVER}}/content_display.php?content=Policies policies]''' for shipping and return information<br>
Keep your language and operating system '''[[Software Overview|libraries]]''' up-to-date <br>
Discover how '''[[About Phidgets Inc.|Phidgets Inc.]]''' was founded <br>
'''[[Contact Us|Contact us]]''' for support <br>
|}
|}