Phidgets Legacy Support - User contributions [en]

Template:Phidget21Box

2024-02-23T17:43:37Z

Patrick:

{|cellpadding="5" style="background-color: #ffcccc;"
|[[Image:alert.png|40px|link=]]
| style="text-align:center;" |
'''Notice:''' This page contains information for the legacy Phidget21 Library.

Phidget21 is out of support. Bugfixes may be considered on a case by case basis.

Phidget21 does not support VINT Phidgets, or new USB Phidgets released after 2020. We maintain a selection of legacy devices for sale that are supported in Phidget21.

We recommend that new projects be developed against the Phidget22 Library.

<font size=3>'''Click on the [[Image:2phidget22.jpg|link=|100px]] button in the menu bar to go to the Phidget22 version of this page.'''</font>
|[[Image:alert.png|40px|link=]]
|}

MediaWiki:Common.js

2022-06-15T23:51:14Z

Patrick:

/**
* Redirect User:Name/skin.js and skin.css to the current skin's pages
* (unless the 'skin' page really exists).
*
* Dependencies: mediawiki.util
*
* @source https://www.mediawiki.org/wiki/Snippets/Redirect_skin.js
* @revision 2016-04-13
*/
if ( mw.config.get( 'wgArticleId' ) === 0 && mw.config.get( 'wgNamespaceNumber' ) === 2 ) {
mw.loader.using( 'mediawiki.util', function () {
var titleParts = mw.config.get( 'wgPageName' ).split( '/' );
// Make sure there was a part before and after the slash
// And that the latter is 'skin.js' or 'skin.css'
if ( titleParts.length === 2 ) {
var userSkinPage = titleParts[0] + '/' + mw.config.get( 'skin' );
if ( titleParts[1] === 'skin.js' ) {
window.location.href = mw.util.getUrl( userSkinPage + '.js' );
} else if ( titleParts[1] === 'skin.css' ) {
window.location.href = mw.util.getUrl( userSkinPage + '.css' );
}
}
} );
}

// Book specific
var wgBookName = ( mw.config.get( 'wgPageName' ).split( '/', 1)[0] || '' ).split( ':', 2 ).join( ':' );
mw.loader.load( '/docs/index.php?title=MediaWiki:Common.css/'+wgBookName+'&action=raw&ctype=text/css', 'text/css' );

// Imported scripts
mw.loader.load( '/docs/index.php?title=MediaWiki:Common.js/CollapseElements.js&action=raw&ctype=text/javascript');

Driver Changelog

2019-10-08T19:59:46Z

Patrick:

[[Category:Administrative]]
__NOTOC__

===2.1.9.20191008===
*macOS release
**Fix Java library

===2.1.9.20191007===
*macOS release
**Fix kernel driver for macos 10.9 and 10.10

===2.1.9.20191001===
*macOS / Windows release
**Support for macos 10.15 Catalina
**Update firmware files

===2.1.9.20190409===
*Fix GPS Date after April 6 2019 week rollover event

===2.1.9.20190208===
*macOS release
**Fixed USB bug where devices plugged in before boot were inaccessible until unplugged/re-plugged on 2018 Mac Mini.

===2.1.9.20180622===
*Python fix

===2.1.9.20180215===
*Move to .NET 4.0

===2.1.8.20171215===
*macOS release
**Fixed USB bug where opening two of the same device with -1 serial could cause missed attach/detach events and other errors.

===2.1.8.20160921===
*macOS release
**Fixed USB bug where devices plugged in before boot were inaccessible until unplugged/re-plugged, under OS X 10.11.

===2.1.8.20160202===
*Windows release
**Labview 7.1 support

===2.1.8.20160107===
*Windows release
**Don't throw an exception on EncoderPositionChangeEventArgs.Time in the .Net library when time it unknown - just return 0x7fffffff

===2.1.8.20160104===
*Mac/Windows release
**New firmware for 1042 and 1044, fixing digital gyro
===2.1.8.20151217===
*Fixed 1045 bug where it will display an unknown ambient temperature sometimes
*Fixed a crash in the windows control panel

===2.1.8.20151020===
*Windows release
**Fixed an issue where the examples would error when trying to run them from the control panel.

===2.1.8.20151009===
*OS X and Windows release
**Upgraded firmware for 1024, 1032, 1041, 1042, 1043, 1044 and 1067 to address issues with these Phidgets on OS X El Capitan
*SBC release
**Support for multiple webcams
===2.1.8.20150821===
*OS X-only release
**Support OS X 10.11 El Capitan
===2.1.8.20150805===
*OS X-only release
**Preliminary support for OS X 10.11 El Capitan
===2.1.8.20150410===
*Linux-only release
**Fixed Makefile phidget21.h target issues
===2.1.8.20150326===
*Windows-only release
**Fixed issue with webservice buttons not being visible in the control panel
===2.1.8.20150323===
*Windows-only release
**Updated icons with new company logo
===2.1.8.20150227===
*Linux-only release
**Added copyright/licence headers to source code files
**Updated cvtutf files to a newer version
===2.1.8.20150109===
*Windows-only
**Fixed examples for Labview 8.5
===2.1.8.20141209===
*OS X-only release
**Added support for armv7s and arm64 to the iOS library. Dropped support for armv6. Requires iOS 5.1.1 or later.
===2.1.8.20141202===
*Windows-only release
**Labview release to support older versions
===2.1.8.20141119===
*OS X-only release
**Fixed an issue with the 2.1.8.20141117 release where nothing was actually installed.
===2.1.8.20141117===
*OS X-only release
**Fixed a code-signing issue that make the installer appear unsigned on OS X 10.10
**Dropped support for OS X 10.4
===2.1.8.20140905===
*Windows-only release
**Added an IA32 folder to the windows libraries download - this supports Windows on the Intel Galileo platform
===2.1.8.20140428===
*Windows-only release
**Fixes to C# Stepper GUI Example
===2.1.8.20140319===
*CPhidget_getDeviceClass can now be called on handle before it is attached.
*Added support for 64-bit Max/MSP (Version 6.1+) on both OS X and Windows.
===2.1.8.20140227===
*Deals with 1046 bug in v100 and v101 firmware.
**No longer reports bad values that appear right after a channel is enabled.
**Fixes issue where changing the gain while channel 0 is disabled would sometimes cause bad readings.

===2.1.8.20131105===
* Fixed a defect in the Flash examples for the 1012 (Outputs 11-16 were not addressed properly).

===2.1.8.20130926===
*Windows-only release
**Support setting label on 1067 from Windows
===2.1.8.20130820===
*Windows-only release
**Added logging option to control panel / C# full examples
===2.1.8.20130802===
*Windows-only release
**Fix for Windows 8 issue where only 'Uninitialized Phidget Handle' would show up in the Manager, and Phidgets could not be opened.
===2.1.8.20130723===
*Improvement to java: we don't attach/detach our native threads for each event, just one attach, then detach before the thread exits.
**This increases performance, esp. when debugging on Android.
*Improvement to Android: We reuse the UsbRequest object rather then creating a new one for each transfer. This reduces logcat messages tremendously, and increases performance.
===2.1.8.20130710===
*Android-only release
**Added extra android target architectures: x86, MIPS, armeabi-v7a
===2.1.8.20130618===
*Changed setCompassCorrectionParameters() API call so that compass calibration parameters are written out to non-volatile storage on 1042/1044, so that they persist across power cycles. Previously, calibration data would need to be re-programmed at each attach.
*Changes to C# Spatial example:
**Compass calibration parameter set dialog removed from for 1042/1044 because parameters are set by the calibration software - and thus do not need setting in the example.
**Stores/restores parameters for 1056 based on serial number, so multiple different calibrations can be maintained.
===2.1.8.20130607===
*Windows-only release
**Fixes to compass calibration software for 1042/1044
===2.1.8.20130419===
*Windows-only release
**Fixed setCompassCorrectionParameters in the COM library
===2.1.8.20130327===
*Windows-only release
**Changed Windows installer to stop virus-scanner false positives
**Dropped support for Windows 2000
===2.1.8.20130320===
*Added EPHIDGET_NOTFOUND exception to Dictionary.getKey() for when the key is not found.
*Added exceptions back into the Java library - they have been missing since 2.1.8.20121015 release.
===2.1.8.20130313===
*Updates to Matlab support
**Works properly on Matlab 7+, on Windows, Mac, Linux without needing changes to .m files.
===2.1.8.20130221===
*Windows-only release
**Encoder Index event added to C and .NET libraries
===2.1.8.20121218===
*Webservice version: 1.0.10
**Support for 1024, 1032
*Support for 1024, 1032
*fixed bug where if one half of a composite device is open, and PHIDGET_USB_ERROR_FLAG gets set, the device may never re-attach.
===2.1.8.20121015===
*Windows-only release
**Support for new pressure/light sensors in example.
===2.1.8.20120914===
*Windows-only release
**Improved firmware upgrading in control panel - it was giving some false-errors on some machines.
===2.1.8.20120912===
*Fixed bug where 1065 could fail to attach when opened over webservice
*Fixed bug where close() could deadlock on Phidgets opened over the webservice
*Changed LED64 LED Brightness from int to double
**this may cause issues when controlling the LED64 over the webservice and library/webservice are not the same version
**the old setDiscreteLED call will remain, deprecated, with an int argument for compatibility.
===2.1.8.20120716===
*Linux-Only Release
**Fixed a bug where opening a device in two program at once would cause an attach-detach cycle as they fight each other for control.
===2.1.8.20120713===
*Mac-Only Release
**Added signing of the Mac installer, so Mountain Lion (OS X 10.8) doesn't refuse to run it.
===2.1.8.20120615===
*Windows-only release
**Fixed a bug that caused java to crash on events introduced in 2.1.8.20120612
===2.1.8.20120612===
*Windows-only release
**Fixed another bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120606===
*Windows-only release
**Fixed a bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120525===
*Windows-only release
**Fixed PhidgetIR sendRawData bug in .NET on 64-bit machines.
===2.1.8.20120514===
*Linux-only release
**Fixed a bug that causes a segfault with libusb-1.0 under 64-bit Linux.
===2.1.8.20120507===
*Mac/Linux-only release
**Fixes a setLabel bug introduced in 2.1.8.20120503
===2.1.8.20120503===
*Fixed some spelling mistakes
*Moved to libusb-1.0
**This resolves a bug where having a webcam plugged in caused a memory leak in the webservice.
*Fixed bug with advanced servo where setting acceleration to accelerationMax would cause an exception for some servo types
===2.1.8.20120216===
*Fixed bug with RFID Reader on OS X and Linux, as well as .NET over the webservice
*Fixed bug that could cause the Java Phidget Manager to crash during garbage collection.
===2.1.8.20120131===
*Fixed RFID Reader bug that caused tag event to not get thrown in .NET Applications
*Changed compass bearing calculations in spatial C# example
===2.1.8.20120123===
*Added support for 1061 v300+
*Fixed a bug where the firmware version could be mis-reported over Bonjour
===2.1.8.20111220===
*Fixed a bug in AppleScript where closing a Phidget opened via label would give a 'Connection Invalid' error.
*Fixed a bug where the webservice may fail to start on Linux systems that don't support IPv6 (ie. SBC2).
*Fixed issue where ratiometric state on newest interfacekit wouldn't be read back properly if it was false during attach.
*Fixed webservice issue where ratiometric state would not be reported properly for newest interfacekits
*Increased the number of overrun errors ignored during initial attach for InterfaceKit.
*Fixed an issue with the iPhone library and header
===2.1.8.20111219===
*fixed various other webservice stability/performance/memory leak bugs
*Faster connection to SBC-connected Phidgets from Mac OS
*Don't report packetlost or overrun errors that happen during early initialization - these are just noise.
*Fixed a bug in the webservice tree removal function that could cause memory leaks.
*Fixed bug where Webservice would crash on Linux if the chosen serverID was already under use on the network
*Stopped sending hardware Error Events before the Attach event - they are now queued up and sent after Attach
*Fixed a crash in the [[Phidget Control Panel]]
*Added ability to remove dictionary keys from a key change listener
*Reduced the number of false 'pending command not finished' error events on Close()
*Fixed a webservice bug where exceptions/false attach events could occur when close() is called soon after open
*Fixed bug where closing a PhidgetRFID soon after attach could cause a crash
*Fixed webservice but on MacOS where client could exit with SIG_PIPE error
*Fixed webservice bug where the server would sometimes exit(1) after many connect/disconnect cycles
*Fixed webservice bug where client could deadlock during close()
*Fixed webservice bug where opening a single remote phidget multiple times from the same application would fail
*Fixed a webservice bug where sockets weren't being closed properly sometimes
*Fixed a webservice bug where pre-attach error events wouldn't get through
*Fixed a bug where the webservice running on Linux would stop responding to clients after ~300 connect/disconnect cycles
*Fixed bug where a Phidget would become inaccessible until the app is restarted if a thread creation failed
*Fixed webservice bug where connect is slow on Windows when multiple clients are running simultaneously
*Fixed webservice bug where authentication would fail on a valid password
*Fixed webservice bug where attach may never happen, and would require a close()/open()

===2.1.8.20111121===
*Added support for new servo types to all libraries
*Fixed min/max position/velocity causing invalid arg exception on servo/advservo
*IPv6 support on MacOS
*Fixed some memory leaks
*Fixed hostname lookup issue on Mac OS with Back To My Mac enabled.
===2.1.8.20111028===
*Fixed Applescript bugs and released examples
*Added openLabel to .NET, Java, COM
*Setting change trigger to 0 on interfacekit will not set event mode.
**Previously setting change trigger to 0 after setting data rate would supersede the data rate setting, which is probably unexpected.
===2.1.8.20110630 - MacOS Only===
*handle USB bug introduced in MacOS 10.6.8
===2.1.8.20110615===
*Added error event when trying to open Phidgets with an unsupported version
===2.1.8.20110614 - Windows Only===
*Fixed bug in C# Spatial example
*Added support for negative gains in 1056
===2.1.8.20110601 - MacOS Only===
*Fixed AppleScript issues
===2.1.8.20110527===
*Fixed AS3.0 library (Flash/Flex) - wouldn't connect to webservice as of last release
*Fixed bug where webservice doesn't release a closed Phidget
*Fixed bug where devices that don't support label didn't show up on MacOS
*Fixed iPhone library issues
===2.1.8.20110524===
*AppleScript support added
*fixed problem with Spatial in .NET on 64-bit Windows
*Added remote setLabel to mac preference pane.
*fixed a bug where label characters 7,8,9 would be read back corrupted on certain devices.
**labels >7 characters that exhibit this bug will now be truncated to 7 characters when being read back
**call setLabel again using this library or newer to support 10 character labels.
**To maintain compatibility with older library versions, limit labels to <=7 characters on these devices.
*fixed bug on MacOS where serial number and/or label strings could be read wrong.
*better support for recovering misbehaving devices in Linux
*fixed a deadlock on linux when Avahi is installed but not running
*clear list of attached devices when closing remote manager
*Added support for Unicode labels
**To maintain compatibility with older library versions, limit labels to ASCII.
*Added open by label
*Webservice protocol version up to 1.0.9 (for open by label)
*Made opening multiple device is one application faster.
*TextLCD changes:
**cursor is disabled while writing to the display or setting a custom character to prevent display artifacts
**cursor is disabled when a full line is written so it doesn't go to the start of another line
**1204 should be stable
**setDisplayCharacter supports 0x00-0xff
*stopped property reflected more accurately in the C# stepper example
*Added error events to mac examples
===2.1.8.20110329 - Windows only===
*Fixed problem with control panel encoder example where enable wouldn't work
*Fixed issue with SpatialData, GPSPositionChange, PHChange and WeightChange events in Labview 64-bit
===2.1.8.20110322===
*Fixed [[Phidget Control Panel]] memory leak when Bonjour in installed but not running
*Fixed current sense formula on 1061_0 v200
*Fixed bug in webservice protocol while using the PhidgetAdvancedServo
*Fixed bug in old PhidgetTemperatureSensor

===2.1.8.20110310===
*Fixed bug in webservice protocol while using the PhidgetServo
*Fixed some Labview bugs
*Added some Java and VB.NET examples
===2.1.8.20110301===
*Full Support for 1002, 1011, 1040, 1046, 1054, 1065, 1204
*New webservice version - 1.0.8
**Support for new devices
**Support for error events
===2.1.7.20110203===
*fixed crash on close of remote Phidget on MacOS
*C# ifkit example bugfix - crashed on 1015/1016
*webservice improvements
*Switch to IP address for SBC config in browser
*Faster IP lookup for SBCs in control panel
===2.1.7.20101222 / 2.1.7.20101223===
*fixed getServerID on Linux
*removed report ack
**this was causing some bad side effects
*manual .local lookups on Windows
**much faster then letting Windows do it itself
*Support for new Labview library
*Fixed PhidgetIR bug where library would crash if repeat code is longer then IR_MAX_REPEAT_LENGTH
===2.1.7.20101103===
*Decreased Phidget Webservice event latency on Windows
*Preliminary support for 1002, 1011, 1040, 1045, 1046, 1054, 1065, 1204 (C, .NET)
*Webservice version updated to 1.0.7
**support for 1045, 1011, 1204
*Fixed a bug where webservice connections could be unexpectedly lost
*Bugfix: couldn't set interfacekit data rate over webservice.
*Fixed some memory leaks in the Mac library
*Fixed bug where blocking for >2 seconds in an events handler when opening remotely could cause a crash.
===2.1.7.20100803===
*Windows only release
*fixed setLabel in WindowsCE
*fixed getHashCode in .NET library - needed for working with Phidgets in Labview via .NET
===2.1.7.20100621===
*Linux only release - autotools updates
**call ldconfig automatically
**remove old phidget21 library (pre-autotools) when installing new one.
===2.1.7.20100620===
*Linux only release - added version.sh for autoreconf
===2.1.7.20100618===
*Linux only release - added udev/hotplug files
===2.1.7.20100617===
*Linux only release
*Transitioned to autotools in linux for phidget21 / webservice
*phidget21 library and webservice are now separate downloads
===2.1.7.20100525===
*full support for PhidgetSpatial and PhidgetIR in all libraries
*fixed 1031 not attaching in AS3.0
*Better error messages in JNI
*Updated error codes, device ID/Class lists in Java, Flash, COM, etc.
*Fixed TemperatureSensor version 200,201,202 bug - ambient sensor would not report negative temperatures.
*Revised temperaturesensor API to report tempMin/tempMax and errors more accurately.
*Added initial events for encoder digital inputs
*full support for 1047
*Added new device support to WindowsCE
*Updated mac examples for 1047, 1048
===2.1.6.20100504===
*Windows only Release
**Added 1131 and 1132 to InterfaceKit example in MSI
===2.1.6.20100428===
*limit data rate maximum to 16ms over the webservice for devices that expose dataRate (InterfaceKit, Spatial)
*fixed bug where TextLCD 8/8/8 would stay in Bonjour list after webservice is shutdown
*set/get Brightness for 1203_2
*Support 1048 in C# example
*webservice version incremented to 1.0.6
**TextLCD set/get brightness
**PhidgetIR support
**PhidgetSpatial support
**1047 support (enable, index)
===2.1.6.20100406===
*Support for 1018_2 (dataRate)
*Webservice version incremented to 1.0.5
===2.1.6.20100401===
*Updated InterfaceKit example with new sensors
*make Windows connect cancelable
*make pending zeroconf lookups cancelable during close
===2.1.6.20100318===
*Mac only release
**Added WillSleep and Wakeup events to give user control of Phidgets immediately before and after a system sleep (MacOS Only).
===2.1.6.20100317===
*Windows only release
**Some of the examples were being built using an out of date .NET library
===2.1.6.20100310===
*MaxMSP fix - 2.1.6.20100126 introduced a bug for some Phidgets where openremote/open by serial didn't work and MaxMSP would sometimes crash.
**No code changes to any of the other libraries.
===2.1.6.20100304===
*stopped property changes trigger events over webservice so they are noticed.
**more compatible with how local open works
*added 5 new servos
*fixed bug where remote close would not set detached so a subsequent open would not always connect.
*handle UninitializeZeroconf better - shut down thread before closing handles, fixes hang on SBC
*fixed bug on Mac where detaching 2 or more Phidgets at the same time caused a crash
*fixed close blocking because of a pending connect (mac, linux)
*Final support for 1031 in all libraries.
===2.1.6.20100129===
*Implemented initial events in Flash
**Flash behaviour should now be identical to C library local and remote.
*Fix RFID issue where close could cause crash
*increment webservice version to 1.0.4
*fixed RFID remote open
**Flash would never get an attach event if the reader had been previously opened
**Initial tag event would not be fired when a tag was present and the antenna was enabled prior to open
*fixed openRemote failing on Mac
*fixed deadlock in webservice which could be hit by opening/closing a device over and over again.
*fixed bug in stepper, which caused seg fault on SBC on position change events.
===2.1.6.20100126===
*added network open support in Max/MSP
===2.1.6.20100115===
*Increased network performance for Linux/MacOS
*Added five servo types
===2.1.6.20091215===
*Fixed busy loop in Linux openRemote
*JNI Library relocated to /Library/Java/Extensions on MacOS
===2.1.6.20091211===
*Heartbeat now works on Linux as well (had to make sockets non-blocking)
===2.1.6.20091130===
*Added heartbeat to webservice (client side)
**Better detects network failures by using active polling timeouts
*Fixed 0/8/8 over webservice
===2.1.6.20091020===
*Fixed 1052 counting issue on 1070 (-1 reported as 255)
*Fixed issue where Phidget21 would try to reinstall from a limited user account or when the Control Panel was disabled.
*64-bit kernel support in Snow Leopard
===2.1.6.20090928===
*Support for PhidgetSBC (1070)
*zeroconf can handle starting up before the mdns daemon, and will keep trying to connect.
*fixed 1066 not showing up on Mac
*added advanced servo example to mac pref pane
*implemented proper error handling in COM
**default behavious remains the same, enable proper error handling with 'EnableVerboseErrors'
*implemented error events in Java
===2.1.6.20090917===
*Updated webservice protocol version to 1.0.3
*Fixed stepper under AS3.0
*added setServoType, getServoType, setServoParameters to PhidgetServo and PhidgetAdvancedServo
*possible race condition fixed in webservice (pdictclient.c:907)
===2.1.6.20090902 (mac only release)===
*Support MacOSX 10.6, drop support for 10.3.9, require 10.4 or newer
**Fully 64-bit compliant, library supports ppc, i386, x86_64
===2.1.6.20090806===
*Added 1049 support
*Fixed RFID tag events over webservice
===2.1.6.20090804===
*Added 1051_2 support
*Fixed various small initialization issues - stepper, adv servo, rfid
*Added 32-bit library install to 64-bit installer
**VB6.0, etc. need the 32-bit COM library on 64-bit windows
===2.1.6.20090717===
*?
===2.1.6.20090708===
*Added DeviceID to zeroconf
*fixed RFID.LastTag in .NET
*Changed the error codes returned by error events; error events now have their own set of error codes rather then sharing the function return codes.
*Added support for 1047, 1048
*Added error event codes rather then trying to reuse the EPHIDGET return codes.
*fixed TextLCD issue where display could get corrupted during a detach/attach
*made mac more reliable on attach
*more error logging on mac
===2.1.6.20090525===
*fixed RFID not attaching via webservice if a tag is present.
*bugfix related to double free on detach event.
*Implemented getKey
*Added MIPS II support to Windows CE
===2.1.6.20090430===
*Added ActiveX interface to COM library
*Added stepper and advancedServo to Flex .swc library
===2.1.6.20090417===
*added PhidgetIR prototype support to C library
*properly handles sleeping on OSX
*fixed some webservice field initializations in Flash and C
*fixed security exceptions in [[Phidget Control Panel]] under Vista
*added [[Phidget Control Panel]] to start menu

===2.1.6.20090318 (Examples/AS3.0 only release)===
*Fixed AdvancedServo in Flash - wouldn't attach
===2.1.6.20090317===
*[[Phidget Control Panel]] properly supports Vista UAC and Limited user accounts in XP, etc.
*Added 64-bit release of Phidget21.msi for Windows

===2.1.6.20090312===
*added 1064, 1059 to WindowsCE
*fixed opening 1051 over webservice
*fixed opening 1015/1016 over webservice broken in last release
===2.1.6.20090302===
*Advanced servo bugfix: stopped would stop being true if min/max was set to exclude current position.
*linux USB improvements when many Phidgets are attached and opened at once.
*1031 support in phidget21, webservice, .NET - hidden until product release
**CPhidgetLED_setVoltage
**CPhidgetLED_getVoltage
**CPhidgetLED_setCurrentLimit
**CPhidgetLED_getCurrentLimit
*unknown timechange == PUNK_INT in encoder position change event
**1st position change event
**> 30 seconds time change
*AS3 updates
**updated to 1.0.2 webservice
**encoder position change events report relative change rather then absolute position
**encoder adds getTimeChange function for timing encoder changes
*webservice updated to 1.0.2
**Authorization is asynchronous
**Doesn't match the old version checking, so errors will not be nice when trying to connect to an old webservice
**Sends out all initial data, so it's just like opening locally
**supports interfacekit Raw sensor value
**supports labels on remoteIP managers
*avahi bugfix
*webservice more stable against forcefully closed clients
*closing a network Phidget won't block - ever.
**no longer using quit, just closing the socket
*added libavahi-client.so.3 reference to linux library.
*Fixed bug with opening one phidget with serial and no serial at the same time over the webservice
===2.1.5.20090105===
*[[Phidget Control Panel]] stability improvements
*added CPhidgetSBC_getHostname
*advanced servo 1 motor current sense equation - support should now be complete
*webservice and network code bugfixes - crash / deadlock during close, problems with concurrent connections, etc.
*fixed close on remote and remoteIP managers
*name of RFID changed from "Phidget RFID 4-output" to "Phidget RFID 2-output" - updated anything referencing old name.

===2.1.5.20081023===
*added advanced servo and stepper examples to VB6.0, VB.NET and C
*added deviceClass and deviceID
*updated Mac examples
*webservice protocol version enforcement
*internal fix/rework of device id's etc.
*Fixed memory leaks in webservice and phidget21 network code.
*Dictionary and network stability improvements.
*duplicate calls to open or close are now silently ignored.
===2.1.4.20080924===
*Old TextLCD 0/8/8's can now have both halves open at the same time on Windows
*fixed bug with composite devices on linux
*fixed manager on linux to better deal with unique devices
===2.1.4.20080922===
*Updated Delphi files
*TextLCD can display 0x80-0xFF characters from Java
*getAttachedDevices works for mdns managers
*fixed a deadlock in the webservice
*better network error handling / password support for windows C# examples
*waitForAttachment will return EPHIDGET_CLOSED if the handle is closed while it is waiting.
*added EPHIDGET_CLOSED
*joining central threads checks whether they are trying to be joined by themselves first (avoid deadlocks).
*changed context of error event to be free from locks (can call close, open, etc. from them).
===2.1.4.20080821===
*zeroconf threads exit cleanly on last _close (apple zeroconf)
*Added advanced servo and stepper to Max
===2.1.4.20080811 (mac only release)===
*Fixed manager on Mac (wasn't working at all since 2.1.4.20080808)
===2.1.4.20080808===
*added CPhidgetSBC and CPhidgetSBCManager to the c library - these interfaces are hidden from users and meant to be used internally (for now).
*CPhidgetManager_open no longer blocks to send out initial attach events. These initial events are sent from the CentralThread context like all other attach events.
*fixed CThread_wait_on_event on Linux
*added CPhidgetGeneric interface for prototyping to C, .NET libraries. product ID is 0x99. These are only visible in debug releases, only to be used internally.
===2.1.4.20080715===
*udev rules fixed for product IDs with alpha-hex values
*blocking in an attach event does not block calls to open anymore
*RFID tag event handlers can now handle blocking - tag lost is timed after the tag handler exits.
===2.1.4.20080623===
*Flex .swc library was out of sync
*fixed CPhidgetManager_getAttachedDevices for network managers
*Added CPhidgetManager_freeAttachedDevicesArray
===2.1.4.20080613===
*Max/MSP RFID fixed
*0/0/8 and advanced servo added to CE
*fixed flash policy file server in webservice
*webservice with password and asynchronous together work now
===2.1.4.20080602===
*phidget21.h -> phidget21int.h so as not to be confused with generated phidget21.h
*some changes to Makefile fro crosscompiling
*no more vbscript in msi
===2.1.4.20080513===
*removed long long from COM - not supported by VB6.0
*added LastTag to RFID in .NET
===2.1.4.20080428===
*support Mac OS X 10.3.9 again
*Rev up to 2.1.4
*finalize Phidget Stepper API - Phidget Stepper requires 2.1.4 as a minimum
*fixed serverConnect and serverDisconnect handlers for manager and dictionary in COM
*Changed:
**PhidgetStepper and PhidgetAdvancedServo
***MotorPosition -> Position
***MotorOn -> Engaged
***MotorStopped -> Stopped
*Added:
**CPhidgetStepper_getCurrentLimit
**CPhidgetEncoder_getPosition
**CPhidgetEncoder_setPosition
**CPhidgetMotorControl_getVelocity
**CPhidgetMotorControl_setVelocity
**CPhidgetMotorControl_set_OnVelocityChange_Handler
**CPhidgetServo_setEngaged
**CPhidgetServo_getEngaged
**CPhidgetServo_getPosition
**CPhidgetServo_setPosition
**CPhidgetServo_set_OnPositionChange_Handler
**CPhidgetServo_getPositionMax
**CPhidgetServo_getPositionMin
**Count functions
*Deprecated:
**CPhidgetEncoder_getEncoderPosition
**CPhidgetEncoder_setEncoderPosition
**CPhidgetMotorControl_getMotorSpeed
**CPhidgetMotorControl_setMotorSpeed
**CPhidgetMotorControl_set_OnMotorChange_Handler
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
**CPhidgetServo_getMotorPosition
**CPhidgetServo_setMotorPosition
**CPhidgetServo_set_OnMotorPositionChange_Handler
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**Num functions
*Added ability to deprecate funcitons in the C library - compiler will issue a warning when they are used.
*added names to some arguments in phidget21.h
*fixes to the webservice for initial state stuff - now it behaves almost like non-webservice, with guaranteed initial events, but we don't guarantee initial state in the attach event yet. Min/Max, Num motors, inputs, etc. are all guaranteed in the attach handler.
*Finalized support for Phidget Stepper
===2.1.3.20080402===
*Fixed windows BUG - Device Type was showing up wrong
*CPhidgetStepper_getPosition -> CPhidgetStepper_getCurrentPosition
===2.1.3.20080327===
*added:
**CPhidgetAdvancedServo_setMotorPositionMax
**CPhidgetAdvancedServo_setMotorPositionMin
**CPhidgetAdvancedServo_getMotorStopped
*changes to API
**CPhidgetStepper_setMotorPosition -> CPhidgetStepper_setTargetMotorPosition
**added CPhidgetStepper_getTargetMotorPosition
**Stepper MotorSpeed -> Velocity
**Stepper and AdvancedServo MaxVelocity -> VelocityLimit
*add waitForAttachment to COM
*COM getbool (not indexed) will now return FALSE on false (rather then always returning true)
*fixed write thread timeouts - was setting attached after starting write thread so write thread would see a detached device and exit immediately
===2.1.3.20080206===
*changed long long to __int64, to be happy in borland C++
*added:
**CPhidgetStepper_getMaxMotorSpeed
**CPhidgetStepper_setMotorOn
**CPhidgetStepper_getMotorOn
**CPhidgetStepper_getMotorStopped
**CPhidgetStepper_setCurrentMotorPosition
*removed CPhidgetStepper_setVelocity
*added CPhidgetStepper_setMaxVelocity, CPhidgetStepper_getMaxVelocity
===2.1.3.20080114===
*Added new functions to Flash API
*Added new functions to Webservice Protocol
*Added new functions to COM Library
*Added new functions to Java Library
*All device fiels in C library cleaned up and made consistent
*Open in windows is exclusive - this needs to be tested for stability
*No data will be returned / accepted if it lies outside of max/min range
*if a data value is unknown, user variable is set to PUNK_INT, PUNK_DBL, or PUNK_BOOL, and return value is EPHIDGET_UNKNOWNVAL
*Proper Device initializations on Attach:
**triggers are set to defaults on attach
**device state is read in and preserved on attach
**during attach event, all sensor data, etc. is provided if available
**no data events until after the attach event returns
**everything initialized by the time waitForAttachment returns
**after attach event returns, a full set of initial state data events are thrown
*.NET collections are readonly, and never NULL (but empty when phidget detached)
*.NET callbacks no longer catch and hide all exceptions
**make sure to use try/catch blocks especially in Attach when accessing properties that may not be initialized.
*added min/max functions:
**CPhidgetAccelerometer_getAccelerationMax
**CPhidgetAccelerometer_getAccelerationMin
**CPhidgetAdvancedServo_getAccelerationMax
**CPhidgetAdvancedServo_getAccelerationMin
**CPhidgetAdvancedServo_getVelocityMax
**CPhidgetAdvancedServo_getVelocityMin
**CPhidgetAdvancedServo_getMotorPositionMax
**CPhidgetAdvancedServo_getMotorPositionMin
**CPhidgetMotorControl_getAccelerationMax
**CPhidgetMotorControl_getAccelerationMin
**CPhidgetPHSensor_getPHMax
**CPhidgetPHSensor_getPHMin
**CPhidgetPHSensor_getPotentialMax
**CPhidgetPHSensor_getPotentialMin
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**CPhidgetStepper_getAccelerationMax
**CPhidgetStepper_getAccelerationMin
**CPhidgetStepper_getMotorSpeedMax
**CPhidgetStepper_getMotorSpeedMin
**CPhidgetStepper_getMotorPositionMax
**CPhidgetStepper_getMotorPositionMin
**CPhidgetTemperatureSensor_getPotentialMax
**CPhidgetTemperatureSensor_getPotentialMin
**CPhidgetTemperatureSensor_getAmbientTemperatureMax
**CPhidgetTemperatureSensor_getAmbientTemperatureMin
**CPhidgetTemperatureSensor_getTemperatureMax
**CPhidgetTemperatureSensor_getTemperatureMin
*Added functions:
**CPhidgetTemperatureSensor_getAmbientTemperature
**CPhidgetTemperatureSensor_getThermocoupleType
**CPhidgetTemperatureSensor_setThermocoupleType
**CPhidget_set_OnServerConnectHandler
**CPhidget_set_OnServerDisconnectHandler
**CPhidgetDictionary_set_OnServerConnectHandler
**CPhidgetDictionary_set_OnServerDisconnectHandler
**CPhidgetManager_set_OnServerConnectHandler
**CPhidgetManager_set_OnServerDisconnectHandler
**CPhidgetDictionary_getServerID
**CPhidgetDictionary_getServerAddress
**CPhidgetDictionary_getServerStatus
**CPhidgetManager_getServerID
**CPhidgetManager_getServerAddress
**CPhidgetManager_getServerStatus
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
*Removed functions:
**CPhidgetServo_setMotorOff
*TemperatureSensor:
**Ambient sensor is accessed with it's own function
**first thermocouple is Index 0 everywhere
**no ambient sensor events
*getServerID is implemented
*changed the internal network structure (added CPhidgetRemote)
*reworked the USB code (mostly on Windows)
**Better handles closing, ESD events, timeouts
**fixed issues with Encoder, RFID stopping reading after a certain time.
**added USB error flag
*openRemote functions have been implemented
**these require bonjour (mac / windows) or avahi (linux) to be installed on both the client and server
**if they are not, you get EPHIDGET_UNSUPPORTED when you call them
*openRemoteIP functions are asynchronous and persistent
*include cphidgetconstants.h in phidget21.h for users
===2.1.2.20071108===
*start of chagelog

Driver Changelog

2019-10-07T18:09:44Z

Patrick:

[[Category:Administrative]]
__NOTOC__

===2.1.9.20191007===
*macOS release
**Fix kernel driver for macos 10.9 and 10.10

===2.1.9.20191001===
*macOS / Windows release
**Support for macos 10.15 Catalina
**Update firmware files

===2.1.9.20190409===
*Fix GPS Date after April 6 2019 week rollover event

===2.1.9.20190208===
*macOS release
**Fixed USB bug where devices plugged in before boot were inaccessible until unplugged/re-plugged on 2018 Mac Mini.

===2.1.9.20180622===
*Python fix

===2.1.9.20180215===
*Move to .NET 4.0

===2.1.8.20171215===
*macOS release
**Fixed USB bug where opening two of the same device with -1 serial could cause missed attach/detach events and other errors.

===2.1.8.20160921===
*macOS release
**Fixed USB bug where devices plugged in before boot were inaccessible until unplugged/re-plugged, under OS X 10.11.

===2.1.8.20160202===
*Windows release
**Labview 7.1 support

===2.1.8.20160107===
*Windows release
**Don't throw an exception on EncoderPositionChangeEventArgs.Time in the .Net library when time it unknown - just return 0x7fffffff

===2.1.8.20160104===
*Mac/Windows release
**New firmware for 1042 and 1044, fixing digital gyro
===2.1.8.20151217===
*Fixed 1045 bug where it will display an unknown ambient temperature sometimes
*Fixed a crash in the windows control panel

===2.1.8.20151020===
*Windows release
**Fixed an issue where the examples would error when trying to run them from the control panel.

===2.1.8.20151009===
*OS X and Windows release
**Upgraded firmware for 1024, 1032, 1041, 1042, 1043, 1044 and 1067 to address issues with these Phidgets on OS X El Capitan
*SBC release
**Support for multiple webcams
===2.1.8.20150821===
*OS X-only release
**Support OS X 10.11 El Capitan
===2.1.8.20150805===
*OS X-only release
**Preliminary support for OS X 10.11 El Capitan
===2.1.8.20150410===
*Linux-only release
**Fixed Makefile phidget21.h target issues
===2.1.8.20150326===
*Windows-only release
**Fixed issue with webservice buttons not being visible in the control panel
===2.1.8.20150323===
*Windows-only release
**Updated icons with new company logo
===2.1.8.20150227===
*Linux-only release
**Added copyright/licence headers to source code files
**Updated cvtutf files to a newer version
===2.1.8.20150109===
*Windows-only
**Fixed examples for Labview 8.5
===2.1.8.20141209===
*OS X-only release
**Added support for armv7s and arm64 to the iOS library. Dropped support for armv6. Requires iOS 5.1.1 or later.
===2.1.8.20141202===
*Windows-only release
**Labview release to support older versions
===2.1.8.20141119===
*OS X-only release
**Fixed an issue with the 2.1.8.20141117 release where nothing was actually installed.
===2.1.8.20141117===
*OS X-only release
**Fixed a code-signing issue that make the installer appear unsigned on OS X 10.10
**Dropped support for OS X 10.4
===2.1.8.20140905===
*Windows-only release
**Added an IA32 folder to the windows libraries download - this supports Windows on the Intel Galileo platform
===2.1.8.20140428===
*Windows-only release
**Fixes to C# Stepper GUI Example
===2.1.8.20140319===
*CPhidget_getDeviceClass can now be called on handle before it is attached.
*Added support for 64-bit Max/MSP (Version 6.1+) on both OS X and Windows.
===2.1.8.20140227===
*Deals with 1046 bug in v100 and v101 firmware.
**No longer reports bad values that appear right after a channel is enabled.
**Fixes issue where changing the gain while channel 0 is disabled would sometimes cause bad readings.

===2.1.8.20131105===
* Fixed a defect in the Flash examples for the 1012 (Outputs 11-16 were not addressed properly).

===2.1.8.20130926===
*Windows-only release
**Support setting label on 1067 from Windows
===2.1.8.20130820===
*Windows-only release
**Added logging option to control panel / C# full examples
===2.1.8.20130802===
*Windows-only release
**Fix for Windows 8 issue where only 'Uninitialized Phidget Handle' would show up in the Manager, and Phidgets could not be opened.
===2.1.8.20130723===
*Improvement to java: we don't attach/detach our native threads for each event, just one attach, then detach before the thread exits.
**This increases performance, esp. when debugging on Android.
*Improvement to Android: We reuse the UsbRequest object rather then creating a new one for each transfer. This reduces logcat messages tremendously, and increases performance.
===2.1.8.20130710===
*Android-only release
**Added extra android target architectures: x86, MIPS, armeabi-v7a
===2.1.8.20130618===
*Changed setCompassCorrectionParameters() API call so that compass calibration parameters are written out to non-volatile storage on 1042/1044, so that they persist across power cycles. Previously, calibration data would need to be re-programmed at each attach.
*Changes to C# Spatial example:
**Compass calibration parameter set dialog removed from for 1042/1044 because parameters are set by the calibration software - and thus do not need setting in the example.
**Stores/restores parameters for 1056 based on serial number, so multiple different calibrations can be maintained.
===2.1.8.20130607===
*Windows-only release
**Fixes to compass calibration software for 1042/1044
===2.1.8.20130419===
*Windows-only release
**Fixed setCompassCorrectionParameters in the COM library
===2.1.8.20130327===
*Windows-only release
**Changed Windows installer to stop virus-scanner false positives
**Dropped support for Windows 2000
===2.1.8.20130320===
*Added EPHIDGET_NOTFOUND exception to Dictionary.getKey() for when the key is not found.
*Added exceptions back into the Java library - they have been missing since 2.1.8.20121015 release.
===2.1.8.20130313===
*Updates to Matlab support
**Works properly on Matlab 7+, on Windows, Mac, Linux without needing changes to .m files.
===2.1.8.20130221===
*Windows-only release
**Encoder Index event added to C and .NET libraries
===2.1.8.20121218===
*Webservice version: 1.0.10
**Support for 1024, 1032
*Support for 1024, 1032
*fixed bug where if one half of a composite device is open, and PHIDGET_USB_ERROR_FLAG gets set, the device may never re-attach.
===2.1.8.20121015===
*Windows-only release
**Support for new pressure/light sensors in example.
===2.1.8.20120914===
*Windows-only release
**Improved firmware upgrading in control panel - it was giving some false-errors on some machines.
===2.1.8.20120912===
*Fixed bug where 1065 could fail to attach when opened over webservice
*Fixed bug where close() could deadlock on Phidgets opened over the webservice
*Changed LED64 LED Brightness from int to double
**this may cause issues when controlling the LED64 over the webservice and library/webservice are not the same version
**the old setDiscreteLED call will remain, deprecated, with an int argument for compatibility.
===2.1.8.20120716===
*Linux-Only Release
**Fixed a bug where opening a device in two program at once would cause an attach-detach cycle as they fight each other for control.
===2.1.8.20120713===
*Mac-Only Release
**Added signing of the Mac installer, so Mountain Lion (OS X 10.8) doesn't refuse to run it.
===2.1.8.20120615===
*Windows-only release
**Fixed a bug that caused java to crash on events introduced in 2.1.8.20120612
===2.1.8.20120612===
*Windows-only release
**Fixed another bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120606===
*Windows-only release
**Fixed a bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120525===
*Windows-only release
**Fixed PhidgetIR sendRawData bug in .NET on 64-bit machines.
===2.1.8.20120514===
*Linux-only release
**Fixed a bug that causes a segfault with libusb-1.0 under 64-bit Linux.
===2.1.8.20120507===
*Mac/Linux-only release
**Fixes a setLabel bug introduced in 2.1.8.20120503
===2.1.8.20120503===
*Fixed some spelling mistakes
*Moved to libusb-1.0
**This resolves a bug where having a webcam plugged in caused a memory leak in the webservice.
*Fixed bug with advanced servo where setting acceleration to accelerationMax would cause an exception for some servo types
===2.1.8.20120216===
*Fixed bug with RFID Reader on OS X and Linux, as well as .NET over the webservice
*Fixed bug that could cause the Java Phidget Manager to crash during garbage collection.
===2.1.8.20120131===
*Fixed RFID Reader bug that caused tag event to not get thrown in .NET Applications
*Changed compass bearing calculations in spatial C# example
===2.1.8.20120123===
*Added support for 1061 v300+
*Fixed a bug where the firmware version could be mis-reported over Bonjour
===2.1.8.20111220===
*Fixed a bug in AppleScript where closing a Phidget opened via label would give a 'Connection Invalid' error.
*Fixed a bug where the webservice may fail to start on Linux systems that don't support IPv6 (ie. SBC2).
*Fixed issue where ratiometric state on newest interfacekit wouldn't be read back properly if it was false during attach.
*Fixed webservice issue where ratiometric state would not be reported properly for newest interfacekits
*Increased the number of overrun errors ignored during initial attach for InterfaceKit.
*Fixed an issue with the iPhone library and header
===2.1.8.20111219===
*fixed various other webservice stability/performance/memory leak bugs
*Faster connection to SBC-connected Phidgets from Mac OS
*Don't report packetlost or overrun errors that happen during early initialization - these are just noise.
*Fixed a bug in the webservice tree removal function that could cause memory leaks.
*Fixed bug where Webservice would crash on Linux if the chosen serverID was already under use on the network
*Stopped sending hardware Error Events before the Attach event - they are now queued up and sent after Attach
*Fixed a crash in the [[Phidget Control Panel]]
*Added ability to remove dictionary keys from a key change listener
*Reduced the number of false 'pending command not finished' error events on Close()
*Fixed a webservice bug where exceptions/false attach events could occur when close() is called soon after open
*Fixed bug where closing a PhidgetRFID soon after attach could cause a crash
*Fixed webservice but on MacOS where client could exit with SIG_PIPE error
*Fixed webservice bug where the server would sometimes exit(1) after many connect/disconnect cycles
*Fixed webservice bug where client could deadlock during close()
*Fixed webservice bug where opening a single remote phidget multiple times from the same application would fail
*Fixed a webservice bug where sockets weren't being closed properly sometimes
*Fixed a webservice bug where pre-attach error events wouldn't get through
*Fixed a bug where the webservice running on Linux would stop responding to clients after ~300 connect/disconnect cycles
*Fixed bug where a Phidget would become inaccessible until the app is restarted if a thread creation failed
*Fixed webservice bug where connect is slow on Windows when multiple clients are running simultaneously
*Fixed webservice bug where authentication would fail on a valid password
*Fixed webservice bug where attach may never happen, and would require a close()/open()

===2.1.8.20111121===
*Added support for new servo types to all libraries
*Fixed min/max position/velocity causing invalid arg exception on servo/advservo
*IPv6 support on MacOS
*Fixed some memory leaks
*Fixed hostname lookup issue on Mac OS with Back To My Mac enabled.
===2.1.8.20111028===
*Fixed Applescript bugs and released examples
*Added openLabel to .NET, Java, COM
*Setting change trigger to 0 on interfacekit will not set event mode.
**Previously setting change trigger to 0 after setting data rate would supersede the data rate setting, which is probably unexpected.
===2.1.8.20110630 - MacOS Only===
*handle USB bug introduced in MacOS 10.6.8
===2.1.8.20110615===
*Added error event when trying to open Phidgets with an unsupported version
===2.1.8.20110614 - Windows Only===
*Fixed bug in C# Spatial example
*Added support for negative gains in 1056
===2.1.8.20110601 - MacOS Only===
*Fixed AppleScript issues
===2.1.8.20110527===
*Fixed AS3.0 library (Flash/Flex) - wouldn't connect to webservice as of last release
*Fixed bug where webservice doesn't release a closed Phidget
*Fixed bug where devices that don't support label didn't show up on MacOS
*Fixed iPhone library issues
===2.1.8.20110524===
*AppleScript support added
*fixed problem with Spatial in .NET on 64-bit Windows
*Added remote setLabel to mac preference pane.
*fixed a bug where label characters 7,8,9 would be read back corrupted on certain devices.
**labels >7 characters that exhibit this bug will now be truncated to 7 characters when being read back
**call setLabel again using this library or newer to support 10 character labels.
**To maintain compatibility with older library versions, limit labels to <=7 characters on these devices.
*fixed bug on MacOS where serial number and/or label strings could be read wrong.
*better support for recovering misbehaving devices in Linux
*fixed a deadlock on linux when Avahi is installed but not running
*clear list of attached devices when closing remote manager
*Added support for Unicode labels
**To maintain compatibility with older library versions, limit labels to ASCII.
*Added open by label
*Webservice protocol version up to 1.0.9 (for open by label)
*Made opening multiple device is one application faster.
*TextLCD changes:
**cursor is disabled while writing to the display or setting a custom character to prevent display artifacts
**cursor is disabled when a full line is written so it doesn't go to the start of another line
**1204 should be stable
**setDisplayCharacter supports 0x00-0xff
*stopped property reflected more accurately in the C# stepper example
*Added error events to mac examples
===2.1.8.20110329 - Windows only===
*Fixed problem with control panel encoder example where enable wouldn't work
*Fixed issue with SpatialData, GPSPositionChange, PHChange and WeightChange events in Labview 64-bit
===2.1.8.20110322===
*Fixed [[Phidget Control Panel]] memory leak when Bonjour in installed but not running
*Fixed current sense formula on 1061_0 v200
*Fixed bug in webservice protocol while using the PhidgetAdvancedServo
*Fixed bug in old PhidgetTemperatureSensor

===2.1.8.20110310===
*Fixed bug in webservice protocol while using the PhidgetServo
*Fixed some Labview bugs
*Added some Java and VB.NET examples
===2.1.8.20110301===
*Full Support for 1002, 1011, 1040, 1046, 1054, 1065, 1204
*New webservice version - 1.0.8
**Support for new devices
**Support for error events
===2.1.7.20110203===
*fixed crash on close of remote Phidget on MacOS
*C# ifkit example bugfix - crashed on 1015/1016
*webservice improvements
*Switch to IP address for SBC config in browser
*Faster IP lookup for SBCs in control panel
===2.1.7.20101222 / 2.1.7.20101223===
*fixed getServerID on Linux
*removed report ack
**this was causing some bad side effects
*manual .local lookups on Windows
**much faster then letting Windows do it itself
*Support for new Labview library
*Fixed PhidgetIR bug where library would crash if repeat code is longer then IR_MAX_REPEAT_LENGTH
===2.1.7.20101103===
*Decreased Phidget Webservice event latency on Windows
*Preliminary support for 1002, 1011, 1040, 1045, 1046, 1054, 1065, 1204 (C, .NET)
*Webservice version updated to 1.0.7
**support for 1045, 1011, 1204
*Fixed a bug where webservice connections could be unexpectedly lost
*Bugfix: couldn't set interfacekit data rate over webservice.
*Fixed some memory leaks in the Mac library
*Fixed bug where blocking for >2 seconds in an events handler when opening remotely could cause a crash.
===2.1.7.20100803===
*Windows only release
*fixed setLabel in WindowsCE
*fixed getHashCode in .NET library - needed for working with Phidgets in Labview via .NET
===2.1.7.20100621===
*Linux only release - autotools updates
**call ldconfig automatically
**remove old phidget21 library (pre-autotools) when installing new one.
===2.1.7.20100620===
*Linux only release - added version.sh for autoreconf
===2.1.7.20100618===
*Linux only release - added udev/hotplug files
===2.1.7.20100617===
*Linux only release
*Transitioned to autotools in linux for phidget21 / webservice
*phidget21 library and webservice are now separate downloads
===2.1.7.20100525===
*full support for PhidgetSpatial and PhidgetIR in all libraries
*fixed 1031 not attaching in AS3.0
*Better error messages in JNI
*Updated error codes, device ID/Class lists in Java, Flash, COM, etc.
*Fixed TemperatureSensor version 200,201,202 bug - ambient sensor would not report negative temperatures.
*Revised temperaturesensor API to report tempMin/tempMax and errors more accurately.
*Added initial events for encoder digital inputs
*full support for 1047
*Added new device support to WindowsCE
*Updated mac examples for 1047, 1048
===2.1.6.20100504===
*Windows only Release
**Added 1131 and 1132 to InterfaceKit example in MSI
===2.1.6.20100428===
*limit data rate maximum to 16ms over the webservice for devices that expose dataRate (InterfaceKit, Spatial)
*fixed bug where TextLCD 8/8/8 would stay in Bonjour list after webservice is shutdown
*set/get Brightness for 1203_2
*Support 1048 in C# example
*webservice version incremented to 1.0.6
**TextLCD set/get brightness
**PhidgetIR support
**PhidgetSpatial support
**1047 support (enable, index)
===2.1.6.20100406===
*Support for 1018_2 (dataRate)
*Webservice version incremented to 1.0.5
===2.1.6.20100401===
*Updated InterfaceKit example with new sensors
*make Windows connect cancelable
*make pending zeroconf lookups cancelable during close
===2.1.6.20100318===
*Mac only release
**Added WillSleep and Wakeup events to give user control of Phidgets immediately before and after a system sleep (MacOS Only).
===2.1.6.20100317===
*Windows only release
**Some of the examples were being built using an out of date .NET library
===2.1.6.20100310===
*MaxMSP fix - 2.1.6.20100126 introduced a bug for some Phidgets where openremote/open by serial didn't work and MaxMSP would sometimes crash.
**No code changes to any of the other libraries.
===2.1.6.20100304===
*stopped property changes trigger events over webservice so they are noticed.
**more compatible with how local open works
*added 5 new servos
*fixed bug where remote close would not set detached so a subsequent open would not always connect.
*handle UninitializeZeroconf better - shut down thread before closing handles, fixes hang on SBC
*fixed bug on Mac where detaching 2 or more Phidgets at the same time caused a crash
*fixed close blocking because of a pending connect (mac, linux)
*Final support for 1031 in all libraries.
===2.1.6.20100129===
*Implemented initial events in Flash
**Flash behaviour should now be identical to C library local and remote.
*Fix RFID issue where close could cause crash
*increment webservice version to 1.0.4
*fixed RFID remote open
**Flash would never get an attach event if the reader had been previously opened
**Initial tag event would not be fired when a tag was present and the antenna was enabled prior to open
*fixed openRemote failing on Mac
*fixed deadlock in webservice which could be hit by opening/closing a device over and over again.
*fixed bug in stepper, which caused seg fault on SBC on position change events.
===2.1.6.20100126===
*added network open support in Max/MSP
===2.1.6.20100115===
*Increased network performance for Linux/MacOS
*Added five servo types
===2.1.6.20091215===
*Fixed busy loop in Linux openRemote
*JNI Library relocated to /Library/Java/Extensions on MacOS
===2.1.6.20091211===
*Heartbeat now works on Linux as well (had to make sockets non-blocking)
===2.1.6.20091130===
*Added heartbeat to webservice (client side)
**Better detects network failures by using active polling timeouts
*Fixed 0/8/8 over webservice
===2.1.6.20091020===
*Fixed 1052 counting issue on 1070 (-1 reported as 255)
*Fixed issue where Phidget21 would try to reinstall from a limited user account or when the Control Panel was disabled.
*64-bit kernel support in Snow Leopard
===2.1.6.20090928===
*Support for PhidgetSBC (1070)
*zeroconf can handle starting up before the mdns daemon, and will keep trying to connect.
*fixed 1066 not showing up on Mac
*added advanced servo example to mac pref pane
*implemented proper error handling in COM
**default behavious remains the same, enable proper error handling with 'EnableVerboseErrors'
*implemented error events in Java
===2.1.6.20090917===
*Updated webservice protocol version to 1.0.3
*Fixed stepper under AS3.0
*added setServoType, getServoType, setServoParameters to PhidgetServo and PhidgetAdvancedServo
*possible race condition fixed in webservice (pdictclient.c:907)
===2.1.6.20090902 (mac only release)===
*Support MacOSX 10.6, drop support for 10.3.9, require 10.4 or newer
**Fully 64-bit compliant, library supports ppc, i386, x86_64
===2.1.6.20090806===
*Added 1049 support
*Fixed RFID tag events over webservice
===2.1.6.20090804===
*Added 1051_2 support
*Fixed various small initialization issues - stepper, adv servo, rfid
*Added 32-bit library install to 64-bit installer
**VB6.0, etc. need the 32-bit COM library on 64-bit windows
===2.1.6.20090717===
*?
===2.1.6.20090708===
*Added DeviceID to zeroconf
*fixed RFID.LastTag in .NET
*Changed the error codes returned by error events; error events now have their own set of error codes rather then sharing the function return codes.
*Added support for 1047, 1048
*Added error event codes rather then trying to reuse the EPHIDGET return codes.
*fixed TextLCD issue where display could get corrupted during a detach/attach
*made mac more reliable on attach
*more error logging on mac
===2.1.6.20090525===
*fixed RFID not attaching via webservice if a tag is present.
*bugfix related to double free on detach event.
*Implemented getKey
*Added MIPS II support to Windows CE
===2.1.6.20090430===
*Added ActiveX interface to COM library
*Added stepper and advancedServo to Flex .swc library
===2.1.6.20090417===
*added PhidgetIR prototype support to C library
*properly handles sleeping on OSX
*fixed some webservice field initializations in Flash and C
*fixed security exceptions in [[Phidget Control Panel]] under Vista
*added [[Phidget Control Panel]] to start menu

===2.1.6.20090318 (Examples/AS3.0 only release)===
*Fixed AdvancedServo in Flash - wouldn't attach
===2.1.6.20090317===
*[[Phidget Control Panel]] properly supports Vista UAC and Limited user accounts in XP, etc.
*Added 64-bit release of Phidget21.msi for Windows

===2.1.6.20090312===
*added 1064, 1059 to WindowsCE
*fixed opening 1051 over webservice
*fixed opening 1015/1016 over webservice broken in last release
===2.1.6.20090302===
*Advanced servo bugfix: stopped would stop being true if min/max was set to exclude current position.
*linux USB improvements when many Phidgets are attached and opened at once.
*1031 support in phidget21, webservice, .NET - hidden until product release
**CPhidgetLED_setVoltage
**CPhidgetLED_getVoltage
**CPhidgetLED_setCurrentLimit
**CPhidgetLED_getCurrentLimit
*unknown timechange == PUNK_INT in encoder position change event
**1st position change event
**> 30 seconds time change
*AS3 updates
**updated to 1.0.2 webservice
**encoder position change events report relative change rather then absolute position
**encoder adds getTimeChange function for timing encoder changes
*webservice updated to 1.0.2
**Authorization is asynchronous
**Doesn't match the old version checking, so errors will not be nice when trying to connect to an old webservice
**Sends out all initial data, so it's just like opening locally
**supports interfacekit Raw sensor value
**supports labels on remoteIP managers
*avahi bugfix
*webservice more stable against forcefully closed clients
*closing a network Phidget won't block - ever.
**no longer using quit, just closing the socket
*added libavahi-client.so.3 reference to linux library.
*Fixed bug with opening one phidget with serial and no serial at the same time over the webservice
===2.1.5.20090105===
*[[Phidget Control Panel]] stability improvements
*added CPhidgetSBC_getHostname
*advanced servo 1 motor current sense equation - support should now be complete
*webservice and network code bugfixes - crash / deadlock during close, problems with concurrent connections, etc.
*fixed close on remote and remoteIP managers
*name of RFID changed from "Phidget RFID 4-output" to "Phidget RFID 2-output" - updated anything referencing old name.

===2.1.5.20081023===
*added advanced servo and stepper examples to VB6.0, VB.NET and C
*added deviceClass and deviceID
*updated Mac examples
*webservice protocol version enforcement
*internal fix/rework of device id's etc.
*Fixed memory leaks in webservice and phidget21 network code.
*Dictionary and network stability improvements.
*duplicate calls to open or close are now silently ignored.
===2.1.4.20080924===
*Old TextLCD 0/8/8's can now have both halves open at the same time on Windows
*fixed bug with composite devices on linux
*fixed manager on linux to better deal with unique devices
===2.1.4.20080922===
*Updated Delphi files
*TextLCD can display 0x80-0xFF characters from Java
*getAttachedDevices works for mdns managers
*fixed a deadlock in the webservice
*better network error handling / password support for windows C# examples
*waitForAttachment will return EPHIDGET_CLOSED if the handle is closed while it is waiting.
*added EPHIDGET_CLOSED
*joining central threads checks whether they are trying to be joined by themselves first (avoid deadlocks).
*changed context of error event to be free from locks (can call close, open, etc. from them).
===2.1.4.20080821===
*zeroconf threads exit cleanly on last _close (apple zeroconf)
*Added advanced servo and stepper to Max
===2.1.4.20080811 (mac only release)===
*Fixed manager on Mac (wasn't working at all since 2.1.4.20080808)
===2.1.4.20080808===
*added CPhidgetSBC and CPhidgetSBCManager to the c library - these interfaces are hidden from users and meant to be used internally (for now).
*CPhidgetManager_open no longer blocks to send out initial attach events. These initial events are sent from the CentralThread context like all other attach events.
*fixed CThread_wait_on_event on Linux
*added CPhidgetGeneric interface for prototyping to C, .NET libraries. product ID is 0x99. These are only visible in debug releases, only to be used internally.
===2.1.4.20080715===
*udev rules fixed for product IDs with alpha-hex values
*blocking in an attach event does not block calls to open anymore
*RFID tag event handlers can now handle blocking - tag lost is timed after the tag handler exits.
===2.1.4.20080623===
*Flex .swc library was out of sync
*fixed CPhidgetManager_getAttachedDevices for network managers
*Added CPhidgetManager_freeAttachedDevicesArray
===2.1.4.20080613===
*Max/MSP RFID fixed
*0/0/8 and advanced servo added to CE
*fixed flash policy file server in webservice
*webservice with password and asynchronous together work now
===2.1.4.20080602===
*phidget21.h -> phidget21int.h so as not to be confused with generated phidget21.h
*some changes to Makefile fro crosscompiling
*no more vbscript in msi
===2.1.4.20080513===
*removed long long from COM - not supported by VB6.0
*added LastTag to RFID in .NET
===2.1.4.20080428===
*support Mac OS X 10.3.9 again
*Rev up to 2.1.4
*finalize Phidget Stepper API - Phidget Stepper requires 2.1.4 as a minimum
*fixed serverConnect and serverDisconnect handlers for manager and dictionary in COM
*Changed:
**PhidgetStepper and PhidgetAdvancedServo
***MotorPosition -> Position
***MotorOn -> Engaged
***MotorStopped -> Stopped
*Added:
**CPhidgetStepper_getCurrentLimit
**CPhidgetEncoder_getPosition
**CPhidgetEncoder_setPosition
**CPhidgetMotorControl_getVelocity
**CPhidgetMotorControl_setVelocity
**CPhidgetMotorControl_set_OnVelocityChange_Handler
**CPhidgetServo_setEngaged
**CPhidgetServo_getEngaged
**CPhidgetServo_getPosition
**CPhidgetServo_setPosition
**CPhidgetServo_set_OnPositionChange_Handler
**CPhidgetServo_getPositionMax
**CPhidgetServo_getPositionMin
**Count functions
*Deprecated:
**CPhidgetEncoder_getEncoderPosition
**CPhidgetEncoder_setEncoderPosition
**CPhidgetMotorControl_getMotorSpeed
**CPhidgetMotorControl_setMotorSpeed
**CPhidgetMotorControl_set_OnMotorChange_Handler
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
**CPhidgetServo_getMotorPosition
**CPhidgetServo_setMotorPosition
**CPhidgetServo_set_OnMotorPositionChange_Handler
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**Num functions
*Added ability to deprecate funcitons in the C library - compiler will issue a warning when they are used.
*added names to some arguments in phidget21.h
*fixes to the webservice for initial state stuff - now it behaves almost like non-webservice, with guaranteed initial events, but we don't guarantee initial state in the attach event yet. Min/Max, Num motors, inputs, etc. are all guaranteed in the attach handler.
*Finalized support for Phidget Stepper
===2.1.3.20080402===
*Fixed windows BUG - Device Type was showing up wrong
*CPhidgetStepper_getPosition -> CPhidgetStepper_getCurrentPosition
===2.1.3.20080327===
*added:
**CPhidgetAdvancedServo_setMotorPositionMax
**CPhidgetAdvancedServo_setMotorPositionMin
**CPhidgetAdvancedServo_getMotorStopped
*changes to API
**CPhidgetStepper_setMotorPosition -> CPhidgetStepper_setTargetMotorPosition
**added CPhidgetStepper_getTargetMotorPosition
**Stepper MotorSpeed -> Velocity
**Stepper and AdvancedServo MaxVelocity -> VelocityLimit
*add waitForAttachment to COM
*COM getbool (not indexed) will now return FALSE on false (rather then always returning true)
*fixed write thread timeouts - was setting attached after starting write thread so write thread would see a detached device and exit immediately
===2.1.3.20080206===
*changed long long to __int64, to be happy in borland C++
*added:
**CPhidgetStepper_getMaxMotorSpeed
**CPhidgetStepper_setMotorOn
**CPhidgetStepper_getMotorOn
**CPhidgetStepper_getMotorStopped
**CPhidgetStepper_setCurrentMotorPosition
*removed CPhidgetStepper_setVelocity
*added CPhidgetStepper_setMaxVelocity, CPhidgetStepper_getMaxVelocity
===2.1.3.20080114===
*Added new functions to Flash API
*Added new functions to Webservice Protocol
*Added new functions to COM Library
*Added new functions to Java Library
*All device fiels in C library cleaned up and made consistent
*Open in windows is exclusive - this needs to be tested for stability
*No data will be returned / accepted if it lies outside of max/min range
*if a data value is unknown, user variable is set to PUNK_INT, PUNK_DBL, or PUNK_BOOL, and return value is EPHIDGET_UNKNOWNVAL
*Proper Device initializations on Attach:
**triggers are set to defaults on attach
**device state is read in and preserved on attach
**during attach event, all sensor data, etc. is provided if available
**no data events until after the attach event returns
**everything initialized by the time waitForAttachment returns
**after attach event returns, a full set of initial state data events are thrown
*.NET collections are readonly, and never NULL (but empty when phidget detached)
*.NET callbacks no longer catch and hide all exceptions
**make sure to use try/catch blocks especially in Attach when accessing properties that may not be initialized.
*added min/max functions:
**CPhidgetAccelerometer_getAccelerationMax
**CPhidgetAccelerometer_getAccelerationMin
**CPhidgetAdvancedServo_getAccelerationMax
**CPhidgetAdvancedServo_getAccelerationMin
**CPhidgetAdvancedServo_getVelocityMax
**CPhidgetAdvancedServo_getVelocityMin
**CPhidgetAdvancedServo_getMotorPositionMax
**CPhidgetAdvancedServo_getMotorPositionMin
**CPhidgetMotorControl_getAccelerationMax
**CPhidgetMotorControl_getAccelerationMin
**CPhidgetPHSensor_getPHMax
**CPhidgetPHSensor_getPHMin
**CPhidgetPHSensor_getPotentialMax
**CPhidgetPHSensor_getPotentialMin
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**CPhidgetStepper_getAccelerationMax
**CPhidgetStepper_getAccelerationMin
**CPhidgetStepper_getMotorSpeedMax
**CPhidgetStepper_getMotorSpeedMin
**CPhidgetStepper_getMotorPositionMax
**CPhidgetStepper_getMotorPositionMin
**CPhidgetTemperatureSensor_getPotentialMax
**CPhidgetTemperatureSensor_getPotentialMin
**CPhidgetTemperatureSensor_getAmbientTemperatureMax
**CPhidgetTemperatureSensor_getAmbientTemperatureMin
**CPhidgetTemperatureSensor_getTemperatureMax
**CPhidgetTemperatureSensor_getTemperatureMin
*Added functions:
**CPhidgetTemperatureSensor_getAmbientTemperature
**CPhidgetTemperatureSensor_getThermocoupleType
**CPhidgetTemperatureSensor_setThermocoupleType
**CPhidget_set_OnServerConnectHandler
**CPhidget_set_OnServerDisconnectHandler
**CPhidgetDictionary_set_OnServerConnectHandler
**CPhidgetDictionary_set_OnServerDisconnectHandler
**CPhidgetManager_set_OnServerConnectHandler
**CPhidgetManager_set_OnServerDisconnectHandler
**CPhidgetDictionary_getServerID
**CPhidgetDictionary_getServerAddress
**CPhidgetDictionary_getServerStatus
**CPhidgetManager_getServerID
**CPhidgetManager_getServerAddress
**CPhidgetManager_getServerStatus
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
*Removed functions:
**CPhidgetServo_setMotorOff
*TemperatureSensor:
**Ambient sensor is accessed with it's own function
**first thermocouple is Index 0 everywhere
**no ambient sensor events
*getServerID is implemented
*changed the internal network structure (added CPhidgetRemote)
*reworked the USB code (mostly on Windows)
**Better handles closing, ESD events, timeouts
**fixed issues with Encoder, RFID stopping reading after a certain time.
**added USB error flag
*openRemote functions have been implemented
**these require bonjour (mac / windows) or avahi (linux) to be installed on both the client and server
**if they are not, you get EPHIDGET_UNSUPPORTED when you call them
*openRemoteIP functions are asynchronous and persistent
*include cphidgetconstants.h in phidget21.h for users
===2.1.2.20071108===
*start of chagelog

OS - OS X

2019-10-01T18:10:53Z

Patrick:

[[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.5 Leopard 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:
*OS X 10.11+: [{{SERVER}}/downloads/phidget21/libraries/macos/Phidget.dmg Installer Download]
*Mac OS X 10.7 - OS X 10.10: [{{SERVER}}/downloads/phidget21/libraries/macos/Phidget_OS_X_10_7.dmg Installer Download]
*Mac OS X 10.5 - OS X 10.6: [{{SERVER}}/downloads/phidget21/libraries/macos/Phidget_OS_X_10_5.dmg Installer Download]
*[[Software License]]

If you need old versions of the libraries, [{{SERVER}}/downloads/phidget21/libraries/macos/Phidget/ click here].

==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/phidget21/libraries/macos/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.5 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===

You can get debugging information from the WebService itself. This 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.

Driver Changelog

2019-10-01T18:08:16Z

Patrick:

[[Category:Administrative]]
__NOTOC__

===2.1.9.20191001===
*macOS / Windows release
**Support for macos 10.15 Catalina
**Update firmware files

===2.1.9.20190409===
*Fix GPS Date after April 6 2019 week rollover event

===2.1.9.20190208===
*macOS release
**Fixed USB bug where devices plugged in before boot were inaccessible until unplugged/re-plugged on 2018 Mac Mini.

===2.1.9.20180622===
*Python fix

===2.1.9.20180215===
*Move to .NET 4.0

===2.1.8.20171215===
*macOS release
**Fixed USB bug where opening two of the same device with -1 serial could cause missed attach/detach events and other errors.

===2.1.8.20160921===
*macOS release
**Fixed USB bug where devices plugged in before boot were inaccessible until unplugged/re-plugged, under OS X 10.11.

===2.1.8.20160202===
*Windows release
**Labview 7.1 support

===2.1.8.20160107===
*Windows release
**Don't throw an exception on EncoderPositionChangeEventArgs.Time in the .Net library when time it unknown - just return 0x7fffffff

===2.1.8.20160104===
*Mac/Windows release
**New firmware for 1042 and 1044, fixing digital gyro
===2.1.8.20151217===
*Fixed 1045 bug where it will display an unknown ambient temperature sometimes
*Fixed a crash in the windows control panel

===2.1.8.20151020===
*Windows release
**Fixed an issue where the examples would error when trying to run them from the control panel.

===2.1.8.20151009===
*OS X and Windows release
**Upgraded firmware for 1024, 1032, 1041, 1042, 1043, 1044 and 1067 to address issues with these Phidgets on OS X El Capitan
*SBC release
**Support for multiple webcams
===2.1.8.20150821===
*OS X-only release
**Support OS X 10.11 El Capitan
===2.1.8.20150805===
*OS X-only release
**Preliminary support for OS X 10.11 El Capitan
===2.1.8.20150410===
*Linux-only release
**Fixed Makefile phidget21.h target issues
===2.1.8.20150326===
*Windows-only release
**Fixed issue with webservice buttons not being visible in the control panel
===2.1.8.20150323===
*Windows-only release
**Updated icons with new company logo
===2.1.8.20150227===
*Linux-only release
**Added copyright/licence headers to source code files
**Updated cvtutf files to a newer version
===2.1.8.20150109===
*Windows-only
**Fixed examples for Labview 8.5
===2.1.8.20141209===
*OS X-only release
**Added support for armv7s and arm64 to the iOS library. Dropped support for armv6. Requires iOS 5.1.1 or later.
===2.1.8.20141202===
*Windows-only release
**Labview release to support older versions
===2.1.8.20141119===
*OS X-only release
**Fixed an issue with the 2.1.8.20141117 release where nothing was actually installed.
===2.1.8.20141117===
*OS X-only release
**Fixed a code-signing issue that make the installer appear unsigned on OS X 10.10
**Dropped support for OS X 10.4
===2.1.8.20140905===
*Windows-only release
**Added an IA32 folder to the windows libraries download - this supports Windows on the Intel Galileo platform
===2.1.8.20140428===
*Windows-only release
**Fixes to C# Stepper GUI Example
===2.1.8.20140319===
*CPhidget_getDeviceClass can now be called on handle before it is attached.
*Added support for 64-bit Max/MSP (Version 6.1+) on both OS X and Windows.
===2.1.8.20140227===
*Deals with 1046 bug in v100 and v101 firmware.
**No longer reports bad values that appear right after a channel is enabled.
**Fixes issue where changing the gain while channel 0 is disabled would sometimes cause bad readings.

===2.1.8.20131105===
* Fixed a defect in the Flash examples for the 1012 (Outputs 11-16 were not addressed properly).

===2.1.8.20130926===
*Windows-only release
**Support setting label on 1067 from Windows
===2.1.8.20130820===
*Windows-only release
**Added logging option to control panel / C# full examples
===2.1.8.20130802===
*Windows-only release
**Fix for Windows 8 issue where only 'Uninitialized Phidget Handle' would show up in the Manager, and Phidgets could not be opened.
===2.1.8.20130723===
*Improvement to java: we don't attach/detach our native threads for each event, just one attach, then detach before the thread exits.
**This increases performance, esp. when debugging on Android.
*Improvement to Android: We reuse the UsbRequest object rather then creating a new one for each transfer. This reduces logcat messages tremendously, and increases performance.
===2.1.8.20130710===
*Android-only release
**Added extra android target architectures: x86, MIPS, armeabi-v7a
===2.1.8.20130618===
*Changed setCompassCorrectionParameters() API call so that compass calibration parameters are written out to non-volatile storage on 1042/1044, so that they persist across power cycles. Previously, calibration data would need to be re-programmed at each attach.
*Changes to C# Spatial example:
**Compass calibration parameter set dialog removed from for 1042/1044 because parameters are set by the calibration software - and thus do not need setting in the example.
**Stores/restores parameters for 1056 based on serial number, so multiple different calibrations can be maintained.
===2.1.8.20130607===
*Windows-only release
**Fixes to compass calibration software for 1042/1044
===2.1.8.20130419===
*Windows-only release
**Fixed setCompassCorrectionParameters in the COM library
===2.1.8.20130327===
*Windows-only release
**Changed Windows installer to stop virus-scanner false positives
**Dropped support for Windows 2000
===2.1.8.20130320===
*Added EPHIDGET_NOTFOUND exception to Dictionary.getKey() for when the key is not found.
*Added exceptions back into the Java library - they have been missing since 2.1.8.20121015 release.
===2.1.8.20130313===
*Updates to Matlab support
**Works properly on Matlab 7+, on Windows, Mac, Linux without needing changes to .m files.
===2.1.8.20130221===
*Windows-only release
**Encoder Index event added to C and .NET libraries
===2.1.8.20121218===
*Webservice version: 1.0.10
**Support for 1024, 1032
*Support for 1024, 1032
*fixed bug where if one half of a composite device is open, and PHIDGET_USB_ERROR_FLAG gets set, the device may never re-attach.
===2.1.8.20121015===
*Windows-only release
**Support for new pressure/light sensors in example.
===2.1.8.20120914===
*Windows-only release
**Improved firmware upgrading in control panel - it was giving some false-errors on some machines.
===2.1.8.20120912===
*Fixed bug where 1065 could fail to attach when opened over webservice
*Fixed bug where close() could deadlock on Phidgets opened over the webservice
*Changed LED64 LED Brightness from int to double
**this may cause issues when controlling the LED64 over the webservice and library/webservice are not the same version
**the old setDiscreteLED call will remain, deprecated, with an int argument for compatibility.
===2.1.8.20120716===
*Linux-Only Release
**Fixed a bug where opening a device in two program at once would cause an attach-detach cycle as they fight each other for control.
===2.1.8.20120713===
*Mac-Only Release
**Added signing of the Mac installer, so Mountain Lion (OS X 10.8) doesn't refuse to run it.
===2.1.8.20120615===
*Windows-only release
**Fixed a bug that caused java to crash on events introduced in 2.1.8.20120612
===2.1.8.20120612===
*Windows-only release
**Fixed another bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120606===
*Windows-only release
**Fixed a bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120525===
*Windows-only release
**Fixed PhidgetIR sendRawData bug in .NET on 64-bit machines.
===2.1.8.20120514===
*Linux-only release
**Fixed a bug that causes a segfault with libusb-1.0 under 64-bit Linux.
===2.1.8.20120507===
*Mac/Linux-only release
**Fixes a setLabel bug introduced in 2.1.8.20120503
===2.1.8.20120503===
*Fixed some spelling mistakes
*Moved to libusb-1.0
**This resolves a bug where having a webcam plugged in caused a memory leak in the webservice.
*Fixed bug with advanced servo where setting acceleration to accelerationMax would cause an exception for some servo types
===2.1.8.20120216===
*Fixed bug with RFID Reader on OS X and Linux, as well as .NET over the webservice
*Fixed bug that could cause the Java Phidget Manager to crash during garbage collection.
===2.1.8.20120131===
*Fixed RFID Reader bug that caused tag event to not get thrown in .NET Applications
*Changed compass bearing calculations in spatial C# example
===2.1.8.20120123===
*Added support for 1061 v300+
*Fixed a bug where the firmware version could be mis-reported over Bonjour
===2.1.8.20111220===
*Fixed a bug in AppleScript where closing a Phidget opened via label would give a 'Connection Invalid' error.
*Fixed a bug where the webservice may fail to start on Linux systems that don't support IPv6 (ie. SBC2).
*Fixed issue where ratiometric state on newest interfacekit wouldn't be read back properly if it was false during attach.
*Fixed webservice issue where ratiometric state would not be reported properly for newest interfacekits
*Increased the number of overrun errors ignored during initial attach for InterfaceKit.
*Fixed an issue with the iPhone library and header
===2.1.8.20111219===
*fixed various other webservice stability/performance/memory leak bugs
*Faster connection to SBC-connected Phidgets from Mac OS
*Don't report packetlost or overrun errors that happen during early initialization - these are just noise.
*Fixed a bug in the webservice tree removal function that could cause memory leaks.
*Fixed bug where Webservice would crash on Linux if the chosen serverID was already under use on the network
*Stopped sending hardware Error Events before the Attach event - they are now queued up and sent after Attach
*Fixed a crash in the [[Phidget Control Panel]]
*Added ability to remove dictionary keys from a key change listener
*Reduced the number of false 'pending command not finished' error events on Close()
*Fixed a webservice bug where exceptions/false attach events could occur when close() is called soon after open
*Fixed bug where closing a PhidgetRFID soon after attach could cause a crash
*Fixed webservice but on MacOS where client could exit with SIG_PIPE error
*Fixed webservice bug where the server would sometimes exit(1) after many connect/disconnect cycles
*Fixed webservice bug where client could deadlock during close()
*Fixed webservice bug where opening a single remote phidget multiple times from the same application would fail
*Fixed a webservice bug where sockets weren't being closed properly sometimes
*Fixed a webservice bug where pre-attach error events wouldn't get through
*Fixed a bug where the webservice running on Linux would stop responding to clients after ~300 connect/disconnect cycles
*Fixed bug where a Phidget would become inaccessible until the app is restarted if a thread creation failed
*Fixed webservice bug where connect is slow on Windows when multiple clients are running simultaneously
*Fixed webservice bug where authentication would fail on a valid password
*Fixed webservice bug where attach may never happen, and would require a close()/open()

===2.1.8.20111121===
*Added support for new servo types to all libraries
*Fixed min/max position/velocity causing invalid arg exception on servo/advservo
*IPv6 support on MacOS
*Fixed some memory leaks
*Fixed hostname lookup issue on Mac OS with Back To My Mac enabled.
===2.1.8.20111028===
*Fixed Applescript bugs and released examples
*Added openLabel to .NET, Java, COM
*Setting change trigger to 0 on interfacekit will not set event mode.
**Previously setting change trigger to 0 after setting data rate would supersede the data rate setting, which is probably unexpected.
===2.1.8.20110630 - MacOS Only===
*handle USB bug introduced in MacOS 10.6.8
===2.1.8.20110615===
*Added error event when trying to open Phidgets with an unsupported version
===2.1.8.20110614 - Windows Only===
*Fixed bug in C# Spatial example
*Added support for negative gains in 1056
===2.1.8.20110601 - MacOS Only===
*Fixed AppleScript issues
===2.1.8.20110527===
*Fixed AS3.0 library (Flash/Flex) - wouldn't connect to webservice as of last release
*Fixed bug where webservice doesn't release a closed Phidget
*Fixed bug where devices that don't support label didn't show up on MacOS
*Fixed iPhone library issues
===2.1.8.20110524===
*AppleScript support added
*fixed problem with Spatial in .NET on 64-bit Windows
*Added remote setLabel to mac preference pane.
*fixed a bug where label characters 7,8,9 would be read back corrupted on certain devices.
**labels >7 characters that exhibit this bug will now be truncated to 7 characters when being read back
**call setLabel again using this library or newer to support 10 character labels.
**To maintain compatibility with older library versions, limit labels to <=7 characters on these devices.
*fixed bug on MacOS where serial number and/or label strings could be read wrong.
*better support for recovering misbehaving devices in Linux
*fixed a deadlock on linux when Avahi is installed but not running
*clear list of attached devices when closing remote manager
*Added support for Unicode labels
**To maintain compatibility with older library versions, limit labels to ASCII.
*Added open by label
*Webservice protocol version up to 1.0.9 (for open by label)
*Made opening multiple device is one application faster.
*TextLCD changes:
**cursor is disabled while writing to the display or setting a custom character to prevent display artifacts
**cursor is disabled when a full line is written so it doesn't go to the start of another line
**1204 should be stable
**setDisplayCharacter supports 0x00-0xff
*stopped property reflected more accurately in the C# stepper example
*Added error events to mac examples
===2.1.8.20110329 - Windows only===
*Fixed problem with control panel encoder example where enable wouldn't work
*Fixed issue with SpatialData, GPSPositionChange, PHChange and WeightChange events in Labview 64-bit
===2.1.8.20110322===
*Fixed [[Phidget Control Panel]] memory leak when Bonjour in installed but not running
*Fixed current sense formula on 1061_0 v200
*Fixed bug in webservice protocol while using the PhidgetAdvancedServo
*Fixed bug in old PhidgetTemperatureSensor

===2.1.8.20110310===
*Fixed bug in webservice protocol while using the PhidgetServo
*Fixed some Labview bugs
*Added some Java and VB.NET examples
===2.1.8.20110301===
*Full Support for 1002, 1011, 1040, 1046, 1054, 1065, 1204
*New webservice version - 1.0.8
**Support for new devices
**Support for error events
===2.1.7.20110203===
*fixed crash on close of remote Phidget on MacOS
*C# ifkit example bugfix - crashed on 1015/1016
*webservice improvements
*Switch to IP address for SBC config in browser
*Faster IP lookup for SBCs in control panel
===2.1.7.20101222 / 2.1.7.20101223===
*fixed getServerID on Linux
*removed report ack
**this was causing some bad side effects
*manual .local lookups on Windows
**much faster then letting Windows do it itself
*Support for new Labview library
*Fixed PhidgetIR bug where library would crash if repeat code is longer then IR_MAX_REPEAT_LENGTH
===2.1.7.20101103===
*Decreased Phidget Webservice event latency on Windows
*Preliminary support for 1002, 1011, 1040, 1045, 1046, 1054, 1065, 1204 (C, .NET)
*Webservice version updated to 1.0.7
**support for 1045, 1011, 1204
*Fixed a bug where webservice connections could be unexpectedly lost
*Bugfix: couldn't set interfacekit data rate over webservice.
*Fixed some memory leaks in the Mac library
*Fixed bug where blocking for >2 seconds in an events handler when opening remotely could cause a crash.
===2.1.7.20100803===
*Windows only release
*fixed setLabel in WindowsCE
*fixed getHashCode in .NET library - needed for working with Phidgets in Labview via .NET
===2.1.7.20100621===
*Linux only release - autotools updates
**call ldconfig automatically
**remove old phidget21 library (pre-autotools) when installing new one.
===2.1.7.20100620===
*Linux only release - added version.sh for autoreconf
===2.1.7.20100618===
*Linux only release - added udev/hotplug files
===2.1.7.20100617===
*Linux only release
*Transitioned to autotools in linux for phidget21 / webservice
*phidget21 library and webservice are now separate downloads
===2.1.7.20100525===
*full support for PhidgetSpatial and PhidgetIR in all libraries
*fixed 1031 not attaching in AS3.0
*Better error messages in JNI
*Updated error codes, device ID/Class lists in Java, Flash, COM, etc.
*Fixed TemperatureSensor version 200,201,202 bug - ambient sensor would not report negative temperatures.
*Revised temperaturesensor API to report tempMin/tempMax and errors more accurately.
*Added initial events for encoder digital inputs
*full support for 1047
*Added new device support to WindowsCE
*Updated mac examples for 1047, 1048
===2.1.6.20100504===
*Windows only Release
**Added 1131 and 1132 to InterfaceKit example in MSI
===2.1.6.20100428===
*limit data rate maximum to 16ms over the webservice for devices that expose dataRate (InterfaceKit, Spatial)
*fixed bug where TextLCD 8/8/8 would stay in Bonjour list after webservice is shutdown
*set/get Brightness for 1203_2
*Support 1048 in C# example
*webservice version incremented to 1.0.6
**TextLCD set/get brightness
**PhidgetIR support
**PhidgetSpatial support
**1047 support (enable, index)
===2.1.6.20100406===
*Support for 1018_2 (dataRate)
*Webservice version incremented to 1.0.5
===2.1.6.20100401===
*Updated InterfaceKit example with new sensors
*make Windows connect cancelable
*make pending zeroconf lookups cancelable during close
===2.1.6.20100318===
*Mac only release
**Added WillSleep and Wakeup events to give user control of Phidgets immediately before and after a system sleep (MacOS Only).
===2.1.6.20100317===
*Windows only release
**Some of the examples were being built using an out of date .NET library
===2.1.6.20100310===
*MaxMSP fix - 2.1.6.20100126 introduced a bug for some Phidgets where openremote/open by serial didn't work and MaxMSP would sometimes crash.
**No code changes to any of the other libraries.
===2.1.6.20100304===
*stopped property changes trigger events over webservice so they are noticed.
**more compatible with how local open works
*added 5 new servos
*fixed bug where remote close would not set detached so a subsequent open would not always connect.
*handle UninitializeZeroconf better - shut down thread before closing handles, fixes hang on SBC
*fixed bug on Mac where detaching 2 or more Phidgets at the same time caused a crash
*fixed close blocking because of a pending connect (mac, linux)
*Final support for 1031 in all libraries.
===2.1.6.20100129===
*Implemented initial events in Flash
**Flash behaviour should now be identical to C library local and remote.
*Fix RFID issue where close could cause crash
*increment webservice version to 1.0.4
*fixed RFID remote open
**Flash would never get an attach event if the reader had been previously opened
**Initial tag event would not be fired when a tag was present and the antenna was enabled prior to open
*fixed openRemote failing on Mac
*fixed deadlock in webservice which could be hit by opening/closing a device over and over again.
*fixed bug in stepper, which caused seg fault on SBC on position change events.
===2.1.6.20100126===
*added network open support in Max/MSP
===2.1.6.20100115===
*Increased network performance for Linux/MacOS
*Added five servo types
===2.1.6.20091215===
*Fixed busy loop in Linux openRemote
*JNI Library relocated to /Library/Java/Extensions on MacOS
===2.1.6.20091211===
*Heartbeat now works on Linux as well (had to make sockets non-blocking)
===2.1.6.20091130===
*Added heartbeat to webservice (client side)
**Better detects network failures by using active polling timeouts
*Fixed 0/8/8 over webservice
===2.1.6.20091020===
*Fixed 1052 counting issue on 1070 (-1 reported as 255)
*Fixed issue where Phidget21 would try to reinstall from a limited user account or when the Control Panel was disabled.
*64-bit kernel support in Snow Leopard
===2.1.6.20090928===
*Support for PhidgetSBC (1070)
*zeroconf can handle starting up before the mdns daemon, and will keep trying to connect.
*fixed 1066 not showing up on Mac
*added advanced servo example to mac pref pane
*implemented proper error handling in COM
**default behavious remains the same, enable proper error handling with 'EnableVerboseErrors'
*implemented error events in Java
===2.1.6.20090917===
*Updated webservice protocol version to 1.0.3
*Fixed stepper under AS3.0
*added setServoType, getServoType, setServoParameters to PhidgetServo and PhidgetAdvancedServo
*possible race condition fixed in webservice (pdictclient.c:907)
===2.1.6.20090902 (mac only release)===
*Support MacOSX 10.6, drop support for 10.3.9, require 10.4 or newer
**Fully 64-bit compliant, library supports ppc, i386, x86_64
===2.1.6.20090806===
*Added 1049 support
*Fixed RFID tag events over webservice
===2.1.6.20090804===
*Added 1051_2 support
*Fixed various small initialization issues - stepper, adv servo, rfid
*Added 32-bit library install to 64-bit installer
**VB6.0, etc. need the 32-bit COM library on 64-bit windows
===2.1.6.20090717===
*?
===2.1.6.20090708===
*Added DeviceID to zeroconf
*fixed RFID.LastTag in .NET
*Changed the error codes returned by error events; error events now have their own set of error codes rather then sharing the function return codes.
*Added support for 1047, 1048
*Added error event codes rather then trying to reuse the EPHIDGET return codes.
*fixed TextLCD issue where display could get corrupted during a detach/attach
*made mac more reliable on attach
*more error logging on mac
===2.1.6.20090525===
*fixed RFID not attaching via webservice if a tag is present.
*bugfix related to double free on detach event.
*Implemented getKey
*Added MIPS II support to Windows CE
===2.1.6.20090430===
*Added ActiveX interface to COM library
*Added stepper and advancedServo to Flex .swc library
===2.1.6.20090417===
*added PhidgetIR prototype support to C library
*properly handles sleeping on OSX
*fixed some webservice field initializations in Flash and C
*fixed security exceptions in [[Phidget Control Panel]] under Vista
*added [[Phidget Control Panel]] to start menu

===2.1.6.20090318 (Examples/AS3.0 only release)===
*Fixed AdvancedServo in Flash - wouldn't attach
===2.1.6.20090317===
*[[Phidget Control Panel]] properly supports Vista UAC and Limited user accounts in XP, etc.
*Added 64-bit release of Phidget21.msi for Windows

===2.1.6.20090312===
*added 1064, 1059 to WindowsCE
*fixed opening 1051 over webservice
*fixed opening 1015/1016 over webservice broken in last release
===2.1.6.20090302===
*Advanced servo bugfix: stopped would stop being true if min/max was set to exclude current position.
*linux USB improvements when many Phidgets are attached and opened at once.
*1031 support in phidget21, webservice, .NET - hidden until product release
**CPhidgetLED_setVoltage
**CPhidgetLED_getVoltage
**CPhidgetLED_setCurrentLimit
**CPhidgetLED_getCurrentLimit
*unknown timechange == PUNK_INT in encoder position change event
**1st position change event
**> 30 seconds time change
*AS3 updates
**updated to 1.0.2 webservice
**encoder position change events report relative change rather then absolute position
**encoder adds getTimeChange function for timing encoder changes
*webservice updated to 1.0.2
**Authorization is asynchronous
**Doesn't match the old version checking, so errors will not be nice when trying to connect to an old webservice
**Sends out all initial data, so it's just like opening locally
**supports interfacekit Raw sensor value
**supports labels on remoteIP managers
*avahi bugfix
*webservice more stable against forcefully closed clients
*closing a network Phidget won't block - ever.
**no longer using quit, just closing the socket
*added libavahi-client.so.3 reference to linux library.
*Fixed bug with opening one phidget with serial and no serial at the same time over the webservice
===2.1.5.20090105===
*[[Phidget Control Panel]] stability improvements
*added CPhidgetSBC_getHostname
*advanced servo 1 motor current sense equation - support should now be complete
*webservice and network code bugfixes - crash / deadlock during close, problems with concurrent connections, etc.
*fixed close on remote and remoteIP managers
*name of RFID changed from "Phidget RFID 4-output" to "Phidget RFID 2-output" - updated anything referencing old name.

===2.1.5.20081023===
*added advanced servo and stepper examples to VB6.0, VB.NET and C
*added deviceClass and deviceID
*updated Mac examples
*webservice protocol version enforcement
*internal fix/rework of device id's etc.
*Fixed memory leaks in webservice and phidget21 network code.
*Dictionary and network stability improvements.
*duplicate calls to open or close are now silently ignored.
===2.1.4.20080924===
*Old TextLCD 0/8/8's can now have both halves open at the same time on Windows
*fixed bug with composite devices on linux
*fixed manager on linux to better deal with unique devices
===2.1.4.20080922===
*Updated Delphi files
*TextLCD can display 0x80-0xFF characters from Java
*getAttachedDevices works for mdns managers
*fixed a deadlock in the webservice
*better network error handling / password support for windows C# examples
*waitForAttachment will return EPHIDGET_CLOSED if the handle is closed while it is waiting.
*added EPHIDGET_CLOSED
*joining central threads checks whether they are trying to be joined by themselves first (avoid deadlocks).
*changed context of error event to be free from locks (can call close, open, etc. from them).
===2.1.4.20080821===
*zeroconf threads exit cleanly on last _close (apple zeroconf)
*Added advanced servo and stepper to Max
===2.1.4.20080811 (mac only release)===
*Fixed manager on Mac (wasn't working at all since 2.1.4.20080808)
===2.1.4.20080808===
*added CPhidgetSBC and CPhidgetSBCManager to the c library - these interfaces are hidden from users and meant to be used internally (for now).
*CPhidgetManager_open no longer blocks to send out initial attach events. These initial events are sent from the CentralThread context like all other attach events.
*fixed CThread_wait_on_event on Linux
*added CPhidgetGeneric interface for prototyping to C, .NET libraries. product ID is 0x99. These are only visible in debug releases, only to be used internally.
===2.1.4.20080715===
*udev rules fixed for product IDs with alpha-hex values
*blocking in an attach event does not block calls to open anymore
*RFID tag event handlers can now handle blocking - tag lost is timed after the tag handler exits.
===2.1.4.20080623===
*Flex .swc library was out of sync
*fixed CPhidgetManager_getAttachedDevices for network managers
*Added CPhidgetManager_freeAttachedDevicesArray
===2.1.4.20080613===
*Max/MSP RFID fixed
*0/0/8 and advanced servo added to CE
*fixed flash policy file server in webservice
*webservice with password and asynchronous together work now
===2.1.4.20080602===
*phidget21.h -> phidget21int.h so as not to be confused with generated phidget21.h
*some changes to Makefile fro crosscompiling
*no more vbscript in msi
===2.1.4.20080513===
*removed long long from COM - not supported by VB6.0
*added LastTag to RFID in .NET
===2.1.4.20080428===
*support Mac OS X 10.3.9 again
*Rev up to 2.1.4
*finalize Phidget Stepper API - Phidget Stepper requires 2.1.4 as a minimum
*fixed serverConnect and serverDisconnect handlers for manager and dictionary in COM
*Changed:
**PhidgetStepper and PhidgetAdvancedServo
***MotorPosition -> Position
***MotorOn -> Engaged
***MotorStopped -> Stopped
*Added:
**CPhidgetStepper_getCurrentLimit
**CPhidgetEncoder_getPosition
**CPhidgetEncoder_setPosition
**CPhidgetMotorControl_getVelocity
**CPhidgetMotorControl_setVelocity
**CPhidgetMotorControl_set_OnVelocityChange_Handler
**CPhidgetServo_setEngaged
**CPhidgetServo_getEngaged
**CPhidgetServo_getPosition
**CPhidgetServo_setPosition
**CPhidgetServo_set_OnPositionChange_Handler
**CPhidgetServo_getPositionMax
**CPhidgetServo_getPositionMin
**Count functions
*Deprecated:
**CPhidgetEncoder_getEncoderPosition
**CPhidgetEncoder_setEncoderPosition
**CPhidgetMotorControl_getMotorSpeed
**CPhidgetMotorControl_setMotorSpeed
**CPhidgetMotorControl_set_OnMotorChange_Handler
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
**CPhidgetServo_getMotorPosition
**CPhidgetServo_setMotorPosition
**CPhidgetServo_set_OnMotorPositionChange_Handler
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**Num functions
*Added ability to deprecate funcitons in the C library - compiler will issue a warning when they are used.
*added names to some arguments in phidget21.h
*fixes to the webservice for initial state stuff - now it behaves almost like non-webservice, with guaranteed initial events, but we don't guarantee initial state in the attach event yet. Min/Max, Num motors, inputs, etc. are all guaranteed in the attach handler.
*Finalized support for Phidget Stepper
===2.1.3.20080402===
*Fixed windows BUG - Device Type was showing up wrong
*CPhidgetStepper_getPosition -> CPhidgetStepper_getCurrentPosition
===2.1.3.20080327===
*added:
**CPhidgetAdvancedServo_setMotorPositionMax
**CPhidgetAdvancedServo_setMotorPositionMin
**CPhidgetAdvancedServo_getMotorStopped
*changes to API
**CPhidgetStepper_setMotorPosition -> CPhidgetStepper_setTargetMotorPosition
**added CPhidgetStepper_getTargetMotorPosition
**Stepper MotorSpeed -> Velocity
**Stepper and AdvancedServo MaxVelocity -> VelocityLimit
*add waitForAttachment to COM
*COM getbool (not indexed) will now return FALSE on false (rather then always returning true)
*fixed write thread timeouts - was setting attached after starting write thread so write thread would see a detached device and exit immediately
===2.1.3.20080206===
*changed long long to __int64, to be happy in borland C++
*added:
**CPhidgetStepper_getMaxMotorSpeed
**CPhidgetStepper_setMotorOn
**CPhidgetStepper_getMotorOn
**CPhidgetStepper_getMotorStopped
**CPhidgetStepper_setCurrentMotorPosition
*removed CPhidgetStepper_setVelocity
*added CPhidgetStepper_setMaxVelocity, CPhidgetStepper_getMaxVelocity
===2.1.3.20080114===
*Added new functions to Flash API
*Added new functions to Webservice Protocol
*Added new functions to COM Library
*Added new functions to Java Library
*All device fiels in C library cleaned up and made consistent
*Open in windows is exclusive - this needs to be tested for stability
*No data will be returned / accepted if it lies outside of max/min range
*if a data value is unknown, user variable is set to PUNK_INT, PUNK_DBL, or PUNK_BOOL, and return value is EPHIDGET_UNKNOWNVAL
*Proper Device initializations on Attach:
**triggers are set to defaults on attach
**device state is read in and preserved on attach
**during attach event, all sensor data, etc. is provided if available
**no data events until after the attach event returns
**everything initialized by the time waitForAttachment returns
**after attach event returns, a full set of initial state data events are thrown
*.NET collections are readonly, and never NULL (but empty when phidget detached)
*.NET callbacks no longer catch and hide all exceptions
**make sure to use try/catch blocks especially in Attach when accessing properties that may not be initialized.
*added min/max functions:
**CPhidgetAccelerometer_getAccelerationMax
**CPhidgetAccelerometer_getAccelerationMin
**CPhidgetAdvancedServo_getAccelerationMax
**CPhidgetAdvancedServo_getAccelerationMin
**CPhidgetAdvancedServo_getVelocityMax
**CPhidgetAdvancedServo_getVelocityMin
**CPhidgetAdvancedServo_getMotorPositionMax
**CPhidgetAdvancedServo_getMotorPositionMin
**CPhidgetMotorControl_getAccelerationMax
**CPhidgetMotorControl_getAccelerationMin
**CPhidgetPHSensor_getPHMax
**CPhidgetPHSensor_getPHMin
**CPhidgetPHSensor_getPotentialMax
**CPhidgetPHSensor_getPotentialMin
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**CPhidgetStepper_getAccelerationMax
**CPhidgetStepper_getAccelerationMin
**CPhidgetStepper_getMotorSpeedMax
**CPhidgetStepper_getMotorSpeedMin
**CPhidgetStepper_getMotorPositionMax
**CPhidgetStepper_getMotorPositionMin
**CPhidgetTemperatureSensor_getPotentialMax
**CPhidgetTemperatureSensor_getPotentialMin
**CPhidgetTemperatureSensor_getAmbientTemperatureMax
**CPhidgetTemperatureSensor_getAmbientTemperatureMin
**CPhidgetTemperatureSensor_getTemperatureMax
**CPhidgetTemperatureSensor_getTemperatureMin
*Added functions:
**CPhidgetTemperatureSensor_getAmbientTemperature
**CPhidgetTemperatureSensor_getThermocoupleType
**CPhidgetTemperatureSensor_setThermocoupleType
**CPhidget_set_OnServerConnectHandler
**CPhidget_set_OnServerDisconnectHandler
**CPhidgetDictionary_set_OnServerConnectHandler
**CPhidgetDictionary_set_OnServerDisconnectHandler
**CPhidgetManager_set_OnServerConnectHandler
**CPhidgetManager_set_OnServerDisconnectHandler
**CPhidgetDictionary_getServerID
**CPhidgetDictionary_getServerAddress
**CPhidgetDictionary_getServerStatus
**CPhidgetManager_getServerID
**CPhidgetManager_getServerAddress
**CPhidgetManager_getServerStatus
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
*Removed functions:
**CPhidgetServo_setMotorOff
*TemperatureSensor:
**Ambient sensor is accessed with it's own function
**first thermocouple is Index 0 everywhere
**no ambient sensor events
*getServerID is implemented
*changed the internal network structure (added CPhidgetRemote)
*reworked the USB code (mostly on Windows)
**Better handles closing, ESD events, timeouts
**fixed issues with Encoder, RFID stopping reading after a certain time.
**added USB error flag
*openRemote functions have been implemented
**these require bonjour (mac / windows) or avahi (linux) to be installed on both the client and server
**if they are not, you get EPHIDGET_UNSUPPORTED when you call them
*openRemoteIP functions are asynchronous and persistent
*include cphidgetconstants.h in phidget21.h for users
===2.1.2.20071108===
*start of chagelog

OS - Phidget SBC

2019-07-31T21:30:08Z

Patrick:

[[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|SBC3 Getting Started Guide]] right out of the box.

*[[Software License]]

'''For PhidgetSBC (1070):'''
*[{{SERVER}}/downloads/phidgetsbc/1070/changelog.txt changelog]
*[{{SERVER}}/downloads/phidgetsbc/1070/phidgetsbc-minimal.bin Minimal Firmware]
*[{{SERVER}}/downloads/phidgetsbc/1070/phidgetsbc-full.bin Full Firmware]
*[{{SERVER}}/downloads/phidgetsbc/1070/buildroot-phidgetsbc.tar.gz Buildroot/Kernel Sources]
'''For PhidgetSBC2 (1072):'''
*[{{SERVER}}/downloads/phidgetsbc/1072/changelog.txt changelog]
*[{{SERVER}}/downloads/phidgetsbc/1072/phidgetsbc2.bin SBC2 Firmware]
*[{{SERVER}}/downloads/phidgetsbc/1072/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package] (How-to and patch file)
'''The PhidgetSBC3 has different firmware packages based on the kernel version. In order to determine the device version of your SBC3, see the [[1073_User_Guide#SBC_Web_Interface|web configuration page]].'''

[[File:sbcver.jpg|thumb|562px|link=|The system information table is found on the Status -> System tab of the '''[[1073_User_Guide#SBC_Web_Interface|web configuration page]]''' of the SBC.]]
'''For PhidgetSBC3 (1073) kernel version 3.6.3:'''
*[{{SERVER}}/downloads/phidgetsbc/1073/changelog.txt changelog]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.6.3/phidgetsbc3.bin SBC3 Firmware]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.6.3/phidgetsbc3-kerneldev.tar.gz SBC3 Kernel Development Package]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.6.3/phidgetsbc3-upgrade_3.6.3_3.14.27.tar.gz SBC3 Kernel upgrade package (3.6.3 -> 3.14.27)]
'''For PhidgetSBC3 (1073) kernel version 3.14.27:'''
*[{{SERVER}}/downloads/phidgetsbc/1073/changelog.txt changelog]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.14.27/phidgetsbc3.bin SBC3 Firmware]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.14.27/phidgetsbc3-update_3.14.27.tar.gz SBC3 Kernel update package (3.14.27)]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.14.27/phidgetsbc3-kerneldev.tar.gz SBC3 Kernel Development Package]

Note that, instead of using the firmware to update your SBC, updates should normally be done via the System -> Packages page on your SBC3 web interface. It is rarely necessary to completely re-flash your device..
<br clear = all>

==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. If the installation fails because it can't find python, you need to enable the full repository as described in [[#Getting Started_-_The_SBC_(Debian_Linux)|this section]], and then perform an apt-get update.

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

Copy the [{{SERVER}}/downloads/phidget21/libraries/any/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/phidget21/libraries/any/PhidgetsPython.zip Python Libraries].

In an SSH terminal to the SBC, type: {{Code|<nowiki>wget http://www.python_library_link</nowiki>}} where instead of <nowiki>http://www.python_library_link</nowiki> 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/phidget21/examples/java/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/phidget21/examples/java/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/phidget21/libraries/linux/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>
# For 1072 - PhidgetSBC2:
ubiattach /dev/ubi_ctrl -m 6

# For 1073 - PhidgetSBC3:
ubiattach /dev/ubi_ctrl -m 7

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://docs.opencv.org/ The OpenCV Reference], and specifically the section on 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/phidgetsbc/1072/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/phidgetsbc/1072/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:

====For SBC2:====

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

====For SBC3:====

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r $ROOTFS/ system_ubifs.img
ubinize -o system_ubi.img -m 4KiB -p 256KiB 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=83MiB
# 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.

===Saving a file system to flash to multiple SBC's===
You may want to create a complete backup of your SBC root filesystem, which can then be flashed to other SBCs. This is how it could be done:

You will need a USB drive - we have had issues using cheap flash drives, so a real USB drive is recommended. Make sure it's empty, as it will be reformatted.

All of these commands are executed on your SBC, while logged in over SSH.

First, re-format the USB drive as ext3. Assuming the USB drive is sda and has a single partition:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
mkfs.ext3 /dev/sda1
mount -t ext3 /dev/sda1 /media/usb0
</syntaxhighlight>
</div>

Then, remount / as readonly, so it doesn't change as we're copying it. To do this, we need to kill all running processes except sshd:

<div class="source">
<syntaxhighlight lang=bash>
service udev stop
service ifplugd stop
service rsyslog stop
service avahi-daemon stop
service phidgetwebservice stop
service ntp stop
service busybox-httpd stop
service dbus stop
service cron stop
pkill dhclient
mount -o remount,ro /
</syntaxhighlight>
</div>

If the remount says that / is busy, do a 'ps auxww' and 'pkill' anything else that may be running until it remounts properly.

Then, copy / to the flash drive:

<div class="source">
<syntaxhighlight lang=bash>
mkdir /media/usb0/root
mount --bind / /mnt/
cp -a /mnt/* /media/usb0/root/
</syntaxhighlight>
</div>

Then, clean up the copy - removing files specific to this board. We also remove the APT cache to save space.

<div class="source">
<syntaxhighlight lang=bash>
find /media/usb0/root/var/log -type f -print0 | xargs -0 rm -f
rm -rf /media/usb0/root/var/lib/apt/lists/*
mkdir /media/usb0/root/var/lib/apt/lists/partial
rm -f /media/usb0/root/var/cache/apt/*.bin
rm /media/usb0/root/etc/udev/rules.d/70-persistent-net.rules
rm /media/usb0/root/etc/ssh/ssh_host_*
</syntaxhighlight>
</div>

then, create the ubinize.cfg file:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=83MiB
vol_type=dynamic
vol_name=rootfs0
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=64128KiB
vol_type=dynamic
vol_name=rootfs
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

NOTE: you may need to increase vol_size if your filesystem is larger.

then, create the UBI image from the copy:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 4KiB -p 256KiB ubinize.cfg
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -m 2KiB -e 126KiB -c 4050 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 2KiB -p 128KiB -s 512 ubinize.cfg
</syntaxhighlight>
</div>

then, unmount the drive to ensure everything is written out properly:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
</syntaxhighlight>
</div>

Then, you can remove the /root/ folder and system_ubifs.img. system_ubi.img can be flashed to other SBCs using the recovery system.

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

2019-07-31T21:28:37Z

Patrick:

[[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|SBC3 Getting Started Guide]] right out of the box.

*[[Software License]]

'''For PhidgetSBC (1070):'''
*[{{SERVER}}/downloads/phidgetsbc/1070/changelog.txt changelog]
*[{{SERVER}}/downloads/phidgetsbc/1070/phidgetsbc-minimal.bin Minimal Firmware]
*[{{SERVER}}/downloads/phidgetsbc/1070/phidgetsbc-full.bin Full Firmware]
*[{{SERVER}}/downloads/phidgetsbc/1070/buildroot-phidgetsbc.tar.gz Buildroot/Kernel Sources]
'''For PhidgetSBC2 (1072):'''
*[{{SERVER}}/downloads/phidgetsbc/1072/changelog.txt changelog]
*[{{SERVER}}/downloads/phidgetsbc/1072/phidgetsbc2.bin SBC2 Firmware]
*[{{SERVER}}/downloads/phidgetsbc/1072/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package] (How-to and patch file)
'''The PhidgetSBC3 has different firmware packages based on the kernel version. In order to determine the device version of your SBC3, see the [[1073_User_Guide#SBC_Web_Interface|web configuration page]].'''

[[File:sbcver.jpg|thumb|562px|link=|The system information table is found on the Status -> System tab of the '''[[1073_User_Guide#SBC_Web_Interface|web configuration page]]''' of the SBC.]]
'''For PhidgetSBC3 (1073) kernel version 3.6.3:'''
*[{{SERVER}}/downloads/phidgetsbc/1073/changelog.txt changelog]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.6.3/phidgetsbc3.bin SBC3 Firmware]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.6.3/phidgetsbc3-kerneldev.tar.gz SBC3 Kernel Development Package]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.6.3/phidgetsbc3-upgrade_3.6.3_3.14.27.tar.gz SBC3 Kernel upgrade package (3.6.3 -> 3.14.27)]
'''For PhidgetSBC3 (1073) kernel version 3.14.27:'''
*[{{SERVER}}/downloads/phidgetsbc/1073/changelog.txt changelog]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.14.27/phidgetsbc3.bin SBC3 Firmware]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.14.27/phidgetsbc3-update_3.14.27.tar.gz SBC3 Kernel update package (3.14.27)]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.14.27/phidgetsbc3-kerneldev.tar.gz SBC3 Kernel Development Package]

Note that, instead of using the firmware to update your SBC, updates should normally be done via the System -> Packages page on your SBC3 web interface. It is rarely necessary to completely re-flash your device..
<br clear = all>

==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. If the installation fails because it can't find python, you need to enable the full repository as described in [[#Getting Started_-_The_SBC_(Debian_Linux)|this section]], and then perform an apt-get update.

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

Copy the [{{SERVER}}/downloads/phidget21/libraries/any/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/phidget21/libraries/any/PhidgetsPython.zip Python Libraries].

In an SSH terminal to the SBC, type: {{Code|<nowiki>wget http://www.python_library_link</nowiki>}} where instead of <nowiki>http://www.python_library_link</nowiki> 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/phidget21/examples/java/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/phidget21/examples/java/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/phidget21/libraries/linux/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>
cat /proc/mtd
# Note which mtd# is "rootfs" (6 or 7) and pass into ubiattach:
ubiattach /dev/ubi_ctrl -m [rootfs mtd #]
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://docs.opencv.org/ The OpenCV Reference], and specifically the section on 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/phidgetsbc/1072/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/phidgetsbc/1072/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:

====For SBC2:====

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

====For SBC3:====

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r $ROOTFS/ system_ubifs.img
ubinize -o system_ubi.img -m 4KiB -p 256KiB 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=83MiB
# 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.

===Saving a file system to flash to multiple SBC's===
You may want to create a complete backup of your SBC root filesystem, which can then be flashed to other SBCs. This is how it could be done:

You will need a USB drive - we have had issues using cheap flash drives, so a real USB drive is recommended. Make sure it's empty, as it will be reformatted.

All of these commands are executed on your SBC, while logged in over SSH.

First, re-format the USB drive as ext3. Assuming the USB drive is sda and has a single partition:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
mkfs.ext3 /dev/sda1
mount -t ext3 /dev/sda1 /media/usb0
</syntaxhighlight>
</div>

Then, remount / as readonly, so it doesn't change as we're copying it. To do this, we need to kill all running processes except sshd:

<div class="source">
<syntaxhighlight lang=bash>
service udev stop
service ifplugd stop
service rsyslog stop
service avahi-daemon stop
service phidgetwebservice stop
service ntp stop
service busybox-httpd stop
service dbus stop
service cron stop
pkill dhclient
mount -o remount,ro /
</syntaxhighlight>
</div>

If the remount says that / is busy, do a 'ps auxww' and 'pkill' anything else that may be running until it remounts properly.

Then, copy / to the flash drive:

<div class="source">
<syntaxhighlight lang=bash>
mkdir /media/usb0/root
mount --bind / /mnt/
cp -a /mnt/* /media/usb0/root/
</syntaxhighlight>
</div>

Then, clean up the copy - removing files specific to this board. We also remove the APT cache to save space.

<div class="source">
<syntaxhighlight lang=bash>
find /media/usb0/root/var/log -type f -print0 | xargs -0 rm -f
rm -rf /media/usb0/root/var/lib/apt/lists/*
mkdir /media/usb0/root/var/lib/apt/lists/partial
rm -f /media/usb0/root/var/cache/apt/*.bin
rm /media/usb0/root/etc/udev/rules.d/70-persistent-net.rules
rm /media/usb0/root/etc/ssh/ssh_host_*
</syntaxhighlight>
</div>

then, create the ubinize.cfg file:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=83MiB
vol_type=dynamic
vol_name=rootfs0
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=64128KiB
vol_type=dynamic
vol_name=rootfs
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

NOTE: you may need to increase vol_size if your filesystem is larger.

then, create the UBI image from the copy:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 4KiB -p 256KiB ubinize.cfg
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -m 2KiB -e 126KiB -c 4050 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 2KiB -p 128KiB -s 512 ubinize.cfg
</syntaxhighlight>
</div>

then, unmount the drive to ensure everything is written out properly:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
</syntaxhighlight>
</div>

Then, you can remove the /root/ folder and system_ubifs.img. system_ubi.img can be flashed to other SBCs using the recovery system.

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

Driver Changelog

2019-04-09T21:45:30Z

Patrick:

[[Category:Administrative]]
__NOTOC__

===2.1.9.20190409===
*Fix GPS Date after April 6 2019 week rollover event

===2.1.9.20190208===
*macOS release
**Fixed USB bug where devices plugged in before boot were inaccessible until unplugged/re-plugged on 2018 Mac Mini.

===2.1.9.20180622===
*Python fix

===2.1.9.20180215===
*Move to .NET 4.0

===2.1.8.20171215===
*macOS release
**Fixed USB bug where opening two of the same device with -1 serial could cause missed attach/detach events and other errors.

===2.1.8.20160921===
*macOS release
**Fixed USB bug where devices plugged in before boot were inaccessible until unplugged/re-plugged, under OS X 10.11.

===2.1.8.20160202===
*Windows release
**Labview 7.1 support

===2.1.8.20160107===
*Windows release
**Don't throw an exception on EncoderPositionChangeEventArgs.Time in the .Net library when time it unknown - just return 0x7fffffff

===2.1.8.20160104===
*Mac/Windows release
**New firmware for 1042 and 1044, fixing digital gyro
===2.1.8.20151217===
*Fixed 1045 bug where it will display an unknown ambient temperature sometimes
*Fixed a crash in the windows control panel

===2.1.8.20151020===
*Windows release
**Fixed an issue where the examples would error when trying to run them from the control panel.

===2.1.8.20151009===
*OS X and Windows release
**Upgraded firmware for 1024, 1032, 1041, 1042, 1043, 1044 and 1067 to address issues with these Phidgets on OS X El Capitan
*SBC release
**Support for multiple webcams
===2.1.8.20150821===
*OS X-only release
**Support OS X 10.11 El Capitan
===2.1.8.20150805===
*OS X-only release
**Preliminary support for OS X 10.11 El Capitan
===2.1.8.20150410===
*Linux-only release
**Fixed Makefile phidget21.h target issues
===2.1.8.20150326===
*Windows-only release
**Fixed issue with webservice buttons not being visible in the control panel
===2.1.8.20150323===
*Windows-only release
**Updated icons with new company logo
===2.1.8.20150227===
*Linux-only release
**Added copyright/licence headers to source code files
**Updated cvtutf files to a newer version
===2.1.8.20150109===
*Windows-only
**Fixed examples for Labview 8.5
===2.1.8.20141209===
*OS X-only release
**Added support for armv7s and arm64 to the iOS library. Dropped support for armv6. Requires iOS 5.1.1 or later.
===2.1.8.20141202===
*Windows-only release
**Labview release to support older versions
===2.1.8.20141119===
*OS X-only release
**Fixed an issue with the 2.1.8.20141117 release where nothing was actually installed.
===2.1.8.20141117===
*OS X-only release
**Fixed a code-signing issue that make the installer appear unsigned on OS X 10.10
**Dropped support for OS X 10.4
===2.1.8.20140905===
*Windows-only release
**Added an IA32 folder to the windows libraries download - this supports Windows on the Intel Galileo platform
===2.1.8.20140428===
*Windows-only release
**Fixes to C# Stepper GUI Example
===2.1.8.20140319===
*CPhidget_getDeviceClass can now be called on handle before it is attached.
*Added support for 64-bit Max/MSP (Version 6.1+) on both OS X and Windows.
===2.1.8.20140227===
*Deals with 1046 bug in v100 and v101 firmware.
**No longer reports bad values that appear right after a channel is enabled.
**Fixes issue where changing the gain while channel 0 is disabled would sometimes cause bad readings.

===2.1.8.20131105===
* Fixed a defect in the Flash examples for the 1012 (Outputs 11-16 were not addressed properly).

===2.1.8.20130926===
*Windows-only release
**Support setting label on 1067 from Windows
===2.1.8.20130820===
*Windows-only release
**Added logging option to control panel / C# full examples
===2.1.8.20130802===
*Windows-only release
**Fix for Windows 8 issue where only 'Uninitialized Phidget Handle' would show up in the Manager, and Phidgets could not be opened.
===2.1.8.20130723===
*Improvement to java: we don't attach/detach our native threads for each event, just one attach, then detach before the thread exits.
**This increases performance, esp. when debugging on Android.
*Improvement to Android: We reuse the UsbRequest object rather then creating a new one for each transfer. This reduces logcat messages tremendously, and increases performance.
===2.1.8.20130710===
*Android-only release
**Added extra android target architectures: x86, MIPS, armeabi-v7a
===2.1.8.20130618===
*Changed setCompassCorrectionParameters() API call so that compass calibration parameters are written out to non-volatile storage on 1042/1044, so that they persist across power cycles. Previously, calibration data would need to be re-programmed at each attach.
*Changes to C# Spatial example:
**Compass calibration parameter set dialog removed from for 1042/1044 because parameters are set by the calibration software - and thus do not need setting in the example.
**Stores/restores parameters for 1056 based on serial number, so multiple different calibrations can be maintained.
===2.1.8.20130607===
*Windows-only release
**Fixes to compass calibration software for 1042/1044
===2.1.8.20130419===
*Windows-only release
**Fixed setCompassCorrectionParameters in the COM library
===2.1.8.20130327===
*Windows-only release
**Changed Windows installer to stop virus-scanner false positives
**Dropped support for Windows 2000
===2.1.8.20130320===
*Added EPHIDGET_NOTFOUND exception to Dictionary.getKey() for when the key is not found.
*Added exceptions back into the Java library - they have been missing since 2.1.8.20121015 release.
===2.1.8.20130313===
*Updates to Matlab support
**Works properly on Matlab 7+, on Windows, Mac, Linux without needing changes to .m files.
===2.1.8.20130221===
*Windows-only release
**Encoder Index event added to C and .NET libraries
===2.1.8.20121218===
*Webservice version: 1.0.10
**Support for 1024, 1032
*Support for 1024, 1032
*fixed bug where if one half of a composite device is open, and PHIDGET_USB_ERROR_FLAG gets set, the device may never re-attach.
===2.1.8.20121015===
*Windows-only release
**Support for new pressure/light sensors in example.
===2.1.8.20120914===
*Windows-only release
**Improved firmware upgrading in control panel - it was giving some false-errors on some machines.
===2.1.8.20120912===
*Fixed bug where 1065 could fail to attach when opened over webservice
*Fixed bug where close() could deadlock on Phidgets opened over the webservice
*Changed LED64 LED Brightness from int to double
**this may cause issues when controlling the LED64 over the webservice and library/webservice are not the same version
**the old setDiscreteLED call will remain, deprecated, with an int argument for compatibility.
===2.1.8.20120716===
*Linux-Only Release
**Fixed a bug where opening a device in two program at once would cause an attach-detach cycle as they fight each other for control.
===2.1.8.20120713===
*Mac-Only Release
**Added signing of the Mac installer, so Mountain Lion (OS X 10.8) doesn't refuse to run it.
===2.1.8.20120615===
*Windows-only release
**Fixed a bug that caused java to crash on events introduced in 2.1.8.20120612
===2.1.8.20120612===
*Windows-only release
**Fixed another bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120606===
*Windows-only release
**Fixed a bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120525===
*Windows-only release
**Fixed PhidgetIR sendRawData bug in .NET on 64-bit machines.
===2.1.8.20120514===
*Linux-only release
**Fixed a bug that causes a segfault with libusb-1.0 under 64-bit Linux.
===2.1.8.20120507===
*Mac/Linux-only release
**Fixes a setLabel bug introduced in 2.1.8.20120503
===2.1.8.20120503===
*Fixed some spelling mistakes
*Moved to libusb-1.0
**This resolves a bug where having a webcam plugged in caused a memory leak in the webservice.
*Fixed bug with advanced servo where setting acceleration to accelerationMax would cause an exception for some servo types
===2.1.8.20120216===
*Fixed bug with RFID Reader on OS X and Linux, as well as .NET over the webservice
*Fixed bug that could cause the Java Phidget Manager to crash during garbage collection.
===2.1.8.20120131===
*Fixed RFID Reader bug that caused tag event to not get thrown in .NET Applications
*Changed compass bearing calculations in spatial C# example
===2.1.8.20120123===
*Added support for 1061 v300+
*Fixed a bug where the firmware version could be mis-reported over Bonjour
===2.1.8.20111220===
*Fixed a bug in AppleScript where closing a Phidget opened via label would give a 'Connection Invalid' error.
*Fixed a bug where the webservice may fail to start on Linux systems that don't support IPv6 (ie. SBC2).
*Fixed issue where ratiometric state on newest interfacekit wouldn't be read back properly if it was false during attach.
*Fixed webservice issue where ratiometric state would not be reported properly for newest interfacekits
*Increased the number of overrun errors ignored during initial attach for InterfaceKit.
*Fixed an issue with the iPhone library and header
===2.1.8.20111219===
*fixed various other webservice stability/performance/memory leak bugs
*Faster connection to SBC-connected Phidgets from Mac OS
*Don't report packetlost or overrun errors that happen during early initialization - these are just noise.
*Fixed a bug in the webservice tree removal function that could cause memory leaks.
*Fixed bug where Webservice would crash on Linux if the chosen serverID was already under use on the network
*Stopped sending hardware Error Events before the Attach event - they are now queued up and sent after Attach
*Fixed a crash in the [[Phidget Control Panel]]
*Added ability to remove dictionary keys from a key change listener
*Reduced the number of false 'pending command not finished' error events on Close()
*Fixed a webservice bug where exceptions/false attach events could occur when close() is called soon after open
*Fixed bug where closing a PhidgetRFID soon after attach could cause a crash
*Fixed webservice but on MacOS where client could exit with SIG_PIPE error
*Fixed webservice bug where the server would sometimes exit(1) after many connect/disconnect cycles
*Fixed webservice bug where client could deadlock during close()
*Fixed webservice bug where opening a single remote phidget multiple times from the same application would fail
*Fixed a webservice bug where sockets weren't being closed properly sometimes
*Fixed a webservice bug where pre-attach error events wouldn't get through
*Fixed a bug where the webservice running on Linux would stop responding to clients after ~300 connect/disconnect cycles
*Fixed bug where a Phidget would become inaccessible until the app is restarted if a thread creation failed
*Fixed webservice bug where connect is slow on Windows when multiple clients are running simultaneously
*Fixed webservice bug where authentication would fail on a valid password
*Fixed webservice bug where attach may never happen, and would require a close()/open()

===2.1.8.20111121===
*Added support for new servo types to all libraries
*Fixed min/max position/velocity causing invalid arg exception on servo/advservo
*IPv6 support on MacOS
*Fixed some memory leaks
*Fixed hostname lookup issue on Mac OS with Back To My Mac enabled.
===2.1.8.20111028===
*Fixed Applescript bugs and released examples
*Added openLabel to .NET, Java, COM
*Setting change trigger to 0 on interfacekit will not set event mode.
**Previously setting change trigger to 0 after setting data rate would supersede the data rate setting, which is probably unexpected.
===2.1.8.20110630 - MacOS Only===
*handle USB bug introduced in MacOS 10.6.8
===2.1.8.20110615===
*Added error event when trying to open Phidgets with an unsupported version
===2.1.8.20110614 - Windows Only===
*Fixed bug in C# Spatial example
*Added support for negative gains in 1056
===2.1.8.20110601 - MacOS Only===
*Fixed AppleScript issues
===2.1.8.20110527===
*Fixed AS3.0 library (Flash/Flex) - wouldn't connect to webservice as of last release
*Fixed bug where webservice doesn't release a closed Phidget
*Fixed bug where devices that don't support label didn't show up on MacOS
*Fixed iPhone library issues
===2.1.8.20110524===
*AppleScript support added
*fixed problem with Spatial in .NET on 64-bit Windows
*Added remote setLabel to mac preference pane.
*fixed a bug where label characters 7,8,9 would be read back corrupted on certain devices.
**labels >7 characters that exhibit this bug will now be truncated to 7 characters when being read back
**call setLabel again using this library or newer to support 10 character labels.
**To maintain compatibility with older library versions, limit labels to <=7 characters on these devices.
*fixed bug on MacOS where serial number and/or label strings could be read wrong.
*better support for recovering misbehaving devices in Linux
*fixed a deadlock on linux when Avahi is installed but not running
*clear list of attached devices when closing remote manager
*Added support for Unicode labels
**To maintain compatibility with older library versions, limit labels to ASCII.
*Added open by label
*Webservice protocol version up to 1.0.9 (for open by label)
*Made opening multiple device is one application faster.
*TextLCD changes:
**cursor is disabled while writing to the display or setting a custom character to prevent display artifacts
**cursor is disabled when a full line is written so it doesn't go to the start of another line
**1204 should be stable
**setDisplayCharacter supports 0x00-0xff
*stopped property reflected more accurately in the C# stepper example
*Added error events to mac examples
===2.1.8.20110329 - Windows only===
*Fixed problem with control panel encoder example where enable wouldn't work
*Fixed issue with SpatialData, GPSPositionChange, PHChange and WeightChange events in Labview 64-bit
===2.1.8.20110322===
*Fixed [[Phidget Control Panel]] memory leak when Bonjour in installed but not running
*Fixed current sense formula on 1061_0 v200
*Fixed bug in webservice protocol while using the PhidgetAdvancedServo
*Fixed bug in old PhidgetTemperatureSensor

===2.1.8.20110310===
*Fixed bug in webservice protocol while using the PhidgetServo
*Fixed some Labview bugs
*Added some Java and VB.NET examples
===2.1.8.20110301===
*Full Support for 1002, 1011, 1040, 1046, 1054, 1065, 1204
*New webservice version - 1.0.8
**Support for new devices
**Support for error events
===2.1.7.20110203===
*fixed crash on close of remote Phidget on MacOS
*C# ifkit example bugfix - crashed on 1015/1016
*webservice improvements
*Switch to IP address for SBC config in browser
*Faster IP lookup for SBCs in control panel
===2.1.7.20101222 / 2.1.7.20101223===
*fixed getServerID on Linux
*removed report ack
**this was causing some bad side effects
*manual .local lookups on Windows
**much faster then letting Windows do it itself
*Support for new Labview library
*Fixed PhidgetIR bug where library would crash if repeat code is longer then IR_MAX_REPEAT_LENGTH
===2.1.7.20101103===
*Decreased Phidget Webservice event latency on Windows
*Preliminary support for 1002, 1011, 1040, 1045, 1046, 1054, 1065, 1204 (C, .NET)
*Webservice version updated to 1.0.7
**support for 1045, 1011, 1204
*Fixed a bug where webservice connections could be unexpectedly lost
*Bugfix: couldn't set interfacekit data rate over webservice.
*Fixed some memory leaks in the Mac library
*Fixed bug where blocking for >2 seconds in an events handler when opening remotely could cause a crash.
===2.1.7.20100803===
*Windows only release
*fixed setLabel in WindowsCE
*fixed getHashCode in .NET library - needed for working with Phidgets in Labview via .NET
===2.1.7.20100621===
*Linux only release - autotools updates
**call ldconfig automatically
**remove old phidget21 library (pre-autotools) when installing new one.
===2.1.7.20100620===
*Linux only release - added version.sh for autoreconf
===2.1.7.20100618===
*Linux only release - added udev/hotplug files
===2.1.7.20100617===
*Linux only release
*Transitioned to autotools in linux for phidget21 / webservice
*phidget21 library and webservice are now separate downloads
===2.1.7.20100525===
*full support for PhidgetSpatial and PhidgetIR in all libraries
*fixed 1031 not attaching in AS3.0
*Better error messages in JNI
*Updated error codes, device ID/Class lists in Java, Flash, COM, etc.
*Fixed TemperatureSensor version 200,201,202 bug - ambient sensor would not report negative temperatures.
*Revised temperaturesensor API to report tempMin/tempMax and errors more accurately.
*Added initial events for encoder digital inputs
*full support for 1047
*Added new device support to WindowsCE
*Updated mac examples for 1047, 1048
===2.1.6.20100504===
*Windows only Release
**Added 1131 and 1132 to InterfaceKit example in MSI
===2.1.6.20100428===
*limit data rate maximum to 16ms over the webservice for devices that expose dataRate (InterfaceKit, Spatial)
*fixed bug where TextLCD 8/8/8 would stay in Bonjour list after webservice is shutdown
*set/get Brightness for 1203_2
*Support 1048 in C# example
*webservice version incremented to 1.0.6
**TextLCD set/get brightness
**PhidgetIR support
**PhidgetSpatial support
**1047 support (enable, index)
===2.1.6.20100406===
*Support for 1018_2 (dataRate)
*Webservice version incremented to 1.0.5
===2.1.6.20100401===
*Updated InterfaceKit example with new sensors
*make Windows connect cancelable
*make pending zeroconf lookups cancelable during close
===2.1.6.20100318===
*Mac only release
**Added WillSleep and Wakeup events to give user control of Phidgets immediately before and after a system sleep (MacOS Only).
===2.1.6.20100317===
*Windows only release
**Some of the examples were being built using an out of date .NET library
===2.1.6.20100310===
*MaxMSP fix - 2.1.6.20100126 introduced a bug for some Phidgets where openremote/open by serial didn't work and MaxMSP would sometimes crash.
**No code changes to any of the other libraries.
===2.1.6.20100304===
*stopped property changes trigger events over webservice so they are noticed.
**more compatible with how local open works
*added 5 new servos
*fixed bug where remote close would not set detached so a subsequent open would not always connect.
*handle UninitializeZeroconf better - shut down thread before closing handles, fixes hang on SBC
*fixed bug on Mac where detaching 2 or more Phidgets at the same time caused a crash
*fixed close blocking because of a pending connect (mac, linux)
*Final support for 1031 in all libraries.
===2.1.6.20100129===
*Implemented initial events in Flash
**Flash behaviour should now be identical to C library local and remote.
*Fix RFID issue where close could cause crash
*increment webservice version to 1.0.4
*fixed RFID remote open
**Flash would never get an attach event if the reader had been previously opened
**Initial tag event would not be fired when a tag was present and the antenna was enabled prior to open
*fixed openRemote failing on Mac
*fixed deadlock in webservice which could be hit by opening/closing a device over and over again.
*fixed bug in stepper, which caused seg fault on SBC on position change events.
===2.1.6.20100126===
*added network open support in Max/MSP
===2.1.6.20100115===
*Increased network performance for Linux/MacOS
*Added five servo types
===2.1.6.20091215===
*Fixed busy loop in Linux openRemote
*JNI Library relocated to /Library/Java/Extensions on MacOS
===2.1.6.20091211===
*Heartbeat now works on Linux as well (had to make sockets non-blocking)
===2.1.6.20091130===
*Added heartbeat to webservice (client side)
**Better detects network failures by using active polling timeouts
*Fixed 0/8/8 over webservice
===2.1.6.20091020===
*Fixed 1052 counting issue on 1070 (-1 reported as 255)
*Fixed issue where Phidget21 would try to reinstall from a limited user account or when the Control Panel was disabled.
*64-bit kernel support in Snow Leopard
===2.1.6.20090928===
*Support for PhidgetSBC (1070)
*zeroconf can handle starting up before the mdns daemon, and will keep trying to connect.
*fixed 1066 not showing up on Mac
*added advanced servo example to mac pref pane
*implemented proper error handling in COM
**default behavious remains the same, enable proper error handling with 'EnableVerboseErrors'
*implemented error events in Java
===2.1.6.20090917===
*Updated webservice protocol version to 1.0.3
*Fixed stepper under AS3.0
*added setServoType, getServoType, setServoParameters to PhidgetServo and PhidgetAdvancedServo
*possible race condition fixed in webservice (pdictclient.c:907)
===2.1.6.20090902 (mac only release)===
*Support MacOSX 10.6, drop support for 10.3.9, require 10.4 or newer
**Fully 64-bit compliant, library supports ppc, i386, x86_64
===2.1.6.20090806===
*Added 1049 support
*Fixed RFID tag events over webservice
===2.1.6.20090804===
*Added 1051_2 support
*Fixed various small initialization issues - stepper, adv servo, rfid
*Added 32-bit library install to 64-bit installer
**VB6.0, etc. need the 32-bit COM library on 64-bit windows
===2.1.6.20090717===
*?
===2.1.6.20090708===
*Added DeviceID to zeroconf
*fixed RFID.LastTag in .NET
*Changed the error codes returned by error events; error events now have their own set of error codes rather then sharing the function return codes.
*Added support for 1047, 1048
*Added error event codes rather then trying to reuse the EPHIDGET return codes.
*fixed TextLCD issue where display could get corrupted during a detach/attach
*made mac more reliable on attach
*more error logging on mac
===2.1.6.20090525===
*fixed RFID not attaching via webservice if a tag is present.
*bugfix related to double free on detach event.
*Implemented getKey
*Added MIPS II support to Windows CE
===2.1.6.20090430===
*Added ActiveX interface to COM library
*Added stepper and advancedServo to Flex .swc library
===2.1.6.20090417===
*added PhidgetIR prototype support to C library
*properly handles sleeping on OSX
*fixed some webservice field initializations in Flash and C
*fixed security exceptions in [[Phidget Control Panel]] under Vista
*added [[Phidget Control Panel]] to start menu

===2.1.6.20090318 (Examples/AS3.0 only release)===
*Fixed AdvancedServo in Flash - wouldn't attach
===2.1.6.20090317===
*[[Phidget Control Panel]] properly supports Vista UAC and Limited user accounts in XP, etc.
*Added 64-bit release of Phidget21.msi for Windows

===2.1.6.20090312===
*added 1064, 1059 to WindowsCE
*fixed opening 1051 over webservice
*fixed opening 1015/1016 over webservice broken in last release
===2.1.6.20090302===
*Advanced servo bugfix: stopped would stop being true if min/max was set to exclude current position.
*linux USB improvements when many Phidgets are attached and opened at once.
*1031 support in phidget21, webservice, .NET - hidden until product release
**CPhidgetLED_setVoltage
**CPhidgetLED_getVoltage
**CPhidgetLED_setCurrentLimit
**CPhidgetLED_getCurrentLimit
*unknown timechange == PUNK_INT in encoder position change event
**1st position change event
**> 30 seconds time change
*AS3 updates
**updated to 1.0.2 webservice
**encoder position change events report relative change rather then absolute position
**encoder adds getTimeChange function for timing encoder changes
*webservice updated to 1.0.2
**Authorization is asynchronous
**Doesn't match the old version checking, so errors will not be nice when trying to connect to an old webservice
**Sends out all initial data, so it's just like opening locally
**supports interfacekit Raw sensor value
**supports labels on remoteIP managers
*avahi bugfix
*webservice more stable against forcefully closed clients
*closing a network Phidget won't block - ever.
**no longer using quit, just closing the socket
*added libavahi-client.so.3 reference to linux library.
*Fixed bug with opening one phidget with serial and no serial at the same time over the webservice
===2.1.5.20090105===
*[[Phidget Control Panel]] stability improvements
*added CPhidgetSBC_getHostname
*advanced servo 1 motor current sense equation - support should now be complete
*webservice and network code bugfixes - crash / deadlock during close, problems with concurrent connections, etc.
*fixed close on remote and remoteIP managers
*name of RFID changed from "Phidget RFID 4-output" to "Phidget RFID 2-output" - updated anything referencing old name.

===2.1.5.20081023===
*added advanced servo and stepper examples to VB6.0, VB.NET and C
*added deviceClass and deviceID
*updated Mac examples
*webservice protocol version enforcement
*internal fix/rework of device id's etc.
*Fixed memory leaks in webservice and phidget21 network code.
*Dictionary and network stability improvements.
*duplicate calls to open or close are now silently ignored.
===2.1.4.20080924===
*Old TextLCD 0/8/8's can now have both halves open at the same time on Windows
*fixed bug with composite devices on linux
*fixed manager on linux to better deal with unique devices
===2.1.4.20080922===
*Updated Delphi files
*TextLCD can display 0x80-0xFF characters from Java
*getAttachedDevices works for mdns managers
*fixed a deadlock in the webservice
*better network error handling / password support for windows C# examples
*waitForAttachment will return EPHIDGET_CLOSED if the handle is closed while it is waiting.
*added EPHIDGET_CLOSED
*joining central threads checks whether they are trying to be joined by themselves first (avoid deadlocks).
*changed context of error event to be free from locks (can call close, open, etc. from them).
===2.1.4.20080821===
*zeroconf threads exit cleanly on last _close (apple zeroconf)
*Added advanced servo and stepper to Max
===2.1.4.20080811 (mac only release)===
*Fixed manager on Mac (wasn't working at all since 2.1.4.20080808)
===2.1.4.20080808===
*added CPhidgetSBC and CPhidgetSBCManager to the c library - these interfaces are hidden from users and meant to be used internally (for now).
*CPhidgetManager_open no longer blocks to send out initial attach events. These initial events are sent from the CentralThread context like all other attach events.
*fixed CThread_wait_on_event on Linux
*added CPhidgetGeneric interface for prototyping to C, .NET libraries. product ID is 0x99. These are only visible in debug releases, only to be used internally.
===2.1.4.20080715===
*udev rules fixed for product IDs with alpha-hex values
*blocking in an attach event does not block calls to open anymore
*RFID tag event handlers can now handle blocking - tag lost is timed after the tag handler exits.
===2.1.4.20080623===
*Flex .swc library was out of sync
*fixed CPhidgetManager_getAttachedDevices for network managers
*Added CPhidgetManager_freeAttachedDevicesArray
===2.1.4.20080613===
*Max/MSP RFID fixed
*0/0/8 and advanced servo added to CE
*fixed flash policy file server in webservice
*webservice with password and asynchronous together work now
===2.1.4.20080602===
*phidget21.h -> phidget21int.h so as not to be confused with generated phidget21.h
*some changes to Makefile fro crosscompiling
*no more vbscript in msi
===2.1.4.20080513===
*removed long long from COM - not supported by VB6.0
*added LastTag to RFID in .NET
===2.1.4.20080428===
*support Mac OS X 10.3.9 again
*Rev up to 2.1.4
*finalize Phidget Stepper API - Phidget Stepper requires 2.1.4 as a minimum
*fixed serverConnect and serverDisconnect handlers for manager and dictionary in COM
*Changed:
**PhidgetStepper and PhidgetAdvancedServo
***MotorPosition -> Position
***MotorOn -> Engaged
***MotorStopped -> Stopped
*Added:
**CPhidgetStepper_getCurrentLimit
**CPhidgetEncoder_getPosition
**CPhidgetEncoder_setPosition
**CPhidgetMotorControl_getVelocity
**CPhidgetMotorControl_setVelocity
**CPhidgetMotorControl_set_OnVelocityChange_Handler
**CPhidgetServo_setEngaged
**CPhidgetServo_getEngaged
**CPhidgetServo_getPosition
**CPhidgetServo_setPosition
**CPhidgetServo_set_OnPositionChange_Handler
**CPhidgetServo_getPositionMax
**CPhidgetServo_getPositionMin
**Count functions
*Deprecated:
**CPhidgetEncoder_getEncoderPosition
**CPhidgetEncoder_setEncoderPosition
**CPhidgetMotorControl_getMotorSpeed
**CPhidgetMotorControl_setMotorSpeed
**CPhidgetMotorControl_set_OnMotorChange_Handler
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
**CPhidgetServo_getMotorPosition
**CPhidgetServo_setMotorPosition
**CPhidgetServo_set_OnMotorPositionChange_Handler
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**Num functions
*Added ability to deprecate funcitons in the C library - compiler will issue a warning when they are used.
*added names to some arguments in phidget21.h
*fixes to the webservice for initial state stuff - now it behaves almost like non-webservice, with guaranteed initial events, but we don't guarantee initial state in the attach event yet. Min/Max, Num motors, inputs, etc. are all guaranteed in the attach handler.
*Finalized support for Phidget Stepper
===2.1.3.20080402===
*Fixed windows BUG - Device Type was showing up wrong
*CPhidgetStepper_getPosition -> CPhidgetStepper_getCurrentPosition
===2.1.3.20080327===
*added:
**CPhidgetAdvancedServo_setMotorPositionMax
**CPhidgetAdvancedServo_setMotorPositionMin
**CPhidgetAdvancedServo_getMotorStopped
*changes to API
**CPhidgetStepper_setMotorPosition -> CPhidgetStepper_setTargetMotorPosition
**added CPhidgetStepper_getTargetMotorPosition
**Stepper MotorSpeed -> Velocity
**Stepper and AdvancedServo MaxVelocity -> VelocityLimit
*add waitForAttachment to COM
*COM getbool (not indexed) will now return FALSE on false (rather then always returning true)
*fixed write thread timeouts - was setting attached after starting write thread so write thread would see a detached device and exit immediately
===2.1.3.20080206===
*changed long long to __int64, to be happy in borland C++
*added:
**CPhidgetStepper_getMaxMotorSpeed
**CPhidgetStepper_setMotorOn
**CPhidgetStepper_getMotorOn
**CPhidgetStepper_getMotorStopped
**CPhidgetStepper_setCurrentMotorPosition
*removed CPhidgetStepper_setVelocity
*added CPhidgetStepper_setMaxVelocity, CPhidgetStepper_getMaxVelocity
===2.1.3.20080114===
*Added new functions to Flash API
*Added new functions to Webservice Protocol
*Added new functions to COM Library
*Added new functions to Java Library
*All device fiels in C library cleaned up and made consistent
*Open in windows is exclusive - this needs to be tested for stability
*No data will be returned / accepted if it lies outside of max/min range
*if a data value is unknown, user variable is set to PUNK_INT, PUNK_DBL, or PUNK_BOOL, and return value is EPHIDGET_UNKNOWNVAL
*Proper Device initializations on Attach:
**triggers are set to defaults on attach
**device state is read in and preserved on attach
**during attach event, all sensor data, etc. is provided if available
**no data events until after the attach event returns
**everything initialized by the time waitForAttachment returns
**after attach event returns, a full set of initial state data events are thrown
*.NET collections are readonly, and never NULL (but empty when phidget detached)
*.NET callbacks no longer catch and hide all exceptions
**make sure to use try/catch blocks especially in Attach when accessing properties that may not be initialized.
*added min/max functions:
**CPhidgetAccelerometer_getAccelerationMax
**CPhidgetAccelerometer_getAccelerationMin
**CPhidgetAdvancedServo_getAccelerationMax
**CPhidgetAdvancedServo_getAccelerationMin
**CPhidgetAdvancedServo_getVelocityMax
**CPhidgetAdvancedServo_getVelocityMin
**CPhidgetAdvancedServo_getMotorPositionMax
**CPhidgetAdvancedServo_getMotorPositionMin
**CPhidgetMotorControl_getAccelerationMax
**CPhidgetMotorControl_getAccelerationMin
**CPhidgetPHSensor_getPHMax
**CPhidgetPHSensor_getPHMin
**CPhidgetPHSensor_getPotentialMax
**CPhidgetPHSensor_getPotentialMin
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**CPhidgetStepper_getAccelerationMax
**CPhidgetStepper_getAccelerationMin
**CPhidgetStepper_getMotorSpeedMax
**CPhidgetStepper_getMotorSpeedMin
**CPhidgetStepper_getMotorPositionMax
**CPhidgetStepper_getMotorPositionMin
**CPhidgetTemperatureSensor_getPotentialMax
**CPhidgetTemperatureSensor_getPotentialMin
**CPhidgetTemperatureSensor_getAmbientTemperatureMax
**CPhidgetTemperatureSensor_getAmbientTemperatureMin
**CPhidgetTemperatureSensor_getTemperatureMax
**CPhidgetTemperatureSensor_getTemperatureMin
*Added functions:
**CPhidgetTemperatureSensor_getAmbientTemperature
**CPhidgetTemperatureSensor_getThermocoupleType
**CPhidgetTemperatureSensor_setThermocoupleType
**CPhidget_set_OnServerConnectHandler
**CPhidget_set_OnServerDisconnectHandler
**CPhidgetDictionary_set_OnServerConnectHandler
**CPhidgetDictionary_set_OnServerDisconnectHandler
**CPhidgetManager_set_OnServerConnectHandler
**CPhidgetManager_set_OnServerDisconnectHandler
**CPhidgetDictionary_getServerID
**CPhidgetDictionary_getServerAddress
**CPhidgetDictionary_getServerStatus
**CPhidgetManager_getServerID
**CPhidgetManager_getServerAddress
**CPhidgetManager_getServerStatus
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
*Removed functions:
**CPhidgetServo_setMotorOff
*TemperatureSensor:
**Ambient sensor is accessed with it's own function
**first thermocouple is Index 0 everywhere
**no ambient sensor events
*getServerID is implemented
*changed the internal network structure (added CPhidgetRemote)
*reworked the USB code (mostly on Windows)
**Better handles closing, ESD events, timeouts
**fixed issues with Encoder, RFID stopping reading after a certain time.
**added USB error flag
*openRemote functions have been implemented
**these require bonjour (mac / windows) or avahi (linux) to be installed on both the client and server
**if they are not, you get EPHIDGET_UNSUPPORTED when you call them
*openRemoteIP functions are asynchronous and persistent
*include cphidgetconstants.h in phidget21.h for users
===2.1.2.20071108===
*start of chagelog

OS - OS X

2019-02-11T17:22:37Z

Patrick:

[[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.5 Leopard 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:
*OS X 10.7+: [{{SERVER}}/downloads/phidget21/libraries/macos/Phidget.dmg Installer Download]
*Mac OS X 10.5 - OS X 10.6: [{{SERVER}}/downloads/phidget21/libraries/macos/Phidget_OS_X_10_5.dmg Installer Download]
*[[Software License]]

If you need old versions of the libraries, [{{SERVER}}/downloads/phidget21/libraries/macos/Phidget/ click here].

==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/phidget21/libraries/macos/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.5 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===

You can get debugging information from the WebService itself. This 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 - OS X

2019-02-09T16:23:58Z

Patrick:

[[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.5 Leopard 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:
*OS X 10.7+: [{{SERVER}}/downloads/phidget21/libraries/macos/Phidget.dmg Installer Download]
*Mac OS X 10.5 - OS X 10.6: [{{SERVER}}/downloads/phidget21/libraries/macos/Phidget_OS_X_10_5.dmg Legacy Installer Download]
*[[Software License]]

If you need old versions of the libraries, [{{SERVER}}/downloads/phidget21/libraries/macos/Phidget/ click here].

==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/phidget21/libraries/macos/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.5 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===

You can get debugging information from the WebService itself. This 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 - OS X

2019-02-09T16:21:41Z

Patrick:

[[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.5 Leopard 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:
*OS X 10.7+: [{{SERVER}}/downloads/phidget21/libraries/macos/Phidget.dmg Installer Download]
*Mac OS X 10.5 - OS X 10.6: [{{SERVER}}/downloads/phidget21/libraries/macos/Phidget_OX_X_10_5.dmg Legacy Installer Download]

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

If you need old versions of the libraries, [{{SERVER}}/downloads/phidget21/libraries/macos/Phidget/ click here].

==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/phidget21/libraries/macos/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.5 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===

You can get debugging information from the WebService itself. This 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.

Driver Changelog

2019-02-08T23:04:53Z

Patrick:

[[Category:Administrative]]
__NOTOC__

===2.1.9.20190208===
*macOS release
**Fixed USB bug where devices plugged in before boot were inaccessible until unplugged/re-plugged on 2018 Mac Mini.

===2.1.9.20180622===
*Python fix

===2.1.9.20180215===
*Move to .NET 4.0

===2.1.8.20171215===
*macOS release
**Fixed USB bug where opening two of the same device with -1 serial could cause missed attach/detach events and other errors.

===2.1.8.20160921===
*macOS release
**Fixed USB bug where devices plugged in before boot were inaccessible until unplugged/re-plugged, under OS X 10.11.

===2.1.8.20160202===
*Windows release
**Labview 7.1 support

===2.1.8.20160107===
*Windows release
**Don't throw an exception on EncoderPositionChangeEventArgs.Time in the .Net library when time it unknown - just return 0x7fffffff

===2.1.8.20160104===
*Mac/Windows release
**New firmware for 1042 and 1044, fixing digital gyro
===2.1.8.20151217===
*Fixed 1045 bug where it will display an unknown ambient temperature sometimes
*Fixed a crash in the windows control panel

===2.1.8.20151020===
*Windows release
**Fixed an issue where the examples would error when trying to run them from the control panel.

===2.1.8.20151009===
*OS X and Windows release
**Upgraded firmware for 1024, 1032, 1041, 1042, 1043, 1044 and 1067 to address issues with these Phidgets on OS X El Capitan
*SBC release
**Support for multiple webcams
===2.1.8.20150821===
*OS X-only release
**Support OS X 10.11 El Capitan
===2.1.8.20150805===
*OS X-only release
**Preliminary support for OS X 10.11 El Capitan
===2.1.8.20150410===
*Linux-only release
**Fixed Makefile phidget21.h target issues
===2.1.8.20150326===
*Windows-only release
**Fixed issue with webservice buttons not being visible in the control panel
===2.1.8.20150323===
*Windows-only release
**Updated icons with new company logo
===2.1.8.20150227===
*Linux-only release
**Added copyright/licence headers to source code files
**Updated cvtutf files to a newer version
===2.1.8.20150109===
*Windows-only
**Fixed examples for Labview 8.5
===2.1.8.20141209===
*OS X-only release
**Added support for armv7s and arm64 to the iOS library. Dropped support for armv6. Requires iOS 5.1.1 or later.
===2.1.8.20141202===
*Windows-only release
**Labview release to support older versions
===2.1.8.20141119===
*OS X-only release
**Fixed an issue with the 2.1.8.20141117 release where nothing was actually installed.
===2.1.8.20141117===
*OS X-only release
**Fixed a code-signing issue that make the installer appear unsigned on OS X 10.10
**Dropped support for OS X 10.4
===2.1.8.20140905===
*Windows-only release
**Added an IA32 folder to the windows libraries download - this supports Windows on the Intel Galileo platform
===2.1.8.20140428===
*Windows-only release
**Fixes to C# Stepper GUI Example
===2.1.8.20140319===
*CPhidget_getDeviceClass can now be called on handle before it is attached.
*Added support for 64-bit Max/MSP (Version 6.1+) on both OS X and Windows.
===2.1.8.20140227===
*Deals with 1046 bug in v100 and v101 firmware.
**No longer reports bad values that appear right after a channel is enabled.
**Fixes issue where changing the gain while channel 0 is disabled would sometimes cause bad readings.

===2.1.8.20131105===
* Fixed a defect in the Flash examples for the 1012 (Outputs 11-16 were not addressed properly).

===2.1.8.20130926===
*Windows-only release
**Support setting label on 1067 from Windows
===2.1.8.20130820===
*Windows-only release
**Added logging option to control panel / C# full examples
===2.1.8.20130802===
*Windows-only release
**Fix for Windows 8 issue where only 'Uninitialized Phidget Handle' would show up in the Manager, and Phidgets could not be opened.
===2.1.8.20130723===
*Improvement to java: we don't attach/detach our native threads for each event, just one attach, then detach before the thread exits.
**This increases performance, esp. when debugging on Android.
*Improvement to Android: We reuse the UsbRequest object rather then creating a new one for each transfer. This reduces logcat messages tremendously, and increases performance.
===2.1.8.20130710===
*Android-only release
**Added extra android target architectures: x86, MIPS, armeabi-v7a
===2.1.8.20130618===
*Changed setCompassCorrectionParameters() API call so that compass calibration parameters are written out to non-volatile storage on 1042/1044, so that they persist across power cycles. Previously, calibration data would need to be re-programmed at each attach.
*Changes to C# Spatial example:
**Compass calibration parameter set dialog removed from for 1042/1044 because parameters are set by the calibration software - and thus do not need setting in the example.
**Stores/restores parameters for 1056 based on serial number, so multiple different calibrations can be maintained.
===2.1.8.20130607===
*Windows-only release
**Fixes to compass calibration software for 1042/1044
===2.1.8.20130419===
*Windows-only release
**Fixed setCompassCorrectionParameters in the COM library
===2.1.8.20130327===
*Windows-only release
**Changed Windows installer to stop virus-scanner false positives
**Dropped support for Windows 2000
===2.1.8.20130320===
*Added EPHIDGET_NOTFOUND exception to Dictionary.getKey() for when the key is not found.
*Added exceptions back into the Java library - they have been missing since 2.1.8.20121015 release.
===2.1.8.20130313===
*Updates to Matlab support
**Works properly on Matlab 7+, on Windows, Mac, Linux without needing changes to .m files.
===2.1.8.20130221===
*Windows-only release
**Encoder Index event added to C and .NET libraries
===2.1.8.20121218===
*Webservice version: 1.0.10
**Support for 1024, 1032
*Support for 1024, 1032
*fixed bug where if one half of a composite device is open, and PHIDGET_USB_ERROR_FLAG gets set, the device may never re-attach.
===2.1.8.20121015===
*Windows-only release
**Support for new pressure/light sensors in example.
===2.1.8.20120914===
*Windows-only release
**Improved firmware upgrading in control panel - it was giving some false-errors on some machines.
===2.1.8.20120912===
*Fixed bug where 1065 could fail to attach when opened over webservice
*Fixed bug where close() could deadlock on Phidgets opened over the webservice
*Changed LED64 LED Brightness from int to double
**this may cause issues when controlling the LED64 over the webservice and library/webservice are not the same version
**the old setDiscreteLED call will remain, deprecated, with an int argument for compatibility.
===2.1.8.20120716===
*Linux-Only Release
**Fixed a bug where opening a device in two program at once would cause an attach-detach cycle as they fight each other for control.
===2.1.8.20120713===
*Mac-Only Release
**Added signing of the Mac installer, so Mountain Lion (OS X 10.8) doesn't refuse to run it.
===2.1.8.20120615===
*Windows-only release
**Fixed a bug that caused java to crash on events introduced in 2.1.8.20120612
===2.1.8.20120612===
*Windows-only release
**Fixed another bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120606===
*Windows-only release
**Fixed a bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120525===
*Windows-only release
**Fixed PhidgetIR sendRawData bug in .NET on 64-bit machines.
===2.1.8.20120514===
*Linux-only release
**Fixed a bug that causes a segfault with libusb-1.0 under 64-bit Linux.
===2.1.8.20120507===
*Mac/Linux-only release
**Fixes a setLabel bug introduced in 2.1.8.20120503
===2.1.8.20120503===
*Fixed some spelling mistakes
*Moved to libusb-1.0
**This resolves a bug where having a webcam plugged in caused a memory leak in the webservice.
*Fixed bug with advanced servo where setting acceleration to accelerationMax would cause an exception for some servo types
===2.1.8.20120216===
*Fixed bug with RFID Reader on OS X and Linux, as well as .NET over the webservice
*Fixed bug that could cause the Java Phidget Manager to crash during garbage collection.
===2.1.8.20120131===
*Fixed RFID Reader bug that caused tag event to not get thrown in .NET Applications
*Changed compass bearing calculations in spatial C# example
===2.1.8.20120123===
*Added support for 1061 v300+
*Fixed a bug where the firmware version could be mis-reported over Bonjour
===2.1.8.20111220===
*Fixed a bug in AppleScript where closing a Phidget opened via label would give a 'Connection Invalid' error.
*Fixed a bug where the webservice may fail to start on Linux systems that don't support IPv6 (ie. SBC2).
*Fixed issue where ratiometric state on newest interfacekit wouldn't be read back properly if it was false during attach.
*Fixed webservice issue where ratiometric state would not be reported properly for newest interfacekits
*Increased the number of overrun errors ignored during initial attach for InterfaceKit.
*Fixed an issue with the iPhone library and header
===2.1.8.20111219===
*fixed various other webservice stability/performance/memory leak bugs
*Faster connection to SBC-connected Phidgets from Mac OS
*Don't report packetlost or overrun errors that happen during early initialization - these are just noise.
*Fixed a bug in the webservice tree removal function that could cause memory leaks.
*Fixed bug where Webservice would crash on Linux if the chosen serverID was already under use on the network
*Stopped sending hardware Error Events before the Attach event - they are now queued up and sent after Attach
*Fixed a crash in the [[Phidget Control Panel]]
*Added ability to remove dictionary keys from a key change listener
*Reduced the number of false 'pending command not finished' error events on Close()
*Fixed a webservice bug where exceptions/false attach events could occur when close() is called soon after open
*Fixed bug where closing a PhidgetRFID soon after attach could cause a crash
*Fixed webservice but on MacOS where client could exit with SIG_PIPE error
*Fixed webservice bug where the server would sometimes exit(1) after many connect/disconnect cycles
*Fixed webservice bug where client could deadlock during close()
*Fixed webservice bug where opening a single remote phidget multiple times from the same application would fail
*Fixed a webservice bug where sockets weren't being closed properly sometimes
*Fixed a webservice bug where pre-attach error events wouldn't get through
*Fixed a bug where the webservice running on Linux would stop responding to clients after ~300 connect/disconnect cycles
*Fixed bug where a Phidget would become inaccessible until the app is restarted if a thread creation failed
*Fixed webservice bug where connect is slow on Windows when multiple clients are running simultaneously
*Fixed webservice bug where authentication would fail on a valid password
*Fixed webservice bug where attach may never happen, and would require a close()/open()

===2.1.8.20111121===
*Added support for new servo types to all libraries
*Fixed min/max position/velocity causing invalid arg exception on servo/advservo
*IPv6 support on MacOS
*Fixed some memory leaks
*Fixed hostname lookup issue on Mac OS with Back To My Mac enabled.
===2.1.8.20111028===
*Fixed Applescript bugs and released examples
*Added openLabel to .NET, Java, COM
*Setting change trigger to 0 on interfacekit will not set event mode.
**Previously setting change trigger to 0 after setting data rate would supersede the data rate setting, which is probably unexpected.
===2.1.8.20110630 - MacOS Only===
*handle USB bug introduced in MacOS 10.6.8
===2.1.8.20110615===
*Added error event when trying to open Phidgets with an unsupported version
===2.1.8.20110614 - Windows Only===
*Fixed bug in C# Spatial example
*Added support for negative gains in 1056
===2.1.8.20110601 - MacOS Only===
*Fixed AppleScript issues
===2.1.8.20110527===
*Fixed AS3.0 library (Flash/Flex) - wouldn't connect to webservice as of last release
*Fixed bug where webservice doesn't release a closed Phidget
*Fixed bug where devices that don't support label didn't show up on MacOS
*Fixed iPhone library issues
===2.1.8.20110524===
*AppleScript support added
*fixed problem with Spatial in .NET on 64-bit Windows
*Added remote setLabel to mac preference pane.
*fixed a bug where label characters 7,8,9 would be read back corrupted on certain devices.
**labels >7 characters that exhibit this bug will now be truncated to 7 characters when being read back
**call setLabel again using this library or newer to support 10 character labels.
**To maintain compatibility with older library versions, limit labels to <=7 characters on these devices.
*fixed bug on MacOS where serial number and/or label strings could be read wrong.
*better support for recovering misbehaving devices in Linux
*fixed a deadlock on linux when Avahi is installed but not running
*clear list of attached devices when closing remote manager
*Added support for Unicode labels
**To maintain compatibility with older library versions, limit labels to ASCII.
*Added open by label
*Webservice protocol version up to 1.0.9 (for open by label)
*Made opening multiple device is one application faster.
*TextLCD changes:
**cursor is disabled while writing to the display or setting a custom character to prevent display artifacts
**cursor is disabled when a full line is written so it doesn't go to the start of another line
**1204 should be stable
**setDisplayCharacter supports 0x00-0xff
*stopped property reflected more accurately in the C# stepper example
*Added error events to mac examples
===2.1.8.20110329 - Windows only===
*Fixed problem with control panel encoder example where enable wouldn't work
*Fixed issue with SpatialData, GPSPositionChange, PHChange and WeightChange events in Labview 64-bit
===2.1.8.20110322===
*Fixed [[Phidget Control Panel]] memory leak when Bonjour in installed but not running
*Fixed current sense formula on 1061_0 v200
*Fixed bug in webservice protocol while using the PhidgetAdvancedServo
*Fixed bug in old PhidgetTemperatureSensor

===2.1.8.20110310===
*Fixed bug in webservice protocol while using the PhidgetServo
*Fixed some Labview bugs
*Added some Java and VB.NET examples
===2.1.8.20110301===
*Full Support for 1002, 1011, 1040, 1046, 1054, 1065, 1204
*New webservice version - 1.0.8
**Support for new devices
**Support for error events
===2.1.7.20110203===
*fixed crash on close of remote Phidget on MacOS
*C# ifkit example bugfix - crashed on 1015/1016
*webservice improvements
*Switch to IP address for SBC config in browser
*Faster IP lookup for SBCs in control panel
===2.1.7.20101222 / 2.1.7.20101223===
*fixed getServerID on Linux
*removed report ack
**this was causing some bad side effects
*manual .local lookups on Windows
**much faster then letting Windows do it itself
*Support for new Labview library
*Fixed PhidgetIR bug where library would crash if repeat code is longer then IR_MAX_REPEAT_LENGTH
===2.1.7.20101103===
*Decreased Phidget Webservice event latency on Windows
*Preliminary support for 1002, 1011, 1040, 1045, 1046, 1054, 1065, 1204 (C, .NET)
*Webservice version updated to 1.0.7
**support for 1045, 1011, 1204
*Fixed a bug where webservice connections could be unexpectedly lost
*Bugfix: couldn't set interfacekit data rate over webservice.
*Fixed some memory leaks in the Mac library
*Fixed bug where blocking for >2 seconds in an events handler when opening remotely could cause a crash.
===2.1.7.20100803===
*Windows only release
*fixed setLabel in WindowsCE
*fixed getHashCode in .NET library - needed for working with Phidgets in Labview via .NET
===2.1.7.20100621===
*Linux only release - autotools updates
**call ldconfig automatically
**remove old phidget21 library (pre-autotools) when installing new one.
===2.1.7.20100620===
*Linux only release - added version.sh for autoreconf
===2.1.7.20100618===
*Linux only release - added udev/hotplug files
===2.1.7.20100617===
*Linux only release
*Transitioned to autotools in linux for phidget21 / webservice
*phidget21 library and webservice are now separate downloads
===2.1.7.20100525===
*full support for PhidgetSpatial and PhidgetIR in all libraries
*fixed 1031 not attaching in AS3.0
*Better error messages in JNI
*Updated error codes, device ID/Class lists in Java, Flash, COM, etc.
*Fixed TemperatureSensor version 200,201,202 bug - ambient sensor would not report negative temperatures.
*Revised temperaturesensor API to report tempMin/tempMax and errors more accurately.
*Added initial events for encoder digital inputs
*full support for 1047
*Added new device support to WindowsCE
*Updated mac examples for 1047, 1048
===2.1.6.20100504===
*Windows only Release
**Added 1131 and 1132 to InterfaceKit example in MSI
===2.1.6.20100428===
*limit data rate maximum to 16ms over the webservice for devices that expose dataRate (InterfaceKit, Spatial)
*fixed bug where TextLCD 8/8/8 would stay in Bonjour list after webservice is shutdown
*set/get Brightness for 1203_2
*Support 1048 in C# example
*webservice version incremented to 1.0.6
**TextLCD set/get brightness
**PhidgetIR support
**PhidgetSpatial support
**1047 support (enable, index)
===2.1.6.20100406===
*Support for 1018_2 (dataRate)
*Webservice version incremented to 1.0.5
===2.1.6.20100401===
*Updated InterfaceKit example with new sensors
*make Windows connect cancelable
*make pending zeroconf lookups cancelable during close
===2.1.6.20100318===
*Mac only release
**Added WillSleep and Wakeup events to give user control of Phidgets immediately before and after a system sleep (MacOS Only).
===2.1.6.20100317===
*Windows only release
**Some of the examples were being built using an out of date .NET library
===2.1.6.20100310===
*MaxMSP fix - 2.1.6.20100126 introduced a bug for some Phidgets where openremote/open by serial didn't work and MaxMSP would sometimes crash.
**No code changes to any of the other libraries.
===2.1.6.20100304===
*stopped property changes trigger events over webservice so they are noticed.
**more compatible with how local open works
*added 5 new servos
*fixed bug where remote close would not set detached so a subsequent open would not always connect.
*handle UninitializeZeroconf better - shut down thread before closing handles, fixes hang on SBC
*fixed bug on Mac where detaching 2 or more Phidgets at the same time caused a crash
*fixed close blocking because of a pending connect (mac, linux)
*Final support for 1031 in all libraries.
===2.1.6.20100129===
*Implemented initial events in Flash
**Flash behaviour should now be identical to C library local and remote.
*Fix RFID issue where close could cause crash
*increment webservice version to 1.0.4
*fixed RFID remote open
**Flash would never get an attach event if the reader had been previously opened
**Initial tag event would not be fired when a tag was present and the antenna was enabled prior to open
*fixed openRemote failing on Mac
*fixed deadlock in webservice which could be hit by opening/closing a device over and over again.
*fixed bug in stepper, which caused seg fault on SBC on position change events.
===2.1.6.20100126===
*added network open support in Max/MSP
===2.1.6.20100115===
*Increased network performance for Linux/MacOS
*Added five servo types
===2.1.6.20091215===
*Fixed busy loop in Linux openRemote
*JNI Library relocated to /Library/Java/Extensions on MacOS
===2.1.6.20091211===
*Heartbeat now works on Linux as well (had to make sockets non-blocking)
===2.1.6.20091130===
*Added heartbeat to webservice (client side)
**Better detects network failures by using active polling timeouts
*Fixed 0/8/8 over webservice
===2.1.6.20091020===
*Fixed 1052 counting issue on 1070 (-1 reported as 255)
*Fixed issue where Phidget21 would try to reinstall from a limited user account or when the Control Panel was disabled.
*64-bit kernel support in Snow Leopard
===2.1.6.20090928===
*Support for PhidgetSBC (1070)
*zeroconf can handle starting up before the mdns daemon, and will keep trying to connect.
*fixed 1066 not showing up on Mac
*added advanced servo example to mac pref pane
*implemented proper error handling in COM
**default behavious remains the same, enable proper error handling with 'EnableVerboseErrors'
*implemented error events in Java
===2.1.6.20090917===
*Updated webservice protocol version to 1.0.3
*Fixed stepper under AS3.0
*added setServoType, getServoType, setServoParameters to PhidgetServo and PhidgetAdvancedServo
*possible race condition fixed in webservice (pdictclient.c:907)
===2.1.6.20090902 (mac only release)===
*Support MacOSX 10.6, drop support for 10.3.9, require 10.4 or newer
**Fully 64-bit compliant, library supports ppc, i386, x86_64
===2.1.6.20090806===
*Added 1049 support
*Fixed RFID tag events over webservice
===2.1.6.20090804===
*Added 1051_2 support
*Fixed various small initialization issues - stepper, adv servo, rfid
*Added 32-bit library install to 64-bit installer
**VB6.0, etc. need the 32-bit COM library on 64-bit windows
===2.1.6.20090717===
*?
===2.1.6.20090708===
*Added DeviceID to zeroconf
*fixed RFID.LastTag in .NET
*Changed the error codes returned by error events; error events now have their own set of error codes rather then sharing the function return codes.
*Added support for 1047, 1048
*Added error event codes rather then trying to reuse the EPHIDGET return codes.
*fixed TextLCD issue where display could get corrupted during a detach/attach
*made mac more reliable on attach
*more error logging on mac
===2.1.6.20090525===
*fixed RFID not attaching via webservice if a tag is present.
*bugfix related to double free on detach event.
*Implemented getKey
*Added MIPS II support to Windows CE
===2.1.6.20090430===
*Added ActiveX interface to COM library
*Added stepper and advancedServo to Flex .swc library
===2.1.6.20090417===
*added PhidgetIR prototype support to C library
*properly handles sleeping on OSX
*fixed some webservice field initializations in Flash and C
*fixed security exceptions in [[Phidget Control Panel]] under Vista
*added [[Phidget Control Panel]] to start menu

===2.1.6.20090318 (Examples/AS3.0 only release)===
*Fixed AdvancedServo in Flash - wouldn't attach
===2.1.6.20090317===
*[[Phidget Control Panel]] properly supports Vista UAC and Limited user accounts in XP, etc.
*Added 64-bit release of Phidget21.msi for Windows

===2.1.6.20090312===
*added 1064, 1059 to WindowsCE
*fixed opening 1051 over webservice
*fixed opening 1015/1016 over webservice broken in last release
===2.1.6.20090302===
*Advanced servo bugfix: stopped would stop being true if min/max was set to exclude current position.
*linux USB improvements when many Phidgets are attached and opened at once.
*1031 support in phidget21, webservice, .NET - hidden until product release
**CPhidgetLED_setVoltage
**CPhidgetLED_getVoltage
**CPhidgetLED_setCurrentLimit
**CPhidgetLED_getCurrentLimit
*unknown timechange == PUNK_INT in encoder position change event
**1st position change event
**> 30 seconds time change
*AS3 updates
**updated to 1.0.2 webservice
**encoder position change events report relative change rather then absolute position
**encoder adds getTimeChange function for timing encoder changes
*webservice updated to 1.0.2
**Authorization is asynchronous
**Doesn't match the old version checking, so errors will not be nice when trying to connect to an old webservice
**Sends out all initial data, so it's just like opening locally
**supports interfacekit Raw sensor value
**supports labels on remoteIP managers
*avahi bugfix
*webservice more stable against forcefully closed clients
*closing a network Phidget won't block - ever.
**no longer using quit, just closing the socket
*added libavahi-client.so.3 reference to linux library.
*Fixed bug with opening one phidget with serial and no serial at the same time over the webservice
===2.1.5.20090105===
*[[Phidget Control Panel]] stability improvements
*added CPhidgetSBC_getHostname
*advanced servo 1 motor current sense equation - support should now be complete
*webservice and network code bugfixes - crash / deadlock during close, problems with concurrent connections, etc.
*fixed close on remote and remoteIP managers
*name of RFID changed from "Phidget RFID 4-output" to "Phidget RFID 2-output" - updated anything referencing old name.

===2.1.5.20081023===
*added advanced servo and stepper examples to VB6.0, VB.NET and C
*added deviceClass and deviceID
*updated Mac examples
*webservice protocol version enforcement
*internal fix/rework of device id's etc.
*Fixed memory leaks in webservice and phidget21 network code.
*Dictionary and network stability improvements.
*duplicate calls to open or close are now silently ignored.
===2.1.4.20080924===
*Old TextLCD 0/8/8's can now have both halves open at the same time on Windows
*fixed bug with composite devices on linux
*fixed manager on linux to better deal with unique devices
===2.1.4.20080922===
*Updated Delphi files
*TextLCD can display 0x80-0xFF characters from Java
*getAttachedDevices works for mdns managers
*fixed a deadlock in the webservice
*better network error handling / password support for windows C# examples
*waitForAttachment will return EPHIDGET_CLOSED if the handle is closed while it is waiting.
*added EPHIDGET_CLOSED
*joining central threads checks whether they are trying to be joined by themselves first (avoid deadlocks).
*changed context of error event to be free from locks (can call close, open, etc. from them).
===2.1.4.20080821===
*zeroconf threads exit cleanly on last _close (apple zeroconf)
*Added advanced servo and stepper to Max
===2.1.4.20080811 (mac only release)===
*Fixed manager on Mac (wasn't working at all since 2.1.4.20080808)
===2.1.4.20080808===
*added CPhidgetSBC and CPhidgetSBCManager to the c library - these interfaces are hidden from users and meant to be used internally (for now).
*CPhidgetManager_open no longer blocks to send out initial attach events. These initial events are sent from the CentralThread context like all other attach events.
*fixed CThread_wait_on_event on Linux
*added CPhidgetGeneric interface for prototyping to C, .NET libraries. product ID is 0x99. These are only visible in debug releases, only to be used internally.
===2.1.4.20080715===
*udev rules fixed for product IDs with alpha-hex values
*blocking in an attach event does not block calls to open anymore
*RFID tag event handlers can now handle blocking - tag lost is timed after the tag handler exits.
===2.1.4.20080623===
*Flex .swc library was out of sync
*fixed CPhidgetManager_getAttachedDevices for network managers
*Added CPhidgetManager_freeAttachedDevicesArray
===2.1.4.20080613===
*Max/MSP RFID fixed
*0/0/8 and advanced servo added to CE
*fixed flash policy file server in webservice
*webservice with password and asynchronous together work now
===2.1.4.20080602===
*phidget21.h -> phidget21int.h so as not to be confused with generated phidget21.h
*some changes to Makefile fro crosscompiling
*no more vbscript in msi
===2.1.4.20080513===
*removed long long from COM - not supported by VB6.0
*added LastTag to RFID in .NET
===2.1.4.20080428===
*support Mac OS X 10.3.9 again
*Rev up to 2.1.4
*finalize Phidget Stepper API - Phidget Stepper requires 2.1.4 as a minimum
*fixed serverConnect and serverDisconnect handlers for manager and dictionary in COM
*Changed:
**PhidgetStepper and PhidgetAdvancedServo
***MotorPosition -> Position
***MotorOn -> Engaged
***MotorStopped -> Stopped
*Added:
**CPhidgetStepper_getCurrentLimit
**CPhidgetEncoder_getPosition
**CPhidgetEncoder_setPosition
**CPhidgetMotorControl_getVelocity
**CPhidgetMotorControl_setVelocity
**CPhidgetMotorControl_set_OnVelocityChange_Handler
**CPhidgetServo_setEngaged
**CPhidgetServo_getEngaged
**CPhidgetServo_getPosition
**CPhidgetServo_setPosition
**CPhidgetServo_set_OnPositionChange_Handler
**CPhidgetServo_getPositionMax
**CPhidgetServo_getPositionMin
**Count functions
*Deprecated:
**CPhidgetEncoder_getEncoderPosition
**CPhidgetEncoder_setEncoderPosition
**CPhidgetMotorControl_getMotorSpeed
**CPhidgetMotorControl_setMotorSpeed
**CPhidgetMotorControl_set_OnMotorChange_Handler
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
**CPhidgetServo_getMotorPosition
**CPhidgetServo_setMotorPosition
**CPhidgetServo_set_OnMotorPositionChange_Handler
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**Num functions
*Added ability to deprecate funcitons in the C library - compiler will issue a warning when they are used.
*added names to some arguments in phidget21.h
*fixes to the webservice for initial state stuff - now it behaves almost like non-webservice, with guaranteed initial events, but we don't guarantee initial state in the attach event yet. Min/Max, Num motors, inputs, etc. are all guaranteed in the attach handler.
*Finalized support for Phidget Stepper
===2.1.3.20080402===
*Fixed windows BUG - Device Type was showing up wrong
*CPhidgetStepper_getPosition -> CPhidgetStepper_getCurrentPosition
===2.1.3.20080327===
*added:
**CPhidgetAdvancedServo_setMotorPositionMax
**CPhidgetAdvancedServo_setMotorPositionMin
**CPhidgetAdvancedServo_getMotorStopped
*changes to API
**CPhidgetStepper_setMotorPosition -> CPhidgetStepper_setTargetMotorPosition
**added CPhidgetStepper_getTargetMotorPosition
**Stepper MotorSpeed -> Velocity
**Stepper and AdvancedServo MaxVelocity -> VelocityLimit
*add waitForAttachment to COM
*COM getbool (not indexed) will now return FALSE on false (rather then always returning true)
*fixed write thread timeouts - was setting attached after starting write thread so write thread would see a detached device and exit immediately
===2.1.3.20080206===
*changed long long to __int64, to be happy in borland C++
*added:
**CPhidgetStepper_getMaxMotorSpeed
**CPhidgetStepper_setMotorOn
**CPhidgetStepper_getMotorOn
**CPhidgetStepper_getMotorStopped
**CPhidgetStepper_setCurrentMotorPosition
*removed CPhidgetStepper_setVelocity
*added CPhidgetStepper_setMaxVelocity, CPhidgetStepper_getMaxVelocity
===2.1.3.20080114===
*Added new functions to Flash API
*Added new functions to Webservice Protocol
*Added new functions to COM Library
*Added new functions to Java Library
*All device fiels in C library cleaned up and made consistent
*Open in windows is exclusive - this needs to be tested for stability
*No data will be returned / accepted if it lies outside of max/min range
*if a data value is unknown, user variable is set to PUNK_INT, PUNK_DBL, or PUNK_BOOL, and return value is EPHIDGET_UNKNOWNVAL
*Proper Device initializations on Attach:
**triggers are set to defaults on attach
**device state is read in and preserved on attach
**during attach event, all sensor data, etc. is provided if available
**no data events until after the attach event returns
**everything initialized by the time waitForAttachment returns
**after attach event returns, a full set of initial state data events are thrown
*.NET collections are readonly, and never NULL (but empty when phidget detached)
*.NET callbacks no longer catch and hide all exceptions
**make sure to use try/catch blocks especially in Attach when accessing properties that may not be initialized.
*added min/max functions:
**CPhidgetAccelerometer_getAccelerationMax
**CPhidgetAccelerometer_getAccelerationMin
**CPhidgetAdvancedServo_getAccelerationMax
**CPhidgetAdvancedServo_getAccelerationMin
**CPhidgetAdvancedServo_getVelocityMax
**CPhidgetAdvancedServo_getVelocityMin
**CPhidgetAdvancedServo_getMotorPositionMax
**CPhidgetAdvancedServo_getMotorPositionMin
**CPhidgetMotorControl_getAccelerationMax
**CPhidgetMotorControl_getAccelerationMin
**CPhidgetPHSensor_getPHMax
**CPhidgetPHSensor_getPHMin
**CPhidgetPHSensor_getPotentialMax
**CPhidgetPHSensor_getPotentialMin
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**CPhidgetStepper_getAccelerationMax
**CPhidgetStepper_getAccelerationMin
**CPhidgetStepper_getMotorSpeedMax
**CPhidgetStepper_getMotorSpeedMin
**CPhidgetStepper_getMotorPositionMax
**CPhidgetStepper_getMotorPositionMin
**CPhidgetTemperatureSensor_getPotentialMax
**CPhidgetTemperatureSensor_getPotentialMin
**CPhidgetTemperatureSensor_getAmbientTemperatureMax
**CPhidgetTemperatureSensor_getAmbientTemperatureMin
**CPhidgetTemperatureSensor_getTemperatureMax
**CPhidgetTemperatureSensor_getTemperatureMin
*Added functions:
**CPhidgetTemperatureSensor_getAmbientTemperature
**CPhidgetTemperatureSensor_getThermocoupleType
**CPhidgetTemperatureSensor_setThermocoupleType
**CPhidget_set_OnServerConnectHandler
**CPhidget_set_OnServerDisconnectHandler
**CPhidgetDictionary_set_OnServerConnectHandler
**CPhidgetDictionary_set_OnServerDisconnectHandler
**CPhidgetManager_set_OnServerConnectHandler
**CPhidgetManager_set_OnServerDisconnectHandler
**CPhidgetDictionary_getServerID
**CPhidgetDictionary_getServerAddress
**CPhidgetDictionary_getServerStatus
**CPhidgetManager_getServerID
**CPhidgetManager_getServerAddress
**CPhidgetManager_getServerStatus
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
*Removed functions:
**CPhidgetServo_setMotorOff
*TemperatureSensor:
**Ambient sensor is accessed with it's own function
**first thermocouple is Index 0 everywhere
**no ambient sensor events
*getServerID is implemented
*changed the internal network structure (added CPhidgetRemote)
*reworked the USB code (mostly on Windows)
**Better handles closing, ESD events, timeouts
**fixed issues with Encoder, RFID stopping reading after a certain time.
**added USB error flag
*openRemote functions have been implemented
**these require bonjour (mac / windows) or avahi (linux) to be installed on both the client and server
**if they are not, you get EPHIDGET_UNSUPPORTED when you call them
*openRemoteIP functions are asynchronous and persistent
*include cphidgetconstants.h in phidget21.h for users
===2.1.2.20071108===
*start of chagelog

Driver Changelog

2018-06-22T17:41:32Z

Patrick:

[[Category:Administrative]]
__NOTOC__

===2.1.9.20180622===
*Python fix

===2.1.9.20180215===
*Move to .NET 4.0

===2.1.8.20171215===
*macOS release
**Fixed USB bug where opening two of the same device with -1 serial could cause missed attach/detach events and other errors.

===2.1.8.20160921===
*macOS release
**Fixed USB bug where devices plugged in before boot were inaccessible until unplugged/re-plugged, under OS X 10.11.

===2.1.8.20160202===
*Windows release
**Labview 7.1 support

===2.1.8.20160107===
*Windows release
**Don't throw an exception on EncoderPositionChangeEventArgs.Time in the .Net library when time it unknown - just return 0x7fffffff

===2.1.8.20160104===
*Mac/Windows release
**New firmware for 1042 and 1044, fixing digital gyro
===2.1.8.20151217===
*Fixed 1045 bug where it will display an unknown ambient temperature sometimes
*Fixed a crash in the windows control panel

===2.1.8.20151020===
*Windows release
**Fixed an issue where the examples would error when trying to run them from the control panel.

===2.1.8.20151009===
*OS X and Windows release
**Upgraded firmware for 1024, 1032, 1041, 1042, 1043, 1044 and 1067 to address issues with these Phidgets on OS X El Capitan
*SBC release
**Support for multiple webcams
===2.1.8.20150821===
*OS X-only release
**Support OS X 10.11 El Capitan
===2.1.8.20150805===
*OS X-only release
**Preliminary support for OS X 10.11 El Capitan
===2.1.8.20150410===
*Linux-only release
**Fixed Makefile phidget21.h target issues
===2.1.8.20150326===
*Windows-only release
**Fixed issue with webservice buttons not being visible in the control panel
===2.1.8.20150323===
*Windows-only release
**Updated icons with new company logo
===2.1.8.20150227===
*Linux-only release
**Added copyright/licence headers to source code files
**Updated cvtutf files to a newer version
===2.1.8.20150109===
*Windows-only
**Fixed examples for Labview 8.5
===2.1.8.20141209===
*OS X-only release
**Added support for armv7s and arm64 to the iOS library. Dropped support for armv6. Requires iOS 5.1.1 or later.
===2.1.8.20141202===
*Windows-only release
**Labview release to support older versions
===2.1.8.20141119===
*OS X-only release
**Fixed an issue with the 2.1.8.20141117 release where nothing was actually installed.
===2.1.8.20141117===
*OS X-only release
**Fixed a code-signing issue that make the installer appear unsigned on OS X 10.10
**Dropped support for OS X 10.4
===2.1.8.20140905===
*Windows-only release
**Added an IA32 folder to the windows libraries download - this supports Windows on the Intel Galileo platform
===2.1.8.20140428===
*Windows-only release
**Fixes to C# Stepper GUI Example
===2.1.8.20140319===
*CPhidget_getDeviceClass can now be called on handle before it is attached.
*Added support for 64-bit Max/MSP (Version 6.1+) on both OS X and Windows.
===2.1.8.20140227===
*Deals with 1046 bug in v100 and v101 firmware.
**No longer reports bad values that appear right after a channel is enabled.
**Fixes issue where changing the gain while channel 0 is disabled would sometimes cause bad readings.

===2.1.8.20131105===
* Fixed a defect in the Flash examples for the 1012 (Outputs 11-16 were not addressed properly).

===2.1.8.20130926===
*Windows-only release
**Support setting label on 1067 from Windows
===2.1.8.20130820===
*Windows-only release
**Added logging option to control panel / C# full examples
===2.1.8.20130802===
*Windows-only release
**Fix for Windows 8 issue where only 'Uninitialized Phidget Handle' would show up in the Manager, and Phidgets could not be opened.
===2.1.8.20130723===
*Improvement to java: we don't attach/detach our native threads for each event, just one attach, then detach before the thread exits.
**This increases performance, esp. when debugging on Android.
*Improvement to Android: We reuse the UsbRequest object rather then creating a new one for each transfer. This reduces logcat messages tremendously, and increases performance.
===2.1.8.20130710===
*Android-only release
**Added extra android target architectures: x86, MIPS, armeabi-v7a
===2.1.8.20130618===
*Changed setCompassCorrectionParameters() API call so that compass calibration parameters are written out to non-volatile storage on 1042/1044, so that they persist across power cycles. Previously, calibration data would need to be re-programmed at each attach.
*Changes to C# Spatial example:
**Compass calibration parameter set dialog removed from for 1042/1044 because parameters are set by the calibration software - and thus do not need setting in the example.
**Stores/restores parameters for 1056 based on serial number, so multiple different calibrations can be maintained.
===2.1.8.20130607===
*Windows-only release
**Fixes to compass calibration software for 1042/1044
===2.1.8.20130419===
*Windows-only release
**Fixed setCompassCorrectionParameters in the COM library
===2.1.8.20130327===
*Windows-only release
**Changed Windows installer to stop virus-scanner false positives
**Dropped support for Windows 2000
===2.1.8.20130320===
*Added EPHIDGET_NOTFOUND exception to Dictionary.getKey() for when the key is not found.
*Added exceptions back into the Java library - they have been missing since 2.1.8.20121015 release.
===2.1.8.20130313===
*Updates to Matlab support
**Works properly on Matlab 7+, on Windows, Mac, Linux without needing changes to .m files.
===2.1.8.20130221===
*Windows-only release
**Encoder Index event added to C and .NET libraries
===2.1.8.20121218===
*Webservice version: 1.0.10
**Support for 1024, 1032
*Support for 1024, 1032
*fixed bug where if one half of a composite device is open, and PHIDGET_USB_ERROR_FLAG gets set, the device may never re-attach.
===2.1.8.20121015===
*Windows-only release
**Support for new pressure/light sensors in example.
===2.1.8.20120914===
*Windows-only release
**Improved firmware upgrading in control panel - it was giving some false-errors on some machines.
===2.1.8.20120912===
*Fixed bug where 1065 could fail to attach when opened over webservice
*Fixed bug where close() could deadlock on Phidgets opened over the webservice
*Changed LED64 LED Brightness from int to double
**this may cause issues when controlling the LED64 over the webservice and library/webservice are not the same version
**the old setDiscreteLED call will remain, deprecated, with an int argument for compatibility.
===2.1.8.20120716===
*Linux-Only Release
**Fixed a bug where opening a device in two program at once would cause an attach-detach cycle as they fight each other for control.
===2.1.8.20120713===
*Mac-Only Release
**Added signing of the Mac installer, so Mountain Lion (OS X 10.8) doesn't refuse to run it.
===2.1.8.20120615===
*Windows-only release
**Fixed a bug that caused java to crash on events introduced in 2.1.8.20120612
===2.1.8.20120612===
*Windows-only release
**Fixed another bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120606===
*Windows-only release
**Fixed a bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120525===
*Windows-only release
**Fixed PhidgetIR sendRawData bug in .NET on 64-bit machines.
===2.1.8.20120514===
*Linux-only release
**Fixed a bug that causes a segfault with libusb-1.0 under 64-bit Linux.
===2.1.8.20120507===
*Mac/Linux-only release
**Fixes a setLabel bug introduced in 2.1.8.20120503
===2.1.8.20120503===
*Fixed some spelling mistakes
*Moved to libusb-1.0
**This resolves a bug where having a webcam plugged in caused a memory leak in the webservice.
*Fixed bug with advanced servo where setting acceleration to accelerationMax would cause an exception for some servo types
===2.1.8.20120216===
*Fixed bug with RFID Reader on OS X and Linux, as well as .NET over the webservice
*Fixed bug that could cause the Java Phidget Manager to crash during garbage collection.
===2.1.8.20120131===
*Fixed RFID Reader bug that caused tag event to not get thrown in .NET Applications
*Changed compass bearing calculations in spatial C# example
===2.1.8.20120123===
*Added support for 1061 v300+
*Fixed a bug where the firmware version could be mis-reported over Bonjour
===2.1.8.20111220===
*Fixed a bug in AppleScript where closing a Phidget opened via label would give a 'Connection Invalid' error.
*Fixed a bug where the webservice may fail to start on Linux systems that don't support IPv6 (ie. SBC2).
*Fixed issue where ratiometric state on newest interfacekit wouldn't be read back properly if it was false during attach.
*Fixed webservice issue where ratiometric state would not be reported properly for newest interfacekits
*Increased the number of overrun errors ignored during initial attach for InterfaceKit.
*Fixed an issue with the iPhone library and header
===2.1.8.20111219===
*fixed various other webservice stability/performance/memory leak bugs
*Faster connection to SBC-connected Phidgets from Mac OS
*Don't report packetlost or overrun errors that happen during early initialization - these are just noise.
*Fixed a bug in the webservice tree removal function that could cause memory leaks.
*Fixed bug where Webservice would crash on Linux if the chosen serverID was already under use on the network
*Stopped sending hardware Error Events before the Attach event - they are now queued up and sent after Attach
*Fixed a crash in the [[Phidget Control Panel]]
*Added ability to remove dictionary keys from a key change listener
*Reduced the number of false 'pending command not finished' error events on Close()
*Fixed a webservice bug where exceptions/false attach events could occur when close() is called soon after open
*Fixed bug where closing a PhidgetRFID soon after attach could cause a crash
*Fixed webservice but on MacOS where client could exit with SIG_PIPE error
*Fixed webservice bug where the server would sometimes exit(1) after many connect/disconnect cycles
*Fixed webservice bug where client could deadlock during close()
*Fixed webservice bug where opening a single remote phidget multiple times from the same application would fail
*Fixed a webservice bug where sockets weren't being closed properly sometimes
*Fixed a webservice bug where pre-attach error events wouldn't get through
*Fixed a bug where the webservice running on Linux would stop responding to clients after ~300 connect/disconnect cycles
*Fixed bug where a Phidget would become inaccessible until the app is restarted if a thread creation failed
*Fixed webservice bug where connect is slow on Windows when multiple clients are running simultaneously
*Fixed webservice bug where authentication would fail on a valid password
*Fixed webservice bug where attach may never happen, and would require a close()/open()

===2.1.8.20111121===
*Added support for new servo types to all libraries
*Fixed min/max position/velocity causing invalid arg exception on servo/advservo
*IPv6 support on MacOS
*Fixed some memory leaks
*Fixed hostname lookup issue on Mac OS with Back To My Mac enabled.
===2.1.8.20111028===
*Fixed Applescript bugs and released examples
*Added openLabel to .NET, Java, COM
*Setting change trigger to 0 on interfacekit will not set event mode.
**Previously setting change trigger to 0 after setting data rate would supersede the data rate setting, which is probably unexpected.
===2.1.8.20110630 - MacOS Only===
*handle USB bug introduced in MacOS 10.6.8
===2.1.8.20110615===
*Added error event when trying to open Phidgets with an unsupported version
===2.1.8.20110614 - Windows Only===
*Fixed bug in C# Spatial example
*Added support for negative gains in 1056
===2.1.8.20110601 - MacOS Only===
*Fixed AppleScript issues
===2.1.8.20110527===
*Fixed AS3.0 library (Flash/Flex) - wouldn't connect to webservice as of last release
*Fixed bug where webservice doesn't release a closed Phidget
*Fixed bug where devices that don't support label didn't show up on MacOS
*Fixed iPhone library issues
===2.1.8.20110524===
*AppleScript support added
*fixed problem with Spatial in .NET on 64-bit Windows
*Added remote setLabel to mac preference pane.
*fixed a bug where label characters 7,8,9 would be read back corrupted on certain devices.
**labels >7 characters that exhibit this bug will now be truncated to 7 characters when being read back
**call setLabel again using this library or newer to support 10 character labels.
**To maintain compatibility with older library versions, limit labels to <=7 characters on these devices.
*fixed bug on MacOS where serial number and/or label strings could be read wrong.
*better support for recovering misbehaving devices in Linux
*fixed a deadlock on linux when Avahi is installed but not running
*clear list of attached devices when closing remote manager
*Added support for Unicode labels
**To maintain compatibility with older library versions, limit labels to ASCII.
*Added open by label
*Webservice protocol version up to 1.0.9 (for open by label)
*Made opening multiple device is one application faster.
*TextLCD changes:
**cursor is disabled while writing to the display or setting a custom character to prevent display artifacts
**cursor is disabled when a full line is written so it doesn't go to the start of another line
**1204 should be stable
**setDisplayCharacter supports 0x00-0xff
*stopped property reflected more accurately in the C# stepper example
*Added error events to mac examples
===2.1.8.20110329 - Windows only===
*Fixed problem with control panel encoder example where enable wouldn't work
*Fixed issue with SpatialData, GPSPositionChange, PHChange and WeightChange events in Labview 64-bit
===2.1.8.20110322===
*Fixed [[Phidget Control Panel]] memory leak when Bonjour in installed but not running
*Fixed current sense formula on 1061_0 v200
*Fixed bug in webservice protocol while using the PhidgetAdvancedServo
*Fixed bug in old PhidgetTemperatureSensor

===2.1.8.20110310===
*Fixed bug in webservice protocol while using the PhidgetServo
*Fixed some Labview bugs
*Added some Java and VB.NET examples
===2.1.8.20110301===
*Full Support for 1002, 1011, 1040, 1046, 1054, 1065, 1204
*New webservice version - 1.0.8
**Support for new devices
**Support for error events
===2.1.7.20110203===
*fixed crash on close of remote Phidget on MacOS
*C# ifkit example bugfix - crashed on 1015/1016
*webservice improvements
*Switch to IP address for SBC config in browser
*Faster IP lookup for SBCs in control panel
===2.1.7.20101222 / 2.1.7.20101223===
*fixed getServerID on Linux
*removed report ack
**this was causing some bad side effects
*manual .local lookups on Windows
**much faster then letting Windows do it itself
*Support for new Labview library
*Fixed PhidgetIR bug where library would crash if repeat code is longer then IR_MAX_REPEAT_LENGTH
===2.1.7.20101103===
*Decreased Phidget Webservice event latency on Windows
*Preliminary support for 1002, 1011, 1040, 1045, 1046, 1054, 1065, 1204 (C, .NET)
*Webservice version updated to 1.0.7
**support for 1045, 1011, 1204
*Fixed a bug where webservice connections could be unexpectedly lost
*Bugfix: couldn't set interfacekit data rate over webservice.
*Fixed some memory leaks in the Mac library
*Fixed bug where blocking for >2 seconds in an events handler when opening remotely could cause a crash.
===2.1.7.20100803===
*Windows only release
*fixed setLabel in WindowsCE
*fixed getHashCode in .NET library - needed for working with Phidgets in Labview via .NET
===2.1.7.20100621===
*Linux only release - autotools updates
**call ldconfig automatically
**remove old phidget21 library (pre-autotools) when installing new one.
===2.1.7.20100620===
*Linux only release - added version.sh for autoreconf
===2.1.7.20100618===
*Linux only release - added udev/hotplug files
===2.1.7.20100617===
*Linux only release
*Transitioned to autotools in linux for phidget21 / webservice
*phidget21 library and webservice are now separate downloads
===2.1.7.20100525===
*full support for PhidgetSpatial and PhidgetIR in all libraries
*fixed 1031 not attaching in AS3.0
*Better error messages in JNI
*Updated error codes, device ID/Class lists in Java, Flash, COM, etc.
*Fixed TemperatureSensor version 200,201,202 bug - ambient sensor would not report negative temperatures.
*Revised temperaturesensor API to report tempMin/tempMax and errors more accurately.
*Added initial events for encoder digital inputs
*full support for 1047
*Added new device support to WindowsCE
*Updated mac examples for 1047, 1048
===2.1.6.20100504===
*Windows only Release
**Added 1131 and 1132 to InterfaceKit example in MSI
===2.1.6.20100428===
*limit data rate maximum to 16ms over the webservice for devices that expose dataRate (InterfaceKit, Spatial)
*fixed bug where TextLCD 8/8/8 would stay in Bonjour list after webservice is shutdown
*set/get Brightness for 1203_2
*Support 1048 in C# example
*webservice version incremented to 1.0.6
**TextLCD set/get brightness
**PhidgetIR support
**PhidgetSpatial support
**1047 support (enable, index)
===2.1.6.20100406===
*Support for 1018_2 (dataRate)
*Webservice version incremented to 1.0.5
===2.1.6.20100401===
*Updated InterfaceKit example with new sensors
*make Windows connect cancelable
*make pending zeroconf lookups cancelable during close
===2.1.6.20100318===
*Mac only release
**Added WillSleep and Wakeup events to give user control of Phidgets immediately before and after a system sleep (MacOS Only).
===2.1.6.20100317===
*Windows only release
**Some of the examples were being built using an out of date .NET library
===2.1.6.20100310===
*MaxMSP fix - 2.1.6.20100126 introduced a bug for some Phidgets where openremote/open by serial didn't work and MaxMSP would sometimes crash.
**No code changes to any of the other libraries.
===2.1.6.20100304===
*stopped property changes trigger events over webservice so they are noticed.
**more compatible with how local open works
*added 5 new servos
*fixed bug where remote close would not set detached so a subsequent open would not always connect.
*handle UninitializeZeroconf better - shut down thread before closing handles, fixes hang on SBC
*fixed bug on Mac where detaching 2 or more Phidgets at the same time caused a crash
*fixed close blocking because of a pending connect (mac, linux)
*Final support for 1031 in all libraries.
===2.1.6.20100129===
*Implemented initial events in Flash
**Flash behaviour should now be identical to C library local and remote.
*Fix RFID issue where close could cause crash
*increment webservice version to 1.0.4
*fixed RFID remote open
**Flash would never get an attach event if the reader had been previously opened
**Initial tag event would not be fired when a tag was present and the antenna was enabled prior to open
*fixed openRemote failing on Mac
*fixed deadlock in webservice which could be hit by opening/closing a device over and over again.
*fixed bug in stepper, which caused seg fault on SBC on position change events.
===2.1.6.20100126===
*added network open support in Max/MSP
===2.1.6.20100115===
*Increased network performance for Linux/MacOS
*Added five servo types
===2.1.6.20091215===
*Fixed busy loop in Linux openRemote
*JNI Library relocated to /Library/Java/Extensions on MacOS
===2.1.6.20091211===
*Heartbeat now works on Linux as well (had to make sockets non-blocking)
===2.1.6.20091130===
*Added heartbeat to webservice (client side)
**Better detects network failures by using active polling timeouts
*Fixed 0/8/8 over webservice
===2.1.6.20091020===
*Fixed 1052 counting issue on 1070 (-1 reported as 255)
*Fixed issue where Phidget21 would try to reinstall from a limited user account or when the Control Panel was disabled.
*64-bit kernel support in Snow Leopard
===2.1.6.20090928===
*Support for PhidgetSBC (1070)
*zeroconf can handle starting up before the mdns daemon, and will keep trying to connect.
*fixed 1066 not showing up on Mac
*added advanced servo example to mac pref pane
*implemented proper error handling in COM
**default behavious remains the same, enable proper error handling with 'EnableVerboseErrors'
*implemented error events in Java
===2.1.6.20090917===
*Updated webservice protocol version to 1.0.3
*Fixed stepper under AS3.0
*added setServoType, getServoType, setServoParameters to PhidgetServo and PhidgetAdvancedServo
*possible race condition fixed in webservice (pdictclient.c:907)
===2.1.6.20090902 (mac only release)===
*Support MacOSX 10.6, drop support for 10.3.9, require 10.4 or newer
**Fully 64-bit compliant, library supports ppc, i386, x86_64
===2.1.6.20090806===
*Added 1049 support
*Fixed RFID tag events over webservice
===2.1.6.20090804===
*Added 1051_2 support
*Fixed various small initialization issues - stepper, adv servo, rfid
*Added 32-bit library install to 64-bit installer
**VB6.0, etc. need the 32-bit COM library on 64-bit windows
===2.1.6.20090717===
*?
===2.1.6.20090708===
*Added DeviceID to zeroconf
*fixed RFID.LastTag in .NET
*Changed the error codes returned by error events; error events now have their own set of error codes rather then sharing the function return codes.
*Added support for 1047, 1048
*Added error event codes rather then trying to reuse the EPHIDGET return codes.
*fixed TextLCD issue where display could get corrupted during a detach/attach
*made mac more reliable on attach
*more error logging on mac
===2.1.6.20090525===
*fixed RFID not attaching via webservice if a tag is present.
*bugfix related to double free on detach event.
*Implemented getKey
*Added MIPS II support to Windows CE
===2.1.6.20090430===
*Added ActiveX interface to COM library
*Added stepper and advancedServo to Flex .swc library
===2.1.6.20090417===
*added PhidgetIR prototype support to C library
*properly handles sleeping on OSX
*fixed some webservice field initializations in Flash and C
*fixed security exceptions in [[Phidget Control Panel]] under Vista
*added [[Phidget Control Panel]] to start menu

===2.1.6.20090318 (Examples/AS3.0 only release)===
*Fixed AdvancedServo in Flash - wouldn't attach
===2.1.6.20090317===
*[[Phidget Control Panel]] properly supports Vista UAC and Limited user accounts in XP, etc.
*Added 64-bit release of Phidget21.msi for Windows

===2.1.6.20090312===
*added 1064, 1059 to WindowsCE
*fixed opening 1051 over webservice
*fixed opening 1015/1016 over webservice broken in last release
===2.1.6.20090302===
*Advanced servo bugfix: stopped would stop being true if min/max was set to exclude current position.
*linux USB improvements when many Phidgets are attached and opened at once.
*1031 support in phidget21, webservice, .NET - hidden until product release
**CPhidgetLED_setVoltage
**CPhidgetLED_getVoltage
**CPhidgetLED_setCurrentLimit
**CPhidgetLED_getCurrentLimit
*unknown timechange == PUNK_INT in encoder position change event
**1st position change event
**> 30 seconds time change
*AS3 updates
**updated to 1.0.2 webservice
**encoder position change events report relative change rather then absolute position
**encoder adds getTimeChange function for timing encoder changes
*webservice updated to 1.0.2
**Authorization is asynchronous
**Doesn't match the old version checking, so errors will not be nice when trying to connect to an old webservice
**Sends out all initial data, so it's just like opening locally
**supports interfacekit Raw sensor value
**supports labels on remoteIP managers
*avahi bugfix
*webservice more stable against forcefully closed clients
*closing a network Phidget won't block - ever.
**no longer using quit, just closing the socket
*added libavahi-client.so.3 reference to linux library.
*Fixed bug with opening one phidget with serial and no serial at the same time over the webservice
===2.1.5.20090105===
*[[Phidget Control Panel]] stability improvements
*added CPhidgetSBC_getHostname
*advanced servo 1 motor current sense equation - support should now be complete
*webservice and network code bugfixes - crash / deadlock during close, problems with concurrent connections, etc.
*fixed close on remote and remoteIP managers
*name of RFID changed from "Phidget RFID 4-output" to "Phidget RFID 2-output" - updated anything referencing old name.

===2.1.5.20081023===
*added advanced servo and stepper examples to VB6.0, VB.NET and C
*added deviceClass and deviceID
*updated Mac examples
*webservice protocol version enforcement
*internal fix/rework of device id's etc.
*Fixed memory leaks in webservice and phidget21 network code.
*Dictionary and network stability improvements.
*duplicate calls to open or close are now silently ignored.
===2.1.4.20080924===
*Old TextLCD 0/8/8's can now have both halves open at the same time on Windows
*fixed bug with composite devices on linux
*fixed manager on linux to better deal with unique devices
===2.1.4.20080922===
*Updated Delphi files
*TextLCD can display 0x80-0xFF characters from Java
*getAttachedDevices works for mdns managers
*fixed a deadlock in the webservice
*better network error handling / password support for windows C# examples
*waitForAttachment will return EPHIDGET_CLOSED if the handle is closed while it is waiting.
*added EPHIDGET_CLOSED
*joining central threads checks whether they are trying to be joined by themselves first (avoid deadlocks).
*changed context of error event to be free from locks (can call close, open, etc. from them).
===2.1.4.20080821===
*zeroconf threads exit cleanly on last _close (apple zeroconf)
*Added advanced servo and stepper to Max
===2.1.4.20080811 (mac only release)===
*Fixed manager on Mac (wasn't working at all since 2.1.4.20080808)
===2.1.4.20080808===
*added CPhidgetSBC and CPhidgetSBCManager to the c library - these interfaces are hidden from users and meant to be used internally (for now).
*CPhidgetManager_open no longer blocks to send out initial attach events. These initial events are sent from the CentralThread context like all other attach events.
*fixed CThread_wait_on_event on Linux
*added CPhidgetGeneric interface for prototyping to C, .NET libraries. product ID is 0x99. These are only visible in debug releases, only to be used internally.
===2.1.4.20080715===
*udev rules fixed for product IDs with alpha-hex values
*blocking in an attach event does not block calls to open anymore
*RFID tag event handlers can now handle blocking - tag lost is timed after the tag handler exits.
===2.1.4.20080623===
*Flex .swc library was out of sync
*fixed CPhidgetManager_getAttachedDevices for network managers
*Added CPhidgetManager_freeAttachedDevicesArray
===2.1.4.20080613===
*Max/MSP RFID fixed
*0/0/8 and advanced servo added to CE
*fixed flash policy file server in webservice
*webservice with password and asynchronous together work now
===2.1.4.20080602===
*phidget21.h -> phidget21int.h so as not to be confused with generated phidget21.h
*some changes to Makefile fro crosscompiling
*no more vbscript in msi
===2.1.4.20080513===
*removed long long from COM - not supported by VB6.0
*added LastTag to RFID in .NET
===2.1.4.20080428===
*support Mac OS X 10.3.9 again
*Rev up to 2.1.4
*finalize Phidget Stepper API - Phidget Stepper requires 2.1.4 as a minimum
*fixed serverConnect and serverDisconnect handlers for manager and dictionary in COM
*Changed:
**PhidgetStepper and PhidgetAdvancedServo
***MotorPosition -> Position
***MotorOn -> Engaged
***MotorStopped -> Stopped
*Added:
**CPhidgetStepper_getCurrentLimit
**CPhidgetEncoder_getPosition
**CPhidgetEncoder_setPosition
**CPhidgetMotorControl_getVelocity
**CPhidgetMotorControl_setVelocity
**CPhidgetMotorControl_set_OnVelocityChange_Handler
**CPhidgetServo_setEngaged
**CPhidgetServo_getEngaged
**CPhidgetServo_getPosition
**CPhidgetServo_setPosition
**CPhidgetServo_set_OnPositionChange_Handler
**CPhidgetServo_getPositionMax
**CPhidgetServo_getPositionMin
**Count functions
*Deprecated:
**CPhidgetEncoder_getEncoderPosition
**CPhidgetEncoder_setEncoderPosition
**CPhidgetMotorControl_getMotorSpeed
**CPhidgetMotorControl_setMotorSpeed
**CPhidgetMotorControl_set_OnMotorChange_Handler
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
**CPhidgetServo_getMotorPosition
**CPhidgetServo_setMotorPosition
**CPhidgetServo_set_OnMotorPositionChange_Handler
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**Num functions
*Added ability to deprecate funcitons in the C library - compiler will issue a warning when they are used.
*added names to some arguments in phidget21.h
*fixes to the webservice for initial state stuff - now it behaves almost like non-webservice, with guaranteed initial events, but we don't guarantee initial state in the attach event yet. Min/Max, Num motors, inputs, etc. are all guaranteed in the attach handler.
*Finalized support for Phidget Stepper
===2.1.3.20080402===
*Fixed windows BUG - Device Type was showing up wrong
*CPhidgetStepper_getPosition -> CPhidgetStepper_getCurrentPosition
===2.1.3.20080327===
*added:
**CPhidgetAdvancedServo_setMotorPositionMax
**CPhidgetAdvancedServo_setMotorPositionMin
**CPhidgetAdvancedServo_getMotorStopped
*changes to API
**CPhidgetStepper_setMotorPosition -> CPhidgetStepper_setTargetMotorPosition
**added CPhidgetStepper_getTargetMotorPosition
**Stepper MotorSpeed -> Velocity
**Stepper and AdvancedServo MaxVelocity -> VelocityLimit
*add waitForAttachment to COM
*COM getbool (not indexed) will now return FALSE on false (rather then always returning true)
*fixed write thread timeouts - was setting attached after starting write thread so write thread would see a detached device and exit immediately
===2.1.3.20080206===
*changed long long to __int64, to be happy in borland C++
*added:
**CPhidgetStepper_getMaxMotorSpeed
**CPhidgetStepper_setMotorOn
**CPhidgetStepper_getMotorOn
**CPhidgetStepper_getMotorStopped
**CPhidgetStepper_setCurrentMotorPosition
*removed CPhidgetStepper_setVelocity
*added CPhidgetStepper_setMaxVelocity, CPhidgetStepper_getMaxVelocity
===2.1.3.20080114===
*Added new functions to Flash API
*Added new functions to Webservice Protocol
*Added new functions to COM Library
*Added new functions to Java Library
*All device fiels in C library cleaned up and made consistent
*Open in windows is exclusive - this needs to be tested for stability
*No data will be returned / accepted if it lies outside of max/min range
*if a data value is unknown, user variable is set to PUNK_INT, PUNK_DBL, or PUNK_BOOL, and return value is EPHIDGET_UNKNOWNVAL
*Proper Device initializations on Attach:
**triggers are set to defaults on attach
**device state is read in and preserved on attach
**during attach event, all sensor data, etc. is provided if available
**no data events until after the attach event returns
**everything initialized by the time waitForAttachment returns
**after attach event returns, a full set of initial state data events are thrown
*.NET collections are readonly, and never NULL (but empty when phidget detached)
*.NET callbacks no longer catch and hide all exceptions
**make sure to use try/catch blocks especially in Attach when accessing properties that may not be initialized.
*added min/max functions:
**CPhidgetAccelerometer_getAccelerationMax
**CPhidgetAccelerometer_getAccelerationMin
**CPhidgetAdvancedServo_getAccelerationMax
**CPhidgetAdvancedServo_getAccelerationMin
**CPhidgetAdvancedServo_getVelocityMax
**CPhidgetAdvancedServo_getVelocityMin
**CPhidgetAdvancedServo_getMotorPositionMax
**CPhidgetAdvancedServo_getMotorPositionMin
**CPhidgetMotorControl_getAccelerationMax
**CPhidgetMotorControl_getAccelerationMin
**CPhidgetPHSensor_getPHMax
**CPhidgetPHSensor_getPHMin
**CPhidgetPHSensor_getPotentialMax
**CPhidgetPHSensor_getPotentialMin
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**CPhidgetStepper_getAccelerationMax
**CPhidgetStepper_getAccelerationMin
**CPhidgetStepper_getMotorSpeedMax
**CPhidgetStepper_getMotorSpeedMin
**CPhidgetStepper_getMotorPositionMax
**CPhidgetStepper_getMotorPositionMin
**CPhidgetTemperatureSensor_getPotentialMax
**CPhidgetTemperatureSensor_getPotentialMin
**CPhidgetTemperatureSensor_getAmbientTemperatureMax
**CPhidgetTemperatureSensor_getAmbientTemperatureMin
**CPhidgetTemperatureSensor_getTemperatureMax
**CPhidgetTemperatureSensor_getTemperatureMin
*Added functions:
**CPhidgetTemperatureSensor_getAmbientTemperature
**CPhidgetTemperatureSensor_getThermocoupleType
**CPhidgetTemperatureSensor_setThermocoupleType
**CPhidget_set_OnServerConnectHandler
**CPhidget_set_OnServerDisconnectHandler
**CPhidgetDictionary_set_OnServerConnectHandler
**CPhidgetDictionary_set_OnServerDisconnectHandler
**CPhidgetManager_set_OnServerConnectHandler
**CPhidgetManager_set_OnServerDisconnectHandler
**CPhidgetDictionary_getServerID
**CPhidgetDictionary_getServerAddress
**CPhidgetDictionary_getServerStatus
**CPhidgetManager_getServerID
**CPhidgetManager_getServerAddress
**CPhidgetManager_getServerStatus
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
*Removed functions:
**CPhidgetServo_setMotorOff
*TemperatureSensor:
**Ambient sensor is accessed with it's own function
**first thermocouple is Index 0 everywhere
**no ambient sensor events
*getServerID is implemented
*changed the internal network structure (added CPhidgetRemote)
*reworked the USB code (mostly on Windows)
**Better handles closing, ESD events, timeouts
**fixed issues with Encoder, RFID stopping reading after a certain time.
**added USB error flag
*openRemote functions have been implemented
**these require bonjour (mac / windows) or avahi (linux) to be installed on both the client and server
**if they are not, you get EPHIDGET_UNSUPPORTED when you call them
*openRemoteIP functions are asynchronous and persistent
*include cphidgetconstants.h in phidget21.h for users
===2.1.2.20071108===
*start of chagelog

Template:Phidget21Box

2018-05-11T18:45:28Z

Patrick:

{|cellpadding="5" style="background-color: #ffcccc;"
|[[Image:alert.png|40px|link=]]
| style="text-align:center;" |
'''Notice:''' This page contains information for the legacy Phidget21 Library. Phidget21 does not support VINT Phidgets, and will not support any new Phidgets. Phidget21 will be maintained until 2020. We recommend that new projects be developed against the Phidget22 Library.

<font size=3>'''Click on the [[Image:2phidget22.jpg|link=|100px]] button in the menu bar to go to the Phidget22 version of this page.'''</font>
|[[Image:alert.png|40px|link=]]
|}

Template:UserguideTOC

2018-05-04T22:39:13Z

Patrick:

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[Image:{{{1}}}|link={{SERVER}}/products.php?product_id={{{2}}}|500px]]
|-
|
|align=center|[{{SERVER}}/products.php?product_id={{{2}}} Go to this device's product page]
|}

<br clear="all" />
__NOINDEX__

Driver Changelog

2018-02-16T00:50:06Z

Patrick:

[[Category:Administrative]]
__NOTOC__

===2.1.9.20180215===
*Move to .NET 4.0

===2.1.8.20171215===
*macOS release
**Fixed USB bug where opening two of the same device with -1 serial could cause missed attach/detach events and other errors.

===2.1.8.20160921===
*macOS release
**Fixed USB bug where devices plugged in before boot were inaccessible until unplugged/re-plugged, under OS X 10.11.

===2.1.8.20160202===
*Windows release
**Labview 7.1 support

===2.1.8.20160107===
*Windows release
**Don't throw an exception on EncoderPositionChangeEventArgs.Time in the .Net library when time it unknown - just return 0x7fffffff

===2.1.8.20160104===
*Mac/Windows release
**New firmware for 1042 and 1044, fixing digital gyro
===2.1.8.20151217===
*Fixed 1045 bug where it will display an unknown ambient temperature sometimes
*Fixed a crash in the windows control panel

===2.1.8.20151020===
*Windows release
**Fixed an issue where the examples would error when trying to run them from the control panel.

===2.1.8.20151009===
*OS X and Windows release
**Upgraded firmware for 1024, 1032, 1041, 1042, 1043, 1044 and 1067 to address issues with these Phidgets on OS X El Capitan
*SBC release
**Support for multiple webcams
===2.1.8.20150821===
*OS X-only release
**Support OS X 10.11 El Capitan
===2.1.8.20150805===
*OS X-only release
**Preliminary support for OS X 10.11 El Capitan
===2.1.8.20150410===
*Linux-only release
**Fixed Makefile phidget21.h target issues
===2.1.8.20150326===
*Windows-only release
**Fixed issue with webservice buttons not being visible in the control panel
===2.1.8.20150323===
*Windows-only release
**Updated icons with new company logo
===2.1.8.20150227===
*Linux-only release
**Added copyright/licence headers to source code files
**Updated cvtutf files to a newer version
===2.1.8.20150109===
*Windows-only
**Fixed examples for Labview 8.5
===2.1.8.20141209===
*OS X-only release
**Added support for armv7s and arm64 to the iOS library. Dropped support for armv6. Requires iOS 5.1.1 or later.
===2.1.8.20141202===
*Windows-only release
**Labview release to support older versions
===2.1.8.20141119===
*OS X-only release
**Fixed an issue with the 2.1.8.20141117 release where nothing was actually installed.
===2.1.8.20141117===
*OS X-only release
**Fixed a code-signing issue that make the installer appear unsigned on OS X 10.10
**Dropped support for OS X 10.4
===2.1.8.20140905===
*Windows-only release
**Added an IA32 folder to the windows libraries download - this supports Windows on the Intel Galileo platform
===2.1.8.20140428===
*Windows-only release
**Fixes to C# Stepper GUI Example
===2.1.8.20140319===
*CPhidget_getDeviceClass can now be called on handle before it is attached.
*Added support for 64-bit Max/MSP (Version 6.1+) on both OS X and Windows.
===2.1.8.20140227===
*Deals with 1046 bug in v100 and v101 firmware.
**No longer reports bad values that appear right after a channel is enabled.
**Fixes issue where changing the gain while channel 0 is disabled would sometimes cause bad readings.

===2.1.8.20131105===
* Fixed a defect in the Flash examples for the 1012 (Outputs 11-16 were not addressed properly).

===2.1.8.20130926===
*Windows-only release
**Support setting label on 1067 from Windows
===2.1.8.20130820===
*Windows-only release
**Added logging option to control panel / C# full examples
===2.1.8.20130802===
*Windows-only release
**Fix for Windows 8 issue where only 'Uninitialized Phidget Handle' would show up in the Manager, and Phidgets could not be opened.
===2.1.8.20130723===
*Improvement to java: we don't attach/detach our native threads for each event, just one attach, then detach before the thread exits.
**This increases performance, esp. when debugging on Android.
*Improvement to Android: We reuse the UsbRequest object rather then creating a new one for each transfer. This reduces logcat messages tremendously, and increases performance.
===2.1.8.20130710===
*Android-only release
**Added extra android target architectures: x86, MIPS, armeabi-v7a
===2.1.8.20130618===
*Changed setCompassCorrectionParameters() API call so that compass calibration parameters are written out to non-volatile storage on 1042/1044, so that they persist across power cycles. Previously, calibration data would need to be re-programmed at each attach.
*Changes to C# Spatial example:
**Compass calibration parameter set dialog removed from for 1042/1044 because parameters are set by the calibration software - and thus do not need setting in the example.
**Stores/restores parameters for 1056 based on serial number, so multiple different calibrations can be maintained.
===2.1.8.20130607===
*Windows-only release
**Fixes to compass calibration software for 1042/1044
===2.1.8.20130419===
*Windows-only release
**Fixed setCompassCorrectionParameters in the COM library
===2.1.8.20130327===
*Windows-only release
**Changed Windows installer to stop virus-scanner false positives
**Dropped support for Windows 2000
===2.1.8.20130320===
*Added EPHIDGET_NOTFOUND exception to Dictionary.getKey() for when the key is not found.
*Added exceptions back into the Java library - they have been missing since 2.1.8.20121015 release.
===2.1.8.20130313===
*Updates to Matlab support
**Works properly on Matlab 7+, on Windows, Mac, Linux without needing changes to .m files.
===2.1.8.20130221===
*Windows-only release
**Encoder Index event added to C and .NET libraries
===2.1.8.20121218===
*Webservice version: 1.0.10
**Support for 1024, 1032
*Support for 1024, 1032
*fixed bug where if one half of a composite device is open, and PHIDGET_USB_ERROR_FLAG gets set, the device may never re-attach.
===2.1.8.20121015===
*Windows-only release
**Support for new pressure/light sensors in example.
===2.1.8.20120914===
*Windows-only release
**Improved firmware upgrading in control panel - it was giving some false-errors on some machines.
===2.1.8.20120912===
*Fixed bug where 1065 could fail to attach when opened over webservice
*Fixed bug where close() could deadlock on Phidgets opened over the webservice
*Changed LED64 LED Brightness from int to double
**this may cause issues when controlling the LED64 over the webservice and library/webservice are not the same version
**the old setDiscreteLED call will remain, deprecated, with an int argument for compatibility.
===2.1.8.20120716===
*Linux-Only Release
**Fixed a bug where opening a device in two program at once would cause an attach-detach cycle as they fight each other for control.
===2.1.8.20120713===
*Mac-Only Release
**Added signing of the Mac installer, so Mountain Lion (OS X 10.8) doesn't refuse to run it.
===2.1.8.20120615===
*Windows-only release
**Fixed a bug that caused java to crash on events introduced in 2.1.8.20120612
===2.1.8.20120612===
*Windows-only release
**Fixed another bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120606===
*Windows-only release
**Fixed a bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120525===
*Windows-only release
**Fixed PhidgetIR sendRawData bug in .NET on 64-bit machines.
===2.1.8.20120514===
*Linux-only release
**Fixed a bug that causes a segfault with libusb-1.0 under 64-bit Linux.
===2.1.8.20120507===
*Mac/Linux-only release
**Fixes a setLabel bug introduced in 2.1.8.20120503
===2.1.8.20120503===
*Fixed some spelling mistakes
*Moved to libusb-1.0
**This resolves a bug where having a webcam plugged in caused a memory leak in the webservice.
*Fixed bug with advanced servo where setting acceleration to accelerationMax would cause an exception for some servo types
===2.1.8.20120216===
*Fixed bug with RFID Reader on OS X and Linux, as well as .NET over the webservice
*Fixed bug that could cause the Java Phidget Manager to crash during garbage collection.
===2.1.8.20120131===
*Fixed RFID Reader bug that caused tag event to not get thrown in .NET Applications
*Changed compass bearing calculations in spatial C# example
===2.1.8.20120123===
*Added support for 1061 v300+
*Fixed a bug where the firmware version could be mis-reported over Bonjour
===2.1.8.20111220===
*Fixed a bug in AppleScript where closing a Phidget opened via label would give a 'Connection Invalid' error.
*Fixed a bug where the webservice may fail to start on Linux systems that don't support IPv6 (ie. SBC2).
*Fixed issue where ratiometric state on newest interfacekit wouldn't be read back properly if it was false during attach.
*Fixed webservice issue where ratiometric state would not be reported properly for newest interfacekits
*Increased the number of overrun errors ignored during initial attach for InterfaceKit.
*Fixed an issue with the iPhone library and header
===2.1.8.20111219===
*fixed various other webservice stability/performance/memory leak bugs
*Faster connection to SBC-connected Phidgets from Mac OS
*Don't report packetlost or overrun errors that happen during early initialization - these are just noise.
*Fixed a bug in the webservice tree removal function that could cause memory leaks.
*Fixed bug where Webservice would crash on Linux if the chosen serverID was already under use on the network
*Stopped sending hardware Error Events before the Attach event - they are now queued up and sent after Attach
*Fixed a crash in the [[Phidget Control Panel]]
*Added ability to remove dictionary keys from a key change listener
*Reduced the number of false 'pending command not finished' error events on Close()
*Fixed a webservice bug where exceptions/false attach events could occur when close() is called soon after open
*Fixed bug where closing a PhidgetRFID soon after attach could cause a crash
*Fixed webservice but on MacOS where client could exit with SIG_PIPE error
*Fixed webservice bug where the server would sometimes exit(1) after many connect/disconnect cycles
*Fixed webservice bug where client could deadlock during close()
*Fixed webservice bug where opening a single remote phidget multiple times from the same application would fail
*Fixed a webservice bug where sockets weren't being closed properly sometimes
*Fixed a webservice bug where pre-attach error events wouldn't get through
*Fixed a bug where the webservice running on Linux would stop responding to clients after ~300 connect/disconnect cycles
*Fixed bug where a Phidget would become inaccessible until the app is restarted if a thread creation failed
*Fixed webservice bug where connect is slow on Windows when multiple clients are running simultaneously
*Fixed webservice bug where authentication would fail on a valid password
*Fixed webservice bug where attach may never happen, and would require a close()/open()

===2.1.8.20111121===
*Added support for new servo types to all libraries
*Fixed min/max position/velocity causing invalid arg exception on servo/advservo
*IPv6 support on MacOS
*Fixed some memory leaks
*Fixed hostname lookup issue on Mac OS with Back To My Mac enabled.
===2.1.8.20111028===
*Fixed Applescript bugs and released examples
*Added openLabel to .NET, Java, COM
*Setting change trigger to 0 on interfacekit will not set event mode.
**Previously setting change trigger to 0 after setting data rate would supersede the data rate setting, which is probably unexpected.
===2.1.8.20110630 - MacOS Only===
*handle USB bug introduced in MacOS 10.6.8
===2.1.8.20110615===
*Added error event when trying to open Phidgets with an unsupported version
===2.1.8.20110614 - Windows Only===
*Fixed bug in C# Spatial example
*Added support for negative gains in 1056
===2.1.8.20110601 - MacOS Only===
*Fixed AppleScript issues
===2.1.8.20110527===
*Fixed AS3.0 library (Flash/Flex) - wouldn't connect to webservice as of last release
*Fixed bug where webservice doesn't release a closed Phidget
*Fixed bug where devices that don't support label didn't show up on MacOS
*Fixed iPhone library issues
===2.1.8.20110524===
*AppleScript support added
*fixed problem with Spatial in .NET on 64-bit Windows
*Added remote setLabel to mac preference pane.
*fixed a bug where label characters 7,8,9 would be read back corrupted on certain devices.
**labels >7 characters that exhibit this bug will now be truncated to 7 characters when being read back
**call setLabel again using this library or newer to support 10 character labels.
**To maintain compatibility with older library versions, limit labels to <=7 characters on these devices.
*fixed bug on MacOS where serial number and/or label strings could be read wrong.
*better support for recovering misbehaving devices in Linux
*fixed a deadlock on linux when Avahi is installed but not running
*clear list of attached devices when closing remote manager
*Added support for Unicode labels
**To maintain compatibility with older library versions, limit labels to ASCII.
*Added open by label
*Webservice protocol version up to 1.0.9 (for open by label)
*Made opening multiple device is one application faster.
*TextLCD changes:
**cursor is disabled while writing to the display or setting a custom character to prevent display artifacts
**cursor is disabled when a full line is written so it doesn't go to the start of another line
**1204 should be stable
**setDisplayCharacter supports 0x00-0xff
*stopped property reflected more accurately in the C# stepper example
*Added error events to mac examples
===2.1.8.20110329 - Windows only===
*Fixed problem with control panel encoder example where enable wouldn't work
*Fixed issue with SpatialData, GPSPositionChange, PHChange and WeightChange events in Labview 64-bit
===2.1.8.20110322===
*Fixed [[Phidget Control Panel]] memory leak when Bonjour in installed but not running
*Fixed current sense formula on 1061_0 v200
*Fixed bug in webservice protocol while using the PhidgetAdvancedServo
*Fixed bug in old PhidgetTemperatureSensor

===2.1.8.20110310===
*Fixed bug in webservice protocol while using the PhidgetServo
*Fixed some Labview bugs
*Added some Java and VB.NET examples
===2.1.8.20110301===
*Full Support for 1002, 1011, 1040, 1046, 1054, 1065, 1204
*New webservice version - 1.0.8
**Support for new devices
**Support for error events
===2.1.7.20110203===
*fixed crash on close of remote Phidget on MacOS
*C# ifkit example bugfix - crashed on 1015/1016
*webservice improvements
*Switch to IP address for SBC config in browser
*Faster IP lookup for SBCs in control panel
===2.1.7.20101222 / 2.1.7.20101223===
*fixed getServerID on Linux
*removed report ack
**this was causing some bad side effects
*manual .local lookups on Windows
**much faster then letting Windows do it itself
*Support for new Labview library
*Fixed PhidgetIR bug where library would crash if repeat code is longer then IR_MAX_REPEAT_LENGTH
===2.1.7.20101103===
*Decreased Phidget Webservice event latency on Windows
*Preliminary support for 1002, 1011, 1040, 1045, 1046, 1054, 1065, 1204 (C, .NET)
*Webservice version updated to 1.0.7
**support for 1045, 1011, 1204
*Fixed a bug where webservice connections could be unexpectedly lost
*Bugfix: couldn't set interfacekit data rate over webservice.
*Fixed some memory leaks in the Mac library
*Fixed bug where blocking for >2 seconds in an events handler when opening remotely could cause a crash.
===2.1.7.20100803===
*Windows only release
*fixed setLabel in WindowsCE
*fixed getHashCode in .NET library - needed for working with Phidgets in Labview via .NET
===2.1.7.20100621===
*Linux only release - autotools updates
**call ldconfig automatically
**remove old phidget21 library (pre-autotools) when installing new one.
===2.1.7.20100620===
*Linux only release - added version.sh for autoreconf
===2.1.7.20100618===
*Linux only release - added udev/hotplug files
===2.1.7.20100617===
*Linux only release
*Transitioned to autotools in linux for phidget21 / webservice
*phidget21 library and webservice are now separate downloads
===2.1.7.20100525===
*full support for PhidgetSpatial and PhidgetIR in all libraries
*fixed 1031 not attaching in AS3.0
*Better error messages in JNI
*Updated error codes, device ID/Class lists in Java, Flash, COM, etc.
*Fixed TemperatureSensor version 200,201,202 bug - ambient sensor would not report negative temperatures.
*Revised temperaturesensor API to report tempMin/tempMax and errors more accurately.
*Added initial events for encoder digital inputs
*full support for 1047
*Added new device support to WindowsCE
*Updated mac examples for 1047, 1048
===2.1.6.20100504===
*Windows only Release
**Added 1131 and 1132 to InterfaceKit example in MSI
===2.1.6.20100428===
*limit data rate maximum to 16ms over the webservice for devices that expose dataRate (InterfaceKit, Spatial)
*fixed bug where TextLCD 8/8/8 would stay in Bonjour list after webservice is shutdown
*set/get Brightness for 1203_2
*Support 1048 in C# example
*webservice version incremented to 1.0.6
**TextLCD set/get brightness
**PhidgetIR support
**PhidgetSpatial support
**1047 support (enable, index)
===2.1.6.20100406===
*Support for 1018_2 (dataRate)
*Webservice version incremented to 1.0.5
===2.1.6.20100401===
*Updated InterfaceKit example with new sensors
*make Windows connect cancelable
*make pending zeroconf lookups cancelable during close
===2.1.6.20100318===
*Mac only release
**Added WillSleep and Wakeup events to give user control of Phidgets immediately before and after a system sleep (MacOS Only).
===2.1.6.20100317===
*Windows only release
**Some of the examples were being built using an out of date .NET library
===2.1.6.20100310===
*MaxMSP fix - 2.1.6.20100126 introduced a bug for some Phidgets where openremote/open by serial didn't work and MaxMSP would sometimes crash.
**No code changes to any of the other libraries.
===2.1.6.20100304===
*stopped property changes trigger events over webservice so they are noticed.
**more compatible with how local open works
*added 5 new servos
*fixed bug where remote close would not set detached so a subsequent open would not always connect.
*handle UninitializeZeroconf better - shut down thread before closing handles, fixes hang on SBC
*fixed bug on Mac where detaching 2 or more Phidgets at the same time caused a crash
*fixed close blocking because of a pending connect (mac, linux)
*Final support for 1031 in all libraries.
===2.1.6.20100129===
*Implemented initial events in Flash
**Flash behaviour should now be identical to C library local and remote.
*Fix RFID issue where close could cause crash
*increment webservice version to 1.0.4
*fixed RFID remote open
**Flash would never get an attach event if the reader had been previously opened
**Initial tag event would not be fired when a tag was present and the antenna was enabled prior to open
*fixed openRemote failing on Mac
*fixed deadlock in webservice which could be hit by opening/closing a device over and over again.
*fixed bug in stepper, which caused seg fault on SBC on position change events.
===2.1.6.20100126===
*added network open support in Max/MSP
===2.1.6.20100115===
*Increased network performance for Linux/MacOS
*Added five servo types
===2.1.6.20091215===
*Fixed busy loop in Linux openRemote
*JNI Library relocated to /Library/Java/Extensions on MacOS
===2.1.6.20091211===
*Heartbeat now works on Linux as well (had to make sockets non-blocking)
===2.1.6.20091130===
*Added heartbeat to webservice (client side)
**Better detects network failures by using active polling timeouts
*Fixed 0/8/8 over webservice
===2.1.6.20091020===
*Fixed 1052 counting issue on 1070 (-1 reported as 255)
*Fixed issue where Phidget21 would try to reinstall from a limited user account or when the Control Panel was disabled.
*64-bit kernel support in Snow Leopard
===2.1.6.20090928===
*Support for PhidgetSBC (1070)
*zeroconf can handle starting up before the mdns daemon, and will keep trying to connect.
*fixed 1066 not showing up on Mac
*added advanced servo example to mac pref pane
*implemented proper error handling in COM
**default behavious remains the same, enable proper error handling with 'EnableVerboseErrors'
*implemented error events in Java
===2.1.6.20090917===
*Updated webservice protocol version to 1.0.3
*Fixed stepper under AS3.0
*added setServoType, getServoType, setServoParameters to PhidgetServo and PhidgetAdvancedServo
*possible race condition fixed in webservice (pdictclient.c:907)
===2.1.6.20090902 (mac only release)===
*Support MacOSX 10.6, drop support for 10.3.9, require 10.4 or newer
**Fully 64-bit compliant, library supports ppc, i386, x86_64
===2.1.6.20090806===
*Added 1049 support
*Fixed RFID tag events over webservice
===2.1.6.20090804===
*Added 1051_2 support
*Fixed various small initialization issues - stepper, adv servo, rfid
*Added 32-bit library install to 64-bit installer
**VB6.0, etc. need the 32-bit COM library on 64-bit windows
===2.1.6.20090717===
*?
===2.1.6.20090708===
*Added DeviceID to zeroconf
*fixed RFID.LastTag in .NET
*Changed the error codes returned by error events; error events now have their own set of error codes rather then sharing the function return codes.
*Added support for 1047, 1048
*Added error event codes rather then trying to reuse the EPHIDGET return codes.
*fixed TextLCD issue where display could get corrupted during a detach/attach
*made mac more reliable on attach
*more error logging on mac
===2.1.6.20090525===
*fixed RFID not attaching via webservice if a tag is present.
*bugfix related to double free on detach event.
*Implemented getKey
*Added MIPS II support to Windows CE
===2.1.6.20090430===
*Added ActiveX interface to COM library
*Added stepper and advancedServo to Flex .swc library
===2.1.6.20090417===
*added PhidgetIR prototype support to C library
*properly handles sleeping on OSX
*fixed some webservice field initializations in Flash and C
*fixed security exceptions in [[Phidget Control Panel]] under Vista
*added [[Phidget Control Panel]] to start menu

===2.1.6.20090318 (Examples/AS3.0 only release)===
*Fixed AdvancedServo in Flash - wouldn't attach
===2.1.6.20090317===
*[[Phidget Control Panel]] properly supports Vista UAC and Limited user accounts in XP, etc.
*Added 64-bit release of Phidget21.msi for Windows

===2.1.6.20090312===
*added 1064, 1059 to WindowsCE
*fixed opening 1051 over webservice
*fixed opening 1015/1016 over webservice broken in last release
===2.1.6.20090302===
*Advanced servo bugfix: stopped would stop being true if min/max was set to exclude current position.
*linux USB improvements when many Phidgets are attached and opened at once.
*1031 support in phidget21, webservice, .NET - hidden until product release
**CPhidgetLED_setVoltage
**CPhidgetLED_getVoltage
**CPhidgetLED_setCurrentLimit
**CPhidgetLED_getCurrentLimit
*unknown timechange == PUNK_INT in encoder position change event
**1st position change event
**> 30 seconds time change
*AS3 updates
**updated to 1.0.2 webservice
**encoder position change events report relative change rather then absolute position
**encoder adds getTimeChange function for timing encoder changes
*webservice updated to 1.0.2
**Authorization is asynchronous
**Doesn't match the old version checking, so errors will not be nice when trying to connect to an old webservice
**Sends out all initial data, so it's just like opening locally
**supports interfacekit Raw sensor value
**supports labels on remoteIP managers
*avahi bugfix
*webservice more stable against forcefully closed clients
*closing a network Phidget won't block - ever.
**no longer using quit, just closing the socket
*added libavahi-client.so.3 reference to linux library.
*Fixed bug with opening one phidget with serial and no serial at the same time over the webservice
===2.1.5.20090105===
*[[Phidget Control Panel]] stability improvements
*added CPhidgetSBC_getHostname
*advanced servo 1 motor current sense equation - support should now be complete
*webservice and network code bugfixes - crash / deadlock during close, problems with concurrent connections, etc.
*fixed close on remote and remoteIP managers
*name of RFID changed from "Phidget RFID 4-output" to "Phidget RFID 2-output" - updated anything referencing old name.

===2.1.5.20081023===
*added advanced servo and stepper examples to VB6.0, VB.NET and C
*added deviceClass and deviceID
*updated Mac examples
*webservice protocol version enforcement
*internal fix/rework of device id's etc.
*Fixed memory leaks in webservice and phidget21 network code.
*Dictionary and network stability improvements.
*duplicate calls to open or close are now silently ignored.
===2.1.4.20080924===
*Old TextLCD 0/8/8's can now have both halves open at the same time on Windows
*fixed bug with composite devices on linux
*fixed manager on linux to better deal with unique devices
===2.1.4.20080922===
*Updated Delphi files
*TextLCD can display 0x80-0xFF characters from Java
*getAttachedDevices works for mdns managers
*fixed a deadlock in the webservice
*better network error handling / password support for windows C# examples
*waitForAttachment will return EPHIDGET_CLOSED if the handle is closed while it is waiting.
*added EPHIDGET_CLOSED
*joining central threads checks whether they are trying to be joined by themselves first (avoid deadlocks).
*changed context of error event to be free from locks (can call close, open, etc. from them).
===2.1.4.20080821===
*zeroconf threads exit cleanly on last _close (apple zeroconf)
*Added advanced servo and stepper to Max
===2.1.4.20080811 (mac only release)===
*Fixed manager on Mac (wasn't working at all since 2.1.4.20080808)
===2.1.4.20080808===
*added CPhidgetSBC and CPhidgetSBCManager to the c library - these interfaces are hidden from users and meant to be used internally (for now).
*CPhidgetManager_open no longer blocks to send out initial attach events. These initial events are sent from the CentralThread context like all other attach events.
*fixed CThread_wait_on_event on Linux
*added CPhidgetGeneric interface for prototyping to C, .NET libraries. product ID is 0x99. These are only visible in debug releases, only to be used internally.
===2.1.4.20080715===
*udev rules fixed for product IDs with alpha-hex values
*blocking in an attach event does not block calls to open anymore
*RFID tag event handlers can now handle blocking - tag lost is timed after the tag handler exits.
===2.1.4.20080623===
*Flex .swc library was out of sync
*fixed CPhidgetManager_getAttachedDevices for network managers
*Added CPhidgetManager_freeAttachedDevicesArray
===2.1.4.20080613===
*Max/MSP RFID fixed
*0/0/8 and advanced servo added to CE
*fixed flash policy file server in webservice
*webservice with password and asynchronous together work now
===2.1.4.20080602===
*phidget21.h -> phidget21int.h so as not to be confused with generated phidget21.h
*some changes to Makefile fro crosscompiling
*no more vbscript in msi
===2.1.4.20080513===
*removed long long from COM - not supported by VB6.0
*added LastTag to RFID in .NET
===2.1.4.20080428===
*support Mac OS X 10.3.9 again
*Rev up to 2.1.4
*finalize Phidget Stepper API - Phidget Stepper requires 2.1.4 as a minimum
*fixed serverConnect and serverDisconnect handlers for manager and dictionary in COM
*Changed:
**PhidgetStepper and PhidgetAdvancedServo
***MotorPosition -> Position
***MotorOn -> Engaged
***MotorStopped -> Stopped
*Added:
**CPhidgetStepper_getCurrentLimit
**CPhidgetEncoder_getPosition
**CPhidgetEncoder_setPosition
**CPhidgetMotorControl_getVelocity
**CPhidgetMotorControl_setVelocity
**CPhidgetMotorControl_set_OnVelocityChange_Handler
**CPhidgetServo_setEngaged
**CPhidgetServo_getEngaged
**CPhidgetServo_getPosition
**CPhidgetServo_setPosition
**CPhidgetServo_set_OnPositionChange_Handler
**CPhidgetServo_getPositionMax
**CPhidgetServo_getPositionMin
**Count functions
*Deprecated:
**CPhidgetEncoder_getEncoderPosition
**CPhidgetEncoder_setEncoderPosition
**CPhidgetMotorControl_getMotorSpeed
**CPhidgetMotorControl_setMotorSpeed
**CPhidgetMotorControl_set_OnMotorChange_Handler
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
**CPhidgetServo_getMotorPosition
**CPhidgetServo_setMotorPosition
**CPhidgetServo_set_OnMotorPositionChange_Handler
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**Num functions
*Added ability to deprecate funcitons in the C library - compiler will issue a warning when they are used.
*added names to some arguments in phidget21.h
*fixes to the webservice for initial state stuff - now it behaves almost like non-webservice, with guaranteed initial events, but we don't guarantee initial state in the attach event yet. Min/Max, Num motors, inputs, etc. are all guaranteed in the attach handler.
*Finalized support for Phidget Stepper
===2.1.3.20080402===
*Fixed windows BUG - Device Type was showing up wrong
*CPhidgetStepper_getPosition -> CPhidgetStepper_getCurrentPosition
===2.1.3.20080327===
*added:
**CPhidgetAdvancedServo_setMotorPositionMax
**CPhidgetAdvancedServo_setMotorPositionMin
**CPhidgetAdvancedServo_getMotorStopped
*changes to API
**CPhidgetStepper_setMotorPosition -> CPhidgetStepper_setTargetMotorPosition
**added CPhidgetStepper_getTargetMotorPosition
**Stepper MotorSpeed -> Velocity
**Stepper and AdvancedServo MaxVelocity -> VelocityLimit
*add waitForAttachment to COM
*COM getbool (not indexed) will now return FALSE on false (rather then always returning true)
*fixed write thread timeouts - was setting attached after starting write thread so write thread would see a detached device and exit immediately
===2.1.3.20080206===
*changed long long to __int64, to be happy in borland C++
*added:
**CPhidgetStepper_getMaxMotorSpeed
**CPhidgetStepper_setMotorOn
**CPhidgetStepper_getMotorOn
**CPhidgetStepper_getMotorStopped
**CPhidgetStepper_setCurrentMotorPosition
*removed CPhidgetStepper_setVelocity
*added CPhidgetStepper_setMaxVelocity, CPhidgetStepper_getMaxVelocity
===2.1.3.20080114===
*Added new functions to Flash API
*Added new functions to Webservice Protocol
*Added new functions to COM Library
*Added new functions to Java Library
*All device fiels in C library cleaned up and made consistent
*Open in windows is exclusive - this needs to be tested for stability
*No data will be returned / accepted if it lies outside of max/min range
*if a data value is unknown, user variable is set to PUNK_INT, PUNK_DBL, or PUNK_BOOL, and return value is EPHIDGET_UNKNOWNVAL
*Proper Device initializations on Attach:
**triggers are set to defaults on attach
**device state is read in and preserved on attach
**during attach event, all sensor data, etc. is provided if available
**no data events until after the attach event returns
**everything initialized by the time waitForAttachment returns
**after attach event returns, a full set of initial state data events are thrown
*.NET collections are readonly, and never NULL (but empty when phidget detached)
*.NET callbacks no longer catch and hide all exceptions
**make sure to use try/catch blocks especially in Attach when accessing properties that may not be initialized.
*added min/max functions:
**CPhidgetAccelerometer_getAccelerationMax
**CPhidgetAccelerometer_getAccelerationMin
**CPhidgetAdvancedServo_getAccelerationMax
**CPhidgetAdvancedServo_getAccelerationMin
**CPhidgetAdvancedServo_getVelocityMax
**CPhidgetAdvancedServo_getVelocityMin
**CPhidgetAdvancedServo_getMotorPositionMax
**CPhidgetAdvancedServo_getMotorPositionMin
**CPhidgetMotorControl_getAccelerationMax
**CPhidgetMotorControl_getAccelerationMin
**CPhidgetPHSensor_getPHMax
**CPhidgetPHSensor_getPHMin
**CPhidgetPHSensor_getPotentialMax
**CPhidgetPHSensor_getPotentialMin
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**CPhidgetStepper_getAccelerationMax
**CPhidgetStepper_getAccelerationMin
**CPhidgetStepper_getMotorSpeedMax
**CPhidgetStepper_getMotorSpeedMin
**CPhidgetStepper_getMotorPositionMax
**CPhidgetStepper_getMotorPositionMin
**CPhidgetTemperatureSensor_getPotentialMax
**CPhidgetTemperatureSensor_getPotentialMin
**CPhidgetTemperatureSensor_getAmbientTemperatureMax
**CPhidgetTemperatureSensor_getAmbientTemperatureMin
**CPhidgetTemperatureSensor_getTemperatureMax
**CPhidgetTemperatureSensor_getTemperatureMin
*Added functions:
**CPhidgetTemperatureSensor_getAmbientTemperature
**CPhidgetTemperatureSensor_getThermocoupleType
**CPhidgetTemperatureSensor_setThermocoupleType
**CPhidget_set_OnServerConnectHandler
**CPhidget_set_OnServerDisconnectHandler
**CPhidgetDictionary_set_OnServerConnectHandler
**CPhidgetDictionary_set_OnServerDisconnectHandler
**CPhidgetManager_set_OnServerConnectHandler
**CPhidgetManager_set_OnServerDisconnectHandler
**CPhidgetDictionary_getServerID
**CPhidgetDictionary_getServerAddress
**CPhidgetDictionary_getServerStatus
**CPhidgetManager_getServerID
**CPhidgetManager_getServerAddress
**CPhidgetManager_getServerStatus
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
*Removed functions:
**CPhidgetServo_setMotorOff
*TemperatureSensor:
**Ambient sensor is accessed with it's own function
**first thermocouple is Index 0 everywhere
**no ambient sensor events
*getServerID is implemented
*changed the internal network structure (added CPhidgetRemote)
*reworked the USB code (mostly on Windows)
**Better handles closing, ESD events, timeouts
**fixed issues with Encoder, RFID stopping reading after a certain time.
**added USB error flag
*openRemote functions have been implemented
**these require bonjour (mac / windows) or avahi (linux) to be installed on both the client and server
**if they are not, you get EPHIDGET_UNSUPPORTED when you call them
*openRemoteIP functions are asynchronous and persistent
*include cphidgetconstants.h in phidget21.h for users
===2.1.2.20071108===
*start of chagelog

Driver Changelog

2017-12-15T22:09:47Z

Patrick:

[[Category:Administrative]]
__NOTOC__

===2.1.8.20171215===
*macOS release
**Fixed USB bug where opening two of the same device with -1 serial could cause missed attach/detach events and other errors.

===2.1.8.20160921===
*macOS release
**Fixed USB bug where devices plugged in before boot were inaccessible until unplugged/re-plugged, under OS X 10.11.

===2.1.8.20160202===
*Windows release
**Labview 7.1 support

===2.1.8.20160107===
*Windows release
**Don't throw an exception on EncoderPositionChangeEventArgs.Time in the .Net library when time it unknown - just return 0x7fffffff

===2.1.8.20160104===
*Mac/Windows release
**New firmware for 1042 and 1044, fixing digital gyro
===2.1.8.20151217===
*Fixed 1045 bug where it will display an unknown ambient temperature sometimes
*Fixed a crash in the windows control panel

===2.1.8.20151020===
*Windows release
**Fixed an issue where the examples would error when trying to run them from the control panel.

===2.1.8.20151009===
*OS X and Windows release
**Upgraded firmware for 1024, 1032, 1041, 1042, 1043, 1044 and 1067 to address issues with these Phidgets on OS X El Capitan
*SBC release
**Support for multiple webcams
===2.1.8.20150821===
*OS X-only release
**Support OS X 10.11 El Capitan
===2.1.8.20150805===
*OS X-only release
**Preliminary support for OS X 10.11 El Capitan
===2.1.8.20150410===
*Linux-only release
**Fixed Makefile phidget21.h target issues
===2.1.8.20150326===
*Windows-only release
**Fixed issue with webservice buttons not being visible in the control panel
===2.1.8.20150323===
*Windows-only release
**Updated icons with new company logo
===2.1.8.20150227===
*Linux-only release
**Added copyright/licence headers to source code files
**Updated cvtutf files to a newer version
===2.1.8.20150109===
*Windows-only
**Fixed examples for Labview 8.5
===2.1.8.20141209===
*OS X-only release
**Added support for armv7s and arm64 to the iOS library. Dropped support for armv6. Requires iOS 5.1.1 or later.
===2.1.8.20141202===
*Windows-only release
**Labview release to support older versions
===2.1.8.20141119===
*OS X-only release
**Fixed an issue with the 2.1.8.20141117 release where nothing was actually installed.
===2.1.8.20141117===
*OS X-only release
**Fixed a code-signing issue that make the installer appear unsigned on OS X 10.10
**Dropped support for OS X 10.4
===2.1.8.20140905===
*Windows-only release
**Added an IA32 folder to the windows libraries download - this supports Windows on the Intel Galileo platform
===2.1.8.20140428===
*Windows-only release
**Fixes to C# Stepper GUI Example
===2.1.8.20140319===
*CPhidget_getDeviceClass can now be called on handle before it is attached.
*Added support for 64-bit Max/MSP (Version 6.1+) on both OS X and Windows.
===2.1.8.20140227===
*Deals with 1046 bug in v100 and v101 firmware.
**No longer reports bad values that appear right after a channel is enabled.
**Fixes issue where changing the gain while channel 0 is disabled would sometimes cause bad readings.

===2.1.8.20131105===
* Fixed a defect in the Flash examples for the 1012 (Outputs 11-16 were not addressed properly).

===2.1.8.20130926===
*Windows-only release
**Support setting label on 1067 from Windows
===2.1.8.20130820===
*Windows-only release
**Added logging option to control panel / C# full examples
===2.1.8.20130802===
*Windows-only release
**Fix for Windows 8 issue where only 'Uninitialized Phidget Handle' would show up in the Manager, and Phidgets could not be opened.
===2.1.8.20130723===
*Improvement to java: we don't attach/detach our native threads for each event, just one attach, then detach before the thread exits.
**This increases performance, esp. when debugging on Android.
*Improvement to Android: We reuse the UsbRequest object rather then creating a new one for each transfer. This reduces logcat messages tremendously, and increases performance.
===2.1.8.20130710===
*Android-only release
**Added extra android target architectures: x86, MIPS, armeabi-v7a
===2.1.8.20130618===
*Changed setCompassCorrectionParameters() API call so that compass calibration parameters are written out to non-volatile storage on 1042/1044, so that they persist across power cycles. Previously, calibration data would need to be re-programmed at each attach.
*Changes to C# Spatial example:
**Compass calibration parameter set dialog removed from for 1042/1044 because parameters are set by the calibration software - and thus do not need setting in the example.
**Stores/restores parameters for 1056 based on serial number, so multiple different calibrations can be maintained.
===2.1.8.20130607===
*Windows-only release
**Fixes to compass calibration software for 1042/1044
===2.1.8.20130419===
*Windows-only release
**Fixed setCompassCorrectionParameters in the COM library
===2.1.8.20130327===
*Windows-only release
**Changed Windows installer to stop virus-scanner false positives
**Dropped support for Windows 2000
===2.1.8.20130320===
*Added EPHIDGET_NOTFOUND exception to Dictionary.getKey() for when the key is not found.
*Added exceptions back into the Java library - they have been missing since 2.1.8.20121015 release.
===2.1.8.20130313===
*Updates to Matlab support
**Works properly on Matlab 7+, on Windows, Mac, Linux without needing changes to .m files.
===2.1.8.20130221===
*Windows-only release
**Encoder Index event added to C and .NET libraries
===2.1.8.20121218===
*Webservice version: 1.0.10
**Support for 1024, 1032
*Support for 1024, 1032
*fixed bug where if one half of a composite device is open, and PHIDGET_USB_ERROR_FLAG gets set, the device may never re-attach.
===2.1.8.20121015===
*Windows-only release
**Support for new pressure/light sensors in example.
===2.1.8.20120914===
*Windows-only release
**Improved firmware upgrading in control panel - it was giving some false-errors on some machines.
===2.1.8.20120912===
*Fixed bug where 1065 could fail to attach when opened over webservice
*Fixed bug where close() could deadlock on Phidgets opened over the webservice
*Changed LED64 LED Brightness from int to double
**this may cause issues when controlling the LED64 over the webservice and library/webservice are not the same version
**the old setDiscreteLED call will remain, deprecated, with an int argument for compatibility.
===2.1.8.20120716===
*Linux-Only Release
**Fixed a bug where opening a device in two program at once would cause an attach-detach cycle as they fight each other for control.
===2.1.8.20120713===
*Mac-Only Release
**Added signing of the Mac installer, so Mountain Lion (OS X 10.8) doesn't refuse to run it.
===2.1.8.20120615===
*Windows-only release
**Fixed a bug that caused java to crash on events introduced in 2.1.8.20120612
===2.1.8.20120612===
*Windows-only release
**Fixed another bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120606===
*Windows-only release
**Fixed a bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120525===
*Windows-only release
**Fixed PhidgetIR sendRawData bug in .NET on 64-bit machines.
===2.1.8.20120514===
*Linux-only release
**Fixed a bug that causes a segfault with libusb-1.0 under 64-bit Linux.
===2.1.8.20120507===
*Mac/Linux-only release
**Fixes a setLabel bug introduced in 2.1.8.20120503
===2.1.8.20120503===
*Fixed some spelling mistakes
*Moved to libusb-1.0
**This resolves a bug where having a webcam plugged in caused a memory leak in the webservice.
*Fixed bug with advanced servo where setting acceleration to accelerationMax would cause an exception for some servo types
===2.1.8.20120216===
*Fixed bug with RFID Reader on OS X and Linux, as well as .NET over the webservice
*Fixed bug that could cause the Java Phidget Manager to crash during garbage collection.
===2.1.8.20120131===
*Fixed RFID Reader bug that caused tag event to not get thrown in .NET Applications
*Changed compass bearing calculations in spatial C# example
===2.1.8.20120123===
*Added support for 1061 v300+
*Fixed a bug where the firmware version could be mis-reported over Bonjour
===2.1.8.20111220===
*Fixed a bug in AppleScript where closing a Phidget opened via label would give a 'Connection Invalid' error.
*Fixed a bug where the webservice may fail to start on Linux systems that don't support IPv6 (ie. SBC2).
*Fixed issue where ratiometric state on newest interfacekit wouldn't be read back properly if it was false during attach.
*Fixed webservice issue where ratiometric state would not be reported properly for newest interfacekits
*Increased the number of overrun errors ignored during initial attach for InterfaceKit.
*Fixed an issue with the iPhone library and header
===2.1.8.20111219===
*fixed various other webservice stability/performance/memory leak bugs
*Faster connection to SBC-connected Phidgets from Mac OS
*Don't report packetlost or overrun errors that happen during early initialization - these are just noise.
*Fixed a bug in the webservice tree removal function that could cause memory leaks.
*Fixed bug where Webservice would crash on Linux if the chosen serverID was already under use on the network
*Stopped sending hardware Error Events before the Attach event - they are now queued up and sent after Attach
*Fixed a crash in the [[Phidget Control Panel]]
*Added ability to remove dictionary keys from a key change listener
*Reduced the number of false 'pending command not finished' error events on Close()
*Fixed a webservice bug where exceptions/false attach events could occur when close() is called soon after open
*Fixed bug where closing a PhidgetRFID soon after attach could cause a crash
*Fixed webservice but on MacOS where client could exit with SIG_PIPE error
*Fixed webservice bug where the server would sometimes exit(1) after many connect/disconnect cycles
*Fixed webservice bug where client could deadlock during close()
*Fixed webservice bug where opening a single remote phidget multiple times from the same application would fail
*Fixed a webservice bug where sockets weren't being closed properly sometimes
*Fixed a webservice bug where pre-attach error events wouldn't get through
*Fixed a bug where the webservice running on Linux would stop responding to clients after ~300 connect/disconnect cycles
*Fixed bug where a Phidget would become inaccessible until the app is restarted if a thread creation failed
*Fixed webservice bug where connect is slow on Windows when multiple clients are running simultaneously
*Fixed webservice bug where authentication would fail on a valid password
*Fixed webservice bug where attach may never happen, and would require a close()/open()

===2.1.8.20111121===
*Added support for new servo types to all libraries
*Fixed min/max position/velocity causing invalid arg exception on servo/advservo
*IPv6 support on MacOS
*Fixed some memory leaks
*Fixed hostname lookup issue on Mac OS with Back To My Mac enabled.
===2.1.8.20111028===
*Fixed Applescript bugs and released examples
*Added openLabel to .NET, Java, COM
*Setting change trigger to 0 on interfacekit will not set event mode.
**Previously setting change trigger to 0 after setting data rate would supersede the data rate setting, which is probably unexpected.
===2.1.8.20110630 - MacOS Only===
*handle USB bug introduced in MacOS 10.6.8
===2.1.8.20110615===
*Added error event when trying to open Phidgets with an unsupported version
===2.1.8.20110614 - Windows Only===
*Fixed bug in C# Spatial example
*Added support for negative gains in 1056
===2.1.8.20110601 - MacOS Only===
*Fixed AppleScript issues
===2.1.8.20110527===
*Fixed AS3.0 library (Flash/Flex) - wouldn't connect to webservice as of last release
*Fixed bug where webservice doesn't release a closed Phidget
*Fixed bug where devices that don't support label didn't show up on MacOS
*Fixed iPhone library issues
===2.1.8.20110524===
*AppleScript support added
*fixed problem with Spatial in .NET on 64-bit Windows
*Added remote setLabel to mac preference pane.
*fixed a bug where label characters 7,8,9 would be read back corrupted on certain devices.
**labels >7 characters that exhibit this bug will now be truncated to 7 characters when being read back
**call setLabel again using this library or newer to support 10 character labels.
**To maintain compatibility with older library versions, limit labels to <=7 characters on these devices.
*fixed bug on MacOS where serial number and/or label strings could be read wrong.
*better support for recovering misbehaving devices in Linux
*fixed a deadlock on linux when Avahi is installed but not running
*clear list of attached devices when closing remote manager
*Added support for Unicode labels
**To maintain compatibility with older library versions, limit labels to ASCII.
*Added open by label
*Webservice protocol version up to 1.0.9 (for open by label)
*Made opening multiple device is one application faster.
*TextLCD changes:
**cursor is disabled while writing to the display or setting a custom character to prevent display artifacts
**cursor is disabled when a full line is written so it doesn't go to the start of another line
**1204 should be stable
**setDisplayCharacter supports 0x00-0xff
*stopped property reflected more accurately in the C# stepper example
*Added error events to mac examples
===2.1.8.20110329 - Windows only===
*Fixed problem with control panel encoder example where enable wouldn't work
*Fixed issue with SpatialData, GPSPositionChange, PHChange and WeightChange events in Labview 64-bit
===2.1.8.20110322===
*Fixed [[Phidget Control Panel]] memory leak when Bonjour in installed but not running
*Fixed current sense formula on 1061_0 v200
*Fixed bug in webservice protocol while using the PhidgetAdvancedServo
*Fixed bug in old PhidgetTemperatureSensor

===2.1.8.20110310===
*Fixed bug in webservice protocol while using the PhidgetServo
*Fixed some Labview bugs
*Added some Java and VB.NET examples
===2.1.8.20110301===
*Full Support for 1002, 1011, 1040, 1046, 1054, 1065, 1204
*New webservice version - 1.0.8
**Support for new devices
**Support for error events
===2.1.7.20110203===
*fixed crash on close of remote Phidget on MacOS
*C# ifkit example bugfix - crashed on 1015/1016
*webservice improvements
*Switch to IP address for SBC config in browser
*Faster IP lookup for SBCs in control panel
===2.1.7.20101222 / 2.1.7.20101223===
*fixed getServerID on Linux
*removed report ack
**this was causing some bad side effects
*manual .local lookups on Windows
**much faster then letting Windows do it itself
*Support for new Labview library
*Fixed PhidgetIR bug where library would crash if repeat code is longer then IR_MAX_REPEAT_LENGTH
===2.1.7.20101103===
*Decreased Phidget Webservice event latency on Windows
*Preliminary support for 1002, 1011, 1040, 1045, 1046, 1054, 1065, 1204 (C, .NET)
*Webservice version updated to 1.0.7
**support for 1045, 1011, 1204
*Fixed a bug where webservice connections could be unexpectedly lost
*Bugfix: couldn't set interfacekit data rate over webservice.
*Fixed some memory leaks in the Mac library
*Fixed bug where blocking for >2 seconds in an events handler when opening remotely could cause a crash.
===2.1.7.20100803===
*Windows only release
*fixed setLabel in WindowsCE
*fixed getHashCode in .NET library - needed for working with Phidgets in Labview via .NET
===2.1.7.20100621===
*Linux only release - autotools updates
**call ldconfig automatically
**remove old phidget21 library (pre-autotools) when installing new one.
===2.1.7.20100620===
*Linux only release - added version.sh for autoreconf
===2.1.7.20100618===
*Linux only release - added udev/hotplug files
===2.1.7.20100617===
*Linux only release
*Transitioned to autotools in linux for phidget21 / webservice
*phidget21 library and webservice are now separate downloads
===2.1.7.20100525===
*full support for PhidgetSpatial and PhidgetIR in all libraries
*fixed 1031 not attaching in AS3.0
*Better error messages in JNI
*Updated error codes, device ID/Class lists in Java, Flash, COM, etc.
*Fixed TemperatureSensor version 200,201,202 bug - ambient sensor would not report negative temperatures.
*Revised temperaturesensor API to report tempMin/tempMax and errors more accurately.
*Added initial events for encoder digital inputs
*full support for 1047
*Added new device support to WindowsCE
*Updated mac examples for 1047, 1048
===2.1.6.20100504===
*Windows only Release
**Added 1131 and 1132 to InterfaceKit example in MSI
===2.1.6.20100428===
*limit data rate maximum to 16ms over the webservice for devices that expose dataRate (InterfaceKit, Spatial)
*fixed bug where TextLCD 8/8/8 would stay in Bonjour list after webservice is shutdown
*set/get Brightness for 1203_2
*Support 1048 in C# example
*webservice version incremented to 1.0.6
**TextLCD set/get brightness
**PhidgetIR support
**PhidgetSpatial support
**1047 support (enable, index)
===2.1.6.20100406===
*Support for 1018_2 (dataRate)
*Webservice version incremented to 1.0.5
===2.1.6.20100401===
*Updated InterfaceKit example with new sensors
*make Windows connect cancelable
*make pending zeroconf lookups cancelable during close
===2.1.6.20100318===
*Mac only release
**Added WillSleep and Wakeup events to give user control of Phidgets immediately before and after a system sleep (MacOS Only).
===2.1.6.20100317===
*Windows only release
**Some of the examples were being built using an out of date .NET library
===2.1.6.20100310===
*MaxMSP fix - 2.1.6.20100126 introduced a bug for some Phidgets where openremote/open by serial didn't work and MaxMSP would sometimes crash.
**No code changes to any of the other libraries.
===2.1.6.20100304===
*stopped property changes trigger events over webservice so they are noticed.
**more compatible with how local open works
*added 5 new servos
*fixed bug where remote close would not set detached so a subsequent open would not always connect.
*handle UninitializeZeroconf better - shut down thread before closing handles, fixes hang on SBC
*fixed bug on Mac where detaching 2 or more Phidgets at the same time caused a crash
*fixed close blocking because of a pending connect (mac, linux)
*Final support for 1031 in all libraries.
===2.1.6.20100129===
*Implemented initial events in Flash
**Flash behaviour should now be identical to C library local and remote.
*Fix RFID issue where close could cause crash
*increment webservice version to 1.0.4
*fixed RFID remote open
**Flash would never get an attach event if the reader had been previously opened
**Initial tag event would not be fired when a tag was present and the antenna was enabled prior to open
*fixed openRemote failing on Mac
*fixed deadlock in webservice which could be hit by opening/closing a device over and over again.
*fixed bug in stepper, which caused seg fault on SBC on position change events.
===2.1.6.20100126===
*added network open support in Max/MSP
===2.1.6.20100115===
*Increased network performance for Linux/MacOS
*Added five servo types
===2.1.6.20091215===
*Fixed busy loop in Linux openRemote
*JNI Library relocated to /Library/Java/Extensions on MacOS
===2.1.6.20091211===
*Heartbeat now works on Linux as well (had to make sockets non-blocking)
===2.1.6.20091130===
*Added heartbeat to webservice (client side)
**Better detects network failures by using active polling timeouts
*Fixed 0/8/8 over webservice
===2.1.6.20091020===
*Fixed 1052 counting issue on 1070 (-1 reported as 255)
*Fixed issue where Phidget21 would try to reinstall from a limited user account or when the Control Panel was disabled.
*64-bit kernel support in Snow Leopard
===2.1.6.20090928===
*Support for PhidgetSBC (1070)
*zeroconf can handle starting up before the mdns daemon, and will keep trying to connect.
*fixed 1066 not showing up on Mac
*added advanced servo example to mac pref pane
*implemented proper error handling in COM
**default behavious remains the same, enable proper error handling with 'EnableVerboseErrors'
*implemented error events in Java
===2.1.6.20090917===
*Updated webservice protocol version to 1.0.3
*Fixed stepper under AS3.0
*added setServoType, getServoType, setServoParameters to PhidgetServo and PhidgetAdvancedServo
*possible race condition fixed in webservice (pdictclient.c:907)
===2.1.6.20090902 (mac only release)===
*Support MacOSX 10.6, drop support for 10.3.9, require 10.4 or newer
**Fully 64-bit compliant, library supports ppc, i386, x86_64
===2.1.6.20090806===
*Added 1049 support
*Fixed RFID tag events over webservice
===2.1.6.20090804===
*Added 1051_2 support
*Fixed various small initialization issues - stepper, adv servo, rfid
*Added 32-bit library install to 64-bit installer
**VB6.0, etc. need the 32-bit COM library on 64-bit windows
===2.1.6.20090717===
*?
===2.1.6.20090708===
*Added DeviceID to zeroconf
*fixed RFID.LastTag in .NET
*Changed the error codes returned by error events; error events now have their own set of error codes rather then sharing the function return codes.
*Added support for 1047, 1048
*Added error event codes rather then trying to reuse the EPHIDGET return codes.
*fixed TextLCD issue where display could get corrupted during a detach/attach
*made mac more reliable on attach
*more error logging on mac
===2.1.6.20090525===
*fixed RFID not attaching via webservice if a tag is present.
*bugfix related to double free on detach event.
*Implemented getKey
*Added MIPS II support to Windows CE
===2.1.6.20090430===
*Added ActiveX interface to COM library
*Added stepper and advancedServo to Flex .swc library
===2.1.6.20090417===
*added PhidgetIR prototype support to C library
*properly handles sleeping on OSX
*fixed some webservice field initializations in Flash and C
*fixed security exceptions in [[Phidget Control Panel]] under Vista
*added [[Phidget Control Panel]] to start menu

===2.1.6.20090318 (Examples/AS3.0 only release)===
*Fixed AdvancedServo in Flash - wouldn't attach
===2.1.6.20090317===
*[[Phidget Control Panel]] properly supports Vista UAC and Limited user accounts in XP, etc.
*Added 64-bit release of Phidget21.msi for Windows

===2.1.6.20090312===
*added 1064, 1059 to WindowsCE
*fixed opening 1051 over webservice
*fixed opening 1015/1016 over webservice broken in last release
===2.1.6.20090302===
*Advanced servo bugfix: stopped would stop being true if min/max was set to exclude current position.
*linux USB improvements when many Phidgets are attached and opened at once.
*1031 support in phidget21, webservice, .NET - hidden until product release
**CPhidgetLED_setVoltage
**CPhidgetLED_getVoltage
**CPhidgetLED_setCurrentLimit
**CPhidgetLED_getCurrentLimit
*unknown timechange == PUNK_INT in encoder position change event
**1st position change event
**> 30 seconds time change
*AS3 updates
**updated to 1.0.2 webservice
**encoder position change events report relative change rather then absolute position
**encoder adds getTimeChange function for timing encoder changes
*webservice updated to 1.0.2
**Authorization is asynchronous
**Doesn't match the old version checking, so errors will not be nice when trying to connect to an old webservice
**Sends out all initial data, so it's just like opening locally
**supports interfacekit Raw sensor value
**supports labels on remoteIP managers
*avahi bugfix
*webservice more stable against forcefully closed clients
*closing a network Phidget won't block - ever.
**no longer using quit, just closing the socket
*added libavahi-client.so.3 reference to linux library.
*Fixed bug with opening one phidget with serial and no serial at the same time over the webservice
===2.1.5.20090105===
*[[Phidget Control Panel]] stability improvements
*added CPhidgetSBC_getHostname
*advanced servo 1 motor current sense equation - support should now be complete
*webservice and network code bugfixes - crash / deadlock during close, problems with concurrent connections, etc.
*fixed close on remote and remoteIP managers
*name of RFID changed from "Phidget RFID 4-output" to "Phidget RFID 2-output" - updated anything referencing old name.

===2.1.5.20081023===
*added advanced servo and stepper examples to VB6.0, VB.NET and C
*added deviceClass and deviceID
*updated Mac examples
*webservice protocol version enforcement
*internal fix/rework of device id's etc.
*Fixed memory leaks in webservice and phidget21 network code.
*Dictionary and network stability improvements.
*duplicate calls to open or close are now silently ignored.
===2.1.4.20080924===
*Old TextLCD 0/8/8's can now have both halves open at the same time on Windows
*fixed bug with composite devices on linux
*fixed manager on linux to better deal with unique devices
===2.1.4.20080922===
*Updated Delphi files
*TextLCD can display 0x80-0xFF characters from Java
*getAttachedDevices works for mdns managers
*fixed a deadlock in the webservice
*better network error handling / password support for windows C# examples
*waitForAttachment will return EPHIDGET_CLOSED if the handle is closed while it is waiting.
*added EPHIDGET_CLOSED
*joining central threads checks whether they are trying to be joined by themselves first (avoid deadlocks).
*changed context of error event to be free from locks (can call close, open, etc. from them).
===2.1.4.20080821===
*zeroconf threads exit cleanly on last _close (apple zeroconf)
*Added advanced servo and stepper to Max
===2.1.4.20080811 (mac only release)===
*Fixed manager on Mac (wasn't working at all since 2.1.4.20080808)
===2.1.4.20080808===
*added CPhidgetSBC and CPhidgetSBCManager to the c library - these interfaces are hidden from users and meant to be used internally (for now).
*CPhidgetManager_open no longer blocks to send out initial attach events. These initial events are sent from the CentralThread context like all other attach events.
*fixed CThread_wait_on_event on Linux
*added CPhidgetGeneric interface for prototyping to C, .NET libraries. product ID is 0x99. These are only visible in debug releases, only to be used internally.
===2.1.4.20080715===
*udev rules fixed for product IDs with alpha-hex values
*blocking in an attach event does not block calls to open anymore
*RFID tag event handlers can now handle blocking - tag lost is timed after the tag handler exits.
===2.1.4.20080623===
*Flex .swc library was out of sync
*fixed CPhidgetManager_getAttachedDevices for network managers
*Added CPhidgetManager_freeAttachedDevicesArray
===2.1.4.20080613===
*Max/MSP RFID fixed
*0/0/8 and advanced servo added to CE
*fixed flash policy file server in webservice
*webservice with password and asynchronous together work now
===2.1.4.20080602===
*phidget21.h -> phidget21int.h so as not to be confused with generated phidget21.h
*some changes to Makefile fro crosscompiling
*no more vbscript in msi
===2.1.4.20080513===
*removed long long from COM - not supported by VB6.0
*added LastTag to RFID in .NET
===2.1.4.20080428===
*support Mac OS X 10.3.9 again
*Rev up to 2.1.4
*finalize Phidget Stepper API - Phidget Stepper requires 2.1.4 as a minimum
*fixed serverConnect and serverDisconnect handlers for manager and dictionary in COM
*Changed:
**PhidgetStepper and PhidgetAdvancedServo
***MotorPosition -> Position
***MotorOn -> Engaged
***MotorStopped -> Stopped
*Added:
**CPhidgetStepper_getCurrentLimit
**CPhidgetEncoder_getPosition
**CPhidgetEncoder_setPosition
**CPhidgetMotorControl_getVelocity
**CPhidgetMotorControl_setVelocity
**CPhidgetMotorControl_set_OnVelocityChange_Handler
**CPhidgetServo_setEngaged
**CPhidgetServo_getEngaged
**CPhidgetServo_getPosition
**CPhidgetServo_setPosition
**CPhidgetServo_set_OnPositionChange_Handler
**CPhidgetServo_getPositionMax
**CPhidgetServo_getPositionMin
**Count functions
*Deprecated:
**CPhidgetEncoder_getEncoderPosition
**CPhidgetEncoder_setEncoderPosition
**CPhidgetMotorControl_getMotorSpeed
**CPhidgetMotorControl_setMotorSpeed
**CPhidgetMotorControl_set_OnMotorChange_Handler
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
**CPhidgetServo_getMotorPosition
**CPhidgetServo_setMotorPosition
**CPhidgetServo_set_OnMotorPositionChange_Handler
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**Num functions
*Added ability to deprecate funcitons in the C library - compiler will issue a warning when they are used.
*added names to some arguments in phidget21.h
*fixes to the webservice for initial state stuff - now it behaves almost like non-webservice, with guaranteed initial events, but we don't guarantee initial state in the attach event yet. Min/Max, Num motors, inputs, etc. are all guaranteed in the attach handler.
*Finalized support for Phidget Stepper
===2.1.3.20080402===
*Fixed windows BUG - Device Type was showing up wrong
*CPhidgetStepper_getPosition -> CPhidgetStepper_getCurrentPosition
===2.1.3.20080327===
*added:
**CPhidgetAdvancedServo_setMotorPositionMax
**CPhidgetAdvancedServo_setMotorPositionMin
**CPhidgetAdvancedServo_getMotorStopped
*changes to API
**CPhidgetStepper_setMotorPosition -> CPhidgetStepper_setTargetMotorPosition
**added CPhidgetStepper_getTargetMotorPosition
**Stepper MotorSpeed -> Velocity
**Stepper and AdvancedServo MaxVelocity -> VelocityLimit
*add waitForAttachment to COM
*COM getbool (not indexed) will now return FALSE on false (rather then always returning true)
*fixed write thread timeouts - was setting attached after starting write thread so write thread would see a detached device and exit immediately
===2.1.3.20080206===
*changed long long to __int64, to be happy in borland C++
*added:
**CPhidgetStepper_getMaxMotorSpeed
**CPhidgetStepper_setMotorOn
**CPhidgetStepper_getMotorOn
**CPhidgetStepper_getMotorStopped
**CPhidgetStepper_setCurrentMotorPosition
*removed CPhidgetStepper_setVelocity
*added CPhidgetStepper_setMaxVelocity, CPhidgetStepper_getMaxVelocity
===2.1.3.20080114===
*Added new functions to Flash API
*Added new functions to Webservice Protocol
*Added new functions to COM Library
*Added new functions to Java Library
*All device fiels in C library cleaned up and made consistent
*Open in windows is exclusive - this needs to be tested for stability
*No data will be returned / accepted if it lies outside of max/min range
*if a data value is unknown, user variable is set to PUNK_INT, PUNK_DBL, or PUNK_BOOL, and return value is EPHIDGET_UNKNOWNVAL
*Proper Device initializations on Attach:
**triggers are set to defaults on attach
**device state is read in and preserved on attach
**during attach event, all sensor data, etc. is provided if available
**no data events until after the attach event returns
**everything initialized by the time waitForAttachment returns
**after attach event returns, a full set of initial state data events are thrown
*.NET collections are readonly, and never NULL (but empty when phidget detached)
*.NET callbacks no longer catch and hide all exceptions
**make sure to use try/catch blocks especially in Attach when accessing properties that may not be initialized.
*added min/max functions:
**CPhidgetAccelerometer_getAccelerationMax
**CPhidgetAccelerometer_getAccelerationMin
**CPhidgetAdvancedServo_getAccelerationMax
**CPhidgetAdvancedServo_getAccelerationMin
**CPhidgetAdvancedServo_getVelocityMax
**CPhidgetAdvancedServo_getVelocityMin
**CPhidgetAdvancedServo_getMotorPositionMax
**CPhidgetAdvancedServo_getMotorPositionMin
**CPhidgetMotorControl_getAccelerationMax
**CPhidgetMotorControl_getAccelerationMin
**CPhidgetPHSensor_getPHMax
**CPhidgetPHSensor_getPHMin
**CPhidgetPHSensor_getPotentialMax
**CPhidgetPHSensor_getPotentialMin
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**CPhidgetStepper_getAccelerationMax
**CPhidgetStepper_getAccelerationMin
**CPhidgetStepper_getMotorSpeedMax
**CPhidgetStepper_getMotorSpeedMin
**CPhidgetStepper_getMotorPositionMax
**CPhidgetStepper_getMotorPositionMin
**CPhidgetTemperatureSensor_getPotentialMax
**CPhidgetTemperatureSensor_getPotentialMin
**CPhidgetTemperatureSensor_getAmbientTemperatureMax
**CPhidgetTemperatureSensor_getAmbientTemperatureMin
**CPhidgetTemperatureSensor_getTemperatureMax
**CPhidgetTemperatureSensor_getTemperatureMin
*Added functions:
**CPhidgetTemperatureSensor_getAmbientTemperature
**CPhidgetTemperatureSensor_getThermocoupleType
**CPhidgetTemperatureSensor_setThermocoupleType
**CPhidget_set_OnServerConnectHandler
**CPhidget_set_OnServerDisconnectHandler
**CPhidgetDictionary_set_OnServerConnectHandler
**CPhidgetDictionary_set_OnServerDisconnectHandler
**CPhidgetManager_set_OnServerConnectHandler
**CPhidgetManager_set_OnServerDisconnectHandler
**CPhidgetDictionary_getServerID
**CPhidgetDictionary_getServerAddress
**CPhidgetDictionary_getServerStatus
**CPhidgetManager_getServerID
**CPhidgetManager_getServerAddress
**CPhidgetManager_getServerStatus
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
*Removed functions:
**CPhidgetServo_setMotorOff
*TemperatureSensor:
**Ambient sensor is accessed with it's own function
**first thermocouple is Index 0 everywhere
**no ambient sensor events
*getServerID is implemented
*changed the internal network structure (added CPhidgetRemote)
*reworked the USB code (mostly on Windows)
**Better handles closing, ESD events, timeouts
**fixed issues with Encoder, RFID stopping reading after a certain time.
**added USB error flag
*openRemote functions have been implemented
**these require bonjour (mac / windows) or avahi (linux) to be installed on both the client and server
**if they are not, you get EPHIDGET_UNSUPPORTED when you call them
*openRemoteIP functions are asynchronous and persistent
*include cphidgetconstants.h in phidget21.h for users
===2.1.2.20071108===
*start of chagelog

Template:UGsbc2

2017-09-18T18:13:04Z

Patrick:

==SBC Web Interface==

Using the operating system sections of this guide, you should have been able to open a web browser with a connection to the SBC using either:
* The Phidget Control Panel (Windows), or
* The Phidget Preference Pane (Mac OS), or
* An mDNS connection (Linux).
Here we cover the basics on the tool that has been opened in the browser, known as the SBC Web Interface.

===Set the Password===

If this is your first time connecting to the SBC (or after a complete factory reset), you will see a screen asking you to set a password:

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

This password will be linked to the user {{Code|admin}} if you use the web interface in the future, and to the user {{Code|root}} if you choose to use SSH. These are actually the same user, and the SSH connection is covered in-depth on the [[OS - Phidget SBC|SBC operating system page]].

Remember this password, as you will need it to connect to the SBC in the future, and the only way to log in if you lose it is to perform a [[OS - Phidget SBC#Factory Reset|full factory reset]] on the SBC.

The next time you connect to the SBC after you log out or reboot the SBC, you will be asked to log in with a user name and password:

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

===Navigating===

The SBC Web Interface has a series of tabs and sub-tabs at the top, and by using these you can access the entire web interface. Note that the web interface only allows you to configure a very small portion of the SBC, please refer to the full [[OS - Phidget SBC]] page for an in-depth introduction on the SBC Linux operating system.

The header also has information about how long the SBC had been powered on without a reboot, what the link local address of the SBC is (here it is {{Code|phidgetsbc}}, so the full link local address is {{Code|phidgetsbc.local}}) and more:

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

The starting page of the web interface will also give you information about:
* The name of the SBC (you can rename it under {{Code|System → General}}, although note that this will '''also change the link local address of the SBC to that name''')
* The build, kernel, and board revision
* The MAC address (of the Ethernet connection...the wireless MAC address can be found on {{Code|Network → Status}} when the adapter is plugged in)
* The space left in your / filesystem (the amount of space you have for programs, and files not written to an external USB key)
* Any additionally mounted filesystems (such as a USB data key)
* The amount of memory your SBC is currently using. This can be a bit misleading however. To get a better idea of the total memory usage go to the "Processes" subtab and look at memory usage on a per-process basis.

This can also be accessed later from {{Code|Status → System}}:

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

===Set up Networking===

After using the initial wired Ethernet connection (as described in detail in the [[#Hardware|hardware section]]) to access the web interface for the first time, you can use the {{Code|Network}} tab in the web interface to configure other network settings for use.

The SBC can switch dynamically between Ethernet (what it tries first) and wireless via the [{{SERVER}}/products.php?product_id=3702 Wi-Fi USB Adapter w/SMA Antenna]. It is also able to dynamically handle both Ethernet and wireless being unplugged and then plugged back in. This is especially useful if you are designing a project where the SBC will operate without a network - when testing you can plug in and remove the network adapters to check on how the SBC is doing.

====Wireless====

The SBC can only access wireless networks using the [{{SERVER}}/products.php?product_id=3702 Wi-Fi USB Adapter w/SMA Antenna]. If this WiFi adapter is plugged in to a USB port on the SBC, you will see something like this under {{Code|Network → Wireless}} in the web interface:

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

Here you can add and remember networks with passwords. These do not necessarily have to be networks that are currently seen - you can add the SSID and password of your home network, for example, and the next time the SBC boots at home with wireless only it will connect to your home wireless network. These SSID settings are only for DHCP networks.

====Static IP====

If you do not have DHCP on your main network, and do not want to use link local addressing, you can set the network connection to be static. These settings can be found in the web interface under {{Code|Network → Settings}} for the Ethernet interface, and at the bottom of {{Code|Network → Wireless}} for wireless networking. In the Ethernet settings, for example, you can specify network elements manually in the same way you would for a desktop computer:

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

This setting is also useful to work entirely without mDNS and link local addressing. After setting it, the SBC will start using that static IP immediately, so if this is done improperly this can make the SBC very hard to re-connect to depending on the routing within the rest of your network. If you are not sure whether this will be a problem, it may help to read the in-depth [[OS - Phidget SBC#Initial Internet Setup|network troubleshooting section]] for the SBC.

===View Attached Phidgets===

You can view Phidgets that are directly attached to the SBC by going to {{Code|Phidgets → Status}} in the web interface:

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

This will always show the attached Interface Kit that is part of the SBC board. It will also show any Phidgets plugged into the SBC's USB ports.

On the right hand side of this screen (not shown in the screenshot) you will see the serial numbers of the attached Phidgets. If you want to use these Phidgets within your code over a network using the webservice, you can use these serial numbers in your programming project.

Note that any analog or digital sensors will not show up here, as they are a 'part' of the Interface Kit and can be accessed through the ports in the Interface Kit API. Taking a look at the [[1018 User Guide|User Guide]] for the [{{SERVER}}/products.php?product_id=1018 PhidgetInterfaceKit 8/8/8] will show you a good example of how this works.

===Use the Webcam===

Using the webcam (either the [{{SERVER}}/products.php?product_id=3402 Phidget USB Webcam] or another [https://en.wikipedia.org/wiki/List_of_USB_video_class_devices UVC-compatible webcam]) should be fairly straightforward. Plug it in, then head to the web interface under {{Code|Webcam → Webcam}}:

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

This will allow you to stream video into the web interface. This stream can also be viewed with any compatible M-JPG viewer, such as VLC. To take pictures with the webcam within your code, see the [[OS - Phidget SBC#Taking Pictures with the Webcam|how-to]] on the main SBC operating system page.

Webcams that support pan/tilt can be controlled via the web interface. Multiple frame rates and resolutions are supported.

If the video stream is to be exported over the internet, it is recommended that the password be enabled. However, it must be noted that this is a simple HTTP authentication, which is sent unencrypted, and is thus not highly secure.

If prompted for the webcam password, the username is ‘webcam’.

If multiple webcams are attached, they will all start up using the same settings, except that each additional webcam will run on the next higher port number. Multiple webcams will generally only work when the resolution and framerate are set to low levels.

At this point, we have covered most of the common uses of the web interface. But the web interface offers many more configuration options. This reference section covers all of the available options. If you want to continue on to tasks such as writing and running code on the SBC, visit the [[OS - Phidget SBC]] page.

====Can I use multiple webcams?====
Probably... In theory you can connect multiple webcams to the SBC, however, the bandwidth of a USB1.1 hub will limit the amount of data you can stream meaning you might have to use reduces resolution/framerate to do it successfully.

Template:UGsbc1

2017-09-18T18:11:45Z

Patrick:

===Basic Use===

Basic use of the PhidgetSBC allows the opening of connected Phidgets over the network. Using another Phidget with the PhidgetSBC in this way is almost exactly like using Phidgets over USB, in respect to the API calls and behavior. However, some extra considerations need to be made when working with the PhidgetWebservice.

===Phidget Webservice===

Support for opening Phidgets over the network is made possible via the Phidget Webservice. This allows a user to write an application in a system and language of their choosing and then operate Phidgets connected to the PhidgetSBC. It is a socket based server that runs on the PhidgetSBC, and allows any attached Phidgets to be seen and opened directly over the network. To use this server go to the "Phidgets->WebService" tab in the web configuration page and enable it.

Opening and controlling a Phidget over the network is nearly the same as opening one locally. The main differences are:

*Different open calls that include server information. New calls OpenRemote and openRemoteIP (naming depends on language).
*Access to Webservice based properties: Server hostname, port and ID.
*Access to server connect and disconnect events, and network error events.
*Phidgets can be opened by more then one separate application at the same time.
*Reliability is more of a issue because network connections are easily broken

Opening a Phidget over the network is asynchronous and pervasive, just like opening locally. This means that if a connection to the remote server cannot be established right away, it will keep trying indefinitely, and even survive the server being stopped and started, etc. Instances of the Phidget Webservice can be referred to either using hostname (IP Address) and port number, or by Server ID. The advantage of using a Server ID is that it stays consistent compared to IP addresses, and you don’t need to know the Port number. A Webservice Server ID is assigned when the Webservice is run - which on the PhidgetSBC defaults to ‘phidgetsbc’. In order to use a Server ID, the Bonjour utility also needs to be installed. Refer to the Programming Manual and the API manual for your language for more information about using the Phidget Webservice.

====Reliability====

Determining reliability needs can become important while opening Phidgets over the network, because the network connection can potentially be interrupted at any time. This can leave the network attached Phidget in an undesirable state. For example - if a motor controller is driving a motor and the connection is lost, there is no way to stop the motor until the connection is re-established. These issues are less important if you are just receiving sensor data from an Interface Kit.

It’s generally a good idea to catch server connect and disconnect and Phidget attach and detach events in order to know the state of the connections. It’s also a good idea to catch error events - this is where network errors will be reported. If reliability is important, you should consider writing a program to run locally on the PhidgetSBC, and communicate with it through the Dictionary interface. This way, if the connection is broken, the local application will notice and be able to take any appropriate actions. See the advanced chapter for more information.

====Finding Phidgets on the Network====

Any Phidgets attached to the PhidgetSBC can be identified using the Status >> Phidgets page in the configuration interface, and should be seen on the network through the Webservice. The Phidget Control Panel has a Bonjour tab (under WebService >> Bonjour) that lists all detected network attached Phidgets. The Phidgets connected to the PhidgetSBC should be seen here and can be opened by double clicking its name in the menu. Network attached Phidgets can also be located programmatically with the Phidget Manager. The Phidget Manager is used with either hostname and port, or server ID, just like with ‘Open’. The manager can also be used to find all Phidgets on any Webservice through Bonjour, by specifying a NULL Server ID. See your specific language’s guide for more information about coding with the Phidget Manager.

===Testing Using Mac OS X===
The steps are very similar to the Windows process described above:
#Ensure you have OS X 10.3.9 or later running.
#Download and run the [{{SERVER}}/downloads/phidget21/libraries/macos/Phidget.dmg Installer] ([{{SERVER}}/docs/Software_License#OS_X software license])
#Click on System Preferences → Phidgets (under Other) to activate the Preference Pane
#Make sure that the Phidget SBC is properly attached to the network as described in the [[#Getting_Started|Getting Started section]]
#Double Click on the Phidget SBC in the Phidget Preference Pane to bring up the Web Interface in your default browser
#Or, click on the Bonjour tab to see attached Phidgets being run over the network and to bring up their examples

The address in the browser that connects to the SBC is either an '''IP address''' (such as 192.168.2.181) or a '''link local address''', (such as {{Code|phidgetsbc.local}}, which is the default). Note down the address in the browser, as you will need this information for later if you will be working [[OS - Phidget SBC|directly with the SBC]] to perform tasks such as writing or running code. But for now, with the web interface open, we have a [[#SBC Web Interface|section to walk you through it]].

===Using Linux===

With Linux, you have many setup options, but all involve knowing the IP address or link local address of the SBC after you have plugged it in as described in [[#Getting_Started|Getting Started section]]. The IP address can be somewhat difficult to obtain, but the default link local address for all new Phidget SBCs is {{Code|phidgetsbc.local}} - which is an mDNS address. Wait at least three minutes after booting the SBC to make sure link local addressing is started. You'll also need some form of mDNS (either {{Code|avahi}} or {{Code|mDNSResponder}}) installed on your main computer. The {{Code|avahi}} service is usually installed by default on most Linux machines, try {{Code|which avahi-resolve}} to make sure. Then, try typing {{Code|phidgetsbc.local}} into a web browser. The [[#SBC Web Interface|web interface]] should come up, starting with the [[#Set the Password|Set the Password]] screen.

Note that some browsers (i.e. Google Chrome) combine search and addressing in the same address bar, so you may need to turn off web service and prediction service in {{Code|Preferences → Under The Bonnet}} for Chrome to treat {{Code|phidgetsbc.local}} like a web address rather than a search term. If these steps do not bring you to the initial setup password screen as shown in the [[#SBC Web Interface|SBC Web Interface section]], you will probably need to read the [[OS - Phidget SBC#Initial Internet Setup|internet setup section on the SBC OS Page]]. That section contains more than just troubleshooting information - it includes in-depth information on how the SBC starts its network, your initial network configuration options, and how to connect to the SBC without mDNS using both DHCP and static IP.

If you want to use the SBC to broadcast data from Phidgets over a network, the SBC is already automatically performing this function with its attached Interface Kit, and will also do so for any Phidgets plugged into its USB ports. If this is your sole intended use of the SBC, you can skip ahead to our example on using the [[#Linux - Attached Interface Kit | attached Interface Kit]].

However, the SBC is much, much more than simply a way to get data from Phidgets over a network. You can use the SBC as an external Linux computer. You'll need to [[#Set the Password|set a password]] using the SBC web interface, and write down a network address of the SBC ({{Code|phidgetsbc.local}}, or an IP address if you worked through the [[OS - Phidget SBC#Initial Internet Setup|internet setup section on the SBC OS Page]]). But after that, if no other sections in the basic [[#SBC Web Interface|SBC web interface]] section apply to you (using the webcam, setting up wireless networking, or checking system parameters like memory), you can skip ahead to the [[OS - Phidget SBC]] page.

====Linux - Attached Interface Kit====

As soon as the SBC boots and can connect to the network (either by DHCP or by mDNS/avahi), it begins broadcasting the state of its attached InterfaceKit over the network using the [[Phidget WebService]]. To test the InterfaceKit on your Linux computer over the network, you will need to install the Phidget libraries and the Phidget webservice if you haven't already. (If you have used any Phidget via USB and over a network on your Linux computer, you have already done this.) This process is described on the general [[OS - Linux|Linux OS]] page, so follow those installation instructions, with the following modifications to the [[OS - Linux#Using the WebService|Linux webservice introduction]]:
* Instead of using a localhost (127.0.0.1) address, use the the SBC's IP or link local ({{Code|phidgetsbc}}) address,
* Instead of using the function call {{Code|openRemoteIP}} in your code, use the function call {{Code|openRemote}}, and the Interface Kit serial number which is on the back of the SBC.

Note that any attached analog sensors in the black ports will not show up over the webservice as individual Phidgets. Rather, they will show up as part of the Interface Kit, through the port number that they are attached to on the SBC board.

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

{{UGce}}

Language - Cocoa

2017-09-18T18:04:57Z

Patrick: Patrick moved page Language - Cocoa to Language - Objective C

#REDIRECT [[Language - Objective C]]

Language - Objective C

2017-09-18T18:04:56Z

Patrick: Patrick moved page Language - Cocoa to Language - Objective C

[[Category:Language]]
{{OSLang|[[File:icon-Cocoa.png|64x64px|alt=|link=]]|Cocoa is Apple's native object-oriented application programming interface (API) for the [http://www.apple.com/macosx Mac OS X] operating system.}}
__TOC__

==Introduction==

{{LanguageSupport|Cocoa|the complete Phidget API, including events|all Phidget devices.|XCode on OS X|}}

==Quick Downloads==

{{QuickDownloads|Cocoa|
{{APIQuickDownloads|{{SERVER}}/documentation/Phidget21_C_Doc.zip C/C++}}
{{ExtraAPIQuickDownloads|{{SERVER}}/documentation/web/cdoc/index.html|HTML Version of}}|
{{ExampleQuickDownloads|{{SERVER}}/downloads/phidget21/examples/objc/Cocoa.zip|}}|
{{MacQuickDownloads}}}}

==Getting started with Cocoa==

If you are new to writing code for Phidgets, we recommend starting by running, then modifying existing examples. This will allow you to:
{{ExampleCodeReasons}}

We offer support for developing Cocoa on [[#OS X |OS X]].

==OS X==

The Phidget examples were written in Objective-C and Xcode 3.2.4, and this tutorial assumes their use. Other versions of Xcode should work as well and would be set up in a similar manner.

===Description of Files===

Any files we think are worth knowing about specifically, or at the minimum a note that the OS X install puts things in their proper place.

===XCode===

====Use Our Examples====
If Xcode is not already installed on your system then you will need to get it. You can download it from the Mac app store free of charge.

Once that is done, you need to download our [{{SERVER}}/downloads/phidget21/examples/objc/Cocoa.zip examples]. If this is your first time working with Phidgets we recommend using the HelloWorld example as it will work with every Phidget device and it fairly easy to understand.

Open the HelloWorld example and before anything, run it. You should see a window that looks like this:

[[image:xcodehelloworld1.png|600px|link=]]

The window will list every Phidgets device connected to the system. In addition to this it will register when devices are connected or disconnected from the system. Now go and find the example project for your specific device. You can run this is the exact same way. After that you can take a look at the code and see how things work. While you are doing that you can refer to the [[#Follow The Examples|Follow the Examples]] section to guide you through all the parts of the example project.

====Write Your Own Code====

First, generate a new Cocoa project with a descriptive name such as PhidgetTest.

Then, add the Phidget21 Framework (Groups & Files → Frameworks → Other Frameworks).

Then, create a new Objective-C class with a descriptive name. For the purpose of this guide, the class name will be PhidgetInterfaceKit.

At this point, a header file(.h) as well as an implementation file(.m) will automatically be created. Open the header file for editing, and add a reference to phidget21.h:

<div class="source"><syntaxhighlight lang=objc>
#import <Phidget21/phidget21.h>
</syntaxhighlight></div>

Let's say you want to use a text field to capture output. Add a text field outlet in the header file:

<div class="source"><syntaxhighlight lang=objc>
@interface PhidgetInterfaceKit : NSObject{
IBOutlet NSTextField *sensorValueTxt;
}
@end
</syntaxhighlight></div>

Then, in Groups & Files → Resources, open up MainMenu.nib to bring up the Interface Builder. Drag a text field from the Library to the Window.

Now, an instance of the PhidgetInterfaceKit class will need to be created:
#In the Library, drag an object to the MainMenu.nib Window.
#In the Identity tab of the Inspector for this object, add the PhidgetInterfaceKit class.
#Connect the PhidgetInterfaceKit class instance to the text field.
The project now has access to Phidgets and we are ready to begin coding.

==Follow The Examples==

By following the instructions above, you probably now have a working example and want to understand it better so you can change it to do what you want. This teaching section has resources for you to learn from the examples and write your own.

Your main reference for writing Cocoa code will be our C/C++ API information, with syntax for all of our functions:

{{UsingAPhidgetInCodeGeneral|both of which are available in AppleScript|[{{SERVER}}/documentation/Phidget21_C_Doc.zip C/C++ API]}}

===Code Snippets===

Specific calls in Cocoa will differ in syntax from those on the [[General Phidget Programming]] page, but the concepts stay the same.

It may help to have the [[General Phidget Programming]] page and this section open at the same time, because they parallel each other and you can refer to the Cocoa syntax. However, ''many'' additional concepts are covered on the General Phidget Programming page on a high level, such as using multiple Phidgets, handling errors, and different styles of programming.

====Step One: Initialize and Open====

First, make sure you have given your program access to Phidgets as described in the [[#Write Your Own Code | Write Your Own Code]] section. Then, you will need to declare your Phidget variable in your code. For example, we can declare a Phidget Interface Kit in the .m implementation file with:

<div class="source"><syntaxhighlight lang=objc>
CPhidgetInterfaceKitHandle ifkit
</syntaxhighlight></div>

The object name for any type of Phidget - Temperature Sensor, Spatial, Motor Controller, etc - is listed in the API manual. Every type of Phidget also inherits functionality from the Phidget base class.

Next, the Phidget object needs to be initialized and the program needs to try and connect to the Phidget through a call to open(). Open will tell the program to continuously try to connect to a Phidget, based on the parameters given, even trying to reconnect if it gets disconnected. For example, we can connect to a Phidget Interface Kit in the .m implementation file with:

<div class="source"><syntaxhighlight lang=objc>
@implementation PhidgetInterfaceKit
- (void)awakeFromNib
{
CPhidgetInterfaceKit_create(&ifkit);
CPhidget_open((CPhidgetHandle)ifkit, -1);
}
@end
</syntaxhighlight></div>

The different types of open can be used with parameters to try and get the first device it can find, open based on its serial number, or even open across the network. The API manual lists all of the available modes that open provides. One important thing to remember is that when working with Phidgets, a local connection will reserve the device until closed. This prevents any other instances from retrieving data from the Phidget, including other programs. The one connection per device limit does not apply when exclusively using the [[Phidget WebService]].

====Step Two: Wait for Attachment (plugging in) of the Phidget====

Simply calling open does not guarantee you can use the Phidget immediately. To use the Phidget, it must be plugged in (attached). We can handle this by using event driven programming and tracking the AttachEvents and DetachEvents, or by calling waitForAttachment. WaitForAttachment will block indefinitely until a connection is made to the Phidget, or an optional timeout is exceeded.

To instead use events to handle attachment, first you declare the function that will be called when an Attach event is fired - in this case we call the function {{Code|gotAttach}}:

<div class="source"><syntaxhighlight lang=objc>
int gotAttach(CPhidgetHandle phid, void *context) {
[(id)context performSelectorOnMainThread:@selector(phidgetAdded:) withObject:nil waitUntilDone:NO];
return 0;
}
</syntaxhighlight></div>

Then, after our {{Code|create}} call [[#Step One: Initialize and Open|in the Step One code snippet]], but before our {{Code|open}} call, we hook our {{Code|gotAttach}} event function into our Phidget software object with the {{Code|CPhidget_set_OnAttach_Handler}} function:

<div class="source"><syntaxhighlight lang=objc>
CPhidget_set_OnAttach_Handler((CPhidgetHandle)ifkit, gotAttach, self);
</syntaxhighlight></div>

Check our examples for putting these attachment calls into the context of your larger program.

====Step Three: Do Things with the Phidget====

We recommend the use of event driven programming when working with Phidgets. In a similar way to [[#Step Two: Wait for Attachment (plugging in) of the Phidget|handling an attach event]] as described above, we can hook an event handler at loading with the following code:

<div class="source"><syntaxhighlight lang=objc>
CPhidgetInterfaceKit_set_OnSensorChange_Handler(ifkit, gotSensorChange, self);
</syntaxhighlight></div>

A call like this connects a function and an event. In this case, the {{Code|CPhidgetInterfaceKit_set_OnSensorChange_Handler}} hook connects the {{Code|gotSensorChange}} function to the event of a sensor (black analog input port) changing value on a Phidget Interface Kit. Next, the callback method {{Code|gotSensorChange}} needs to be set up before it can be used. For example,

<div class="source"><syntaxhighlight lang=objc>
int gotSensorChange(CPhidgetInterfaceKitHandle phid, void *context, int ind, int val)
{
NSAutoreleasePool *pool = [[NSAutoreleasePool alloc] init];
[(id)context performSelectorOnMainThread:@selector(SensorChange:)
withObject:[NSArray arrayWithObjects:[NSNumber numberWithInt:ind], [NSNumber numberWithInt:val], nil] waitUntilDone:NO];
[pool release];
return 0;
}
</syntaxhighlight></div>

Above, the SensorChange method is invoked on the main thread. Event data is stored in a {{Code|NSArray}}, which in turn is sent as a single argument to the SensorChange method. The {{Code|NSAutoreleasePool}} object is created to clean up released objects on the event thread, and is released at the end of the method.

The method calls selector on the SensorChange method, which is defined as follows:

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

- (void)SensorChange:(NSArray *)sensorChangeData
{
int sensorIndex, sensorValue;
sensorIndex = [[sensorChangeData objectAtIndex:0] intValue];
sensorValue = [[sensorChangeData objectAtIndex:1] intValue];
[sensorValueTxt setStringValue:[NSString stringWithFormat:@"Sensor: %d, Value:
%d", sensorIndex, sensorValue]];
}

</syntaxhighlight></div>

With this series of declarations and functions, the code inside SensorChange will get executed every time the PhidgetInterfaceKit reports a change on one of its analog inputs. Some events such as Attach and Detach belong to the base Phidget object and thus are common to all types of Phidgets.
Please refer to the API manual and the Cocoa examples for a list of events and their usage.

Some values can be read and sent directly to the Phidget, simply use the C API functions such as CPhidgetInterfaceKit_getSensorValue() for PhidgetInterfaceKits.

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

int sensorValue;
CPhidgetInterfaceKit_getSensorValue(ifkit, 0, &sensorValue);
[sensorValueTxt setintValue: sensorValue];

</syntaxhighlight></div>

These functions can be used inside a polling loop as an alternative to event driven programming.

====Step Four: Close and Delete====

At the end of your program, don’t forget to call close to free any locks on the Phidget:

<div class="source"><syntaxhighlight lang=objc>
CPhidget_close((CPhidgetHandle)ifkit);
CPhidget_delete((CPhidgetHandle)ifkit);
</syntaxhighlight></div>

{{MoreHowTos}}

==Common Problems and Solutions/Workarounds==

None at this time.

OS - Linux

2017-09-18T17:17:53Z

Patrick:

[[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/phidget21/libraries/linux/libphidget.tar.gz Phidget Libraries for Linux]
*[{{SERVER}}/downloads/phidget21/servers/linux/phidgetwebservice.tar.gz Phidget WebService for Linux]
*[[Software License]]

If you need old versions of the libraries, [{{SERVER}}/downloads/phidget21/libraries/linux/libphidget/ click here].

==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://libusb.info/ from source].
#Unpack and install the [{{SERVER}}/downloads/phidget21/libraries/linux/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/phidget21/examples/c/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/phidget21/servers/linux/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.

Stepper Motor and Controller Primer

2017-09-18T17:17:04Z

Patrick:

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[Image:3302.jpg|link=]]
| [[Image:1063.jpg|link=]]
|}

<br clear="all" />

==Introduction==
Stepper motors are broadly available motors commonly used for positioning. The rotor of a stepper moves in a series of discrete steps. By energizing the coils of the motor in sequence through many of these steps, the direction of rotation, number of rotations, and exact position of the motor shaft can be easily controlled. By controlling the time between the steps, the speed and acceleration of the stepper is regulated. In contrast, a DC motor will blindly spin at the highest speed possible when powered, unless it is controlled with an [[Encoder Primer|Encoder]] and a control system program. It is not necessary to use an encoder on a stepper motor unless you're concerned about the motor losing count of the steps over a long period of time or in high torque situations.

Each stepper motor is designed to move by a certain angle with each discrete step. The simplest stepper motors will rotate 90 degrees per step. Standard industrial steppers will rotate 1.8 degrees per step. The stepping angle can be further reduced through use of a gearbox.

In addition to the ease of precisely controlling position and speed, Steppers have other advantages:

*Most motors have very little torque when they are operating at low speed or standstill. Since a stepper’s rotor is held in place by a magnetic field during each step, steppers have full torque at low speed or standstill, making them very useful for low speed rotation and actuation. Additionally, a stepper motor can remain in a fixed position for long periods of time with the rated current in the windings, whereas with DC motors, stalling and remaining in a fixed position for long periods of time will cause motor burnout.
*DC Motors have brushes with a finite lifetime. Steppers have no brushes, and are limited only by the life of the bearings.

Compared to DC Motors, there are disadvantages to Steppers:

*Each step will produce vibration in the motor. If these vibrations are at the mechanical resonant frequency of the motor, they can cause the rotor to overshoot and bounce back and forth, resulting in a severe loss of torque. This phenomenon is called “ringing” and is often accompanied by a loud buzzing or grinding noise. To prevent the motor from operating in such a way, you should test the motor at various speeds in the physical application it is intended for, and try to avoid running the motor at a speed which exhibits ringing behaviour.
*If the motor encounters a brief overload, the fixed coils on the stator and the free-spinning rotor can lose track of each other. If this happens at higher speeds, the motor will often stall. Even at lower speeds, your system will have lost track of where exactly the motor is positioned – unless there is an independent system (e.g., an optical encoder) tracking the position.
*A Stepper motor cannot be loaded at its maximum torque, as it will almost certainly be overloaded during operation. A DC Motor will naturally adjust its speed depending on how much power is provided, and the torque required to turn it’s shaft.

For more information about the differences between stepper motors, DC motors, and servo motors, see the [[Motor Selection Guide]].

==Types of Stepper Motors==

We find it useful to classify motors according to how the coils are wound (Bipolar / Unipolar), the internal magnetic construction (Permanent Magnet / Hybrid), and how the current in the coils is regulated (Chopper Drive / Resistive Limited).

===Coils===
=====Bipolar=====
These motors are manufactured with two coils of wire, resulting in one winding per phase. By alternating the power between coils, as well as the direction of the current, the motor is rotated. This configuration produces magnetic fields within the coils in either direction, hence the term “Bipolar.” The controller is more expensive because it has to be able to produce both positive and negative electrical currents, but the advantage is that the entire coil is being used, thus increasing torque capabilities at all speeds. We do not recommend using a bipolar controller to run a unipolar motor, even though it is theoretically possible.

=====Unipolar=====
In a unipolar motor, the motor windings consist of two identical coils per phase, wound in opposite directions (each occupying half of the space a coil normally would in a bipolar stepper). As a result, the controller only needs to select which of the two coils to pass current through in order to change the magnetic polarity, and only a positive current is required to be generated. Due to this simplified control mechanism which uses only half of each coil, the torque of unipolar motors are usually much lower, but the overall cost of the system is much cheaper. The simplicity of the unipolar controller also means that you cannot use it to run a bipolar stepper motor.

===Magnets===
=====Permanent Magnet=====
Permanent magnet motors are small, low torque, and inexpensive. They use a permanent magnet in the rotor that is attracted or repelled by magnetic field generated by the stator coils. Step angles are often 7.5 or 15 degrees, and the motors are usually unipolar.

=====Variable Reluctance=====
The rotor of a variable reluctance stepper is made of iron, and it therefore aligns with the magnetic field generated by the stator coils. Since it doesn’t use a permanent magnet, it doesn’t matter which direction the current flows as long as each coil is wound in the opposite direction as the coil across from it. Therefore, variable reluctance steppers are unipolar and are typically designed to have larger step angles of 15 or more degrees.

=====Hybrid=====
Hybrid Motors dominate the stepper motor world – they use a combination of characteristics from permanent magnet and variable reluctance steppers and have the best torque and speed, but are more expensive to produce. Step angles are typically 0.9 to 3.75 degrees, giving much better step resolution.

===Drive===
=====Chopper Drive=====
Chopper Drive is an electronic control technique which allows specific motors to produce more power, torque, speed, and be more efficient. Instead of relying on the resistance of the coil wiring, the inductance of the wiring is exploited by sophisticated control electronics as a short-term limitation of motor current. Motor Manufacturers don’t do a good job of distinguishing motors suitable for use with Chopper Drive electronics. The motors will often be large, square, with very low resistance.
=====Resistive Limited=====
Small, inexpensive steppers are designed to be built and controlled as cheaply as possible. To simplify the control electronics, the length and thickness of the wire in the coils is selected for a particular control voltage. This allows the coil itself to regulate the power available to the motor – provided the appropriate voltage is used, of course. We call this type of motor Resistive Limited.

==How it Works==

[[Image:Stepper_back_web.jpg|left|link=|thumb|230px|Cross-Section of a Hybrid Bipolar Stepper<br />[[Media:Stepper_back_web.jpg|Full-size Image]]]]

===Hybrid Bipolar Steppers===
This section of the primer will cover the general principle of operation for stepper motors. While this information is by no means necessary to use a stepper motor, those who are curious about their inner workings may read on.

The thumbnail to the left is a cross-sectional view of the inside of a hybrid bipolar stepper motor. As you can see, it has eight poles with six teeth each. This motor contains two coils- one wrapping the odd-numbered poles, and the other wrapping the even-numbered poles. The steel end-cap in the center of the image covers a cylindrical permanent magnet which surrounds the shaft.

If positive current is sent to the odd-numbered coil, poles 1 and 5 are magnetized as south, and poles 3 and 7 are magnetized as north. Assuming the permanent magnet in the center of the motor has its north pole facing toward us, this will result in the rotor turning so that the teeth line up with stator poles 1 and 5, as they are in the image. At the same time, poles 3 and 7 will become aligned on the opposite end of the motor, where the gear on the rotor is permanently offset by the width of one tooth and the permanent magnet has magnetized the rotor as south. The rotation of the motor is continued by sending negative current through the even-numbered phase, then negative current through the odd-numbered phase, then positive current through the even-numbered phase, and so on. The stepper controller can reverse the direction of rotation simply by reversing this sequence.

When a stepper motor becomes engaged in software, and current is applied to the coils, it may abruptly "snap" to the position that the rotor is being held at.

<br clear="all">

===Hybrid Unipolar Steppers===
The operation of a hybrid unipolar stepper is very similar to the bipolar stepper described above, except that each pole has two seperate coils wound in opposite directions. This results in four phases which only require positive current to operate. Rather than alternating the direction of current, the motor controller simply sends positive current to the appropriate half of the coil.

==Controlling the Stepper Motor==

The following information has been derived from using the 3308 stepper motor connected to a 1063 - PhidgetStepper Bipolar 1-Motor controller.
===Setting the Current Limit===

[[Image:Graph12v.jpg|border|400px|link=|thumb|The current/speed characteristics for the 3308 at 12V.<br />[[Media:Graph12v.jpg|Full-size Image]]]]

[[Image:Graph24v.jpg|border|400px|link=|thumb|The current/speed characteristics for the 3308 at 24V.<br />[[Media:Graph24v.jpg|Full-size Image]]]]

[[Image:Graph30v.jpg|border|400px|link=|thumb|The current/speed characteristics for the 3308 at 30V.<br />[[Media:Graph30v.jpg|Full-size Image]]]]

The current limit is an important control property of stepper controllers. Since many stepper motors have a very low coil resistance, the current through the coils cannot “self-regulate” to a safe level on their own. They require the sophisticated control techniques of a Chopper Drive, which is used in the [{{SERVER}}/products.php?product_id=1063 1063 PhidgetStepper] controller. As a result, the maximum current allowed should be explicitly set.

There are many factors that influence what the current limit should be set to. These include, but are not limited to,the acceleration and speed of the stepper, the supply voltage, applied torque, motor inductance, and coil resistance. The process of choosing the current limit can be simplified by following some general rules of thumb. The graphs in this section show a set of speed vs. current characteristics for the 3308 stepper with various power supplies.

In the these graphs, the '''“actual speed”''' of the motor is the maximum speed attainable in a real world test done with no load on the motor, but at very high acceleration. The '''“max speed”''' shows the limitation on speed imposed by the inductance of the motor coils at a given supply voltage. Given that the 1063 controller is only able to run at a maximum speed of 2048 full steps per second, our graphs don’t show data at higher speeds.

When the current limit is set low and the acceleration is high, the motor will not be able to provide enough power to accelerate itself and the load it’s driving. The motor also has to overcome friction losses within the system, and do work on the load - for example, lifting a weight. By increasing the current limit, more current and power is made available to accelerate and maintain maximum speeds. This can be seen on any of the graphs in the initial steep ramp of the actual speed. As the current limit increases, the motor is able to achieve higher speeds.

In the case of this particular motor, the large inductance of the coils - great for producing lots of torque, quickly overwhelms a 12V power supply. To get higher speeds and more performance out of this motor, higher supply voltages are necessary. Compare the actual speed curve on the 12V graph to the 30V graph. At 30V, the motor is able to achieve a much higher speed. It’s important to remember that the actual speed was measured at very high accelerations - by lowering acceleration, higher velocities can be achieved. Of course, if your motor is doing a lot of work, you’ll need to supply enough current to produce the necessary torque, therefore limiting the maximum speed.

Setting Current Limit for your application is a balancing act. By increasing the current limit, more torque is available, but far more power will be consumed when the motor is turning very slowly or stopped. When setting a high acceleration, more power (therefore current) is required to accelerate the motor and it’s load. Selecting the current limit is often done dynamically in the actual application - set the current limit very low, and run the system, increasing the Current Limit if it stalls. After a set up has been determined that is reliable, increase the current limit by another 25% to give some margin.

There is no point in setting the current limit to be greater than the motor’s rated current- the increased inductance will only further limit the motor speed. In this case, the 30V graph shows that it’s not feasible to operate this motor at maximum torque (1.7 Amps) at a speed greater than 1100 full steps per second. By reducing the current limit, greater speeds are possible, but less torque will be available. Most motors designed for Chopper Drive control can operate at much higher voltages, but Phidgets Inc. does not carry a controller that can provide these voltages at this time.

Note that just because you have set the current limit to some amount (for the sake of example let's say 2A) the motor will not draw 2A at all times. The motor will only draw as much current as it needs. This means that if there is only a small load on the motor and it is spinning at less than its top speed the motor might only draw a small fraction of the allotted 2A. Even as low as 300 or 400mA. As more load or higher speed is applied, the current usage will go up until the controller is giving the motor the full current limit. As a motor draws more current, it will also produce more heat. It is normal for a stepper motor to be hot to the touch after running for a while. If the motor is getting very hot, you may be trying to drive too large a load for that particular motor.

===Choosing a Supply Voltage===

When looking at a stepper motor's specifications, you may come across a "Rated Voltage" value. This value is usually equal to the rated current multiplied by the resistance of the coils of the motor, making it somewhat of a redundant specification. As mentioned earlier, you can increase your controller's supply voltage in order to allow the motor to reach higher speeds at a lower current (because high current causes high inductance which puts a hard limit on how much speed and torque a motor can produce). The motor will also produce more heat as you increase the supply voltage, so it's a good idea to choose a supply voltage based on the performance you need for the motor. Some motors will have a "Recommended Voltage" for a particular controller, which is the amount of voltage needed to reach the optimal speed and torque of the motor with minimal heating.

===Setting the Velocity Limit===

The velocity of a motor cannot be directly chosen with our stepper controllers. However, a velocity limit can be chosen to ensure that the motor does not go faster than a certain speed. This is useful because every stepper motor has a speed that causes itself to vibrate at the resonant frequency of its own moving parts. When the motor vibrates at this frequency, the motor will often overshoot its target position, causing it to lose most of its torque, sometimes even rotating in the wrong direction. This phenomenon is sometimes called "ringing". If you experience these problems while running your stepper motor at a constant velocity, try setting the velocity limit to lower or higher than it was previously, in an attempt to minimize the amount of time spent operating at this particular velocity.

===Setting the Acceleration===
The acceleration of a stepper motor is an important consideration when driving a load. Setting the acceleration too high can result in the motor stalling, especially with a heavy load. Try to use low acceleration in high-torque applications.

===Continuous Rotation and Forward/Reverse===

A stepper motor can be caused to rotate continuously by simply setting the controller's target position property to an extremely large number of steps.

Stepper motors can easily be run in forward or reverse by choosing a target position greater than or less than the current position, respectively. Reversing the polarity of either of the motor's wire pairs will invert this effect- causing a lesser target position to result in forward rotation, and a greater target position to result in reverse rotation. For this reason, you should pay attention to the way you wire a motor when developing and testing code, and ensure that you wire it with the same polarity in the future to avoid erroneous behaviour in applications where rotation direction matters.

===Cooling===
The stepper controllers sold at Phidgets Inc. have a current rating that is limited by the heat dissipation capability of the board. You could add heatsinks, fans, or other cooling devices to increase the current limit, but do so with caution. Unless you have a way of monitoring the temperature of the driver chip during operation, you have no way of knowing how far beyond the rated specification you can go.

===Wire Length===

Since the stepper controller is sending a fairly simple signal to the motor, interference is not a big concern. You should be able to have quite long wires between your motor and controller. For more information, see the [[Effects_of_Long_Wires|effects of long wires]] page.

===Saving Power===

When the stepper motor has rotated the requested number of steps, and is stopped, the coils will remain energized to hold it in position. This is necessary to allow the motor to support a load on its shaft without rotating to an unknown position.

'''Holding torque''' is the amount of torque required to rotate the motor ‘against it’s will’ when the full rated current is flowing through the coils. If power consumption or overheating is a problem, and full holding torque is not required, the Current Limit can be decreased in software when the motor is not moving. Holding torque will decrease linearly as you decrease the Current Limit, but will also allow you to save power and reduce the heat generated in your system.

There is also a small resistance to movement within the motor even when there is no current, called '''Detent Torque'''. This may be sufficient to prevent rotation in your application, especially if the stepper has a gearbox on it.

If the motor is not supporting a load or is not required to maintain a specific angle, it is recommended to set the Enable property to false. This will allow the motor shaft to rotate freely, but the present angle may be lost if forces on the motor-shaft are greater than can be resisted by the detent torque of the unpowered motor.

<br clear=all>

===Braking===

There are several ways to stop a stepper motor, each with different characteristics:

'''Set Target Position''' - If you set the target position to the motor's current position, it will stop. This is typically the best way to stop quickly and hold position, since the motor coils will still be engaged. You could also set the motor velocity limit to zero for a similar effect.

'''Short the coils''' - If you have the stepper wires connected to some external circuitry, you could use a switch to short the A and B terminals together, and the C and D terminals together. Due to the [http://en.wikipedia.org/wiki/Lorentz_force Lorentz force] of the electrons in the coil, the motor will begin to brake and hold position.

'''Cut power''' - You could cut power to the controller, but since the motor coils would no longer be engaged, the momentum would cause it to continue rotating until it slows down from friction and detent.

==Stepping Modes==

===Full Stepping===
This is the default mode of stepping for bipolar motors, where both phases of the motor are controlled by two square waves of current. One wave lags behind the other by 90 degrees, and the motion of the motor is locked to these waves. A full step is completed when the square waves advance by 90 degrees. Since both phases are always fully energized, full stepping provides the best torque.

===Half Stepping===
In this stepping mode, the controller alternates between having one phase energized and both phases energized. This results in the rotor pausing at half-steps in between the poles, effectively halving the step angle. However, since the current to each coil cannot be exactly balanced, the angle that the rotor comes to rest at between poles may not be exactly half the step angle. The downside to half stepping is that the motor will have less torque on the steps when only one phase is energized.

===Mini/Micro-stepping===
By controlling the the relative current of both phases, the rotor position can come to rest at various equally spaced sub-steps between the two phases. This is achieved by following the same procedure for Full Stepping, except that the current supplied more closely resembles a sine wave rather than a square wave. Some bipolar controllers are designed to micro-step at low speeds to allow for smooth rotation.

==Selecting a Gearbox==

Using a stepper motor with a gearbox can be a good solution in applications that need very low rotation speeds and/or lots of torque. Selecting a gearbox to attach to the stepper will result in increasing the output torque and decreasing the speed.
Simply, the Gearbox Output Speed is:

<math>
\text{Output Speed} =\frac{\text{Motor Speed}}{\text{Gearbox Ratio}}
</math>

Although the reduction ratio plays a large part in determining the Gearbox Output Torque, there is also an inefficiency that is introduced through the use of a gearbox. Some of the torque of the motor is internally converted into heat and lost. So to calculate the Gearbox Output Torque:

<math>
\text{Output Torque} = \text{Motor Output Torque } \times \text{ Gearbox Ratio } \times \text{ Gearbox Efficiency}
</math>

When choosing a stepper motor with a gearbox, keep in mind that the gearbox is rated to sustain a specific amount of torque, beyond which the gearbox could become damaged. This limit is often much lower than the amount of torque specified by the above equation.

The Gearbox Step Angle can be determined by:

<math>
\text{Gearbox Step Angle} = \frac{\text{Motor Step Angle}}{\text{Gearbox Ratio}}
</math>

===Planetary Gearbox Reduction Ratios===

[[File:Planetary_gearing.jpg|thumb|300px|link=|This diagram illustrates the parts of a 5.18:1 planetary gearbox.<br>[{{SERVER}}/docs21/images/1/1a/Planetary_gearing.jpg Click for Larger Image]]]

In some applications, it is important to know the exact gear ratio of a gearbox (for example, when you need the output shaft to make a several complete rotations
and stop in the same position it started). Most motor datasheets will only list an approximate ratio, like "10:1" or "27:1". However, there are ways to figure out
the exact ratio.

In a planetary gearbox where the sun gear is used as an input and the rotation of the spider linking the planet gears is the output, the reduction ratio can be
expressed by the following equation:

<math>
\text{Gearbox Ratio} = \frac{T_R + T_S}{T_S}
</math>

Where <math>T_R</math> is the number of teeth on the ring gear, and <math>T_S</math> is the number of teeth on the sun gear. In this situation, the number of teeth on the planetary gears
don't affect the reduction ratio and serve only to connect the ring and sun gears. In order to increase the reduction ratio, you need to increase the number of
teeth on the ring gear. Since there is limited space inside a motor's gearbox, it eventually becomes impossible to increase the gear ratio. This limitation can be
bypassed by introducing multiple gear '''stages'''. In a multi-stage planetary gearbox, the axles of the planet gears of the first stage are connected to a piece
of metal called a "spider", whose rotation is used to turn the sun of the next stage. It's very common for multi-stage planetary gearboxes to have a tall ring
gear that spans multiple stages. To determine the overall reduction ratio of a multi-stage planetary gearbox, simply multiply the two ratios together. For
example, two stages each with a 5:1 reduction ratio would result in a total ratio of 25:1.
The following table lists exact ratios for gearboxes commonly sold at Phidgets Inc. :

[[File:Gearbox_table.jpg|link=]]

The colored squares visualize the stages that compose each gearbox. For example, a two-stage gearbox with 1 blue and 1 green square indicates that one stage is
the same ratio as the 1-stage gearbox with the green square beside it, and the other stage is the same as the one with a blue square beside it.
If you have a third party gearbox and are unable to open it to count the gear teeth, you could also determine the approximate reduction ratio experimentally by
measuring the rotation angle after a known number of steps have occured. The more accurately you can measure the angle, the better your approximation will be.

===Gearbox Terminology===

Here is a short list of terms you might come across when deciding upon a gearbox:

'''Backlash'''

The amount of clearance between mated gear teeth. Theoretically, the backlash should be “the smaller the better,” but in actual practice, some backlash must be allowed to prevent jamming.

'''Gear Ratio'''

The gearbox accepts the power (think of power as a torque that rotates) from the motor, reducing the speed (exactly) by a given ratio, while increasing the torque (roughly) by the same ratio – a ratio of the gear head with which the gear head reduces the motor speed. For example, if a motor has a speed of 500RPM and the reduction ratio is 100:1, the speed of the gear head is 500/100 = 5RPM. This is the actual reduction ratio. The calculated speed from the gear head should be based on this ratio.

'''Gearbox Step Angle'''

A full step of the motor will result in the gearbox making a smaller step. The angle of this step is the step angle of the motor divided by the gearbox reduction ratio. For example, a motor with a step angle of 1.8º and a gearbox with a reduction ratio of 20:1 will have a step angle of 1.8/20 = 0.09º at the output of the gearbox.

'''Gearbox Output Torque'''

The gearbox takes the torque from the output shaft of the motor, reducing the speed and increasing the torque. The gearbox, depending on its efficiency, loses some of the torque as it is converted into heat. Therefore, the Gearbox Output Torque is the motor output torque multiplied by the reduction ratio multiplied by the efficiency of the gearbox. For example, a motor with a low-speed output torque of 500g*cm and a gearbox with a reduction ratio of 5:1 and 90% efficiency will have a Gearbox Output Torque of 500*5*0.9 = 2.25 kg*cm. Remember, however, that if the Gearbox Output Torque exceeds the allowable torque the gearbox is rated for, you can cause damage to the gearbox.

'''Gear Trains'''

Planetary gearboxes use multiple gear sets to achieve large gear reductions. Each gear set makes the gearbox longer, and reduces the efficiency.

==Product Comparison Tables==

{|border=1
|+'''Stepper Motor Product Specifications'''
! Phidgets Product #
! Motor Model Number
! Motor Type (Unipolar/Bipolar)
! Step Angle (deg)
! Holding Torque (g•cm)
! Low-Speed Torque (g•cm)
! Rated Current (A)
! Number of Leads
! Mounting Plate Size
! Shaft Diameter (mm)
! Total Weight (g)
! Motor Length (mm)
! Motor Size/Diameter (mm)
|-
| 3302|| 42BYGHM810 || Hybrid Bipolar || 0.9|| 4800|| 4280|| 2.4 || 4|| NEMA-17|| 5 || 362|| 48 || 42 x 42
|-
| 3303|| 42BYGHW811 || Hybrid Bipolar || 1.8|| 4800|| 4240|| 2.5 || 4|| NEMA-17|| 5 || 332|| 48 || 42 x 42
|-
| 3304|| 39BYGS202 || Hybrid Bipolar || 3.75|| 750|| 590 || 1 || 4|| NEMA-17|| 5 || 171|| 32 || 39 x 39
|-
| 3305|| 39BYG013 || Hybrid Bipolar || 1.8|| 550|| 450 || 0.4 || 4|| NEMA-17|| 5 || 110|| 20 || 39 x 39
|-
| 3314|| PM42L-048-17|| Hybrid Unipolar|| 7.5|| 950 || 710 || 0.28|| 6|| N/A || 3 || 138|| 14.4|| 42
|-
| 3315|| PM25S-048-15|| Hybrid Unipolar|| 7.5|| 140 || 50 || 0.1 || 6|| N/A || 2 || 31 || 15 || 25
|-
| 3316|| PM20L-20-14 || Hybrid Unipolar|| 18 || 50 || 30 || 0.08|| 6|| N/A || 1.5|| 24 || 16.5|| 20
|-
| 3320|| 28STH32 || Hybrid Bipolar || 1.8|| 600 || 520 || 0.67|| 4|| NEMA-11|| 5 || 111|| 32|| 28 x 28
|-
| 3323|| 35STH40 || Hybrid Bipolar || 1.8|| 1400|| 1200|| 1 || 4|| NEMA-14|| 5 || 200|| 40|| 35 x 35
|-
| 3324|| 42STH38 || Hybrid Bipolar || 1.8|| 3600|| 3300|| 1.7 || 4|| NEMA-17|| 5 || 289|| 40|| 42 x 42
|-
| 3330|| 57STH56 || Hybrid Bipolar || 0.9||12000||11200|| 2.8 || 4|| NEMA-23|| 6.4|| 695|| 56|| 56 x 56
|-
| 3331|| 57STH56 || Hybrid Bipolar || 1.8||12600||11000|| 2.8 || 4|| NEMA-23|| 6.4|| 686|| 56|| 56 x 56
|-
| 3335|| 86STH65 || Hybrid Bipolar || 1.8||34000||30000||2 or 4 || 4|| NEMA-34|| 12|| 1800|| 65|| 85 x 85
|-
| 3336|| 86STH156 || Hybrid Bipolar || 1.8||122000||106000||3 or 6 || 4|| NEMA-34|| 16|| 5200|| 156|| 85 x 85
|-
| 3340|| 42STH38 || Hybrid Bipolar || 0.9||3600||3300||1.7 || 4|| NEMA-17|| 5||288|| 40|| 42 x 42
|}

{| border=1
|+'''Gearbox Stepper Motor Product Specifications'''
!Product #
!Motor Model #
!Motor Type
!Step Angle<sup>†</sup> (deg)
!Holding Torque*,<sup>†</sup> (g-cm)
!Low-speed Torque*,<sup>†</sup> (g-cm)
!Rated Current (A)
!# of Leads
!Mounting Plate Size
!Shaft Diameter (mm)
!Total Weight (g)
!Motor Length (mm)
!Gearbox Length (mm)
!Motor Size/Diameter (mm)
!Gear Ratio
!Gearbox Max Torque (g-cm)
!Gearbox Efficiency
!Max Speed<sup>†</sup> (RPM)
|-
| 3310||57BYG630-07AG20||Hybrid Bipolar||0.09||30000||30000||2.8||4||NEMA-23||8||1330||73||38||56x56||20:1||30000||||30
|-
| 3311||42BYGHW811-AG5.18||Hybrid Bipolar||0.35||24860||17790||2.5||4||NEMA-17||8||513||48||31||42x42||5.18:1||30000||0.9||115
|-
| 3312||42BYGHW811-AG26.8||Hybrid Bipolar||0.07||40000||40000||2.5||4||NEMA-17||8||526||48||39||42x42||26.8:1||40000||0.81||22
|-
| 3313||42BYGHW811-AG99.5||Hybrid Bipolar||0.02||50000||50000||2.5||4||NEMA-17||8||610||48||47||42x42||99.5:1||50000||0.73||6
|-
| 3317||42BYGH40(M)-160-4A||Hybrid Bipolar||0.35||16780||12000||1.6||4||NEMA-17||8||464||40||30||42x42||5.18:1||20000||0.9||115
|-
| 3318||42BYGH40(M)-160-4A||Hybrid Bipolar||0.07||30000||30000||1.6||4||NEMA-17||8||464||40||38||42x42||26.8:1||30000||0.8||22
|-
| 3319||42BYGH40(M)-160-4A||Hybrid Bipolar||0.02||40000||40000||1.6||4||NEMA-17||8||464||40||46||42x42||99.5:1||40000||0.7||6
|-
| 3321||28STH32-0674B/28JXS40K27||Hybrid Bipolar||0.067||16100||14000||0.67||4||NEMA-11||6||218||32||40||28x28||27:1||20000|| ||120
|-
| 3322||28STH32-0674B/28JXS40K100||Hybrid Bipolar||0.018||32000||32000||0.67||4||NEMA-11||6||243||32||49||28x28||100:1||32000|| ||35
|-
| 3325||42STH38-1684B/36JXS60K5.18||Hybrid Bipolar||0.35||18000||18000||1.7||4||NEMA-17||8||457||40||31||42x42||5.18:1||18000|| ||904
|-
| 3326||42STH38-1684B/36JXS60K14||Hybrid Bipolar||0.13||30000||30000||1.7||4||NEMA-17||8||502||40||39||42x42||14:1||30000|| ||295
|-
| 3327||42STH38-1684B/36JXS60K26||Hybrid Bipolar||0.067||30000||30000||1.7||4||NEMA-17||8||503||40||39||42x42||26.85:1||30000|| ||174
|-
| 3328||42STH38-1684B/36JXS60K51||Hybrid Bipolar||0.035||48000||48000||1.7||4||NEMA-17||8||564||40||48||42x42||51:1||48000|| ||63
|-
| 3329||42STH38-1684B/36JXS60K99.51||Hybrid Bipolar||0.018||48000||48000||1.7||4||NEMA-17||8||564||40||48||42x42||100:1||48000|| ||34
|-
| 3332||57STH56-2804B/56JXS300K4.25||Hybrid Bipolar||0.42||53000||46600||2.8||4||NEMA-23||12||1200||56||48||57x57||4.25:1||90000|| ||375
|-
| 3333||57STH56-2804B/56JXS300K15||Hybrid Bipolar||0.12||150000||150000||2.8||4||NEMA-23||12||1300||56||61||57x57||15:1||150000|| || 116
|-
| 3334||57STH56-2804B/56JXS300K77||Hybrid Bipolar||0.023||240000||240000||2.8||4||NEMA-23||12||1500||56||72||57x57||77:1||240000|| ||25
|}

<sup>†</sup>Step angle, torque values, and max speed are all measured at the output of the gearbox.

<nowiki>*</nowiki>Holding torque and low speed torque for gearbox motors are limited by the max torque that the gearbox is rated to sustain.
<nowiki>*</nowiki>

==Glossary of Terms==

===Motor Terms===

'''Coil Resistance'''

The electrical resistance (to direct current) of the wiring within the motor. This resistance causes some of the energy being applied to the motor to be converted into heat. Some motors and motor controllers rely solely on the electrical resistance to regulate the current flowing through the motor. The Unipolar Motors we sell, and the 1062 PhidgetStepper Unipolar rely on this inexpensive, but inefficient technique. Other motors will have very low resistance, increasing their efficiency, but requiring very sophisticated control techniques because the resistance cannot regulate the current to a safe level on its own. Our Bipolar controllers and our Bipolar motors use this technique, otherwise known as Chopper Drive.

'''Holding Torque'''

Holding Torque is the amount of torque needed to rotate the shaft of the stepper motor while the controller attempts to hold the position, using the maximum current allowed for the motor. Holding Torque is the sum of the magnetic force exerted by the electrical coils to hold the current position, and the detent torque, which is the natural resistance of the motor against rotation due to the permanent magnet inside the motor. Once the motor begins to rotate, the torque it can exert (at least at low speeds) is Holding Torque minus twice the detent torque (because the motor is now working against the detent). As the motor speed increases, torque begins to decrease. If the power supply voltage is low, or the inductance of the motor is high, the torque will fall more rapidly.

'''Motor Inductance'''

Stepper motors are built with a specific coil inductance. A high inductance motor will provide a greater amount of torque at low speeds, at the cost of having lower torque at high speeds.

'''Overhung Load (OHL) / Radial Load'''

An external load applied on the output shaft of the gearbox. This load is often produced if pulleys are mounted directly on the shaft, pulling perpendicular to it. When the OHL exceeds a safe value, the bearings can fail, or the shaft can break from bending fatigue. While OHL and Thrust Load specifications are only available for our gearbox motors, both types of load should be avoided when using any of our motors.

'''Rated Current'''

The rated current is the maximum current that should be applied to each coil of the motor. Current generates heat within the motor, and exceeding the regulated current will cause the motor to overheat. If the motor is operated in a hot environment, or is enclosed, it can overheat at currents lower than the rated current.

'''Step Angle'''

The change in the shaft angle when the motor moves forward or backward by one full step.

'''Step Accuracy'''

Depending on the motor and how it is loaded down, the step positions will vary slightly. Fortunately, this variance doesn’t accumulate – so if you move the motor by one step or one million steps, the angle that the motor stops at will have the same margin of error.

'''Thrust load / Axial Load'''

A load applied directly in line with the output shaft of the gearbox. Avoid thrust as much as possible. If thrust load is unavoidable, keep it to no more than the permissible value.

Stepper Motor and Controller Primer

2017-09-18T17:16:40Z

Patrick:

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[Image:3302.jpg|link=]]
| [[Image:1063.jpg|link=]]
|}

<br clear="all" />

==Introduction==
Stepper motors are broadly available motors commonly used for positioning. The rotor of a stepper moves in a series of discrete steps. By energizing the coils of the motor in sequence through many of these steps, the direction of rotation, number of rotations, and exact position of the motor shaft can be easily controlled. By controlling the time between the steps, the speed and acceleration of the stepper is regulated. In contrast, a DC motor will blindly spin at the highest speed possible when powered, unless it is controlled with an [[Encoder Primer|Encoder]] and a control system program. It is not necessary to use an encoder on a stepper motor unless you're concerned about the motor losing count of the steps over a long period of time or in high torque situations.

Each stepper motor is designed to move by a certain angle with each discrete step. The simplest stepper motors will rotate 90 degrees per step. Standard industrial steppers will rotate 1.8 degrees per step. The stepping angle can be further reduced through use of a gearbox.

In addition to the ease of precisely controlling position and speed, Steppers have other advantages:

*Most motors have very little torque when they are operating at low speed or standstill. Since a stepper’s rotor is held in place by a magnetic field during each step, steppers have full torque at low speed or standstill, making them very useful for low speed rotation and actuation. Additionally, a stepper motor can remain in a fixed position for long periods of time with the rated current in the windings, whereas with DC motors, stalling and remaining in a fixed position for long periods of time will cause motor burnout.
*DC Motors have brushes with a finite lifetime. Steppers have no brushes, and are limited only by the life of the bearings.

Compared to DC Motors, there are disadvantages to Steppers:

*Each step will produce vibration in the motor. If these vibrations are at the mechanical resonant frequency of the motor, they can cause the rotor to overshoot and bounce back and forth, resulting in a severe loss of torque. This phenomenon is called “ringing” and is often accompanied by a loud buzzing or grinding noise. To prevent the motor from operating in such a way, you should test the motor at various speeds in the physical application it is intended for, and try to avoid running the motor at a speed which exhibits ringing behaviour.
*If the motor encounters a brief overload, the fixed coils on the stator and the free-spinning rotor can lose track of each other. If this happens at higher speeds, the motor will often stall. Even at lower speeds, your system will have lost track of where exactly the motor is positioned – unless there is an independent system (e.g., an optical encoder) tracking the position.
*A Stepper motor cannot be loaded at its maximum torque, as it will almost certainly be overloaded during operation. A DC Motor will naturally adjust its speed depending on how much power is provided, and the torque required to turn it’s shaft.

For more information about the differences between stepper motors, DC motors, and servo motors, see the [[Motor Selection Guide]].

==Types of Stepper Motors==

We find it useful to classify motors according to how the coils are wound (Bipolar / Unipolar), the internal magnetic construction (Permanent Magnet / Hybrid), and how the current in the coils is regulated (Chopper Drive / Resistive Limited).

===Coils===
=====Bipolar=====
These motors are manufactured with two coils of wire, resulting in one winding per phase. By alternating the power between coils, as well as the direction of the current, the motor is rotated. This configuration produces magnetic fields within the coils in either direction, hence the term “Bipolar.” The controller is more expensive because it has to be able to produce both positive and negative electrical currents, but the advantage is that the entire coil is being used, thus increasing torque capabilities at all speeds. We do not recommend using a bipolar controller to run a unipolar motor, even though it is theoretically possible.

=====Unipolar=====
In a unipolar motor, the motor windings consist of two identical coils per phase, wound in opposite directions (each occupying half of the space a coil normally would in a bipolar stepper). As a result, the controller only needs to select which of the two coils to pass current through in order to change the magnetic polarity, and only a positive current is required to be generated. Due to this simplified control mechanism which uses only half of each coil, the torque of unipolar motors are usually much lower, but the overall cost of the system is much cheaper. The simplicity of the unipolar controller also means that you cannot use it to run a bipolar stepper motor.

===Magnets===
=====Permanent Magnet=====
Permanent magnet motors are small, low torque, and inexpensive. They use a permanent magnet in the rotor that is attracted or repelled by magnetic field generated by the stator coils. Step angles are often 7.5 or 15 degrees, and the motors are usually unipolar.

=====Variable Reluctance=====
The rotor of a variable reluctance stepper is made of iron, and it therefore aligns with the magnetic field generated by the stator coils. Since it doesn’t use a permanent magnet, it doesn’t matter which direction the current flows as long as each coil is wound in the opposite direction as the coil across from it. Therefore, variable reluctance steppers are unipolar and are typically designed to have larger step angles of 15 or more degrees.

=====Hybrid=====
Hybrid Motors dominate the stepper motor world – they use a combination of characteristics from permanent magnet and variable reluctance steppers and have the best torque and speed, but are more expensive to produce. Step angles are typically 0.9 to 3.75 degrees, giving much better step resolution.

===Drive===
=====Chopper Drive=====
Chopper Drive is an electronic control technique which allows specific motors to produce more power, torque, speed, and be more efficient. Instead of relying on the resistance of the coil wiring, the inductance of the wiring is exploited by sophisticated control electronics as a short-term limitation of motor current. Motor Manufacturers don’t do a good job of distinguishing motors suitable for use with Chopper Drive electronics. The motors will often be large, square, with very low resistance.
=====Resistive Limited=====
Small, inexpensive steppers are designed to be built and controlled as cheaply as possible. To simplify the control electronics, the length and thickness of the wire in the coils is selected for a particular control voltage. This allows the coil itself to regulate the power available to the motor – provided the appropriate voltage is used, of course. We call this type of motor Resistive Limited.

==How it Works==

[[Image:Stepper_back_web.jpg|left|link=|thumb|230px|Cross-Section of a Hybrid Bipolar Stepper<br />[[Media:Stepper_back_web.jpg|Full-size Image]]]]

===Hybrid Bipolar Steppers===
This section of the primer will cover the general principle of operation for stepper motors. While this information is by no means necessary to use a stepper motor, those who are curious about their inner workings may read on.

The thumbnail to the left is a cross-sectional view of the inside of a hybrid bipolar stepper motor. As you can see, it has eight poles with six teeth each. This motor contains two coils- one wrapping the odd-numbered poles, and the other wrapping the even-numbered poles. The steel end-cap in the center of the image covers a cylindrical permanent magnet which surrounds the shaft.

If positive current is sent to the odd-numbered coil, poles 1 and 5 are magnetized as south, and poles 3 and 7 are magnetized as north. Assuming the permanent magnet in the center of the motor has its north pole facing toward us, this will result in the rotor turning so that the teeth line up with stator poles 1 and 5, as they are in the image. At the same time, poles 3 and 7 will become aligned on the opposite end of the motor, where the gear on the rotor is permanently offset by the width of one tooth and the permanent magnet has magnetized the rotor as south. The rotation of the motor is continued by sending negative current through the even-numbered phase, then negative current through the odd-numbered phase, then positive current through the even-numbered phase, and so on. The stepper controller can reverse the direction of rotation simply by reversing this sequence.

When a stepper motor becomes engaged in software, and current is applied to the coils, it may abruptly "snap" to the position that the rotor is being held at.

<br clear="all">

===Hybrid Unipolar Steppers===
The operation of a hybrid unipolar stepper is very similar to the bipolar stepper described above, except that each pole has two seperate coils wound in opposite directions. This results in four phases which only require positive current to operate. Rather than alternating the direction of current, the motor controller simply sends positive current to the appropriate half of the coil.

==Controlling the Stepper Motor==

The following information has been derived from using the 3308 stepper motor connected to a 1063 - PhidgetStepper Bipolar 1-Motor controller.
===Setting the Current Limit===

[[Image:Graph12v.jpg|border|400px|link=|thumb|The current/speed characteristics for the 3308 at 12V.<br />[[Media:Graph12v.jpg|Full-size Image]]]]

[[Image:Graph24v.jpg|border|400px|link=|thumb|The current/speed characteristics for the 3308 at 24V.<br />[[Media:Graph24v.jpg|Full-size Image]]]]

[[Image:Graph30v.jpg|border|400px|link=|thumb|The current/speed characteristics for the 3308 at 30V.<br />[[Media:Graph30v.jpg|Full-size Image]]]]

The current limit is an important control property of stepper controllers. Since many stepper motors have a very low coil resistance, the current through the coils cannot “self-regulate” to a safe level on their own. They require the sophisticated control techniques of a Chopper Drive, which is used in the [{{SERVER}}/products.php?product_id=1063 1063 PhidgetStepper] controller. As a result, the maximum current allowed should be explicitly set.

There are many factors that influence what the current limit should be set to. These include, but are not limited to,the acceleration and speed of the stepper, the supply voltage, applied torque, motor inductance, and coil resistance. The process of choosing the current limit can be simplified by following some general rules of thumb. The graphs in this section show a set of speed vs. current characteristics for the 3308 stepper with various power supplies.

In the these graphs, the '''“actual speed”''' of the motor is the maximum speed attainable in a real world test done with no load on the motor, but at very high acceleration. The '''“max speed”''' shows the limitation on speed imposed by the inductance of the motor coils at a given supply voltage. Given that the 1063 controller is only able to run at a maximum speed of 2048 full steps per second, our graphs don’t show data at higher speeds.

When the current limit is set low and the acceleration is high, the motor will not be able to provide enough power to accelerate itself and the load it’s driving. The motor also has to overcome friction losses within the system, and do work on the load - for example, lifting a weight. By increasing the current limit, more current and power is made available to accelerate and maintain maximum speeds. This can be seen on any of the graphs in the initial steep ramp of the actual speed. As the current limit increases, the motor is able to achieve higher speeds.

In the case of this particular motor, the large inductance of the coils - great for producing lots of torque, quickly overwhelms a 12V power supply. To get higher speeds and more performance out of this motor, higher supply voltages are necessary. Compare the actual speed curve on the 12V graph to the 30V graph. At 30V, the motor is able to achieve a much higher speed. It’s important to remember that the actual speed was measured at very high accelerations - by lowering acceleration, higher velocities can be achieved. Of course, if your motor is doing a lot of work, you’ll need to supply enough current to produce the necessary torque, therefore limiting the maximum speed.

Setting Current Limit for your application is a balancing act. By increasing the current limit, more torque is available, but far more power will be consumed when the motor is turning very slowly or stopped. When setting a high acceleration, more power (therefore current) is required to accelerate the motor and it’s load. Selecting the current limit is often done dynamically in the actual application - set the current limit very low, and run the system, increasing the Current Limit if it stalls. After a set up has been determined that is reliable, increase the current limit by another 25% to give some margin.

There is no point in setting the current limit to be greater than the motor’s rated current- the increased inductance will only further limit the motor speed. In this case, the 30V graph shows that it’s not feasible to operate this motor at maximum torque (1.7 Amps) at a speed greater than 1100 full steps per second. By reducing the current limit, greater speeds are possible, but less torque will be available. Most motors designed for Chopper Drive control can operate at much higher voltages, but Phidgets Inc. does not carry a controller that can provide these voltages at this time.

Note that just because you have set the current limit to some amount (for the sake of example let's say 2A) the motor will not draw 2A at all times. The motor will only draw as much current as it needs. This means that if there is only a small load on the motor and it is spinning at less than its top speed the motor might only draw a small fraction of the allotted 2A. Even as low as 300 or 400mA. As more load or higher speed is applied, the current usage will go up until the controller is giving the motor the full current limit. As a motor draws more current, it will also produce more heat. It is normal for a stepper motor to be hot to the touch after running for a while. If the motor is getting very hot, you may be trying to drive too large a load for that particular motor.

===Choosing a Supply Voltage===

When looking at a stepper motor's specifications, you may come across a "Rated Voltage" value. This value is usually equal to the rated current multiplied by the resistance of the coils of the motor, making it somewhat of a redundant specification. As mentioned earlier, you can increase your controller's supply voltage in order to allow the motor to reach higher speeds at a lower current (because high current causes high inductance which puts a hard limit on how much speed and torque a motor can produce). The motor will also produce more heat as you increase the supply voltage, so it's a good idea to choose a supply voltage based on the performance you need for the motor. Some motors will have a "Recommended Voltage" for a particular controller, which is the amount of voltage needed to reach the optimal speed and torque of the motor with minimal heating.

===Setting the Velocity Limit===

The velocity of a motor cannot be directly chosen with our stepper controllers. However, a velocity limit can be chosen to ensure that the motor does not go faster than a certain speed. This is useful because every stepper motor has a speed that causes itself to vibrate at the resonant frequency of its own moving parts. When the motor vibrates at this frequency, the motor will often overshoot its target position, causing it to lose most of its torque, sometimes even rotating in the wrong direction. This phenomenon is sometimes called "ringing". If you experience these problems while running your stepper motor at a constant velocity, try setting the velocity limit to lower or higher than it was previously, in an attempt to minimize the amount of time spent operating at this particular velocity.

===Setting the Acceleration===
The acceleration of a stepper motor is an important consideration when driving a load. Setting the acceleration too high can result in the motor stalling, especially with a heavy load. Try to use low acceleration in high-torque applications.

===Continuous Rotation and Forward/Reverse===

A stepper motor can be caused to rotate continuously by simply setting the controller's target position property to an extremely large number of steps.

Stepper motors can easily be run in forward or reverse by choosing a target position greater than or less than the current position, respectively. Reversing the polarity of either of the motor's wire pairs will invert this effect- causing a lesser target position to result in forward rotation, and a greater target position to result in reverse rotation. For this reason, you should pay attention to the way you wire a motor when developing and testing code, and ensure that you wire it with the same polarity in the future to avoid erroneous behaviour in applications where rotation direction matters.

===Cooling===
The stepper controllers sold at Phidgets Inc. have a current rating that is limited by the heat dissipation capability of the board. You could add heatsinks, fans, or other cooling devices to increase the current limit, but do so with caution. Unless you have a way of monitoring the temperature of the driver chip during operation, you have no way of knowing how far beyond the rated specification you can go.

===Wire Length===

Since the stepper controller is sending a fairly simple signal to the motor, interference is not a big concern. You should be able to have quite long wires between your motor and controller. For more information, see the [[Effects_of_Long_Wires|effects of long wires]] page.

===Saving Power===

When the stepper motor has rotated the requested number of steps, and is stopped, the coils will remain energized to hold it in position. This is necessary to allow the motor to support a load on its shaft without rotating to an unknown position.

'''Holding torque''' is the amount of torque required to rotate the motor ‘against it’s will’ when the full rated current is flowing through the coils. If power consumption or overheating is a problem, and full holding torque is not required, the Current Limit can be decreased in software when the motor is not moving. Holding torque will decrease linearly as you decrease the Current Limit, but will also allow you to save power and reduce the heat generated in your system.

There is also a small resistance to movement within the motor even when there is no current, called '''Detent Torque'''. This may be sufficient to prevent rotation in your application, especially if the stepper has a gearbox on it.

If the motor is not supporting a load or is not required to maintain a specific angle, it is recommended to set the Enable property to false. This will allow the motor shaft to rotate freely, but the present angle may be lost if forces on the motor-shaft are greater than can be resisted by the detent torque of the unpowered motor.

<br clear=all>

===Braking===

There are several ways to stop a stepper motor, each with different characteristics:

'''Set Target Position''' - If you set the target position to the motor's current position, it will stop. This is typically the best way to stop quickly and hold position, since the motor coils will still be engaged. You could also set the motor velocity limit to zero for a similar effect.

'''Short the coils''' - If you have the stepper wires connected to some external circuitry, you could use a switch to short the A and B terminals together, and the C and D terminals together. Due to the [http://en.wikipedia.org/wiki/Lorentz_force Lorentz force] of the electrons in the coil, the motor will begin to brake and hold position.

'''Cut power''' - You could cut power to the controller, but since the motor coils would no longer be engaged, the momentum would cause it to continue rotating until it slows down from friction and detent.

==Stepping Modes==

===Full Stepping===
This is the default mode of stepping for bipolar motors, where both phases of the motor are controlled by two square waves of current. One wave lags behind the other by 90 degrees, and the motion of the motor is locked to these waves. A full step is completed when the square waves advance by 90 degrees. Since both phases are always fully energized, full stepping provides the best torque.

===Half Stepping===
In this stepping mode, the controller alternates between having one phase energized and both phases energized. This results in the rotor pausing at half-steps in between the poles, effectively halving the step angle. However, since the current to each coil cannot be exactly balanced, the angle that the rotor comes to rest at between poles may not be exactly half the step angle. The downside to half stepping is that the motor will have less torque on the steps when only one phase is energized.

===Mini/Micro-stepping===
By controlling the the relative current of both phases, the rotor position can come to rest at various equally spaced sub-steps between the two phases. This is achieved by following the same procedure for Full Stepping, except that the current supplied more closely resembles a sine wave rather than a square wave. Some bipolar controllers are designed to micro-step at low speeds to allow for smooth rotation.

==Selecting a Gearbox==

Using a stepper motor with a gearbox can be a good solution in applications that need very low rotation speeds and/or lots of torque. Selecting a gearbox to attach to the stepper will result in increasing the output torque and decreasing the speed.
Simply, the Gearbox Output Speed is:

<math>
\text{Output Speed} =\frac{\text{Motor Speed}}{\text{Gearbox Ratio}}
</math>

Although the reduction ratio plays a large part in determining the Gearbox Output Torque, there is also an inefficiency that is introduced through the use of a gearbox. Some of the torque of the motor is internally converted into heat and lost. So to calculate the Gearbox Output Torque:

<math>
\text{Output Torque} = \text{Motor Output Torque } \times \text{ Gearbox Ratio } \times \text{ Gearbox Efficiency}
</math>

When choosing a stepper motor with a gearbox, keep in mind that the gearbox is rated to sustain a specific amount of torque, beyond which the gearbox could become damaged. This limit is often much lower than the amount of torque specified by the above equation.

The Gearbox Step Angle can be determined by:

<math>
\text{Gearbox Step Angle} = \frac{\text{Motor Step Angle}}{\text{Gearbox Ratio}}
</math>

===Planetary Gearbox Reduction Ratios===

[[File:Planetary_gearing.jpg|thumb|300px|link=|This diagram illustrates the parts of a 5.18:1 planetary gearbox.<br>[/docs21/images/1/1a/Planetary_gearing.jpg Click for Larger Image]]]

In some applications, it is important to know the exact gear ratio of a gearbox (for example, when you need the output shaft to make a several complete rotations
and stop in the same position it started). Most motor datasheets will only list an approximate ratio, like "10:1" or "27:1". However, there are ways to figure out
the exact ratio.

In a planetary gearbox where the sun gear is used as an input and the rotation of the spider linking the planet gears is the output, the reduction ratio can be
expressed by the following equation:

<math>
\text{Gearbox Ratio} = \frac{T_R + T_S}{T_S}
</math>

Where <math>T_R</math> is the number of teeth on the ring gear, and <math>T_S</math> is the number of teeth on the sun gear. In this situation, the number of teeth on the planetary gears
don't affect the reduction ratio and serve only to connect the ring and sun gears. In order to increase the reduction ratio, you need to increase the number of
teeth on the ring gear. Since there is limited space inside a motor's gearbox, it eventually becomes impossible to increase the gear ratio. This limitation can be
bypassed by introducing multiple gear '''stages'''. In a multi-stage planetary gearbox, the axles of the planet gears of the first stage are connected to a piece
of metal called a "spider", whose rotation is used to turn the sun of the next stage. It's very common for multi-stage planetary gearboxes to have a tall ring
gear that spans multiple stages. To determine the overall reduction ratio of a multi-stage planetary gearbox, simply multiply the two ratios together. For
example, two stages each with a 5:1 reduction ratio would result in a total ratio of 25:1.
The following table lists exact ratios for gearboxes commonly sold at Phidgets Inc. :

[[File:Gearbox_table.jpg|link=]]

The colored squares visualize the stages that compose each gearbox. For example, a two-stage gearbox with 1 blue and 1 green square indicates that one stage is
the same ratio as the 1-stage gearbox with the green square beside it, and the other stage is the same as the one with a blue square beside it.
If you have a third party gearbox and are unable to open it to count the gear teeth, you could also determine the approximate reduction ratio experimentally by
measuring the rotation angle after a known number of steps have occured. The more accurately you can measure the angle, the better your approximation will be.

===Gearbox Terminology===

Here is a short list of terms you might come across when deciding upon a gearbox:

'''Backlash'''

The amount of clearance between mated gear teeth. Theoretically, the backlash should be “the smaller the better,” but in actual practice, some backlash must be allowed to prevent jamming.

'''Gear Ratio'''

The gearbox accepts the power (think of power as a torque that rotates) from the motor, reducing the speed (exactly) by a given ratio, while increasing the torque (roughly) by the same ratio – a ratio of the gear head with which the gear head reduces the motor speed. For example, if a motor has a speed of 500RPM and the reduction ratio is 100:1, the speed of the gear head is 500/100 = 5RPM. This is the actual reduction ratio. The calculated speed from the gear head should be based on this ratio.

'''Gearbox Step Angle'''

A full step of the motor will result in the gearbox making a smaller step. The angle of this step is the step angle of the motor divided by the gearbox reduction ratio. For example, a motor with a step angle of 1.8º and a gearbox with a reduction ratio of 20:1 will have a step angle of 1.8/20 = 0.09º at the output of the gearbox.

'''Gearbox Output Torque'''

The gearbox takes the torque from the output shaft of the motor, reducing the speed and increasing the torque. The gearbox, depending on its efficiency, loses some of the torque as it is converted into heat. Therefore, the Gearbox Output Torque is the motor output torque multiplied by the reduction ratio multiplied by the efficiency of the gearbox. For example, a motor with a low-speed output torque of 500g*cm and a gearbox with a reduction ratio of 5:1 and 90% efficiency will have a Gearbox Output Torque of 500*5*0.9 = 2.25 kg*cm. Remember, however, that if the Gearbox Output Torque exceeds the allowable torque the gearbox is rated for, you can cause damage to the gearbox.

'''Gear Trains'''

Planetary gearboxes use multiple gear sets to achieve large gear reductions. Each gear set makes the gearbox longer, and reduces the efficiency.

==Product Comparison Tables==

{|border=1
|+'''Stepper Motor Product Specifications'''
! Phidgets Product #
! Motor Model Number
! Motor Type (Unipolar/Bipolar)
! Step Angle (deg)
! Holding Torque (g•cm)
! Low-Speed Torque (g•cm)
! Rated Current (A)
! Number of Leads
! Mounting Plate Size
! Shaft Diameter (mm)
! Total Weight (g)
! Motor Length (mm)
! Motor Size/Diameter (mm)
|-
| 3302|| 42BYGHM810 || Hybrid Bipolar || 0.9|| 4800|| 4280|| 2.4 || 4|| NEMA-17|| 5 || 362|| 48 || 42 x 42
|-
| 3303|| 42BYGHW811 || Hybrid Bipolar || 1.8|| 4800|| 4240|| 2.5 || 4|| NEMA-17|| 5 || 332|| 48 || 42 x 42
|-
| 3304|| 39BYGS202 || Hybrid Bipolar || 3.75|| 750|| 590 || 1 || 4|| NEMA-17|| 5 || 171|| 32 || 39 x 39
|-
| 3305|| 39BYG013 || Hybrid Bipolar || 1.8|| 550|| 450 || 0.4 || 4|| NEMA-17|| 5 || 110|| 20 || 39 x 39
|-
| 3314|| PM42L-048-17|| Hybrid Unipolar|| 7.5|| 950 || 710 || 0.28|| 6|| N/A || 3 || 138|| 14.4|| 42
|-
| 3315|| PM25S-048-15|| Hybrid Unipolar|| 7.5|| 140 || 50 || 0.1 || 6|| N/A || 2 || 31 || 15 || 25
|-
| 3316|| PM20L-20-14 || Hybrid Unipolar|| 18 || 50 || 30 || 0.08|| 6|| N/A || 1.5|| 24 || 16.5|| 20
|-
| 3320|| 28STH32 || Hybrid Bipolar || 1.8|| 600 || 520 || 0.67|| 4|| NEMA-11|| 5 || 111|| 32|| 28 x 28
|-
| 3323|| 35STH40 || Hybrid Bipolar || 1.8|| 1400|| 1200|| 1 || 4|| NEMA-14|| 5 || 200|| 40|| 35 x 35
|-
| 3324|| 42STH38 || Hybrid Bipolar || 1.8|| 3600|| 3300|| 1.7 || 4|| NEMA-17|| 5 || 289|| 40|| 42 x 42
|-
| 3330|| 57STH56 || Hybrid Bipolar || 0.9||12000||11200|| 2.8 || 4|| NEMA-23|| 6.4|| 695|| 56|| 56 x 56
|-
| 3331|| 57STH56 || Hybrid Bipolar || 1.8||12600||11000|| 2.8 || 4|| NEMA-23|| 6.4|| 686|| 56|| 56 x 56
|-
| 3335|| 86STH65 || Hybrid Bipolar || 1.8||34000||30000||2 or 4 || 4|| NEMA-34|| 12|| 1800|| 65|| 85 x 85
|-
| 3336|| 86STH156 || Hybrid Bipolar || 1.8||122000||106000||3 or 6 || 4|| NEMA-34|| 16|| 5200|| 156|| 85 x 85
|-
| 3340|| 42STH38 || Hybrid Bipolar || 0.9||3600||3300||1.7 || 4|| NEMA-17|| 5||288|| 40|| 42 x 42
|}

{| border=1
|+'''Gearbox Stepper Motor Product Specifications'''
!Product #
!Motor Model #
!Motor Type
!Step Angle<sup>†</sup> (deg)
!Holding Torque*,<sup>†</sup> (g-cm)
!Low-speed Torque*,<sup>†</sup> (g-cm)
!Rated Current (A)
!# of Leads
!Mounting Plate Size
!Shaft Diameter (mm)
!Total Weight (g)
!Motor Length (mm)
!Gearbox Length (mm)
!Motor Size/Diameter (mm)
!Gear Ratio
!Gearbox Max Torque (g-cm)
!Gearbox Efficiency
!Max Speed<sup>†</sup> (RPM)
|-
| 3310||57BYG630-07AG20||Hybrid Bipolar||0.09||30000||30000||2.8||4||NEMA-23||8||1330||73||38||56x56||20:1||30000||||30
|-
| 3311||42BYGHW811-AG5.18||Hybrid Bipolar||0.35||24860||17790||2.5||4||NEMA-17||8||513||48||31||42x42||5.18:1||30000||0.9||115
|-
| 3312||42BYGHW811-AG26.8||Hybrid Bipolar||0.07||40000||40000||2.5||4||NEMA-17||8||526||48||39||42x42||26.8:1||40000||0.81||22
|-
| 3313||42BYGHW811-AG99.5||Hybrid Bipolar||0.02||50000||50000||2.5||4||NEMA-17||8||610||48||47||42x42||99.5:1||50000||0.73||6
|-
| 3317||42BYGH40(M)-160-4A||Hybrid Bipolar||0.35||16780||12000||1.6||4||NEMA-17||8||464||40||30||42x42||5.18:1||20000||0.9||115
|-
| 3318||42BYGH40(M)-160-4A||Hybrid Bipolar||0.07||30000||30000||1.6||4||NEMA-17||8||464||40||38||42x42||26.8:1||30000||0.8||22
|-
| 3319||42BYGH40(M)-160-4A||Hybrid Bipolar||0.02||40000||40000||1.6||4||NEMA-17||8||464||40||46||42x42||99.5:1||40000||0.7||6
|-
| 3321||28STH32-0674B/28JXS40K27||Hybrid Bipolar||0.067||16100||14000||0.67||4||NEMA-11||6||218||32||40||28x28||27:1||20000|| ||120
|-
| 3322||28STH32-0674B/28JXS40K100||Hybrid Bipolar||0.018||32000||32000||0.67||4||NEMA-11||6||243||32||49||28x28||100:1||32000|| ||35
|-
| 3325||42STH38-1684B/36JXS60K5.18||Hybrid Bipolar||0.35||18000||18000||1.7||4||NEMA-17||8||457||40||31||42x42||5.18:1||18000|| ||904
|-
| 3326||42STH38-1684B/36JXS60K14||Hybrid Bipolar||0.13||30000||30000||1.7||4||NEMA-17||8||502||40||39||42x42||14:1||30000|| ||295
|-
| 3327||42STH38-1684B/36JXS60K26||Hybrid Bipolar||0.067||30000||30000||1.7||4||NEMA-17||8||503||40||39||42x42||26.85:1||30000|| ||174
|-
| 3328||42STH38-1684B/36JXS60K51||Hybrid Bipolar||0.035||48000||48000||1.7||4||NEMA-17||8||564||40||48||42x42||51:1||48000|| ||63
|-
| 3329||42STH38-1684B/36JXS60K99.51||Hybrid Bipolar||0.018||48000||48000||1.7||4||NEMA-17||8||564||40||48||42x42||100:1||48000|| ||34
|-
| 3332||57STH56-2804B/56JXS300K4.25||Hybrid Bipolar||0.42||53000||46600||2.8||4||NEMA-23||12||1200||56||48||57x57||4.25:1||90000|| ||375
|-
| 3333||57STH56-2804B/56JXS300K15||Hybrid Bipolar||0.12||150000||150000||2.8||4||NEMA-23||12||1300||56||61||57x57||15:1||150000|| || 116
|-
| 3334||57STH56-2804B/56JXS300K77||Hybrid Bipolar||0.023||240000||240000||2.8||4||NEMA-23||12||1500||56||72||57x57||77:1||240000|| ||25
|}

<sup>†</sup>Step angle, torque values, and max speed are all measured at the output of the gearbox.

<nowiki>*</nowiki>Holding torque and low speed torque for gearbox motors are limited by the max torque that the gearbox is rated to sustain.
<nowiki>*</nowiki>

==Glossary of Terms==

===Motor Terms===

'''Coil Resistance'''

The electrical resistance (to direct current) of the wiring within the motor. This resistance causes some of the energy being applied to the motor to be converted into heat. Some motors and motor controllers rely solely on the electrical resistance to regulate the current flowing through the motor. The Unipolar Motors we sell, and the 1062 PhidgetStepper Unipolar rely on this inexpensive, but inefficient technique. Other motors will have very low resistance, increasing their efficiency, but requiring very sophisticated control techniques because the resistance cannot regulate the current to a safe level on its own. Our Bipolar controllers and our Bipolar motors use this technique, otherwise known as Chopper Drive.

'''Holding Torque'''

Holding Torque is the amount of torque needed to rotate the shaft of the stepper motor while the controller attempts to hold the position, using the maximum current allowed for the motor. Holding Torque is the sum of the magnetic force exerted by the electrical coils to hold the current position, and the detent torque, which is the natural resistance of the motor against rotation due to the permanent magnet inside the motor. Once the motor begins to rotate, the torque it can exert (at least at low speeds) is Holding Torque minus twice the detent torque (because the motor is now working against the detent). As the motor speed increases, torque begins to decrease. If the power supply voltage is low, or the inductance of the motor is high, the torque will fall more rapidly.

'''Motor Inductance'''

Stepper motors are built with a specific coil inductance. A high inductance motor will provide a greater amount of torque at low speeds, at the cost of having lower torque at high speeds.

'''Overhung Load (OHL) / Radial Load'''

An external load applied on the output shaft of the gearbox. This load is often produced if pulleys are mounted directly on the shaft, pulling perpendicular to it. When the OHL exceeds a safe value, the bearings can fail, or the shaft can break from bending fatigue. While OHL and Thrust Load specifications are only available for our gearbox motors, both types of load should be avoided when using any of our motors.

'''Rated Current'''

The rated current is the maximum current that should be applied to each coil of the motor. Current generates heat within the motor, and exceeding the regulated current will cause the motor to overheat. If the motor is operated in a hot environment, or is enclosed, it can overheat at currents lower than the rated current.

'''Step Angle'''

The change in the shaft angle when the motor moves forward or backward by one full step.

'''Step Accuracy'''

Depending on the motor and how it is loaded down, the step positions will vary slightly. Fortunately, this variance doesn’t accumulate – so if you move the motor by one step or one million steps, the angle that the motor stops at will have the same margin of error.

'''Thrust load / Axial Load'''

A load applied directly in line with the output shaft of the gearbox. Avoid thrust as much as possible. If thrust load is unavoidable, keep it to no more than the permissible value.

Stepper Motor and Controller Primer

2017-09-18T17:16:10Z

Patrick:

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[Image:3302.jpg|link=]]
| [[Image:1063.jpg|link=]]
|}

<br clear="all" />

==Introduction==
Stepper motors are broadly available motors commonly used for positioning. The rotor of a stepper moves in a series of discrete steps. By energizing the coils of the motor in sequence through many of these steps, the direction of rotation, number of rotations, and exact position of the motor shaft can be easily controlled. By controlling the time between the steps, the speed and acceleration of the stepper is regulated. In contrast, a DC motor will blindly spin at the highest speed possible when powered, unless it is controlled with an [[Encoder Primer|Encoder]] and a control system program. It is not necessary to use an encoder on a stepper motor unless you're concerned about the motor losing count of the steps over a long period of time or in high torque situations.

Each stepper motor is designed to move by a certain angle with each discrete step. The simplest stepper motors will rotate 90 degrees per step. Standard industrial steppers will rotate 1.8 degrees per step. The stepping angle can be further reduced through use of a gearbox.

In addition to the ease of precisely controlling position and speed, Steppers have other advantages:

*Most motors have very little torque when they are operating at low speed or standstill. Since a stepper’s rotor is held in place by a magnetic field during each step, steppers have full torque at low speed or standstill, making them very useful for low speed rotation and actuation. Additionally, a stepper motor can remain in a fixed position for long periods of time with the rated current in the windings, whereas with DC motors, stalling and remaining in a fixed position for long periods of time will cause motor burnout.
*DC Motors have brushes with a finite lifetime. Steppers have no brushes, and are limited only by the life of the bearings.

Compared to DC Motors, there are disadvantages to Steppers:

*Each step will produce vibration in the motor. If these vibrations are at the mechanical resonant frequency of the motor, they can cause the rotor to overshoot and bounce back and forth, resulting in a severe loss of torque. This phenomenon is called “ringing” and is often accompanied by a loud buzzing or grinding noise. To prevent the motor from operating in such a way, you should test the motor at various speeds in the physical application it is intended for, and try to avoid running the motor at a speed which exhibits ringing behaviour.
*If the motor encounters a brief overload, the fixed coils on the stator and the free-spinning rotor can lose track of each other. If this happens at higher speeds, the motor will often stall. Even at lower speeds, your system will have lost track of where exactly the motor is positioned – unless there is an independent system (e.g., an optical encoder) tracking the position.
*A Stepper motor cannot be loaded at its maximum torque, as it will almost certainly be overloaded during operation. A DC Motor will naturally adjust its speed depending on how much power is provided, and the torque required to turn it’s shaft.

For more information about the differences between stepper motors, DC motors, and servo motors, see the [[Motor Selection Guide]].

==Types of Stepper Motors==

We find it useful to classify motors according to how the coils are wound (Bipolar / Unipolar), the internal magnetic construction (Permanent Magnet / Hybrid), and how the current in the coils is regulated (Chopper Drive / Resistive Limited).

===Coils===
=====Bipolar=====
These motors are manufactured with two coils of wire, resulting in one winding per phase. By alternating the power between coils, as well as the direction of the current, the motor is rotated. This configuration produces magnetic fields within the coils in either direction, hence the term “Bipolar.” The controller is more expensive because it has to be able to produce both positive and negative electrical currents, but the advantage is that the entire coil is being used, thus increasing torque capabilities at all speeds. We do not recommend using a bipolar controller to run a unipolar motor, even though it is theoretically possible.

=====Unipolar=====
In a unipolar motor, the motor windings consist of two identical coils per phase, wound in opposite directions (each occupying half of the space a coil normally would in a bipolar stepper). As a result, the controller only needs to select which of the two coils to pass current through in order to change the magnetic polarity, and only a positive current is required to be generated. Due to this simplified control mechanism which uses only half of each coil, the torque of unipolar motors are usually much lower, but the overall cost of the system is much cheaper. The simplicity of the unipolar controller also means that you cannot use it to run a bipolar stepper motor.

===Magnets===
=====Permanent Magnet=====
Permanent magnet motors are small, low torque, and inexpensive. They use a permanent magnet in the rotor that is attracted or repelled by magnetic field generated by the stator coils. Step angles are often 7.5 or 15 degrees, and the motors are usually unipolar.

=====Variable Reluctance=====
The rotor of a variable reluctance stepper is made of iron, and it therefore aligns with the magnetic field generated by the stator coils. Since it doesn’t use a permanent magnet, it doesn’t matter which direction the current flows as long as each coil is wound in the opposite direction as the coil across from it. Therefore, variable reluctance steppers are unipolar and are typically designed to have larger step angles of 15 or more degrees.

=====Hybrid=====
Hybrid Motors dominate the stepper motor world – they use a combination of characteristics from permanent magnet and variable reluctance steppers and have the best torque and speed, but are more expensive to produce. Step angles are typically 0.9 to 3.75 degrees, giving much better step resolution.

===Drive===
=====Chopper Drive=====
Chopper Drive is an electronic control technique which allows specific motors to produce more power, torque, speed, and be more efficient. Instead of relying on the resistance of the coil wiring, the inductance of the wiring is exploited by sophisticated control electronics as a short-term limitation of motor current. Motor Manufacturers don’t do a good job of distinguishing motors suitable for use with Chopper Drive electronics. The motors will often be large, square, with very low resistance.
=====Resistive Limited=====
Small, inexpensive steppers are designed to be built and controlled as cheaply as possible. To simplify the control electronics, the length and thickness of the wire in the coils is selected for a particular control voltage. This allows the coil itself to regulate the power available to the motor – provided the appropriate voltage is used, of course. We call this type of motor Resistive Limited.

==How it Works==

[[Image:Stepper_back_web.jpg|left|link=|thumb|230px|Cross-Section of a Hybrid Bipolar Stepper<br />[[Media:Stepper_back_web.jpg|Full-size Image]]]]

===Hybrid Bipolar Steppers===
This section of the primer will cover the general principle of operation for stepper motors. While this information is by no means necessary to use a stepper motor, those who are curious about their inner workings may read on.

The thumbnail to the left is a cross-sectional view of the inside of a hybrid bipolar stepper motor. As you can see, it has eight poles with six teeth each. This motor contains two coils- one wrapping the odd-numbered poles, and the other wrapping the even-numbered poles. The steel end-cap in the center of the image covers a cylindrical permanent magnet which surrounds the shaft.

If positive current is sent to the odd-numbered coil, poles 1 and 5 are magnetized as south, and poles 3 and 7 are magnetized as north. Assuming the permanent magnet in the center of the motor has its north pole facing toward us, this will result in the rotor turning so that the teeth line up with stator poles 1 and 5, as they are in the image. At the same time, poles 3 and 7 will become aligned on the opposite end of the motor, where the gear on the rotor is permanently offset by the width of one tooth and the permanent magnet has magnetized the rotor as south. The rotation of the motor is continued by sending negative current through the even-numbered phase, then negative current through the odd-numbered phase, then positive current through the even-numbered phase, and so on. The stepper controller can reverse the direction of rotation simply by reversing this sequence.

When a stepper motor becomes engaged in software, and current is applied to the coils, it may abruptly "snap" to the position that the rotor is being held at.

<br clear="all">

===Hybrid Unipolar Steppers===
The operation of a hybrid unipolar stepper is very similar to the bipolar stepper described above, except that each pole has two seperate coils wound in opposite directions. This results in four phases which only require positive current to operate. Rather than alternating the direction of current, the motor controller simply sends positive current to the appropriate half of the coil.

==Controlling the Stepper Motor==

The following information has been derived from using the 3308 stepper motor connected to a 1063 - PhidgetStepper Bipolar 1-Motor controller.
===Setting the Current Limit===

[[Image:Graph12v.jpg|border|400px|link=|thumb|The current/speed characteristics for the 3308 at 12V.<br />[[Media:Graph12v.jpg|Full-size Image]]]]

[[Image:Graph24v.jpg|border|400px|link=|thumb|The current/speed characteristics for the 3308 at 24V.<br />[[Media:Graph24v.jpg|Full-size Image]]]]

[[Image:Graph30v.jpg|border|400px|link=|thumb|The current/speed characteristics for the 3308 at 30V.<br />[[Media:Graph30v.jpg|Full-size Image]]]]

The current limit is an important control property of stepper controllers. Since many stepper motors have a very low coil resistance, the current through the coils cannot “self-regulate” to a safe level on their own. They require the sophisticated control techniques of a Chopper Drive, which is used in the [{{SERVER}}/products.php?product_id=1063 1063 PhidgetStepper] controller. As a result, the maximum current allowed should be explicitly set.

There are many factors that influence what the current limit should be set to. These include, but are not limited to,the acceleration and speed of the stepper, the supply voltage, applied torque, motor inductance, and coil resistance. The process of choosing the current limit can be simplified by following some general rules of thumb. The graphs in this section show a set of speed vs. current characteristics for the 3308 stepper with various power supplies.

In the these graphs, the '''“actual speed”''' of the motor is the maximum speed attainable in a real world test done with no load on the motor, but at very high acceleration. The '''“max speed”''' shows the limitation on speed imposed by the inductance of the motor coils at a given supply voltage. Given that the 1063 controller is only able to run at a maximum speed of 2048 full steps per second, our graphs don’t show data at higher speeds.

When the current limit is set low and the acceleration is high, the motor will not be able to provide enough power to accelerate itself and the load it’s driving. The motor also has to overcome friction losses within the system, and do work on the load - for example, lifting a weight. By increasing the current limit, more current and power is made available to accelerate and maintain maximum speeds. This can be seen on any of the graphs in the initial steep ramp of the actual speed. As the current limit increases, the motor is able to achieve higher speeds.

In the case of this particular motor, the large inductance of the coils - great for producing lots of torque, quickly overwhelms a 12V power supply. To get higher speeds and more performance out of this motor, higher supply voltages are necessary. Compare the actual speed curve on the 12V graph to the 30V graph. At 30V, the motor is able to achieve a much higher speed. It’s important to remember that the actual speed was measured at very high accelerations - by lowering acceleration, higher velocities can be achieved. Of course, if your motor is doing a lot of work, you’ll need to supply enough current to produce the necessary torque, therefore limiting the maximum speed.

Setting Current Limit for your application is a balancing act. By increasing the current limit, more torque is available, but far more power will be consumed when the motor is turning very slowly or stopped. When setting a high acceleration, more power (therefore current) is required to accelerate the motor and it’s load. Selecting the current limit is often done dynamically in the actual application - set the current limit very low, and run the system, increasing the Current Limit if it stalls. After a set up has been determined that is reliable, increase the current limit by another 25% to give some margin.

There is no point in setting the current limit to be greater than the motor’s rated current- the increased inductance will only further limit the motor speed. In this case, the 30V graph shows that it’s not feasible to operate this motor at maximum torque (1.7 Amps) at a speed greater than 1100 full steps per second. By reducing the current limit, greater speeds are possible, but less torque will be available. Most motors designed for Chopper Drive control can operate at much higher voltages, but Phidgets Inc. does not carry a controller that can provide these voltages at this time.

Note that just because you have set the current limit to some amount (for the sake of example let's say 2A) the motor will not draw 2A at all times. The motor will only draw as much current as it needs. This means that if there is only a small load on the motor and it is spinning at less than its top speed the motor might only draw a small fraction of the allotted 2A. Even as low as 300 or 400mA. As more load or higher speed is applied, the current usage will go up until the controller is giving the motor the full current limit. As a motor draws more current, it will also produce more heat. It is normal for a stepper motor to be hot to the touch after running for a while. If the motor is getting very hot, you may be trying to drive too large a load for that particular motor.

===Choosing a Supply Voltage===

When looking at a stepper motor's specifications, you may come across a "Rated Voltage" value. This value is usually equal to the rated current multiplied by the resistance of the coils of the motor, making it somewhat of a redundant specification. As mentioned earlier, you can increase your controller's supply voltage in order to allow the motor to reach higher speeds at a lower current (because high current causes high inductance which puts a hard limit on how much speed and torque a motor can produce). The motor will also produce more heat as you increase the supply voltage, so it's a good idea to choose a supply voltage based on the performance you need for the motor. Some motors will have a "Recommended Voltage" for a particular controller, which is the amount of voltage needed to reach the optimal speed and torque of the motor with minimal heating.

===Setting the Velocity Limit===

The velocity of a motor cannot be directly chosen with our stepper controllers. However, a velocity limit can be chosen to ensure that the motor does not go faster than a certain speed. This is useful because every stepper motor has a speed that causes itself to vibrate at the resonant frequency of its own moving parts. When the motor vibrates at this frequency, the motor will often overshoot its target position, causing it to lose most of its torque, sometimes even rotating in the wrong direction. This phenomenon is sometimes called "ringing". If you experience these problems while running your stepper motor at a constant velocity, try setting the velocity limit to lower or higher than it was previously, in an attempt to minimize the amount of time spent operating at this particular velocity.

===Setting the Acceleration===
The acceleration of a stepper motor is an important consideration when driving a load. Setting the acceleration too high can result in the motor stalling, especially with a heavy load. Try to use low acceleration in high-torque applications.

===Continuous Rotation and Forward/Reverse===

A stepper motor can be caused to rotate continuously by simply setting the controller's target position property to an extremely large number of steps.

Stepper motors can easily be run in forward or reverse by choosing a target position greater than or less than the current position, respectively. Reversing the polarity of either of the motor's wire pairs will invert this effect- causing a lesser target position to result in forward rotation, and a greater target position to result in reverse rotation. For this reason, you should pay attention to the way you wire a motor when developing and testing code, and ensure that you wire it with the same polarity in the future to avoid erroneous behaviour in applications where rotation direction matters.

===Cooling===
The stepper controllers sold at Phidgets Inc. have a current rating that is limited by the heat dissipation capability of the board. You could add heatsinks, fans, or other cooling devices to increase the current limit, but do so with caution. Unless you have a way of monitoring the temperature of the driver chip during operation, you have no way of knowing how far beyond the rated specification you can go.

===Wire Length===

Since the stepper controller is sending a fairly simple signal to the motor, interference is not a big concern. You should be able to have quite long wires between your motor and controller. For more information, see the [[Effects_of_Long_Wires|effects of long wires]] page.

===Saving Power===

When the stepper motor has rotated the requested number of steps, and is stopped, the coils will remain energized to hold it in position. This is necessary to allow the motor to support a load on its shaft without rotating to an unknown position.

'''Holding torque''' is the amount of torque required to rotate the motor ‘against it’s will’ when the full rated current is flowing through the coils. If power consumption or overheating is a problem, and full holding torque is not required, the Current Limit can be decreased in software when the motor is not moving. Holding torque will decrease linearly as you decrease the Current Limit, but will also allow you to save power and reduce the heat generated in your system.

There is also a small resistance to movement within the motor even when there is no current, called '''Detent Torque'''. This may be sufficient to prevent rotation in your application, especially if the stepper has a gearbox on it.

If the motor is not supporting a load or is not required to maintain a specific angle, it is recommended to set the Enable property to false. This will allow the motor shaft to rotate freely, but the present angle may be lost if forces on the motor-shaft are greater than can be resisted by the detent torque of the unpowered motor.

<br clear=all>

===Braking===

There are several ways to stop a stepper motor, each with different characteristics:

'''Set Target Position''' - If you set the target position to the motor's current position, it will stop. This is typically the best way to stop quickly and hold position, since the motor coils will still be engaged. You could also set the motor velocity limit to zero for a similar effect.

'''Short the coils''' - If you have the stepper wires connected to some external circuitry, you could use a switch to short the A and B terminals together, and the C and D terminals together. Due to the [http://en.wikipedia.org/wiki/Lorentz_force Lorentz force] of the electrons in the coil, the motor will begin to brake and hold position.

'''Cut power''' - You could cut power to the controller, but since the motor coils would no longer be engaged, the momentum would cause it to continue rotating until it slows down from friction and detent.

==Stepping Modes==

===Full Stepping===
This is the default mode of stepping for bipolar motors, where both phases of the motor are controlled by two square waves of current. One wave lags behind the other by 90 degrees, and the motion of the motor is locked to these waves. A full step is completed when the square waves advance by 90 degrees. Since both phases are always fully energized, full stepping provides the best torque.

===Half Stepping===
In this stepping mode, the controller alternates between having one phase energized and both phases energized. This results in the rotor pausing at half-steps in between the poles, effectively halving the step angle. However, since the current to each coil cannot be exactly balanced, the angle that the rotor comes to rest at between poles may not be exactly half the step angle. The downside to half stepping is that the motor will have less torque on the steps when only one phase is energized.

===Mini/Micro-stepping===
By controlling the the relative current of both phases, the rotor position can come to rest at various equally spaced sub-steps between the two phases. This is achieved by following the same procedure for Full Stepping, except that the current supplied more closely resembles a sine wave rather than a square wave. Some bipolar controllers are designed to micro-step at low speeds to allow for smooth rotation.

==Selecting a Gearbox==

Using a stepper motor with a gearbox can be a good solution in applications that need very low rotation speeds and/or lots of torque. Selecting a gearbox to attach to the stepper will result in increasing the output torque and decreasing the speed.
Simply, the Gearbox Output Speed is:

<math>
\text{Output Speed} =\frac{\text{Motor Speed}}{\text{Gearbox Ratio}}
</math>

Although the reduction ratio plays a large part in determining the Gearbox Output Torque, there is also an inefficiency that is introduced through the use of a gearbox. Some of the torque of the motor is internally converted into heat and lost. So to calculate the Gearbox Output Torque:

<math>
\text{Output Torque} = \text{Motor Output Torque } \times \text{ Gearbox Ratio } \times \text{ Gearbox Efficiency}
</math>

When choosing a stepper motor with a gearbox, keep in mind that the gearbox is rated to sustain a specific amount of torque, beyond which the gearbox could become damaged. This limit is often much lower than the amount of torque specified by the above equation.

The Gearbox Step Angle can be determined by:

<math>
\text{Gearbox Step Angle} = \frac{\text{Motor Step Angle}}{\text{Gearbox Ratio}}
</math>

===Planetary Gearbox Reduction Ratios===

[[File:Planetary_gearing.jpg|thumb|300px|link=|This diagram illustrates the parts of a 5.18:1 planetary gearbox.<br>[[[/docs21/images/1/1a/Planetary_gearing.jpg Click for Larger Image]]]

In some applications, it is important to know the exact gear ratio of a gearbox (for example, when you need the output shaft to make a several complete rotations
and stop in the same position it started). Most motor datasheets will only list an approximate ratio, like "10:1" or "27:1". However, there are ways to figure out
the exact ratio.

In a planetary gearbox where the sun gear is used as an input and the rotation of the spider linking the planet gears is the output, the reduction ratio can be
expressed by the following equation:

<math>
\text{Gearbox Ratio} = \frac{T_R + T_S}{T_S}
</math>

Where <math>T_R</math> is the number of teeth on the ring gear, and <math>T_S</math> is the number of teeth on the sun gear. In this situation, the number of teeth on the planetary gears
don't affect the reduction ratio and serve only to connect the ring and sun gears. In order to increase the reduction ratio, you need to increase the number of
teeth on the ring gear. Since there is limited space inside a motor's gearbox, it eventually becomes impossible to increase the gear ratio. This limitation can be
bypassed by introducing multiple gear '''stages'''. In a multi-stage planetary gearbox, the axles of the planet gears of the first stage are connected to a piece
of metal called a "spider", whose rotation is used to turn the sun of the next stage. It's very common for multi-stage planetary gearboxes to have a tall ring
gear that spans multiple stages. To determine the overall reduction ratio of a multi-stage planetary gearbox, simply multiply the two ratios together. For
example, two stages each with a 5:1 reduction ratio would result in a total ratio of 25:1.
The following table lists exact ratios for gearboxes commonly sold at Phidgets Inc. :

[[File:Gearbox_table.jpg|link=]]

The colored squares visualize the stages that compose each gearbox. For example, a two-stage gearbox with 1 blue and 1 green square indicates that one stage is
the same ratio as the 1-stage gearbox with the green square beside it, and the other stage is the same as the one with a blue square beside it.
If you have a third party gearbox and are unable to open it to count the gear teeth, you could also determine the approximate reduction ratio experimentally by
measuring the rotation angle after a known number of steps have occured. The more accurately you can measure the angle, the better your approximation will be.

===Gearbox Terminology===

Here is a short list of terms you might come across when deciding upon a gearbox:

'''Backlash'''

The amount of clearance between mated gear teeth. Theoretically, the backlash should be “the smaller the better,” but in actual practice, some backlash must be allowed to prevent jamming.

'''Gear Ratio'''

The gearbox accepts the power (think of power as a torque that rotates) from the motor, reducing the speed (exactly) by a given ratio, while increasing the torque (roughly) by the same ratio – a ratio of the gear head with which the gear head reduces the motor speed. For example, if a motor has a speed of 500RPM and the reduction ratio is 100:1, the speed of the gear head is 500/100 = 5RPM. This is the actual reduction ratio. The calculated speed from the gear head should be based on this ratio.

'''Gearbox Step Angle'''

A full step of the motor will result in the gearbox making a smaller step. The angle of this step is the step angle of the motor divided by the gearbox reduction ratio. For example, a motor with a step angle of 1.8º and a gearbox with a reduction ratio of 20:1 will have a step angle of 1.8/20 = 0.09º at the output of the gearbox.

'''Gearbox Output Torque'''

The gearbox takes the torque from the output shaft of the motor, reducing the speed and increasing the torque. The gearbox, depending on its efficiency, loses some of the torque as it is converted into heat. Therefore, the Gearbox Output Torque is the motor output torque multiplied by the reduction ratio multiplied by the efficiency of the gearbox. For example, a motor with a low-speed output torque of 500g*cm and a gearbox with a reduction ratio of 5:1 and 90% efficiency will have a Gearbox Output Torque of 500*5*0.9 = 2.25 kg*cm. Remember, however, that if the Gearbox Output Torque exceeds the allowable torque the gearbox is rated for, you can cause damage to the gearbox.

'''Gear Trains'''

Planetary gearboxes use multiple gear sets to achieve large gear reductions. Each gear set makes the gearbox longer, and reduces the efficiency.

==Product Comparison Tables==

{|border=1
|+'''Stepper Motor Product Specifications'''
! Phidgets Product #
! Motor Model Number
! Motor Type (Unipolar/Bipolar)
! Step Angle (deg)
! Holding Torque (g•cm)
! Low-Speed Torque (g•cm)
! Rated Current (A)
! Number of Leads
! Mounting Plate Size
! Shaft Diameter (mm)
! Total Weight (g)
! Motor Length (mm)
! Motor Size/Diameter (mm)
|-
| 3302|| 42BYGHM810 || Hybrid Bipolar || 0.9|| 4800|| 4280|| 2.4 || 4|| NEMA-17|| 5 || 362|| 48 || 42 x 42
|-
| 3303|| 42BYGHW811 || Hybrid Bipolar || 1.8|| 4800|| 4240|| 2.5 || 4|| NEMA-17|| 5 || 332|| 48 || 42 x 42
|-
| 3304|| 39BYGS202 || Hybrid Bipolar || 3.75|| 750|| 590 || 1 || 4|| NEMA-17|| 5 || 171|| 32 || 39 x 39
|-
| 3305|| 39BYG013 || Hybrid Bipolar || 1.8|| 550|| 450 || 0.4 || 4|| NEMA-17|| 5 || 110|| 20 || 39 x 39
|-
| 3314|| PM42L-048-17|| Hybrid Unipolar|| 7.5|| 950 || 710 || 0.28|| 6|| N/A || 3 || 138|| 14.4|| 42
|-
| 3315|| PM25S-048-15|| Hybrid Unipolar|| 7.5|| 140 || 50 || 0.1 || 6|| N/A || 2 || 31 || 15 || 25
|-
| 3316|| PM20L-20-14 || Hybrid Unipolar|| 18 || 50 || 30 || 0.08|| 6|| N/A || 1.5|| 24 || 16.5|| 20
|-
| 3320|| 28STH32 || Hybrid Bipolar || 1.8|| 600 || 520 || 0.67|| 4|| NEMA-11|| 5 || 111|| 32|| 28 x 28
|-
| 3323|| 35STH40 || Hybrid Bipolar || 1.8|| 1400|| 1200|| 1 || 4|| NEMA-14|| 5 || 200|| 40|| 35 x 35
|-
| 3324|| 42STH38 || Hybrid Bipolar || 1.8|| 3600|| 3300|| 1.7 || 4|| NEMA-17|| 5 || 289|| 40|| 42 x 42
|-
| 3330|| 57STH56 || Hybrid Bipolar || 0.9||12000||11200|| 2.8 || 4|| NEMA-23|| 6.4|| 695|| 56|| 56 x 56
|-
| 3331|| 57STH56 || Hybrid Bipolar || 1.8||12600||11000|| 2.8 || 4|| NEMA-23|| 6.4|| 686|| 56|| 56 x 56
|-
| 3335|| 86STH65 || Hybrid Bipolar || 1.8||34000||30000||2 or 4 || 4|| NEMA-34|| 12|| 1800|| 65|| 85 x 85
|-
| 3336|| 86STH156 || Hybrid Bipolar || 1.8||122000||106000||3 or 6 || 4|| NEMA-34|| 16|| 5200|| 156|| 85 x 85
|-
| 3340|| 42STH38 || Hybrid Bipolar || 0.9||3600||3300||1.7 || 4|| NEMA-17|| 5||288|| 40|| 42 x 42
|}

{| border=1
|+'''Gearbox Stepper Motor Product Specifications'''
!Product #
!Motor Model #
!Motor Type
!Step Angle<sup>†</sup> (deg)
!Holding Torque*,<sup>†</sup> (g-cm)
!Low-speed Torque*,<sup>†</sup> (g-cm)
!Rated Current (A)
!# of Leads
!Mounting Plate Size
!Shaft Diameter (mm)
!Total Weight (g)
!Motor Length (mm)
!Gearbox Length (mm)
!Motor Size/Diameter (mm)
!Gear Ratio
!Gearbox Max Torque (g-cm)
!Gearbox Efficiency
!Max Speed<sup>†</sup> (RPM)
|-
| 3310||57BYG630-07AG20||Hybrid Bipolar||0.09||30000||30000||2.8||4||NEMA-23||8||1330||73||38||56x56||20:1||30000||||30
|-
| 3311||42BYGHW811-AG5.18||Hybrid Bipolar||0.35||24860||17790||2.5||4||NEMA-17||8||513||48||31||42x42||5.18:1||30000||0.9||115
|-
| 3312||42BYGHW811-AG26.8||Hybrid Bipolar||0.07||40000||40000||2.5||4||NEMA-17||8||526||48||39||42x42||26.8:1||40000||0.81||22
|-
| 3313||42BYGHW811-AG99.5||Hybrid Bipolar||0.02||50000||50000||2.5||4||NEMA-17||8||610||48||47||42x42||99.5:1||50000||0.73||6
|-
| 3317||42BYGH40(M)-160-4A||Hybrid Bipolar||0.35||16780||12000||1.6||4||NEMA-17||8||464||40||30||42x42||5.18:1||20000||0.9||115
|-
| 3318||42BYGH40(M)-160-4A||Hybrid Bipolar||0.07||30000||30000||1.6||4||NEMA-17||8||464||40||38||42x42||26.8:1||30000||0.8||22
|-
| 3319||42BYGH40(M)-160-4A||Hybrid Bipolar||0.02||40000||40000||1.6||4||NEMA-17||8||464||40||46||42x42||99.5:1||40000||0.7||6
|-
| 3321||28STH32-0674B/28JXS40K27||Hybrid Bipolar||0.067||16100||14000||0.67||4||NEMA-11||6||218||32||40||28x28||27:1||20000|| ||120
|-
| 3322||28STH32-0674B/28JXS40K100||Hybrid Bipolar||0.018||32000||32000||0.67||4||NEMA-11||6||243||32||49||28x28||100:1||32000|| ||35
|-
| 3325||42STH38-1684B/36JXS60K5.18||Hybrid Bipolar||0.35||18000||18000||1.7||4||NEMA-17||8||457||40||31||42x42||5.18:1||18000|| ||904
|-
| 3326||42STH38-1684B/36JXS60K14||Hybrid Bipolar||0.13||30000||30000||1.7||4||NEMA-17||8||502||40||39||42x42||14:1||30000|| ||295
|-
| 3327||42STH38-1684B/36JXS60K26||Hybrid Bipolar||0.067||30000||30000||1.7||4||NEMA-17||8||503||40||39||42x42||26.85:1||30000|| ||174
|-
| 3328||42STH38-1684B/36JXS60K51||Hybrid Bipolar||0.035||48000||48000||1.7||4||NEMA-17||8||564||40||48||42x42||51:1||48000|| ||63
|-
| 3329||42STH38-1684B/36JXS60K99.51||Hybrid Bipolar||0.018||48000||48000||1.7||4||NEMA-17||8||564||40||48||42x42||100:1||48000|| ||34
|-
| 3332||57STH56-2804B/56JXS300K4.25||Hybrid Bipolar||0.42||53000||46600||2.8||4||NEMA-23||12||1200||56||48||57x57||4.25:1||90000|| ||375
|-
| 3333||57STH56-2804B/56JXS300K15||Hybrid Bipolar||0.12||150000||150000||2.8||4||NEMA-23||12||1300||56||61||57x57||15:1||150000|| || 116
|-
| 3334||57STH56-2804B/56JXS300K77||Hybrid Bipolar||0.023||240000||240000||2.8||4||NEMA-23||12||1500||56||72||57x57||77:1||240000|| ||25
|}

<sup>†</sup>Step angle, torque values, and max speed are all measured at the output of the gearbox.

<nowiki>*</nowiki>Holding torque and low speed torque for gearbox motors are limited by the max torque that the gearbox is rated to sustain.
<nowiki>*</nowiki>

==Glossary of Terms==

===Motor Terms===

'''Coil Resistance'''

The electrical resistance (to direct current) of the wiring within the motor. This resistance causes some of the energy being applied to the motor to be converted into heat. Some motors and motor controllers rely solely on the electrical resistance to regulate the current flowing through the motor. The Unipolar Motors we sell, and the 1062 PhidgetStepper Unipolar rely on this inexpensive, but inefficient technique. Other motors will have very low resistance, increasing their efficiency, but requiring very sophisticated control techniques because the resistance cannot regulate the current to a safe level on its own. Our Bipolar controllers and our Bipolar motors use this technique, otherwise known as Chopper Drive.

'''Holding Torque'''

Holding Torque is the amount of torque needed to rotate the shaft of the stepper motor while the controller attempts to hold the position, using the maximum current allowed for the motor. Holding Torque is the sum of the magnetic force exerted by the electrical coils to hold the current position, and the detent torque, which is the natural resistance of the motor against rotation due to the permanent magnet inside the motor. Once the motor begins to rotate, the torque it can exert (at least at low speeds) is Holding Torque minus twice the detent torque (because the motor is now working against the detent). As the motor speed increases, torque begins to decrease. If the power supply voltage is low, or the inductance of the motor is high, the torque will fall more rapidly.

'''Motor Inductance'''

Stepper motors are built with a specific coil inductance. A high inductance motor will provide a greater amount of torque at low speeds, at the cost of having lower torque at high speeds.

'''Overhung Load (OHL) / Radial Load'''

An external load applied on the output shaft of the gearbox. This load is often produced if pulleys are mounted directly on the shaft, pulling perpendicular to it. When the OHL exceeds a safe value, the bearings can fail, or the shaft can break from bending fatigue. While OHL and Thrust Load specifications are only available for our gearbox motors, both types of load should be avoided when using any of our motors.

'''Rated Current'''

The rated current is the maximum current that should be applied to each coil of the motor. Current generates heat within the motor, and exceeding the regulated current will cause the motor to overheat. If the motor is operated in a hot environment, or is enclosed, it can overheat at currents lower than the rated current.

'''Step Angle'''

The change in the shaft angle when the motor moves forward or backward by one full step.

'''Step Accuracy'''

Depending on the motor and how it is loaded down, the step positions will vary slightly. Fortunately, this variance doesn’t accumulate – so if you move the motor by one step or one million steps, the angle that the motor stops at will have the same margin of error.

'''Thrust load / Axial Load'''

A load applied directly in line with the output shaft of the gearbox. Avoid thrust as much as possible. If thrust load is unavoidable, keep it to no more than the permissible value.

Stepper Motor and Controller Primer

2017-09-18T17:15:46Z

Patrick:

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| [[Image:3302.jpg|link=]]
| [[Image:1063.jpg|link=]]
|}

<br clear="all" />

==Introduction==
Stepper motors are broadly available motors commonly used for positioning. The rotor of a stepper moves in a series of discrete steps. By energizing the coils of the motor in sequence through many of these steps, the direction of rotation, number of rotations, and exact position of the motor shaft can be easily controlled. By controlling the time between the steps, the speed and acceleration of the stepper is regulated. In contrast, a DC motor will blindly spin at the highest speed possible when powered, unless it is controlled with an [[Encoder Primer|Encoder]] and a control system program. It is not necessary to use an encoder on a stepper motor unless you're concerned about the motor losing count of the steps over a long period of time or in high torque situations.

Each stepper motor is designed to move by a certain angle with each discrete step. The simplest stepper motors will rotate 90 degrees per step. Standard industrial steppers will rotate 1.8 degrees per step. The stepping angle can be further reduced through use of a gearbox.

In addition to the ease of precisely controlling position and speed, Steppers have other advantages:

*Most motors have very little torque when they are operating at low speed or standstill. Since a stepper’s rotor is held in place by a magnetic field during each step, steppers have full torque at low speed or standstill, making them very useful for low speed rotation and actuation. Additionally, a stepper motor can remain in a fixed position for long periods of time with the rated current in the windings, whereas with DC motors, stalling and remaining in a fixed position for long periods of time will cause motor burnout.
*DC Motors have brushes with a finite lifetime. Steppers have no brushes, and are limited only by the life of the bearings.

Compared to DC Motors, there are disadvantages to Steppers:

*Each step will produce vibration in the motor. If these vibrations are at the mechanical resonant frequency of the motor, they can cause the rotor to overshoot and bounce back and forth, resulting in a severe loss of torque. This phenomenon is called “ringing” and is often accompanied by a loud buzzing or grinding noise. To prevent the motor from operating in such a way, you should test the motor at various speeds in the physical application it is intended for, and try to avoid running the motor at a speed which exhibits ringing behaviour.
*If the motor encounters a brief overload, the fixed coils on the stator and the free-spinning rotor can lose track of each other. If this happens at higher speeds, the motor will often stall. Even at lower speeds, your system will have lost track of where exactly the motor is positioned – unless there is an independent system (e.g., an optical encoder) tracking the position.
*A Stepper motor cannot be loaded at its maximum torque, as it will almost certainly be overloaded during operation. A DC Motor will naturally adjust its speed depending on how much power is provided, and the torque required to turn it’s shaft.

For more information about the differences between stepper motors, DC motors, and servo motors, see the [[Motor Selection Guide]].

==Types of Stepper Motors==

We find it useful to classify motors according to how the coils are wound (Bipolar / Unipolar), the internal magnetic construction (Permanent Magnet / Hybrid), and how the current in the coils is regulated (Chopper Drive / Resistive Limited).

===Coils===
=====Bipolar=====
These motors are manufactured with two coils of wire, resulting in one winding per phase. By alternating the power between coils, as well as the direction of the current, the motor is rotated. This configuration produces magnetic fields within the coils in either direction, hence the term “Bipolar.” The controller is more expensive because it has to be able to produce both positive and negative electrical currents, but the advantage is that the entire coil is being used, thus increasing torque capabilities at all speeds. We do not recommend using a bipolar controller to run a unipolar motor, even though it is theoretically possible.

=====Unipolar=====
In a unipolar motor, the motor windings consist of two identical coils per phase, wound in opposite directions (each occupying half of the space a coil normally would in a bipolar stepper). As a result, the controller only needs to select which of the two coils to pass current through in order to change the magnetic polarity, and only a positive current is required to be generated. Due to this simplified control mechanism which uses only half of each coil, the torque of unipolar motors are usually much lower, but the overall cost of the system is much cheaper. The simplicity of the unipolar controller also means that you cannot use it to run a bipolar stepper motor.

===Magnets===
=====Permanent Magnet=====
Permanent magnet motors are small, low torque, and inexpensive. They use a permanent magnet in the rotor that is attracted or repelled by magnetic field generated by the stator coils. Step angles are often 7.5 or 15 degrees, and the motors are usually unipolar.

=====Variable Reluctance=====
The rotor of a variable reluctance stepper is made of iron, and it therefore aligns with the magnetic field generated by the stator coils. Since it doesn’t use a permanent magnet, it doesn’t matter which direction the current flows as long as each coil is wound in the opposite direction as the coil across from it. Therefore, variable reluctance steppers are unipolar and are typically designed to have larger step angles of 15 or more degrees.

=====Hybrid=====
Hybrid Motors dominate the stepper motor world – they use a combination of characteristics from permanent magnet and variable reluctance steppers and have the best torque and speed, but are more expensive to produce. Step angles are typically 0.9 to 3.75 degrees, giving much better step resolution.

===Drive===
=====Chopper Drive=====
Chopper Drive is an electronic control technique which allows specific motors to produce more power, torque, speed, and be more efficient. Instead of relying on the resistance of the coil wiring, the inductance of the wiring is exploited by sophisticated control electronics as a short-term limitation of motor current. Motor Manufacturers don’t do a good job of distinguishing motors suitable for use with Chopper Drive electronics. The motors will often be large, square, with very low resistance.
=====Resistive Limited=====
Small, inexpensive steppers are designed to be built and controlled as cheaply as possible. To simplify the control electronics, the length and thickness of the wire in the coils is selected for a particular control voltage. This allows the coil itself to regulate the power available to the motor – provided the appropriate voltage is used, of course. We call this type of motor Resistive Limited.

==How it Works==

[[Image:Stepper_back_web.jpg|left|link=|thumb|230px|Cross-Section of a Hybrid Bipolar Stepper<br />[[Media:Stepper_back_web.jpg|Full-size Image]]]]

===Hybrid Bipolar Steppers===
This section of the primer will cover the general principle of operation for stepper motors. While this information is by no means necessary to use a stepper motor, those who are curious about their inner workings may read on.

The thumbnail to the left is a cross-sectional view of the inside of a hybrid bipolar stepper motor. As you can see, it has eight poles with six teeth each. This motor contains two coils- one wrapping the odd-numbered poles, and the other wrapping the even-numbered poles. The steel end-cap in the center of the image covers a cylindrical permanent magnet which surrounds the shaft.

If positive current is sent to the odd-numbered coil, poles 1 and 5 are magnetized as south, and poles 3 and 7 are magnetized as north. Assuming the permanent magnet in the center of the motor has its north pole facing toward us, this will result in the rotor turning so that the teeth line up with stator poles 1 and 5, as they are in the image. At the same time, poles 3 and 7 will become aligned on the opposite end of the motor, where the gear on the rotor is permanently offset by the width of one tooth and the permanent magnet has magnetized the rotor as south. The rotation of the motor is continued by sending negative current through the even-numbered phase, then negative current through the odd-numbered phase, then positive current through the even-numbered phase, and so on. The stepper controller can reverse the direction of rotation simply by reversing this sequence.

When a stepper motor becomes engaged in software, and current is applied to the coils, it may abruptly "snap" to the position that the rotor is being held at.

<br clear="all">

===Hybrid Unipolar Steppers===
The operation of a hybrid unipolar stepper is very similar to the bipolar stepper described above, except that each pole has two seperate coils wound in opposite directions. This results in four phases which only require positive current to operate. Rather than alternating the direction of current, the motor controller simply sends positive current to the appropriate half of the coil.

==Controlling the Stepper Motor==

The following information has been derived from using the 3308 stepper motor connected to a 1063 - PhidgetStepper Bipolar 1-Motor controller.
===Setting the Current Limit===

[[Image:Graph12v.jpg|border|400px|link=|thumb|The current/speed characteristics for the 3308 at 12V.<br />[[Media:Graph12v.jpg|Full-size Image]]]]

[[Image:Graph24v.jpg|border|400px|link=|thumb|The current/speed characteristics for the 3308 at 24V.<br />[[Media:Graph24v.jpg|Full-size Image]]]]

[[Image:Graph30v.jpg|border|400px|link=|thumb|The current/speed characteristics for the 3308 at 30V.<br />[[Media:Graph30v.jpg|Full-size Image]]]]

The current limit is an important control property of stepper controllers. Since many stepper motors have a very low coil resistance, the current through the coils cannot “self-regulate” to a safe level on their own. They require the sophisticated control techniques of a Chopper Drive, which is used in the [{{SERVER}}/products.php?product_id=1063 1063 PhidgetStepper] controller. As a result, the maximum current allowed should be explicitly set.

There are many factors that influence what the current limit should be set to. These include, but are not limited to,the acceleration and speed of the stepper, the supply voltage, applied torque, motor inductance, and coil resistance. The process of choosing the current limit can be simplified by following some general rules of thumb. The graphs in this section show a set of speed vs. current characteristics for the 3308 stepper with various power supplies.

In the these graphs, the '''“actual speed”''' of the motor is the maximum speed attainable in a real world test done with no load on the motor, but at very high acceleration. The '''“max speed”''' shows the limitation on speed imposed by the inductance of the motor coils at a given supply voltage. Given that the 1063 controller is only able to run at a maximum speed of 2048 full steps per second, our graphs don’t show data at higher speeds.

When the current limit is set low and the acceleration is high, the motor will not be able to provide enough power to accelerate itself and the load it’s driving. The motor also has to overcome friction losses within the system, and do work on the load - for example, lifting a weight. By increasing the current limit, more current and power is made available to accelerate and maintain maximum speeds. This can be seen on any of the graphs in the initial steep ramp of the actual speed. As the current limit increases, the motor is able to achieve higher speeds.

In the case of this particular motor, the large inductance of the coils - great for producing lots of torque, quickly overwhelms a 12V power supply. To get higher speeds and more performance out of this motor, higher supply voltages are necessary. Compare the actual speed curve on the 12V graph to the 30V graph. At 30V, the motor is able to achieve a much higher speed. It’s important to remember that the actual speed was measured at very high accelerations - by lowering acceleration, higher velocities can be achieved. Of course, if your motor is doing a lot of work, you’ll need to supply enough current to produce the necessary torque, therefore limiting the maximum speed.

Setting Current Limit for your application is a balancing act. By increasing the current limit, more torque is available, but far more power will be consumed when the motor is turning very slowly or stopped. When setting a high acceleration, more power (therefore current) is required to accelerate the motor and it’s load. Selecting the current limit is often done dynamically in the actual application - set the current limit very low, and run the system, increasing the Current Limit if it stalls. After a set up has been determined that is reliable, increase the current limit by another 25% to give some margin.

There is no point in setting the current limit to be greater than the motor’s rated current- the increased inductance will only further limit the motor speed. In this case, the 30V graph shows that it’s not feasible to operate this motor at maximum torque (1.7 Amps) at a speed greater than 1100 full steps per second. By reducing the current limit, greater speeds are possible, but less torque will be available. Most motors designed for Chopper Drive control can operate at much higher voltages, but Phidgets Inc. does not carry a controller that can provide these voltages at this time.

Note that just because you have set the current limit to some amount (for the sake of example let's say 2A) the motor will not draw 2A at all times. The motor will only draw as much current as it needs. This means that if there is only a small load on the motor and it is spinning at less than its top speed the motor might only draw a small fraction of the allotted 2A. Even as low as 300 or 400mA. As more load or higher speed is applied, the current usage will go up until the controller is giving the motor the full current limit. As a motor draws more current, it will also produce more heat. It is normal for a stepper motor to be hot to the touch after running for a while. If the motor is getting very hot, you may be trying to drive too large a load for that particular motor.

===Choosing a Supply Voltage===

When looking at a stepper motor's specifications, you may come across a "Rated Voltage" value. This value is usually equal to the rated current multiplied by the resistance of the coils of the motor, making it somewhat of a redundant specification. As mentioned earlier, you can increase your controller's supply voltage in order to allow the motor to reach higher speeds at a lower current (because high current causes high inductance which puts a hard limit on how much speed and torque a motor can produce). The motor will also produce more heat as you increase the supply voltage, so it's a good idea to choose a supply voltage based on the performance you need for the motor. Some motors will have a "Recommended Voltage" for a particular controller, which is the amount of voltage needed to reach the optimal speed and torque of the motor with minimal heating.

===Setting the Velocity Limit===

The velocity of a motor cannot be directly chosen with our stepper controllers. However, a velocity limit can be chosen to ensure that the motor does not go faster than a certain speed. This is useful because every stepper motor has a speed that causes itself to vibrate at the resonant frequency of its own moving parts. When the motor vibrates at this frequency, the motor will often overshoot its target position, causing it to lose most of its torque, sometimes even rotating in the wrong direction. This phenomenon is sometimes called "ringing". If you experience these problems while running your stepper motor at a constant velocity, try setting the velocity limit to lower or higher than it was previously, in an attempt to minimize the amount of time spent operating at this particular velocity.

===Setting the Acceleration===
The acceleration of a stepper motor is an important consideration when driving a load. Setting the acceleration too high can result in the motor stalling, especially with a heavy load. Try to use low acceleration in high-torque applications.

===Continuous Rotation and Forward/Reverse===

A stepper motor can be caused to rotate continuously by simply setting the controller's target position property to an extremely large number of steps.

Stepper motors can easily be run in forward or reverse by choosing a target position greater than or less than the current position, respectively. Reversing the polarity of either of the motor's wire pairs will invert this effect- causing a lesser target position to result in forward rotation, and a greater target position to result in reverse rotation. For this reason, you should pay attention to the way you wire a motor when developing and testing code, and ensure that you wire it with the same polarity in the future to avoid erroneous behaviour in applications where rotation direction matters.

===Cooling===
The stepper controllers sold at Phidgets Inc. have a current rating that is limited by the heat dissipation capability of the board. You could add heatsinks, fans, or other cooling devices to increase the current limit, but do so with caution. Unless you have a way of monitoring the temperature of the driver chip during operation, you have no way of knowing how far beyond the rated specification you can go.

===Wire Length===

Since the stepper controller is sending a fairly simple signal to the motor, interference is not a big concern. You should be able to have quite long wires between your motor and controller. For more information, see the [[Effects_of_Long_Wires|effects of long wires]] page.

===Saving Power===

When the stepper motor has rotated the requested number of steps, and is stopped, the coils will remain energized to hold it in position. This is necessary to allow the motor to support a load on its shaft without rotating to an unknown position.

'''Holding torque''' is the amount of torque required to rotate the motor ‘against it’s will’ when the full rated current is flowing through the coils. If power consumption or overheating is a problem, and full holding torque is not required, the Current Limit can be decreased in software when the motor is not moving. Holding torque will decrease linearly as you decrease the Current Limit, but will also allow you to save power and reduce the heat generated in your system.

There is also a small resistance to movement within the motor even when there is no current, called '''Detent Torque'''. This may be sufficient to prevent rotation in your application, especially if the stepper has a gearbox on it.

If the motor is not supporting a load or is not required to maintain a specific angle, it is recommended to set the Enable property to false. This will allow the motor shaft to rotate freely, but the present angle may be lost if forces on the motor-shaft are greater than can be resisted by the detent torque of the unpowered motor.

<br clear=all>

===Braking===

There are several ways to stop a stepper motor, each with different characteristics:

'''Set Target Position''' - If you set the target position to the motor's current position, it will stop. This is typically the best way to stop quickly and hold position, since the motor coils will still be engaged. You could also set the motor velocity limit to zero for a similar effect.

'''Short the coils''' - If you have the stepper wires connected to some external circuitry, you could use a switch to short the A and B terminals together, and the C and D terminals together. Due to the [http://en.wikipedia.org/wiki/Lorentz_force Lorentz force] of the electrons in the coil, the motor will begin to brake and hold position.

'''Cut power''' - You could cut power to the controller, but since the motor coils would no longer be engaged, the momentum would cause it to continue rotating until it slows down from friction and detent.

==Stepping Modes==

===Full Stepping===
This is the default mode of stepping for bipolar motors, where both phases of the motor are controlled by two square waves of current. One wave lags behind the other by 90 degrees, and the motion of the motor is locked to these waves. A full step is completed when the square waves advance by 90 degrees. Since both phases are always fully energized, full stepping provides the best torque.

===Half Stepping===
In this stepping mode, the controller alternates between having one phase energized and both phases energized. This results in the rotor pausing at half-steps in between the poles, effectively halving the step angle. However, since the current to each coil cannot be exactly balanced, the angle that the rotor comes to rest at between poles may not be exactly half the step angle. The downside to half stepping is that the motor will have less torque on the steps when only one phase is energized.

===Mini/Micro-stepping===
By controlling the the relative current of both phases, the rotor position can come to rest at various equally spaced sub-steps between the two phases. This is achieved by following the same procedure for Full Stepping, except that the current supplied more closely resembles a sine wave rather than a square wave. Some bipolar controllers are designed to micro-step at low speeds to allow for smooth rotation.

==Selecting a Gearbox==

Using a stepper motor with a gearbox can be a good solution in applications that need very low rotation speeds and/or lots of torque. Selecting a gearbox to attach to the stepper will result in increasing the output torque and decreasing the speed.
Simply, the Gearbox Output Speed is:

<math>
\text{Output Speed} =\frac{\text{Motor Speed}}{\text{Gearbox Ratio}}
</math>

Although the reduction ratio plays a large part in determining the Gearbox Output Torque, there is also an inefficiency that is introduced through the use of a gearbox. Some of the torque of the motor is internally converted into heat and lost. So to calculate the Gearbox Output Torque:

<math>
\text{Output Torque} = \text{Motor Output Torque } \times \text{ Gearbox Ratio } \times \text{ Gearbox Efficiency}
</math>

When choosing a stepper motor with a gearbox, keep in mind that the gearbox is rated to sustain a specific amount of torque, beyond which the gearbox could become damaged. This limit is often much lower than the amount of torque specified by the above equation.

The Gearbox Step Angle can be determined by:

<math>
\text{Gearbox Step Angle} = \frac{\text{Motor Step Angle}}{\text{Gearbox Ratio}}
</math>

===Planetary Gearbox Reduction Ratios===

[[File:Planetary_gearing.jpg|thumb|300px|link=|This diagram illustrates the parts of a 5.18:1 planetary gearbox.<br>[/docs21/images/1/1a/Planetary_gearing.jpg Click for Larger Image]]]

In some applications, it is important to know the exact gear ratio of a gearbox (for example, when you need the output shaft to make a several complete rotations
and stop in the same position it started). Most motor datasheets will only list an approximate ratio, like "10:1" or "27:1". However, there are ways to figure out
the exact ratio.

In a planetary gearbox where the sun gear is used as an input and the rotation of the spider linking the planet gears is the output, the reduction ratio can be
expressed by the following equation:

<math>
\text{Gearbox Ratio} = \frac{T_R + T_S}{T_S}
</math>

Where <math>T_R</math> is the number of teeth on the ring gear, and <math>T_S</math> is the number of teeth on the sun gear. In this situation, the number of teeth on the planetary gears
don't affect the reduction ratio and serve only to connect the ring and sun gears. In order to increase the reduction ratio, you need to increase the number of
teeth on the ring gear. Since there is limited space inside a motor's gearbox, it eventually becomes impossible to increase the gear ratio. This limitation can be
bypassed by introducing multiple gear '''stages'''. In a multi-stage planetary gearbox, the axles of the planet gears of the first stage are connected to a piece
of metal called a "spider", whose rotation is used to turn the sun of the next stage. It's very common for multi-stage planetary gearboxes to have a tall ring
gear that spans multiple stages. To determine the overall reduction ratio of a multi-stage planetary gearbox, simply multiply the two ratios together. For
example, two stages each with a 5:1 reduction ratio would result in a total ratio of 25:1.
The following table lists exact ratios for gearboxes commonly sold at Phidgets Inc. :

[[File:Gearbox_table.jpg|link=]]

The colored squares visualize the stages that compose each gearbox. For example, a two-stage gearbox with 1 blue and 1 green square indicates that one stage is
the same ratio as the 1-stage gearbox with the green square beside it, and the other stage is the same as the one with a blue square beside it.
If you have a third party gearbox and are unable to open it to count the gear teeth, you could also determine the approximate reduction ratio experimentally by
measuring the rotation angle after a known number of steps have occured. The more accurately you can measure the angle, the better your approximation will be.

===Gearbox Terminology===

Here is a short list of terms you might come across when deciding upon a gearbox:

'''Backlash'''

The amount of clearance between mated gear teeth. Theoretically, the backlash should be “the smaller the better,” but in actual practice, some backlash must be allowed to prevent jamming.

'''Gear Ratio'''

The gearbox accepts the power (think of power as a torque that rotates) from the motor, reducing the speed (exactly) by a given ratio, while increasing the torque (roughly) by the same ratio – a ratio of the gear head with which the gear head reduces the motor speed. For example, if a motor has a speed of 500RPM and the reduction ratio is 100:1, the speed of the gear head is 500/100 = 5RPM. This is the actual reduction ratio. The calculated speed from the gear head should be based on this ratio.

'''Gearbox Step Angle'''

A full step of the motor will result in the gearbox making a smaller step. The angle of this step is the step angle of the motor divided by the gearbox reduction ratio. For example, a motor with a step angle of 1.8º and a gearbox with a reduction ratio of 20:1 will have a step angle of 1.8/20 = 0.09º at the output of the gearbox.

'''Gearbox Output Torque'''

The gearbox takes the torque from the output shaft of the motor, reducing the speed and increasing the torque. The gearbox, depending on its efficiency, loses some of the torque as it is converted into heat. Therefore, the Gearbox Output Torque is the motor output torque multiplied by the reduction ratio multiplied by the efficiency of the gearbox. For example, a motor with a low-speed output torque of 500g*cm and a gearbox with a reduction ratio of 5:1 and 90% efficiency will have a Gearbox Output Torque of 500*5*0.9 = 2.25 kg*cm. Remember, however, that if the Gearbox Output Torque exceeds the allowable torque the gearbox is rated for, you can cause damage to the gearbox.

'''Gear Trains'''

Planetary gearboxes use multiple gear sets to achieve large gear reductions. Each gear set makes the gearbox longer, and reduces the efficiency.

==Product Comparison Tables==

{|border=1
|+'''Stepper Motor Product Specifications'''
! Phidgets Product #
! Motor Model Number
! Motor Type (Unipolar/Bipolar)
! Step Angle (deg)
! Holding Torque (g•cm)
! Low-Speed Torque (g•cm)
! Rated Current (A)
! Number of Leads
! Mounting Plate Size
! Shaft Diameter (mm)
! Total Weight (g)
! Motor Length (mm)
! Motor Size/Diameter (mm)
|-
| 3302|| 42BYGHM810 || Hybrid Bipolar || 0.9|| 4800|| 4280|| 2.4 || 4|| NEMA-17|| 5 || 362|| 48 || 42 x 42
|-
| 3303|| 42BYGHW811 || Hybrid Bipolar || 1.8|| 4800|| 4240|| 2.5 || 4|| NEMA-17|| 5 || 332|| 48 || 42 x 42
|-
| 3304|| 39BYGS202 || Hybrid Bipolar || 3.75|| 750|| 590 || 1 || 4|| NEMA-17|| 5 || 171|| 32 || 39 x 39
|-
| 3305|| 39BYG013 || Hybrid Bipolar || 1.8|| 550|| 450 || 0.4 || 4|| NEMA-17|| 5 || 110|| 20 || 39 x 39
|-
| 3314|| PM42L-048-17|| Hybrid Unipolar|| 7.5|| 950 || 710 || 0.28|| 6|| N/A || 3 || 138|| 14.4|| 42
|-
| 3315|| PM25S-048-15|| Hybrid Unipolar|| 7.5|| 140 || 50 || 0.1 || 6|| N/A || 2 || 31 || 15 || 25
|-
| 3316|| PM20L-20-14 || Hybrid Unipolar|| 18 || 50 || 30 || 0.08|| 6|| N/A || 1.5|| 24 || 16.5|| 20
|-
| 3320|| 28STH32 || Hybrid Bipolar || 1.8|| 600 || 520 || 0.67|| 4|| NEMA-11|| 5 || 111|| 32|| 28 x 28
|-
| 3323|| 35STH40 || Hybrid Bipolar || 1.8|| 1400|| 1200|| 1 || 4|| NEMA-14|| 5 || 200|| 40|| 35 x 35
|-
| 3324|| 42STH38 || Hybrid Bipolar || 1.8|| 3600|| 3300|| 1.7 || 4|| NEMA-17|| 5 || 289|| 40|| 42 x 42
|-
| 3330|| 57STH56 || Hybrid Bipolar || 0.9||12000||11200|| 2.8 || 4|| NEMA-23|| 6.4|| 695|| 56|| 56 x 56
|-
| 3331|| 57STH56 || Hybrid Bipolar || 1.8||12600||11000|| 2.8 || 4|| NEMA-23|| 6.4|| 686|| 56|| 56 x 56
|-
| 3335|| 86STH65 || Hybrid Bipolar || 1.8||34000||30000||2 or 4 || 4|| NEMA-34|| 12|| 1800|| 65|| 85 x 85
|-
| 3336|| 86STH156 || Hybrid Bipolar || 1.8||122000||106000||3 or 6 || 4|| NEMA-34|| 16|| 5200|| 156|| 85 x 85
|-
| 3340|| 42STH38 || Hybrid Bipolar || 0.9||3600||3300||1.7 || 4|| NEMA-17|| 5||288|| 40|| 42 x 42
|}

{| border=1
|+'''Gearbox Stepper Motor Product Specifications'''
!Product #
!Motor Model #
!Motor Type
!Step Angle<sup>†</sup> (deg)
!Holding Torque*,<sup>†</sup> (g-cm)
!Low-speed Torque*,<sup>†</sup> (g-cm)
!Rated Current (A)
!# of Leads
!Mounting Plate Size
!Shaft Diameter (mm)
!Total Weight (g)
!Motor Length (mm)
!Gearbox Length (mm)
!Motor Size/Diameter (mm)
!Gear Ratio
!Gearbox Max Torque (g-cm)
!Gearbox Efficiency
!Max Speed<sup>†</sup> (RPM)
|-
| 3310||57BYG630-07AG20||Hybrid Bipolar||0.09||30000||30000||2.8||4||NEMA-23||8||1330||73||38||56x56||20:1||30000||||30
|-
| 3311||42BYGHW811-AG5.18||Hybrid Bipolar||0.35||24860||17790||2.5||4||NEMA-17||8||513||48||31||42x42||5.18:1||30000||0.9||115
|-
| 3312||42BYGHW811-AG26.8||Hybrid Bipolar||0.07||40000||40000||2.5||4||NEMA-17||8||526||48||39||42x42||26.8:1||40000||0.81||22
|-
| 3313||42BYGHW811-AG99.5||Hybrid Bipolar||0.02||50000||50000||2.5||4||NEMA-17||8||610||48||47||42x42||99.5:1||50000||0.73||6
|-
| 3317||42BYGH40(M)-160-4A||Hybrid Bipolar||0.35||16780||12000||1.6||4||NEMA-17||8||464||40||30||42x42||5.18:1||20000||0.9||115
|-
| 3318||42BYGH40(M)-160-4A||Hybrid Bipolar||0.07||30000||30000||1.6||4||NEMA-17||8||464||40||38||42x42||26.8:1||30000||0.8||22
|-
| 3319||42BYGH40(M)-160-4A||Hybrid Bipolar||0.02||40000||40000||1.6||4||NEMA-17||8||464||40||46||42x42||99.5:1||40000||0.7||6
|-
| 3321||28STH32-0674B/28JXS40K27||Hybrid Bipolar||0.067||16100||14000||0.67||4||NEMA-11||6||218||32||40||28x28||27:1||20000|| ||120
|-
| 3322||28STH32-0674B/28JXS40K100||Hybrid Bipolar||0.018||32000||32000||0.67||4||NEMA-11||6||243||32||49||28x28||100:1||32000|| ||35
|-
| 3325||42STH38-1684B/36JXS60K5.18||Hybrid Bipolar||0.35||18000||18000||1.7||4||NEMA-17||8||457||40||31||42x42||5.18:1||18000|| ||904
|-
| 3326||42STH38-1684B/36JXS60K14||Hybrid Bipolar||0.13||30000||30000||1.7||4||NEMA-17||8||502||40||39||42x42||14:1||30000|| ||295
|-
| 3327||42STH38-1684B/36JXS60K26||Hybrid Bipolar||0.067||30000||30000||1.7||4||NEMA-17||8||503||40||39||42x42||26.85:1||30000|| ||174
|-
| 3328||42STH38-1684B/36JXS60K51||Hybrid Bipolar||0.035||48000||48000||1.7||4||NEMA-17||8||564||40||48||42x42||51:1||48000|| ||63
|-
| 3329||42STH38-1684B/36JXS60K99.51||Hybrid Bipolar||0.018||48000||48000||1.7||4||NEMA-17||8||564||40||48||42x42||100:1||48000|| ||34
|-
| 3332||57STH56-2804B/56JXS300K4.25||Hybrid Bipolar||0.42||53000||46600||2.8||4||NEMA-23||12||1200||56||48||57x57||4.25:1||90000|| ||375
|-
| 3333||57STH56-2804B/56JXS300K15||Hybrid Bipolar||0.12||150000||150000||2.8||4||NEMA-23||12||1300||56||61||57x57||15:1||150000|| || 116
|-
| 3334||57STH56-2804B/56JXS300K77||Hybrid Bipolar||0.023||240000||240000||2.8||4||NEMA-23||12||1500||56||72||57x57||77:1||240000|| ||25
|}

<sup>†</sup>Step angle, torque values, and max speed are all measured at the output of the gearbox.

<nowiki>*</nowiki>Holding torque and low speed torque for gearbox motors are limited by the max torque that the gearbox is rated to sustain.
<nowiki>*</nowiki>

==Glossary of Terms==

===Motor Terms===

'''Coil Resistance'''

The electrical resistance (to direct current) of the wiring within the motor. This resistance causes some of the energy being applied to the motor to be converted into heat. Some motors and motor controllers rely solely on the electrical resistance to regulate the current flowing through the motor. The Unipolar Motors we sell, and the 1062 PhidgetStepper Unipolar rely on this inexpensive, but inefficient technique. Other motors will have very low resistance, increasing their efficiency, but requiring very sophisticated control techniques because the resistance cannot regulate the current to a safe level on its own. Our Bipolar controllers and our Bipolar motors use this technique, otherwise known as Chopper Drive.

'''Holding Torque'''

Holding Torque is the amount of torque needed to rotate the shaft of the stepper motor while the controller attempts to hold the position, using the maximum current allowed for the motor. Holding Torque is the sum of the magnetic force exerted by the electrical coils to hold the current position, and the detent torque, which is the natural resistance of the motor against rotation due to the permanent magnet inside the motor. Once the motor begins to rotate, the torque it can exert (at least at low speeds) is Holding Torque minus twice the detent torque (because the motor is now working against the detent). As the motor speed increases, torque begins to decrease. If the power supply voltage is low, or the inductance of the motor is high, the torque will fall more rapidly.

'''Motor Inductance'''

Stepper motors are built with a specific coil inductance. A high inductance motor will provide a greater amount of torque at low speeds, at the cost of having lower torque at high speeds.

'''Overhung Load (OHL) / Radial Load'''

An external load applied on the output shaft of the gearbox. This load is often produced if pulleys are mounted directly on the shaft, pulling perpendicular to it. When the OHL exceeds a safe value, the bearings can fail, or the shaft can break from bending fatigue. While OHL and Thrust Load specifications are only available for our gearbox motors, both types of load should be avoided when using any of our motors.

'''Rated Current'''

The rated current is the maximum current that should be applied to each coil of the motor. Current generates heat within the motor, and exceeding the regulated current will cause the motor to overheat. If the motor is operated in a hot environment, or is enclosed, it can overheat at currents lower than the rated current.

'''Step Angle'''

The change in the shaft angle when the motor moves forward or backward by one full step.

'''Step Accuracy'''

Depending on the motor and how it is loaded down, the step positions will vary slightly. Fortunately, this variance doesn’t accumulate – so if you move the motor by one step or one million steps, the angle that the motor stops at will have the same margin of error.

'''Thrust load / Axial Load'''

A load applied directly in line with the output shaft of the gearbox. Avoid thrust as much as possible. If thrust load is unavoidable, keep it to no more than the permissible value.

Template:UGsbc1

2017-09-18T15:47:00Z

Patrick:

===Basic Use===

Basic use of the PhidgetSBC allows the opening of connected Phidgets over the network. Using another Phidget with the PhidgetSBC in this way is almost exactly like using Phidgets over USB, in respect to the API calls and behavior. However, some extra considerations need to be made when working with the PhidgetWebservice.

===Phidget Webservice===

Support for opening Phidgets over the network is made possible via the Phidget Webservice. This allows a user to write an application in a system and language of their choosing and then operate Phidgets connected to the PhidgetSBC. It is a socket based server that runs on the PhidgetSBC, and allows any attached Phidgets to be seen and opened directly over the network. To use this server go to the "Phidgets->WebService" tab in the web configuration page and enable it.

Opening and controlling a Phidget over the network is nearly the same as opening one locally. The main differences are:

*Different open calls that include server information. New calls OpenRemote and openRemoteIP (naming depends on language).
*Access to Webservice based properties: Server hostname, port and ID.
*Access to server connect and disconnect events, and network error events.
*Phidgets can be opened by more then one separate application at the same time.
*Reliability is more of a issue because network connections are easily broken

Opening a Phidget over the network is asynchronous and pervasive, just like opening locally. This means that if a connection to the remote server cannot be established right away, it will keep trying indefinitely, and even survive the server being stopped and started, etc. Instances of the Phidget Webservice can be referred to either using hostname (IP Address) and port number, or by Server ID. The advantage of using a Server ID is that it stays consistent compared to IP addresses, and you don’t need to know the Port number. A Webservice Server ID is assigned when the Webservice is run - which on the PhidgetSBC defaults to ‘phidgetsbc’. In order to use a Server ID, the Bonjour utility also needs to be installed. Refer to the Programming Manual and the API manual for your language for more information about using the Phidget Webservice.

====Reliability====

Determining reliability needs can become important while opening Phidgets over the network, because the network connection can potentially be interrupted at any time. This can leave the network attached Phidget in an undesirable state. For example - if a motor controller is driving a motor and the connection is lost, there is no way to stop the motor until the connection is re-established. These issues are less important if you are just receiving sensor data from an Interface Kit.

It’s generally a good idea to catch server connect and disconnect and Phidget attach and detach events in order to know the state of the connections. It’s also a good idea to catch error events - this is where network errors will be reported. If reliability is important, you should consider writing a program to run locally on the PhidgetSBC, and communicate with it through the Dictionary interface. This way, if the connection is broken, the local application will notice and be able to take any appropriate actions. See the advanced chapter for more information.

====Finding Phidgets on the Network====

Any Phidgets attached to the PhidgetSBC can be identified using the Status >> Phidgets page in the configuration interface, and should be seen on the network through the Webservice. The Phidget Control Panel has a Bonjour tab (under WebService >> Bonjour) that lists all detected network attached Phidgets. The Phidgets connected to the PhidgetSBC should be seen here and can be opened by double clicking its name in the menu. Network attached Phidgets can also be located programmatically with the Phidget Manager. The Phidget Manager is used with either hostname and port, or server ID, just like with ‘Open’. The manager can also be used to find all Phidgets on any Webservice through Bonjour, by specifying a NULL Server ID. See your specific language’s guide for more information about coding with the Phidget Manager.

===Testing Using Mac OS X===
The steps are very similar to the Windows process described above:
#Ensure you have OS X 10.3.9 or later running.
#Download and run the [{{SERVER}}/downloads/phidget21/libraries/macos/Phidget.dmg Installer] ([{{SERVER}}/Drivers_Info.html#Mac OS software license])
#Click on System Preferences → Phidgets (under Other) to activate the Preference Pane
#Make sure that the Phidget SBC is properly attached to the network as described in the [[#Getting_Started|Getting Started section]]
#Double Click on the Phidget SBC in the Phidget Preference Pane to bring up the Web Interface in your default browser
#Or, click on the Bonjour tab to see attached Phidgets being run over the network and to bring up their examples

The address in the browser that connects to the SBC is either an '''IP address''' (such as 192.168.2.181) or a '''link local address''', (such as {{Code|phidgetsbc.local}}, which is the default). Note down the address in the browser, as you will need this information for later if you will be working [[OS - Phidget SBC|directly with the SBC]] to perform tasks such as writing or running code. But for now, with the web interface open, we have a [[#SBC Web Interface|section to walk you through it]].

===Using Linux===

With Linux, you have many setup options, but all involve knowing the IP address or link local address of the SBC after you have plugged it in as described in [[#Getting_Started|Getting Started section]]. The IP address can be somewhat difficult to obtain, but the default link local address for all new Phidget SBCs is {{Code|phidgetsbc.local}} - which is an mDNS address. Wait at least three minutes after booting the SBC to make sure link local addressing is started. You'll also need some form of mDNS (either {{Code|avahi}} or {{Code|mDNSResponder}}) installed on your main computer. The {{Code|avahi}} service is usually installed by default on most Linux machines, try {{Code|which avahi-resolve}} to make sure. Then, try typing {{Code|phidgetsbc.local}} into a web browser. The [[#SBC Web Interface|web interface]] should come up, starting with the [[#Set the Password|Set the Password]] screen.

Note that some browsers (i.e. Google Chrome) combine search and addressing in the same address bar, so you may need to turn off web service and prediction service in {{Code|Preferences → Under The Bonnet}} for Chrome to treat {{Code|phidgetsbc.local}} like a web address rather than a search term. If these steps do not bring you to the initial setup password screen as shown in the [[#SBC Web Interface|SBC Web Interface section]], you will probably need to read the [[OS - Phidget SBC#Initial Internet Setup|internet setup section on the SBC OS Page]]. That section contains more than just troubleshooting information - it includes in-depth information on how the SBC starts its network, your initial network configuration options, and how to connect to the SBC without mDNS using both DHCP and static IP.

If you want to use the SBC to broadcast data from Phidgets over a network, the SBC is already automatically performing this function with its attached Interface Kit, and will also do so for any Phidgets plugged into its USB ports. If this is your sole intended use of the SBC, you can skip ahead to our example on using the [[#Linux - Attached Interface Kit | attached Interface Kit]].

However, the SBC is much, much more than simply a way to get data from Phidgets over a network. You can use the SBC as an external Linux computer. You'll need to [[#Set the Password|set a password]] using the SBC web interface, and write down a network address of the SBC ({{Code|phidgetsbc.local}}, or an IP address if you worked through the [[OS - Phidget SBC#Initial Internet Setup|internet setup section on the SBC OS Page]]). But after that, if no other sections in the basic [[#SBC Web Interface|SBC web interface]] section apply to you (using the webcam, setting up wireless networking, or checking system parameters like memory), you can skip ahead to the [[OS - Phidget SBC]] page.

====Linux - Attached Interface Kit====

As soon as the SBC boots and can connect to the network (either by DHCP or by mDNS/avahi), it begins broadcasting the state of its attached InterfaceKit over the network using the [[Phidget WebService]]. To test the InterfaceKit on your Linux computer over the network, you will need to install the Phidget libraries and the Phidget webservice if you haven't already. (If you have used any Phidget via USB and over a network on your Linux computer, you have already done this.) This process is described on the general [[OS - Linux|Linux OS]] page, so follow those installation instructions, with the following modifications to the [[OS - Linux#Using the WebService|Linux webservice introduction]]:
* Instead of using a localhost (127.0.0.1) address, use the the SBC's IP or link local ({{Code|phidgetsbc}}) address,
* Instead of using the function call {{Code|openRemoteIP}} in your code, use the function call {{Code|openRemote}}, and the Interface Kit serial number which is on the back of the SBC.

Note that any attached analog sensors in the black ports will not show up over the webservice as individual Phidgets. Rather, they will show up as part of the Interface Kit, through the port number that they are attached to on the SBC board.

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

{{UGce}}

Software License

2017-09-18T15:41:54Z

Patrick:

==Windows==

By downloading the Phidget21.MSI you agree to adhere to the terms of the [{{SERVER}}/documentation/Licenses/Software_Licenses.pdf Phidgets End User License Agreement]. The C API section of Phidget21 is covered by the [{{SERVER}}/documentation/Licenses/Software_Licenses.pdf GNU Lesser General Public License]. The source code of C API can be found [{{SERVER}}/downloads/phidget21/libraries/linux/libphidget.tar.gz here].
==OS X==

By downloading the OS X Framework you agree to adhere to the terms of the [{{SERVER}}/documentation/Licenses/Software_Licenses.pdf Phidgets End User License Agreement]. The C API section of Phidget21 is covered by the [{{SERVER}}/documentation/Licenses/Software_Licenses.pdf GNU Lesser General Public License]. The source code of C API can be found [{{SERVER}}/downloads/phidget21/libraries/linux/libphidget.tar.gz here].

==Linux==

By downloading Linux Source you agree to adhere to the terms of the [{{SERVER}}/documentation/Licenses/Software_Licenses.pdf GNU Lesser General Public License].

==Windows CE==

By downloading the Phidget CE Framework you agree to adhere to the terms of the [{{SERVER}}/documentation/Licenses/Software_Licenses.pdf Phidgets End User License Agreement]. The C API section of Phidget21 is covered by the [{{SERVER}}/documentation/Licenses/Software_Licenses.pdf GNU Lesser General Public License]. The source code of C API can be found [{{SERVER}}/downloads/phidget21/libraries/linux/libphidget.tar.gz here]. The Windows CE Driver is covered by the [{{SERVER}}/documentation/Licenses/Software_Licenses.pdf Shared Source Limited Permissive License (SS-LPL)]. The source code can be found at [http://www.codeplex.com/PhidgetsWinCEDriver CodePlex].

==iOS==

By downloading the iOS library you agree to adhere to the terms of the [{{SERVER}}/documentation/Licenses/Software_Licenses.pdf Phidgets End User License Agreement]. The C API section of Phidget21 is covered by the [{{SERVER}}/documentation/Licenses/Software_Licenses.pdf GNU Lesser General Public License]. The source code of C API can be found [{{SERVER}}/downloads/phidget21/libraries/linux/libphidget.tar.gz here].

==Android==

By downloading the Android library you agree to adhere to the terms of the [{{SERVER}}/documentation/Licenses/Software_Licenses.pdf Phidgets End User License Agreement]. The C API section of Phidget21 is covered by the [{{SERVER}}/documentation/Licenses/Software_Licenses.pdf GNU Lesser General Public License]. The source code of C API can be found [{{SERVER}}/downloads/phidget21/libraries/linux/libphidget.tar.gz here].

==SBC==

By downloading the SBC Firmware or Buildroot/Kernal Sources, you agree to adhere to the terms of the [{{SERVER}}/documentation/Licenses/Software_Licenses.pdf GNU Lesser General Public License].

Language - Simulink

2017-09-18T15:39:20Z

Patrick:

[[Category:Language]]
{{OSLang|[[File:icon-Simulink.png|64x64px]]|Simulink support is no longer maintained by Phidgets}}

=='''Legacy Documentation'''==
<font color=red>We no longer officially support Simulink, as newer versions have been found to be incompatible with Phidgets libraries.</font>

Below is the documentation for previously supported versions of Simulink.

==Introduction==

{{LanguageSupport|Simulink|the non-[[General Phidget Programming#Event Driven Code|event driven]] part of the Phidget API|the Phidget Interface Kit.|Windows, Mac, and Linux; however, we provide a Windows walkthrough here|}}

==Quick Downloads==
{{QuickDownloads|Simulink|
{{APIQuickDownloads|{{SERVER}}/documentation/Phidget21_C_Doc.zip C}}|
{{ExampleQuickDownloads|{{SERVER}}/downloads/phidget21/examples/c/Simulink.zip Simulink|}}
{{ExampleQuickDownloads|{{SERVER}}/downloads/phidget21/examples/c/Matlab.zip MATLAB| (needed for the library)}}|
{{WindowsQuickDownloads}}
{{MacQuickDownloads}}
{{LinuxQuickDownloads}}}}

==Getting Started with Simulink==

We show how to use Simulink on Windows. Simulink, like MATLAB, can run on Mac OS X and Linux systems. Once you have MATLAB set up for your system - as described on our [[Language - MATLAB | MATLAB page]] - these instructions should apply no matter what your operating system behind MATLAB.

This page assumes the reader is familiar with Simulink, Simulink user-defined functions, and interacting with Phidgets using MATLAB. In particular, if you've not written working MATLAB code for Phidgets yet, please work through the [[Language - MATLAB|main MATLAB page]] before working through this one. MATLAB and Simulink depend heavily on hooking MATLAB into the Phidget C library and writing user-defined blocks, and this may be a new aspect of MATLAB for you.

If you are new to writing code for Phidgets in Simulink, we recommend starting by running, then modifying existing examples. This will allow you to:
{{ExampleCodeReasons}}

===Description of Files===

* The '''{{Code|phidget21Matlab.h}}''' file - found in the MATLAB (not Simulink) examples - is the library that makes both the MATLAB and the Simulink Phidget examples and other code work. On both Linux and Mac OS X, this file should be modified as described on the [[Language - MATLAB|main MATLAB page]].

===Use Our Examples===

Please start by downloading the [{{SERVER}}/downloads/phidget21/examples/c/Simulink.zip Simulink examples] and [{{SERVER}}/downloads/phidget21/examples/c/Matlab.zip MATLAB examples] and unpacking them into a folder. The Phidget examples were written using Simulink 6.1/MATLAB 7 in Windows XP. Other recent versions of Simulink should work as well and would be set up in a similar manner.

First, make sure that the '''{{Code|phidget21Matlab.h}}''' file from the MATLAB examples is in your MATLAB path. This would be a good time to also add the path to the Simulink examples that you've unpacked. To add these folders to the Simulink path, choose "File → Set Path..." and add your folders:

[[Image:Simulink setpath.png|link=|alt=]]

You can add them one by one, or include all of the sub-folder of the folder you unpacked the example into:

[[Image:Simulink choosepathfolder.png|link=|alt=]]

Make sure to save and close afterwards.

Now you are ready to run the Simulink Example. At this time, we only have a Simulink example for the Phidget Interface Kit. However, even if you don't have an Interface Kit, you can dig through the code behind the Simulink example and modify it to your own Phidget board (Spatial, Temperature Sensor, etc).

With an Interface Kit, make sure it is plugged in. Then, open the example by navigating to it from Simulink under "File → Open...". This will allow you to open the Interface Kit example:

[[Image:Simulink openexamples.png|link=|alt=]]

Opening the example will open the dashboard within Simulink to observe the Interface Kit. You will have the main layout of the blocks, and then also two traces:

[[Image:Simulink ifktopened.png|link=|alt=]]

Once opened, the example should look like the screenshot above. If the boxes for the Interface Kit are red, and running it results in a Phidgets object unknown error, you need to include the Simulink project and the MATLAB examples in your path.

When you run the example, by using "Simulation → Start", the Interface Kit will turn on and off its digital outputs (to turn on and off any test LEDs you may have in them) and also print the output and sensor values to the screen and the traces:

[[Image:Simulink runexamples.png|link=|alt=]]

At this point, you probably want to set up your own project and [[#Write Your Own Code|write your own code]], or refer to our [[#Follow The Examples|teaching section]] to match code snippets and explanations to the example code.

===Write Your Own Code===

To begin your own project, you can make sure your MATLAB path is set as described in the [[#Use Our Examples|Use Our Examples]] section. Then, you have to decide whether you will need to create new blocks first (refer to our example under the "M" directory for structure and example block code) or use the small set of Phidget blocks we already provide for the Interface Kit. For help writing new blocks, we have some code snippets in the [[#Follow The Examples|Follow The Examples]] section.

Once you have all the blocks you need (and they have been added to your path), you can create a new Model from the Simulink window:

[[Image:Simulink newmodel.png|link=|alt=]]

Then you can open up the Phidgets blocks right on the Simulink window and peruse the functionality of each block via its sub-menus. Here are the two blocks available from the Simulink example:

[[Image:Simulink addifkt.png|link=|alt=]]

Once your blocks appear like this, it is easy to drag and drop them into your new model pane. We have some [[#Follow The Examples|code snippets available]] for you to break down our example code into usable blocks, but as mentioned earlier you should already be familiar with writing user-defined blocks in Simulink as this is beyond the scope of this guide.

==Follow The Examples==

By following the instructions above, you probably now have a working example and want to understand it better so you can change it to do what you want. This section has resources for you to learn from the example and write your own.

Your main reference for writing Simulink code will be our C++ API information (because Simulink calls our C library directly) with syntax for all of our functions:

{{UsingAPhidgetInCodeGeneral|although only traditional non-event driven code is available in Simulink.|[{{SERVER}}/documentation/Phidget21_C_Doc.zip C/C++ API]}}

===Code Snippets===

This tutorial will use MATLAB code to demonstrate how user defined functions can be used to interact with Phidgets through the use of MATLAB Fcn, M Level 1 S Functions, and M Level 2 S Function blocks.
As writing C code is beyond the scope of this guide, C S Function blocks will not be discussed. However, C S Function blocks work similar to M S Function blocks.

MATLAB Fcn blocks are the easiest blocks to use, but have limited features(i.e., only 1 input port). Level 1 S Functions blocks have more featues, but are more complicated to implement. Level 2 S Functions blocks are the most complex, but benefit in supporting the most features.

Specific calls in Simulink user blocks will differ in syntax from those on the [[General Phidget Programming]] page, but the concepts stay the same.

It may help to have the [[General Phidget Programming]] page and this section open at the same time, because they parallel each other and you can refer to the MATLAB/Simulink syntax. However, many additional concepts are covered on the General Phidget Programming page on a high level, such as using multiple Phidgets, handling errors, and different styles of programming.

You may also find it useful to refer to the code snippets main [[Language - MATLAB#Code Snippets|MATLAB page]].

====Step One: Initialize and Open====

Before using the Phidget in your code, the Phidget object will need to be declared and initialized.
For example, we can declare and initialize an instance of a PhidgetInterfaceKit inside a M file of a Level 1 S Function block with:

<div class="source"><syntaxhighlight lang=matlab>
global handle;
loadlibrary('phidget21', 'phidget21Matlab.h');
ptr = libpointer('int32Ptr',0);
calllib('phidget21', 'CPhidgetInterfaceKit_create', ptr);
handle = get(ptr, 'Value');
calllib('phidget21', 'CPhidget_open', handle, -1)
</syntaxhighlight></div>

The handle variable is declared as a global, and can be easily accessed by other blocks. Since blocks repeatedly run until the simulation is completed, the above code will need to be restricted so that it runs only once during a simulation. Hence, you should put such code inside the mdlInitializeSizes function.

====Step Two: Wait for Attachment (plugging in) of the Phidget====

To use the Phidget, it must be plugged in (attached). We can handle this by calling waitForAttachment. This function works for any Phidget. WaitForAttachment will block indefinitely until a connection is made to the Phidget, or an optional timeout is exceeded:

<div class="source"><syntaxhighlight lang=matlab>
calllib('phidget21', 'CPhidget_waitForAttachment', handle, 2500)
</syntaxhighlight></div>

This line is also placed inside the mdlInitializeSizes function.

Because Simulink and MATLAB cannot handle events, you cannot catch the attach events in the C library as you can with our other supported languages.

====Step Three: Do Things with the Phidget====

Although we usually recommend using events to interact with your Phidget, MATLAB and Simulink do not support event handling. Hence, you can only use the "get" and "set" functions from the C library to interact with your Phidget.

For example, here we have a MATLAB Fcn block which can be used to set the output states of the digital output ports on a PhidgetInterfaceKit 8/8/8. The following code is placed inside a M file.
The block’s input variable is the desired output state to be set:

<div class="source"><syntaxhighlight lang=cpp>
function setOutputStates(outputState)
global handle;
for i = 0:7
if (calllib('phidget21', 'CPhidgetInterfaceKit_setOutputState', handle, i, outputState) == 1)
display('Set output state failed')

end
end
</syntaxhighlight></div>

Note that this handle is the same handle that was [[#Step One: Initialize and Open|created]] and [[#Step Two: Wait for Attachment (plugging in) of the Phidget|attached]] earlier.

Next, a M Level 2 S Function will be used to retrieve sensor values of analog sensor ports and output it to a Simulink scope window. The block will contain no inputs and 1 output, with 8 dimensions (1 dimension for each analog sensor of a PhidgetInterfaceKit 8/8/8). For this, you can place the following code in the Output function in the M file:

<div class="source"><syntaxhighlight lang=cpp>
function Output(block)
dataptr = libpointer('int32Ptr',0);
global handle;
for i = 0:7
if (calllib('phidget21', 'CPhidgetInterfaceKit_getSensorValue', handle, i, dataptr) == 0)
block.OutputPort(1).Data(i+1) = get(dataptr, 'Value');
end
end
</syntaxhighlight></div>

====Step Four: Close and Delete====

At the end of the simulation, the Phidget object will need to be closed and deleted.
To do this, the following lines can added to mdlTerminate.

<div class="source"><syntaxhighlight lang=matlab>
calllib('phidget21', 'CPhidget_close', handle);
calllib('phidget21', 'CPhidget_delete', handle);
</syntaxhighlight></div>

====Special Cases: Strings and Real-Time====

=====Strings=====

It is possible for a user to specify a string of characters in the block parameters dialog box of a user defined function such that it is passed into a user defined function.
Please see the PhidgetInterfaceKit_RemoteIP block library in the Simulink examples for details. Simulink cannot display strings in the GUI, however it is possible to write a C S function that displays strings in the MATLAB console.

=====Working in Real Time=====

Even though a model may finish simulating before a user has a chance to interact with Phidgets, there are workarounds that can be used to slow down simulation time to allow for user interaction.

One method is to modify the Solver Options (under Simulation->Configuration Parameters->Solver). Changing the step size and stop time may slow down the simulation. Another method is to implement a user defined function that reduces the simulation speed until the system clock matches the Simulink clock.

The Phidget Simulink example uses the “Real Time Block” to simulate the model in approximate real time.

To use the “Real Time Block”, place the following files in your MATLAB working directory: slblocks.m, rtc.mdl, waitforreal.m. These files can be extracted from the root directory and the Real Time directory of the Phidget Simulink example. Open up the Simulink Library Browser and select “Real Time Clock”. Place the Real Time Clock block onto your model.

For applications where accurate real time simuation is needed, xPC Target can be used. Please note that the simulation speed of these methods may differ depending on the CPU speed, complexity of the model, the amount of text being displayed in the MATLAB console, etc....

{{MoreHowTos}}

Note, however, that although being familiar with both event and traditional programming can help you identify which functions are which within an API, Simulink only supports traditional logic programming.

==Common Problems and Solutions/Workarounds==

None at this time.

SBC2 USB Hub Fix

2017-09-18T15:35:49Z

Patrick:

[[Category:Troubleshooting]]
There is a problem on [[1072 User Guide|SBC2's]] purchased before Jan. 10th 2012. There was an issue with some of the routing to the USB hub which can cause issues with certain devices connected to the hub. Symptoms of this problem include unusual behaviour with devices connected to the USB hub such as devices detaching and attaching as well as the occasional complete failure to attach. Particularly bad offenders are servo controllers. There are 2 solutions to this problem, you can either contact us and send the device in for modification. Or you can make the modifications yourself provided you have the equipment and the ability to solder small components.

==What you will need==
If you intend to make the modifications yourself you will need a fine tip soldering iron, a microscope (or ''very'' sharp eyes), and a capacitor. The capacitor that needs to be added is as follows:

{| border = 1
|Style: ||Capcitance: ||Package:
|-
|Surface Mount||30pF||0603
|}

They can be purchased from Digikey for $0.13 a piece.

==What you need to do==
The capacitor needs to be added to the board in the location highlighted in red in the images that follow:
{|
|colspan = 2 align="center"|[[image:1072 fix1.png|700px]]
|-
|[[image:1072 fix2.jpeg|700px]]||[[image:1072 fix2-2.jpeg|700px]]
|-
|[[image:1072 fix3.jpeg|700px]]||[[image:1072 fix3-2.jpeg|700px]]
|}

Language - C

2017-09-18T15:34:56Z

Patrick:

[[Category:Language]]
{{OSLang|[[File:icon-C++.png|link=|alt=C/C++|64x64px]]|C++ is a general purpose, cross-platform programming language with a vast user base.}}
__TOC__

==Introduction==

{{LanguageSupport|C/C++|the complete Phidget API, including events|all Phidget devices.|Windows XP/Vista/7/8(environments include [[#Visual Studio | Visual Studio]], [[#Borland | Borland]], [[#Cygwin/MinGW | Cygwin, and MinGW]]), [[#Windows CE | Windows CE]], [[#OS X | OS X]], and [[#Linux | Linux]]|}}

==Quick Downloads==
{{QuickDownloads|C/C++|
{{APIQuickDownloads|{{SERVER}}/documentation/Phidget21_C_Doc.zip}}
{{ExtraAPIQuickDownloads|{{SERVER}}/documentation/web/cdoc/index.html|HTML Version of}}|
*[{{SERVER}}/downloads/phidget21/examples/c/VCpp.zip Visual Studio 2005/2008/2010 Projects]
*[{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz All other compilers]|
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/phidget21/libraries/windows/phidget21bcc.zip|Borland(Windows)|}}
{{WindowsQuickDownloads}}
{{MacQuickDownloads}}
{{LinuxQuickDownloads}}
}}

==Getting started with C/C++==

If you are new to writing code for Phidgets, we recommend starting by running, then modifying existing examples. This will allow you to:
{{ExampleCodeReasons}}

Instructions are divided up by operating system. Choose:
*[[#Windows(2000/XP/Vista/7)|Windows 2000 / XP / Vista / 7]]
*[[#OS X |OS X]]
*[[#Linux | Linux]] (including PhidgetSBC)

==Windows (XP/Vista/7/8)==

===Description of Library Files===
C/C++ programs on Windows depend on three files, which the installers in [[#Libraries and Drivers|Quick Downloads]] put onto your system:
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. By default, it is placed in {{Code|C:\Windows\System32}}.
* <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.

If you do not want to use our installer, you can download all three [{{SERVER}}/downloads/phidget21/libraries/windows/Phidget-x86.zip files] and manually install them where you want; refer to our [[OS_-_Windows#Manual_File_Installation | Manual Installation Instructions]].

Running the examples and writing your own code can be fairly compiler-specific, so we include instructions for [[#Visual Studio 2005/2008/2010 | Visual Studio 2005/2008/2010]], [[#Visual Studio 2003 | Visual Studio 2003]], [[#Visual Studio C++ 6.0 | Visual Studio 6]], [[#Borland| Borland]], [[#Cygwin/MinGW | Cygwin/MinGW]], and [[#Dev C++ | Dev C++]].

===Visual Studio===

C++/CLI (which used to be called Managed C++) is very different from mainstream C/C++. If you must use C++/CLI, consider calling the Phidget .NET library, instead of the C API normally used from C/C++. We have no documentation for using C++/CLI.

Microsoft makes free versions of Visual Studio available known as Express Editions. The Express editions are suitable for most applications, but are limited in features for more complex applications. Please see [http://www.microsoft.com/visualstudio Microsoft Visual Studio] for more information.

====Visual Studio 2005/2008/2010====

=====Use Our Examples=====

To run the examples, you first download the [{{SERVER}}/downloads/phidget21/examples/c/VCpp.zip examples] and unpack them into a folder. To load all projects in Visual Studio, go to File → Open → Project → Solution, and open {{Code|Visual Studio Phidgets Examples.sln}} in the {{Code|VCpp}} folder of the examples.

Since the examples were written in Visual Studio 2005, if you are opening the examples in Visual Studio 2008/2010, you will need to go through the Visual Studio Conversion Wizard to open and convert the 2005 project.

[[File:VS2005 Conversion Wizard.PNG|link=|alt=Conversion Wizard]]

This will load all of the examples available for C/C++. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

Start by setting the {{Code|HelloWorld}} project as your start up project.

[[File:VS2005 StartUp Project.PNG|link=|alt=Start Up Project]]

To run the example, click on Debug → Start Debugging. Please note that the projects, by default try to find the {{Code|phidget21.h}} and {{Code|phidget21.lib}} in the {{Code|$(SystemDrive)\Program Files\Phidgets}}. If you have these files installed in another location, please change the path to the file's location accordingly. Please see the [[#Write Your Own Code | Write Your Own Code]] section for details.

[[File:VS2005 Run.PNG|link=|alt=Run]]

This program will detect for devices that are attached/detached on the computer. Go ahead, and attach or detach your devices! Here is an example output:

[[File:VS2005 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

If you have a 64-bit computer (and operating system) then you may also need to adjust the platform. You can do this by selecting x64 from the following drop down menu:

[[File:platform.png|link=]]

If x64 is not a selectable option then go into the Configuration Manager and create it by selecting New... and copying the settings from Win32. You should now be able to select x64 and run the code normally.

[[File:newplatform.png|link=]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|teaching]] section below to help you follow them.

=====Write Your Own Code=====

When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your development environment to properly link the Phidget C/C++ library. To begin:

1. Generate a new Visual C++: Win32 Console Application project with a descriptive name such as PhidgetTest.

[[File:VS2005 New Project.PNG|link=|alt=New Project]]

2. Next, select Console Application.

[[File:VS2005 New Project 2.PNG|link=|alt=New Project]]

3. Open the project properties window.

4. Navigate to Configuration Properties → C/C++.

5. Add {{Code|"C:\Program Files\Phidgets"}} to the additional directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Header.PNG|link=|alt=Header File]]

6. Navigate to Configuration Properties → Linker → Input.

7. Edit the additional dependencies and add {{Code|"C:\Program Files\Phidgets\phidget21.lib"}}. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Library.PNG|link=|alt=Library File]]

8. The project now has access to the Phidget function calls and you are ready to begin coding.

Then, in your code, you will need to include the Phidget C/C++ library:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

The same [[#Follow the Examples|teaching]] section which describes the examples also has further resources for programming your Phidget.

====Visual Studio 2003====

=====Use Our Examples=====

1. Start by downloading the [{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz examples]. You can import these examples into a Visual Studio 2003 C++ project. Afterwards, unpack them into a folder. Here, you can find example programs for all the devices. You will need this example source code to be copied into your C++ project later on. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

2. A new project will need to be created. Generate a new Visual C++ empty project(.NET) with a descriptive name such as HelloWorld.

[[File:VS2003 New Project.PNG|link=|alt=New Project]]

3. Create a new C++ file by adding a new item to the source files folder.

[[File:VS2003 New File.PNG|link=|alt=New File]]

[[File:VS2003 New File 2.PNG|link=|alt=New File]]

4. An empty C++ file will pop up. Please copy and paste the contents of the {{Code|HelloWorld.c}} program into here.

[[File:VS2003 Source.PNG|link=|alt=Source Code]]

5. Next, the project setting needs to be set up. Open the project properties window.

6. Navigate to Configuration Properties → C/C++.

7. Add {{Code|"C:\Program Files\Phidgets"}} to the additional include directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2003 Header.PNG|link=|alt=Header File]]

8. Navigate to Configuration Properties → Linker → Input.

9. Add {{Code|"C:\Program Files\Phidgets\phidget21.lib"}} to the additional dependencies field. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2003 Library.PNG|link=|alt=Library File]]

10. Now, you can run the example. Click on Debug → Start Without Debugging.

[[File:VS2003 Run.PNG|link=|alt=Run]]

11. This program will detect for devices that are attached/detached on the computer. Go ahead, and attach or detach your devices! Here is an example output:

[[File:VS2003 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|teaching]] section below to help you follow them.

=====Write Your Own Code=====

When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 2 | Use Our Examples]] section for instructions.

Then, in your code, you will need to include the Phidget C/C++ library:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

====Visual Studio C++ 6.0====

=====Use Our Examples=====

1. Download the [{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz examples] and unpack them into a folder. Here, you can find example programs for all the devices. You will need this example source code to be copied into your C++ project later on. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

2. Next, a new project will need to be created. Generate a new Win32 Console Application project with a descriptive name such as HelloWorld.

[[File:VS6 New Project.PNG|link=|alt=New Project]]

3. Create an empty project.

[[File:VS6 New Project 2.PNG|link=|alt=New Project]]

4. Next, the project settings needs to be set up. Navigate to Project → Settings → C/C++ → Preprocessor.

5. Add {{Code|C:\Program Files\Phidgets}} to the additional include directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS6 Header.PNG|link=|alt=Header File]]

6. Navigate to Project → Settings → Link → Input → Additional library Path.

7. Add {{Code|phidget21.lib}} to the object/library modules field.

8. Add {{Code|C:\Program Files\Phidgets}} to the additional library path. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS6 Library.PNG|link=|alt=Library File]]

The project now has access to the Phidget function calls and you are ready to begin coding.

To import the example program into your project, please:

9. Create a new C++ file by navigating to File → New → Files → C++ Source File and enter a descriptive name such as HelloWorld.

[[File:VS6 New File.PNG|link=|alt=New File]]

10. An empty C++ file will pop up. Please copy and paste the contents of the {{Code|HelloWorld.c}} program here.

[[File:VS6 Source.PNG|link=|alt=Source Code]]

11. Now, you can run the example. Click on Build → Execute.

[[File:VS6 Run.PNG|link=|alt=Run]]

12. This program will detect for devices that are attached/detached on the computer. Go ahead, and attach or detach your devices! Here is an example output:

[[File:VS6 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|teaching]] section below to help you follow them.

=====Write Your Own Code=====

When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 3 | Use Our Examples]] section for instructions.

In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as shown in the [[#Use Our Examples 3 | Use Our Examples]] section.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===Borland===

====Use Our Examples====

In addition to running one of the two [[#Libraries and Drivers:| Windows Installers]] above (which you probably already have if you worked through the ''Getting Started'' page for your device), you will need the [{{SERVER}}/downloads/phidget21/libraries/windows/phidget21bcc.zip Borland C++ Libraries]. {{Code|phidget21bcc.lib}} is typically placed in {{Code|C:\Program Files\Phidgets}}, but you are free to place it in any directory you wish.

After installing the Phidget C/C++ library, you're ready to download the [{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz examples] and run the examples.

Afterwards, unpack the examples. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example. Locate the {{Code|HelloWorld.c}} file and type the following to compile the file and link the Phidget C/C++ library:

To compile, link the Phidget C/C++ library and build a binary executable, enter the following in a command line prompt in the directory with {{Code|HelloWorld.c}}:
<div class="source">
<syntaxhighlight lang=bash>
bcc32 -eHelloWorld -I"C:\Program Files\Phidgets" -L"C:\Program Files\Phidgets" phidget21bcc.lib HelloWorld.c
</syntaxhighlight>
</div>

It is assumed that {{Code|phidget21bcc.lib}} and {{Code|phidget21.h}} are placed in {{Code|C:\Program Files\Phidgets}}. If the files are placed in another location, please adjust the paths to both of the file's location accordingly.

In this case, {{Code|HelloWorld.c}} would be the '''.c''' file specific to your device. After using {{Code|bcc32}}, you will have an executable named {{Code|HelloWorld}} that you can run.

This program will detect for devices that are attached/detached on the computer. Go ahead, and attach or detach your devices! Here is an example output:

[[File:Borland HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

====Write Your Own Code====

When writing your code from scratch, you start it as you would any C/C++ code with Borland. In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the examples [[#Use Our Examples 4 |above]].

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===GCC on Windows===

====Cygwin/MinGW====

=====Use Our Examples=====

Download the [{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz examples] and unpack them into a folder. Afterwards, unpack the examples. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example. Locate the {{Code|HelloWorld.c}} file and type the following to compile the file and link the Phidget C/C++ library in a command line prompt:

<b>Cygwin</b>

<div class="source">
<syntaxhighlight lang=bash>
gcc example.c -o HelloWorld -I"/cygdrive/c/Program Files/Phidgets" -L"/cygdrive/c/Program Files/Phidgets" -lphidget21
</syntaxhighlight>
</div>

<b>MinGW</b>
<div class="source">
<syntaxhighlight lang=bash>
gcc example.c -o HelloWorld -I"C:\Program Files\Phidgets" -L"C:\Program Files\Phidgets" -lphidget21
</syntaxhighlight>
</div>

After using gcc, you will have an executable named {{Code|HelloWorld}} that you can run.
It is assumed that {{Code|phidget21.h}} and {{Code|phidget21.lib}} are placed in {{Code|C:\Program Files\Phidgets}}. If the files are placed in another location, please adjust the paths to the file's location accordingly.

After using {{Code|gcc}}, you will have an executable named {{Code|HelloWorld}} that you can run.

This program will detect for devices that are attached/detached on the computer. Go ahead, and attach or detach your devices! Here is an example output:

[[File:C MinGW HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

=====Write Your Own Code=====

When writing your code from scratch, you start it as you would any C/C++ code with Cygwin/MinGW in your favourite text editor. In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as shown in the [[#Use Our Examples 5| Use Our Examples]] section above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===Dev C++===

=====Use Our Examples=====

1. Download the [{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz examples] and unpack them into a folder. Here, you can find example programs for all the devices. {{FindYourDevice}} You will need this example source code to be copied into your Dev C++ project later on. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

2. In order to control Phidgets with Dev C++, we will use the {{Code|reimp}} tool to convert the {{Code|phidget21.lib}} to a format that Dev C++ accepts. Download the [http://sourceforge.net/projects/mingw/ reimp tool]. Reimp is part of MinGW, a minimal UNIX emulator for Windows, and it is specifically within the mingw-utils package. You can check MinGW's release notes to ensure Reimp is in the version you are using.

3. Open up command line and traverse to the directory containing the reimp tool. Type the following command to create {{Code|libphidget21.a}}.
<div class="source">
<syntaxhighlight lang=bash>
reimp.exe "C:\Program Files\Phidgets\phidget21.lib"
</syntaxhighlight>
</div>
The command above assumes that the {{Code|phidget21.lib}} is in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly. Please note that the 64 bit version of {{Code|phidget21.lib}} is not supported on Dev C/C++. Please use the 32 bit version of {{Code|phidget21.lib}}.

4. Place {{Code|libphidget21.a}} in {{Code|<Dev-Cpp Install Directory>/lib}}.

5. Next, a new project will need to be created. Generate a new console application with a descriptive name such as PhidgetTest. Please select C as the project type.

[[File:DevC New Project.PNG|link=|alt=New Project]]

6. Next, the project settings needs to be set up. Navigate to Project Options → Directories → Include Directories.

7. Add a new path to {{Code|C:\Program Files\Phidgets}}. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:DevC Header.PNG|link=|alt=Header File]]

8. Navigate to Project Options → Parameters → Linker.

9. Add {{Code|-lphidget21}} to the field. This step will find the {{Code|libphidget21.a}} file in {{Code|<Dev-Cpp Install Directory>/lib}}.

[[File:DevC Library.PNG|link=|alt=Library File]]

10. To import the {{Code|HelloWorld}} program into your project, please open up {{Code|main.c}} in the editor.

11. An empty C file will pop up. Please copy and paste the contents of the example program.

[[File:DevC Source.PNG|link=|alt=Source Code]]

12. Now, you can run the example. Click on Execute → Compile & Run.

[[File:DevC Run.PNG|link=|alt=Run]]

13. This program will detect for devices that are attached/detached on the computer. Go ahead, and attach or detach your devices! Here is an example output:

[[File:DevC HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|teaching]] section below to help you follow them.

=====Write Your Own Code=====

When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 6 | Use Our Examples]] section for instructions.

In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the [[#Use Our Examples 6 | examples]] above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===Code::Blocks===
=====Use Our Examples=====
The process for getting Phidgets working in Code::Blocks is much the same as [[#Dev C++|Dev-C++]]. You will need to download the reimp tool that is linked there and use it on the phidget21.lib file as instructed. After the .a file has been created you can stick it in your /Phidgets folder with the rest of the Phidget library files.

Now that that has been done, open one of the example files that you would like to run, for example InterfaceKit-simple.c. Under the Settings menu, choose "Compiler and debugger..."

[[File:compilersettings.png|link=|916px]]

Go to the "Search directories" tab and add a new entry. Choose your Phidgets installation directory.

[[File:searchdirectories.png|link=|500px]]

Under the "Linker settings" tab add a new entry and type in "phidget21".

[[File:linkersettings.png|link=|500px]]

You can now compile and run the example.

=====Write Your Own Code=====

When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 6 | Use Our Examples]] section for instructions.

In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the [[#Use Our Examples 6 | examples]] above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

==OS X==

C/C++ has excellent support on OS X through the gcc compiler.

The first step in using C/C++ on Mac is to install the Phidget C/C++ library. Compile and install them as explained on the Getting Started guide for your device, which you can find in its [[:Category:UserGuide|user guide]]. Then, the [[OS - OS X#Description of Library files|OS - OS X]] page also describes the different Phidget files, their installed locations, and their roles.

===Use Our Examples===

After installing the main Phidget library for OS X as above, you're ready to download the [{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz examples]. Afterwards, unzip the file. To run the example code, you'll need to find the source code ''for your specific device''. Then, compile the code under your platform and run it.

To compile, link the Phidget C/C++ library, and build an executable binary on OS X, do (for example, depending on the Headers location):

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

gcc example.c -o example -F/Library/Frameworks -framework Phidget21 -I/Library/Frameworks/Phidget21.framework/Headers
</syntaxhighlight>
</div>

After using gcc, you will have an executable named {{Code|example}} that you can run.

===Write Your Own Code===

When writing your code from scratch, you must include a reference to the library header:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as shown in the [[#Use Our Examples 7|Use Our Example]] section above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples. Even more help and references are provided from there.

==Linux==

C/C++ has support on Linux through the gcc compiler.

The first step in using C/C++ on Linux is to install the Phidget libraries. Compile and install them as explained on the main [[OS - Linux | Linux page]]. That Linux page also describes the different Phidget files, their installed locations, and their roles.

===Use Our Examples===

After installing the Phidget libraries for Linux as above, you're ready to download and run the examples:
*[{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz Generic C/C++ Examples]

To run the example code, you'll need to download and unpack the examples, and then find the source code for your device. {{FindYourDevice}} You can also use the HelloWorld program, which a basic program that can run with any Phidget. Then, compile the code under your platform and run it. When compiling, you need to link to the Phidget library.

To compile, link the Phidget libraries and build a binary executable on Linux, do the following in a terminal in the directory with {{Code|example.c}}:

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

In this case, {{Code|example.c}} would be the '''.c''' file specific to your device. After using gcc, you will have an executable named {{Code|example}} that you can run.

On Linux, if you have not set up [[OS_-_Linux#Setting_udev_Rules | your udev rules for USB access]], you will need to run the program '''as root''':

<div class="source">
<syntaxhighlight lang=bash>
sudo ./example
</syntaxhighlight>
</div>

===Write Your Own Code===

When writing your code from scratch, you start it as you would any C/C++ code on Linux, such as within a text editor like Emacs, Vi, Gedit, or Kate. In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>
#include <phidget21.h>
</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the examples above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

==Windows CE==

===Description of Library Files===
C/C++ programs on Windows CE depend on the following files, which the Windows CE installer puts onto your system:
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. It is placed in {{Code|\Windows}}.
* <b>{{Code|PhidgetWebService21.exe}}</b> is used to control Phidgets remotely across a network using the [[#WebService | PhidgetWebService]]. It can be placed anywhere on the system.
* <b>{{Code|phidget21.lib}}</b> is used by your compiler to link to the dll. Your compiler has to know where this file is.
* <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.
* <b>{{Code|phidget.dll}}</b> is the Phidgets kernel driver. It is placed in {{Code|\Windows}}.

===Visual Studio 2005/2008/2010===

=====Use Our Examples=====

Currently, we have no example code for C/C++ on Windows CE. However, set up is very much the same as what it would be with [[#Visual Studio 2005/2008/2010 |Visual Studio 2005/2008/2010]] in Windows. The {{Code|phidget21.h}} and {{Code|phidget21.lib}} can be downloaded [{{SERVER}}/downloads/phidget21/libraries/windows/Phidget21-windevel.zip here].

=====Write Your Own Code=====

When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your development environment to properly link the Phidget C/C++ library. To begin:

1. Generate a new Visual C++: Win32 Smart Device project with a descriptive name such as PhidgetTest.

[[File:WinCE VS C NewProject 1.PNG|link=|alt=New Project]]

2. Select {{Code|Next}}.

[[File:WinCE VS C NewProject 2.PNG|link=|alt=New Project]]

3. Select the SDK(s) that you want to code against and elect {{Code|Next}}.

[[File:WinCE VS C NewProject 3.PNG|link=|alt=SDKs]]

4. Create a console application and select {{Code|Next}}.

[[File:WinCE VS C NewProject 4.PNG|link=|alt=Create Console Application]]

3. Open the project properties window.

4. Navigate to Configuration Properties → C/C++.

5. Add {{Code|"C:\Program Files\Phidgets"}} to the additional directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Header.PNG|link=|alt=Header File]]

6. Navigate to Configuration Properties → Linker → Input.

7. Edit the additional dependencies and add {{Code|"C:\Program Files\Phidgets\phidget21.lib"}}. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Library.PNG|link=|alt=Library File]]

8. The project now has access to the Phidget function calls and you are ready to begin coding.

Then, in your code, you will need to include the Phidget C/C++ library:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

The same [[#Follow the Examples|teaching]] section which describes the examples also has further resources for programming your Phidget.

==Follow the Examples==

By following the instructions for your operating system and compiler above, you probably now have a working example and want to understand it better so you can change it to do what you want.

Your main reference for writing C code will be our C/C++ API information, with syntax for all of our functions:

{{UsingAPhidgetInCodeGeneral|both of which are available in C/C++|[{{SERVER}}/documentation/Phidget21_C_Doc.zip C/C++ API]}}

===Example Flow===

{{ExamplePseudocode|In C/C++, you can name these '''event''' functions whatever you like. You will then pass them as function pointers to the Phidget library below in the Main Code section. This hooks them into the actual events when they occur. <br>
In the example code, the event functions common to all Phidgets are called things like '''AttachHandler()''' and '''DetachHandler()''', etc.<br><br>
Some event functions will be specific to each device, like when a tag is read on an RFID board, or when a sensor value changes on an Interface Kit.
Other functions are given in the examples to show you more detail on using your Phidget. For example, '''DeviceInitialize()''' will show what needs to be set up for your Phidget before using it.
|Creating a Phidget software object in C is specific to the Phidget. For a Phidget Spatial, for example, this would involve creating an object with the {{Code|CPhidgetSpatialHandle}} type, and then initializing it using the {{Code|CPhidgetSpatial_create function}}. The examples show how to do this and other API functions.<br><br>
Other C calls follow a similar syntax - {{Code|CPhidgetXXX_function}}, where XXX is the name of your device, and function is an action available from the API for your specific Phidget.|
[{{SERVER}}/documentation/Phidget21_C_Doc.zip C/C++ API]}}

===Code Snippets===

When programming in C/C++, you're in luck. All of our code snippet examples on our [[General Phidget Programming]] page are in both C++ and Java. Therefore, we do not include any here, because that page is much more in-depth, and you won't have to have two pages open at once. So head over there, and start writing code!

===C++ Events===
If you want to use C++ style, object-oriented events you can do that as well. The following examples show you how to do this:

*[{{SERVER}}/docs21/images/0/05/Simple.cpp Main]
*[{{SERVER}}/docs21/images/1/11/Simple.h Header]

==Common Problems and Solutions/Workarounds==

===Issue: I am using a non US-English version of Windows, and the Visual C/C++ examples run into a linker error===
Affected Operating Systems: '''Windows'''

The example projects, by default finds the {{Code|phidget21.h}} and {{Code|phidget21.lib}} in ${SystemDrive}\Program Files\Phidgets. If you are using a non US-English version of Windows, the Phidget drivers may be installed into a different location. To resolve, you will have to modify the paths to these two files. For instructions, please see your environment/compiler section.

Language - C/C++

2017-09-18T15:33:48Z

Patrick: Patrick moved page Language - C/C++ to Language - C

#REDIRECT [[Language - C]]

Language - C

2017-09-18T15:33:46Z

Patrick: Patrick moved page Language - C/C++ to Language - C

[[Category:Language]]
{{OSLang|[[File:icon-C++.png|link=|alt=C/C++|64x64px]]|C++ is a general purpose, cross-platform programming language with a vast user base.}}
__TOC__

==Introduction==

{{LanguageSupport|C/C++|the complete Phidget API, including events|all Phidget devices.|Windows XP/Vista/7/8(environments include [[#Visual Studio | Visual Studio]], [[#Borland | Borland]], [[#Cygwin/MinGW | Cygwin, and MinGW]]), [[#Windows CE | Windows CE]], [[#OS X | OS X]], and [[#Linux | Linux]]|}}

==Quick Downloads==
{{QuickDownloads|C/C++|
{{APIQuickDownloads|{{SERVER}}/documentation/Phidget21_C_Doc.zip}}
{{ExtraAPIQuickDownloads|{{SERVER}}/documentation/web/cdoc/index.html|HTML Version of}}|
*[{{SERVER}}/downloads/phidget21/examples/c/VCpp.zip Visual Studio 2005/2008/2010 Projects]
*[{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz All other compilers]|
{{ExtraLibraryQuickDownloads|{{SERVER}}/downloads/phidget21/libraries/windows/phidget21bcc.zip|Borland(Windows)|}}
{{WindowsQuickDownloads}}
{{MacQuickDownloads}}
{{LinuxQuickDownloads}}
}}

==Getting started with C/C++==

If you are new to writing code for Phidgets, we recommend starting by running, then modifying existing examples. This will allow you to:
{{ExampleCodeReasons}}

Instructions are divided up by operating system. Choose:
*[[#Windows(2000/XP/Vista/7)|Windows 2000 / XP / Vista / 7]]
*[[#OS X |OS X]]
*[[#Linux | Linux]] (including PhidgetSBC)

==Windows (XP/Vista/7/8)==

===Description of Library Files===
C/C++ programs on Windows depend on three files, which the installers in [[#Libraries and Drivers|Quick Downloads]] put onto your system:
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. By default, it is placed in {{Code|C:\Windows\System32}}.
* <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.

If you do not want to use our installer, you can download all three [{{SERVER}}/downloads/phidget21/libraries/windows/Phidget-x86.zip files] and manually install them where you want; refer to our [[OS_-_Windows#Manual_File_Installation | Manual Installation Instructions]].

Running the examples and writing your own code can be fairly compiler-specific, so we include instructions for [[#Visual Studio 2005/2008/2010 | Visual Studio 2005/2008/2010]], [[#Visual Studio 2003 | Visual Studio 2003]], [[#Visual Studio C++ 6.0 | Visual Studio 6]], [[#Borland| Borland]], [[#Cygwin/MinGW | Cygwin/MinGW]], and [[#Dev C++ | Dev C++]].

===Visual Studio===

C++/CLI (which used to be called Managed C++) is very different from mainstream C/C++. If you must use C++/CLI, consider calling the Phidget .NET library, instead of the C API normally used from C/C++. We have no documentation for using C++/CLI.

Microsoft makes free versions of Visual Studio available known as Express Editions. The Express editions are suitable for most applications, but are limited in features for more complex applications. Please see [http://www.microsoft.com/visualstudio Microsoft Visual Studio] for more information.

====Visual Studio 2005/2008/2010====

=====Use Our Examples=====

To run the examples, you first download the [{{SERVER}}/downloads/phidget21/examples/c/VCpp.zip examples] and unpack them into a folder. To load all projects in Visual Studio, go to File → Open → Project → Solution, and open {{Code|Visual Studio Phidgets Examples.sln}} in the {{Code|VCpp}} folder of the examples.

Since the examples were written in Visual Studio 2005, if you are opening the examples in Visual Studio 2008/2010, you will need to go through the Visual Studio Conversion Wizard to open and convert the 2005 project.

[[File:VS2005 Conversion Wizard.PNG|link=|alt=Conversion Wizard]]

This will load all of the examples available for C/C++. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

Start by setting the {{Code|HelloWorld}} project as your start up project.

[[File:VS2005 StartUp Project.PNG|link=|alt=Start Up Project]]

To run the example, click on Debug → Start Debugging. Please note that the projects, by default try to find the {{Code|phidget21.h}} and {{Code|phidget21.lib}} in the {{Code|$(SystemDrive)\Program Files\Phidgets}}. If you have these files installed in another location, please change the path to the file's location accordingly. Please see the [[#Write Your Own Code | Write Your Own Code]] section for details.

[[File:VS2005 Run.PNG|link=|alt=Run]]

This program will detect for devices that are attached/detached on the computer. Go ahead, and attach or detach your devices! Here is an example output:

[[File:VS2005 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

If you have a 64-bit computer (and operating system) then you may also need to adjust the platform. You can do this by selecting x64 from the following drop down menu:

[[File:platform.png|link=]]

If x64 is not a selectable option then go into the Configuration Manager and create it by selecting New... and copying the settings from Win32. You should now be able to select x64 and run the code normally.

[[File:newplatform.png|link=]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|teaching]] section below to help you follow them.

=====Write Your Own Code=====

When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your development environment to properly link the Phidget C/C++ library. To begin:

1. Generate a new Visual C++: Win32 Console Application project with a descriptive name such as PhidgetTest.

[[File:VS2005 New Project.PNG|link=|alt=New Project]]

2. Next, select Console Application.

[[File:VS2005 New Project 2.PNG|link=|alt=New Project]]

3. Open the project properties window.

4. Navigate to Configuration Properties → C/C++.

5. Add {{Code|"C:\Program Files\Phidgets"}} to the additional directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Header.PNG|link=|alt=Header File]]

6. Navigate to Configuration Properties → Linker → Input.

7. Edit the additional dependencies and add {{Code|"C:\Program Files\Phidgets\phidget21.lib"}}. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Library.PNG|link=|alt=Library File]]

8. The project now has access to the Phidget function calls and you are ready to begin coding.

Then, in your code, you will need to include the Phidget C/C++ library:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

The same [[#Follow the Examples|teaching]] section which describes the examples also has further resources for programming your Phidget.

====Visual Studio 2003====

=====Use Our Examples=====

1. Start by downloading the [{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz examples]. You can import these examples into a Visual Studio 2003 C++ project. Afterwards, unpack them into a folder. Here, you can find example programs for all the devices. You will need this example source code to be copied into your C++ project later on. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

2. A new project will need to be created. Generate a new Visual C++ empty project(.NET) with a descriptive name such as HelloWorld.

[[File:VS2003 New Project.PNG|link=|alt=New Project]]

3. Create a new C++ file by adding a new item to the source files folder.

[[File:VS2003 New File.PNG|link=|alt=New File]]

[[File:VS2003 New File 2.PNG|link=|alt=New File]]

4. An empty C++ file will pop up. Please copy and paste the contents of the {{Code|HelloWorld.c}} program into here.

[[File:VS2003 Source.PNG|link=|alt=Source Code]]

5. Next, the project setting needs to be set up. Open the project properties window.

6. Navigate to Configuration Properties → C/C++.

7. Add {{Code|"C:\Program Files\Phidgets"}} to the additional include directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2003 Header.PNG|link=|alt=Header File]]

8. Navigate to Configuration Properties → Linker → Input.

9. Add {{Code|"C:\Program Files\Phidgets\phidget21.lib"}} to the additional dependencies field. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2003 Library.PNG|link=|alt=Library File]]

10. Now, you can run the example. Click on Debug → Start Without Debugging.

[[File:VS2003 Run.PNG|link=|alt=Run]]

11. This program will detect for devices that are attached/detached on the computer. Go ahead, and attach or detach your devices! Here is an example output:

[[File:VS2003 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|teaching]] section below to help you follow them.

=====Write Your Own Code=====

When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 2 | Use Our Examples]] section for instructions.

Then, in your code, you will need to include the Phidget C/C++ library:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

====Visual Studio C++ 6.0====

=====Use Our Examples=====

1. Download the [{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz examples] and unpack them into a folder. Here, you can find example programs for all the devices. You will need this example source code to be copied into your C++ project later on. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

2. Next, a new project will need to be created. Generate a new Win32 Console Application project with a descriptive name such as HelloWorld.

[[File:VS6 New Project.PNG|link=|alt=New Project]]

3. Create an empty project.

[[File:VS6 New Project 2.PNG|link=|alt=New Project]]

4. Next, the project settings needs to be set up. Navigate to Project → Settings → C/C++ → Preprocessor.

5. Add {{Code|C:\Program Files\Phidgets}} to the additional include directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS6 Header.PNG|link=|alt=Header File]]

6. Navigate to Project → Settings → Link → Input → Additional library Path.

7. Add {{Code|phidget21.lib}} to the object/library modules field.

8. Add {{Code|C:\Program Files\Phidgets}} to the additional library path. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS6 Library.PNG|link=|alt=Library File]]

The project now has access to the Phidget function calls and you are ready to begin coding.

To import the example program into your project, please:

9. Create a new C++ file by navigating to File → New → Files → C++ Source File and enter a descriptive name such as HelloWorld.

[[File:VS6 New File.PNG|link=|alt=New File]]

10. An empty C++ file will pop up. Please copy and paste the contents of the {{Code|HelloWorld.c}} program here.

[[File:VS6 Source.PNG|link=|alt=Source Code]]

11. Now, you can run the example. Click on Build → Execute.

[[File:VS6 Run.PNG|link=|alt=Run]]

12. This program will detect for devices that are attached/detached on the computer. Go ahead, and attach or detach your devices! Here is an example output:

[[File:VS6 HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|teaching]] section below to help you follow them.

=====Write Your Own Code=====

When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 3 | Use Our Examples]] section for instructions.

In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as shown in the [[#Use Our Examples 3 | Use Our Examples]] section.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===Borland===

====Use Our Examples====

In addition to running one of the two [[#Libraries and Drivers:| Windows Installers]] above (which you probably already have if you worked through the ''Getting Started'' page for your device), you will need the [{{SERVER}}/downloads/phidget21/libraries/windows/phidget21bcc.zip Borland C++ Libraries]. {{Code|phidget21bcc.lib}} is typically placed in {{Code|C:\Program Files\Phidgets}}, but you are free to place it in any directory you wish.

After installing the Phidget C/C++ library, you're ready to download the [{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz examples] and run the examples.

Afterwards, unpack the examples. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example. Locate the {{Code|HelloWorld.c}} file and type the following to compile the file and link the Phidget C/C++ library:

To compile, link the Phidget C/C++ library and build a binary executable, enter the following in a command line prompt in the directory with {{Code|HelloWorld.c}}:
<div class="source">
<syntaxhighlight lang=bash>
bcc32 -eHelloWorld -I"C:\Program Files\Phidgets" -L"C:\Program Files\Phidgets" phidget21bcc.lib HelloWorld.c
</syntaxhighlight>
</div>

It is assumed that {{Code|phidget21bcc.lib}} and {{Code|phidget21.h}} are placed in {{Code|C:\Program Files\Phidgets}}. If the files are placed in another location, please adjust the paths to both of the file's location accordingly.

In this case, {{Code|HelloWorld.c}} would be the '''.c''' file specific to your device. After using {{Code|bcc32}}, you will have an executable named {{Code|HelloWorld}} that you can run.

This program will detect for devices that are attached/detached on the computer. Go ahead, and attach or detach your devices! Here is an example output:

[[File:Borland HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

====Write Your Own Code====

When writing your code from scratch, you start it as you would any C/C++ code with Borland. In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the examples [[#Use Our Examples 4 |above]].

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===GCC on Windows===

====Cygwin/MinGW====

=====Use Our Examples=====

Download the [{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz examples] and unpack them into a folder. Afterwards, unpack the examples. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example. Locate the {{Code|HelloWorld.c}} file and type the following to compile the file and link the Phidget C/C++ library in a command line prompt:

<b>Cygwin</b>

<div class="source">
<syntaxhighlight lang=bash>
gcc example.c -o HelloWorld -I"/cygdrive/c/Program Files/Phidgets" -L"/cygdrive/c/Program Files/Phidgets" -lphidget21
</syntaxhighlight>
</div>

<b>MinGW</b>
<div class="source">
<syntaxhighlight lang=bash>
gcc example.c -o HelloWorld -I"C:\Program Files\Phidgets" -L"C:\Program Files\Phidgets" -lphidget21
</syntaxhighlight>
</div>

After using gcc, you will have an executable named {{Code|HelloWorld}} that you can run.
It is assumed that {{Code|phidget21.h}} and {{Code|phidget21.lib}} are placed in {{Code|C:\Program Files\Phidgets}}. If the files are placed in another location, please adjust the paths to the file's location accordingly.

After using {{Code|gcc}}, you will have an executable named {{Code|HelloWorld}} that you can run.

This program will detect for devices that are attached/detached on the computer. Go ahead, and attach or detach your devices! Here is an example output:

[[File:C MinGW HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

=====Write Your Own Code=====

When writing your code from scratch, you start it as you would any C/C++ code with Cygwin/MinGW in your favourite text editor. In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as shown in the [[#Use Our Examples 5| Use Our Examples]] section above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===Dev C++===

=====Use Our Examples=====

1. Download the [{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz examples] and unpack them into a folder. Here, you can find example programs for all the devices. {{FindYourDevice}} You will need this example source code to be copied into your Dev C++ project later on. The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} C/C++ example.

2. In order to control Phidgets with Dev C++, we will use the {{Code|reimp}} tool to convert the {{Code|phidget21.lib}} to a format that Dev C++ accepts. Download the [http://sourceforge.net/projects/mingw/ reimp tool]. Reimp is part of MinGW, a minimal UNIX emulator for Windows, and it is specifically within the mingw-utils package. You can check MinGW's [http://sourceforge.net/project/shownotes.php?release_id=126568 release notes] to ensure Reimp is in the version you are using.

3. Open up command line and traverse to the directory containing the reimp tool. Type the following command to create {{Code|libphidget21.a}}.
<div class="source">
<syntaxhighlight lang=bash>
reimp.exe "C:\Program Files\Phidgets\phidget21.lib"
</syntaxhighlight>
</div>
The command above assumes that the {{Code|phidget21.lib}} is in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly. Please note that the 64 bit version of {{Code|phidget21.lib}} is not supported on Dev C/C++. Please use the 32 bit version of {{Code|phidget21.lib}}.

4. Place {{Code|libphidget21.a}} in {{Code|<Dev-Cpp Install Directory>/lib}}.

5. Next, a new project will need to be created. Generate a new console application with a descriptive name such as PhidgetTest. Please select C as the project type.

[[File:DevC New Project.PNG|link=|alt=New Project]]

6. Next, the project settings needs to be set up. Navigate to Project Options → Directories → Include Directories.

7. Add a new path to {{Code|C:\Program Files\Phidgets}}. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:DevC Header.PNG|link=|alt=Header File]]

8. Navigate to Project Options → Parameters → Linker.

9. Add {{Code|-lphidget21}} to the field. This step will find the {{Code|libphidget21.a}} file in {{Code|<Dev-Cpp Install Directory>/lib}}.

[[File:DevC Library.PNG|link=|alt=Library File]]

10. To import the {{Code|HelloWorld}} program into your project, please open up {{Code|main.c}} in the editor.

11. An empty C file will pop up. Please copy and paste the contents of the example program.

[[File:DevC Source.PNG|link=|alt=Source Code]]

12. Now, you can run the example. Click on Execute → Compile & Run.

[[File:DevC Run.PNG|link=|alt=Run]]

13. This program will detect for devices that are attached/detached on the computer. Go ahead, and attach or detach your devices! Here is an example output:

[[File:DevC HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the C/C++ examples running, we have a [[#Follow the Examples|teaching]] section below to help you follow them.

=====Write Your Own Code=====

When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 6 | Use Our Examples]] section for instructions.

In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the [[#Use Our Examples 6 | examples]] above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

===Code::Blocks===
=====Use Our Examples=====
The process for getting Phidgets working in Code::Blocks is much the same as [[#Dev C++|Dev-C++]]. You will need to download the reimp tool that is linked there and use it on the phidget21.lib file as instructed. After the .a file has been created you can stick it in your /Phidgets folder with the rest of the Phidget library files.

Now that that has been done, open one of the example files that you would like to run, for example InterfaceKit-simple.c. Under the Settings menu, choose "Compiler and debugger..."

[[File:compilersettings.png|link=|916px]]

Go to the "Search directories" tab and add a new entry. Choose your Phidgets installation directory.

[[File:searchdirectories.png|link=|500px]]

Under the "Linker settings" tab add a new entry and type in "phidget21".

[[File:linkersettings.png|link=|500px]]

You can now compile and run the example.

=====Write Your Own Code=====

When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your development environment to properly link the Phidget C/C++ library. Please see the [[#Use Our Examples 6 | Use Our Examples]] section for instructions.

In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the [[#Use Our Examples 6 | examples]] above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

==OS X==

C/C++ has excellent support on OS X through the gcc compiler.

The first step in using C/C++ on Mac is to install the Phidget C/C++ library. Compile and install them as explained on the Getting Started guide for your device, which you can find in its [[:Category:UserGuide|user guide]]. Then, the [[OS - OS X#Description of Library files|OS - OS X]] page also describes the different Phidget files, their installed locations, and their roles.

===Use Our Examples===

After installing the main Phidget library for OS X as above, you're ready to download the [{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz examples]. Afterwards, unzip the file. To run the example code, you'll need to find the source code ''for your specific device''. Then, compile the code under your platform and run it.

To compile, link the Phidget C/C++ library, and build an executable binary on OS X, do (for example, depending on the Headers location):

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

gcc example.c -o example -F/Library/Frameworks -framework Phidget21 -I/Library/Frameworks/Phidget21.framework/Headers
</syntaxhighlight>
</div>

After using gcc, you will have an executable named {{Code|example}} that you can run.

===Write Your Own Code===

When writing your code from scratch, you must include a reference to the library header:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as shown in the [[#Use Our Examples 7|Use Our Example]] section above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples. Even more help and references are provided from there.

==Linux==

C/C++ has support on Linux through the gcc compiler.

The first step in using C/C++ on Linux is to install the Phidget libraries. Compile and install them as explained on the main [[OS - Linux | Linux page]]. That Linux page also describes the different Phidget files, their installed locations, and their roles.

===Use Our Examples===

After installing the Phidget libraries for Linux as above, you're ready to download and run the examples:
*[{{SERVER}}/downloads/phidget21/examples/c/phidget21-c-examples.tar.gz Generic C/C++ Examples]

To run the example code, you'll need to download and unpack the examples, and then find the source code for your device. {{FindYourDevice}} You can also use the HelloWorld program, which a basic program that can run with any Phidget. Then, compile the code under your platform and run it. When compiling, you need to link to the Phidget library.

To compile, link the Phidget libraries and build a binary executable on Linux, do the following in a terminal in the directory with {{Code|example.c}}:

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

In this case, {{Code|example.c}} would be the '''.c''' file specific to your device. After using gcc, you will have an executable named {{Code|example}} that you can run.

On Linux, if you have not set up [[OS_-_Linux#Setting_udev_Rules | your udev rules for USB access]], you will need to run the program '''as root''':

<div class="source">
<syntaxhighlight lang=bash>
sudo ./example
</syntaxhighlight>
</div>

===Write Your Own Code===

When writing your code from scratch, you start it as you would any C/C++ code on Linux, such as within a text editor like Emacs, Vi, Gedit, or Kate. In your '''{{Code|.c}}''' source code file, you must include a reference to the library header:

<div class="source">
<syntaxhighlight lang=cpp>
#include <phidget21.h>
</syntaxhighlight>
</div>

Then, you would compile your completed C/C++ code the same way as the examples above.

To learn how to write your own code for your Phidget, and to learn more about our API, we have a [[#Follow the Examples|teaching]] section to help you follow the provided C/C++ examples and which has resources such as the API reference.

==Windows CE==

===Description of Library Files===
C/C++ programs on Windows CE depend on the following files, which the Windows CE installer puts onto your system:
* <b>{{Code|phidget21.dll}}</b> contains the actual Phidget library, which is used at run-time. It is placed in {{Code|\Windows}}.
* <b>{{Code|PhidgetWebService21.exe}}</b> is used to control Phidgets remotely across a network using the [[#WebService | PhidgetWebService]]. It can be placed anywhere on the system.
* <b>{{Code|phidget21.lib}}</b> is used by your compiler to link to the dll. Your compiler has to know where this file is.
* <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.
* <b>{{Code|phidget.dll}}</b> is the Phidgets kernel driver. It is placed in {{Code|\Windows}}.

===Visual Studio 2005/2008/2010===

=====Use Our Examples=====

Currently, we have no example code for C/C++ on Windows CE. However, set up is very much the same as what it would be with [[#Visual Studio 2005/2008/2010 |Visual Studio 2005/2008/2010]] in Windows. The {{Code|phidget21.h}} and {{Code|phidget21.lib}} can be downloaded [{{SERVER}}/downloads/phidget21/libraries/windows/Phidget21-windevel.zip here].

=====Write Your Own Code=====

When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your development environment to properly link the Phidget C/C++ library. To begin:

1. Generate a new Visual C++: Win32 Smart Device project with a descriptive name such as PhidgetTest.

[[File:WinCE VS C NewProject 1.PNG|link=|alt=New Project]]

2. Select {{Code|Next}}.

[[File:WinCE VS C NewProject 2.PNG|link=|alt=New Project]]

3. Select the SDK(s) that you want to code against and elect {{Code|Next}}.

[[File:WinCE VS C NewProject 3.PNG|link=|alt=SDKs]]

4. Create a console application and select {{Code|Next}}.

[[File:WinCE VS C NewProject 4.PNG|link=|alt=Create Console Application]]

3. Open the project properties window.

4. Navigate to Configuration Properties → C/C++.

5. Add {{Code|"C:\Program Files\Phidgets"}} to the additional directories field. This step will find the {{Code|phidget21.h}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Header.PNG|link=|alt=Header File]]

6. Navigate to Configuration Properties → Linker → Input.

7. Edit the additional dependencies and add {{Code|"C:\Program Files\Phidgets\phidget21.lib"}}. This step will find the {{Code|phidget21.lib}} file in the corresponding directory. If the file is placed in another location, please adjust the path to the file's location accordingly.

[[File:VS2005 Library.PNG|link=|alt=Library File]]

8. The project now has access to the Phidget function calls and you are ready to begin coding.

Then, in your code, you will need to include the Phidget C/C++ library:

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

#include <phidget21.h>

</syntaxhighlight>
</div>

The same [[#Follow the Examples|teaching]] section which describes the examples also has further resources for programming your Phidget.

==Follow the Examples==

By following the instructions for your operating system and compiler above, you probably now have a working example and want to understand it better so you can change it to do what you want.

Your main reference for writing C code will be our C/C++ API information, with syntax for all of our functions:

{{UsingAPhidgetInCodeGeneral|both of which are available in C/C++|[{{SERVER}}/documentation/Phidget21_C_Doc.zip C/C++ API]}}

===Example Flow===

{{ExamplePseudocode|In C/C++, you can name these '''event''' functions whatever you like. You will then pass them as function pointers to the Phidget library below in the Main Code section. This hooks them into the actual events when they occur. <br>
In the example code, the event functions common to all Phidgets are called things like '''AttachHandler()''' and '''DetachHandler()''', etc.<br><br>
Some event functions will be specific to each device, like when a tag is read on an RFID board, or when a sensor value changes on an Interface Kit.
Other functions are given in the examples to show you more detail on using your Phidget. For example, '''DeviceInitialize()''' will show what needs to be set up for your Phidget before using it.
|Creating a Phidget software object in C is specific to the Phidget. For a Phidget Spatial, for example, this would involve creating an object with the {{Code|CPhidgetSpatialHandle}} type, and then initializing it using the {{Code|CPhidgetSpatial_create function}}. The examples show how to do this and other API functions.<br><br>
Other C calls follow a similar syntax - {{Code|CPhidgetXXX_function}}, where XXX is the name of your device, and function is an action available from the API for your specific Phidget.|
[{{SERVER}}/documentation/Phidget21_C_Doc.zip C/C++ API]}}

===Code Snippets===

When programming in C/C++, you're in luck. All of our code snippet examples on our [[General Phidget Programming]] page are in both C++ and Java. Therefore, we do not include any here, because that page is much more in-depth, and you won't have to have two pages open at once. So head over there, and start writing code!

===C++ Events===
If you want to use C++ style, object-oriented events you can do that as well. The following examples show you how to do this:

*[{{SERVER}}/docs21/images/0/05/Simple.cpp Main]
*[{{SERVER}}/docs21/images/1/11/Simple.h Header]

==Common Problems and Solutions/Workarounds==

===Issue: I am using a non US-English version of Windows, and the Visual C/C++ examples run into a linker error===
Affected Operating Systems: '''Windows'''

The example projects, by default finds the {{Code|phidget21.h}} and {{Code|phidget21.lib}} in ${SystemDrive}\Program Files\Phidgets. If you are using a non US-English version of Windows, the Phidget drivers may be installed into a different location. To resolve, you will have to modify the paths to these two files. For instructions, please see your environment/compiler section.

USB Webcam Primer

2017-06-07T20:58:23Z

Patrick:

[[Category: Primer]]

{|
|- valign=middle
| align=center width=300px| __TOC__
| {{SERVER}}/images/3402_0_Web.jpg
|}

==Introduction==

Webcams come in many forms, but the USB ones usually come as UVC (USB Video Class) devices. This primer gives a very brief overview of what they are and how to use them.

==Advantages==

The advantage of UVC devices is their cross-platform compatibility, especially within the various flavours of Linux.

*[http://en.wikipedia.org/wiki/USB_video_device_class Wikpedia] gives a good overview of their levels of compatibility
* Many devices other than the Phidget webcam use the same protocol, please refer to [http://www.ideasonboard.org/uvc/#devices a compatibility list]

==Use==

A UVC device should be truly plug and play. Even on the [{{SERVER}}/products.php?product_id=1072 Phidget Single Board Computer], the drivers are already installed. You can almost immediately begin using video capture programs on your operating system to record video or pictures.

Examples include:

* Capture from Windows media players and creators
* Use iMovie on Mac OS X
* Use Cheese on Linux ({{Code|sudo apt-get install cheese}})

However, these programs are usually graphical programs which don't help if you want to use the webcam in code.

===Code===

Regardless of your platform, a good place to start is [http://opencv.willowgarage.com/wiki/ OpenCV]. It is a library for C/C++ that focuses solely on processing images and video. It also has bindings to other languages like Python.

We also offer a programming example in C# to use the webcam:

*[{{SERVER}}/downloads/misc/MJPEGDecoder.zip C# Program]

Additional advice by operating system is below.

====Phidget SBC====

Any UVC webcam device should work interchangeably with any other UVC webcam device, So you don't have to use the Phidget one, you can find one that fits your needs.

On our Single Board Computer (SBC) page, we give an example of how to use a UVC webcam to take pictures using the SBC and OpenCV in code:
*[[OS - Phidget SBC#Taking Pictures With the Webcam|Taking Pictures with the Webcam]]

====Windows====

On Windows, [http://opencv.willowgarage.com/wiki/ OpenCV] is your best bet.

====Linux====

On full Linux systems, you can possibly use OpenCV, though there have been some problems on standard Ubuntu distributions.<br>
Alternatively, you can use the program {{Code|streamer}} which can then be used in code:
:{{Code|sudo apt-get install streamer}}
:{{Code|streamer -c /dev/video0 -b 16 -o output.jpg}}

==Did You Know==

The UVC standard outlines more than just picture taking - it can control pan, tilt, resolution, etc depending on the functionality for your camera. This is how the Phidget SBC controls what resolution is displayed on its [[1072_User_Guide#SBC Web Interface|Web Interface]].

If you want to play with these advanced features, and you own an SBC, you can look at the scripts in {{Code|/var/www/}} on the SBC.

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

Language - Ruby

2017-06-07T20:56:21Z

Patrick:

[[Category:Language]]
{{OSLang|[[File:Icon-Ruby.png|64x64px|link=|alt=]]|Ruby is an interpreted and object oriented scripting language with simple syntax created by [http://en.wikipedia.org/wiki/Yukihiro_Matsumoto Yukihiro Matsumoto].}}

__TOC__

==Introduction==

{{LanguageSupport|Ruby|the complete Phidget API, including events|all Phidget devices.|Linux and OS X|}}

==Quick Downloads==

{{QuickDownloads|Ruby|
{{APIQuickDownloads|http://www.rubydoc.info/gems/phidgets-ffi/frames RubyDoc}}|
{{ExampleQuickDownloads|http://rubygems.org/gems/phidgets-ffi| (on RubyGems Server)}}|
{{ExtraLibraryQuickDownloads|http://rubygems.org/gems/phidgets-ffi|Ruby| (on RubyGems Server)}}
{{MacQuickDownloads}}
{{LinuxQuickDownloads}}}}

===3rd Party Library===
The following library was submitted by a user and is an alternative means for using Phidgets in Ruby. It is only suitable for the Spatial, GPS, Interface Kit, and Advanced Servo product lines but more may follow.

*[https://github.com/brighton36/phidgets_native Link]

Please note that this is not Phidgets' official library and we take no responsibility for issues stemming from its use nor are we able to support the library ourselves. We are merely making this available for users who wish for an alternative to our own libraries.

==Getting started with Ruby==

If you are new to writing code for Phidgets, we recommend starting by running, then modifying existing examples. This will allow you to:
{{ExampleCodeReasons}}

Instructions for OS X and Linux are similar, so they are combined [[#OS X and Linux|into the same section]].
'''Although Ruby can run on Windows, we do not offer official support for the Phidgets libraries using Ruby on Windows.'''

==OS X and Linux==

Here, we walk you through installing the libraries both on your operating system and within Ruby, and then we walk through examples and writing code from scratch.

===Install the Phidget drivers and libraries===

The first step in using Ruby on OS X or Linux is to install the Phidget libraries. The best way to do this is to go through the ''Getting Started'' guide for your device. This guide can be found in the [[:Category:UserGuide|user guide]].

This process of installing will put the Phidget libraries on your system. Ruby programs on OS X and Linux depend on the following files from the Phidget libraries:

If you are using OS X:
* <b>{{Code|Phidget21.framework}}</b> contains the actual Phidgets library for OS X, which is used at run-time.

If you are using Linuxe:
* <b>{{Code|libphidget21.so}}</b> contains the actual Phidgets library for Linux, which is used at run-time.

===Install phidgets-ffi===

For both OS X and Linux, you will need the ffi and phidgets-ffi Ruby gems to run Phidgets. This requires that you have RubyGems set up so that you can download and install gems (i.e. third-party software) to plug into Ruby and use. The phidgets-ffi gem contains the Ruby library for Phidgets, and Phidgets example code.

For more information, please see phidgets-ffi at [http://rubygems.org/gems/phidgets-ffi RubyGems] and [https://github.com/kreynolds/phidgets-ffi GitHub].

Both Ruby and RubyGems are part of the Debian Linux repository. Both Ruby and RubyGems are a part of Mac OS X 10.5 and higher.

RubyGems will give you the command line program {{Code|gem}}. This is the program you can use to install the phidgets-ffi and ffi gems. First use it to install the [http://rubygems.org/gems/ffi ffi gem]:

<div class="source">
<syntaxhighlight lang=bash>
gem install ffi
</syntaxhighlight>
</div>

Note that this should be run using '''{{Code|sudo}}''' on Linux. A version of ffi 1.0.9 or greater is needed. Next, please install the phidgets-ffi gem by typing the following into the command line:

<div class="source">
<syntaxhighlight lang=bash>
gem install phidgets-ffi
</syntaxhighlight>
</div>

Note that this should be run using '''{{Code|sudo}}''' on Linux. For OS X systems, the gem will be installed into {{Code|/Library/Ruby/Gems/1.x/phidgets-ffi-x.x.x}}. For typical Linux systems, the gem will be installed into {{Code|var/lib/gems/1.x/gems/phidgets-ffi-x.x.x}}.

===Use Our Examples===

Open a command line terminal and navigate to the phidgets-ffi gem directory. {{Code|cd}} into the {{Code|examples}} folder. Here, you will find all of the examples available for Ruby, including a Hello World example that will work with any Phidget. You will also find source code examples specifically designed for each Phidget. {{FindYourDevice}}

The easiest way to confirm that your environment is set up properly will be to compile and run the {{Code|HelloWorld}} Ruby example.

The only thing left to do is to run the examples! Type the following into command line:

<div class="source">
<syntaxhighlight lang=bash>
ruby HelloWorld.rb
</syntaxhighlight>
</div>

Note that, on Linux, unless you have your [[OS_-_Linux#Setting_udev_Rules|udev rules set]], you will need to run Phidgets programs using '''{{Code|sudo}}'''.

This program will detect for devices that are attached/detached on the computer. Go ahead, and attach or detach your devices! Here is an example output:

[[File:Ruby Linux HelloWorld Output.PNG|link=|alt=HelloWorld Output]]

After confirming that the {{Code|HelloWorld}} example is working, you can proceed to run the example for your device. {{FindYourDevice}}

Once you have the Ruby examples running, we have a [[#Follow the Examples|teaching]] section below to help you follow them.

===Write Your Own Code===

When you are building a project from scratch, or adding Phidget function calls to an existing project, you'll need to configure your environment to properly link the Phidget Ruby libraries.

Simply, add the following two lines to the beginning of any {{Code|.rb}} script to make use of the phidgets-ffi gem

<div class="source">
<syntaxhighlight lang=ruby>
require 'rubygems'
require 'phidgets-ffi'
</syntaxhighlight>
</div>

The project now has access to the Phidget21 function calls and you are ready to begin coding.

The same [[#Follow the Examples|teaching ]] section which describes the examples also has further resources for programming your Phidget.

==Follow the Examples==

By following the instructions for your operating system and compiler above, you probably now have a working example and want to understand it better so you can change it to do what you want. This teaching section has resources for you to learn from the examples and write your own.

Your main reference for writing Ruby code will be our Ruby API information, with syntax for all of our functions:

{{UsingAPhidgetInCodeGeneral|both of which are available in Ruby|[{{SERVER}}/documentation/rubydoc Ruby API]}}

===Example Flow===

{{ExamplePseudocode|In Ruby, you catch these events thrown by Phidgets (on a sensor data change, for example) by using the '''do''' command. There are many events for each Phidget, such as device.on_attach, where device is your Interface Kit, Temperature Sensor, etc, etc. <br>
Some event functions will be common to all Phidgets (attach and detach), and some will be specific to each device, like when a tag is read on an RFID board, or when a sensor value changes on an Interface Kit.
|Creating a Phidget software object in Ruby is specific to the Phidget. For a Phidget Spatial, for example, this would involve creating a {{Code|Spatial}} object. The examples show how to do this and other API functions.<br><br>
The object provides device specific methods and properties which are available from the API for your specific Phidget.|
[{{SERVER}}/documentation/rubydoc Ruby API]}}

===Code Snippets===

Specific calls in Ruby will differ in syntax from those on the [[General Phidget Programming]] page, but the concepts stay the same.

It may help to have the [[General Phidget Programming]] page and this section open at the same time, because they parallel each other and you can refer to the Ruby syntax. However, many additional concepts are covered on the General Phidget Programming page on a high level, such as using multiple Phidgets, handling errors, and different styles of programming.

For example, if we were using a [{{SERVER}}/products.php?product_id=1018 Phidget Interface Kit] as our device, our code snippets would look something like those shown here.

====Step One: Initialize and Open====

The Phidget constructor method will need to be called to create the Phidget object. There are two methods or programming a Phidget in Ruby: with and without a block.

=====Block Programming=====

To initialize and open a Phidget with a block of code following, for example, use this structure:

<div class="source">
<syntaxhighlight lang=ruby>
Phidgets::InterfaceKit.new do |device|
..
end
</syntaxhighlight>
</div>

Note that with block programming, the block between '''do....end''' is your entire program. As described in detail in the [[#Step Two: Wait for Attachment (plugging in) of the Phidget|next code snippet]], a block of code will automatically wait for the Phidget to finish opening and attaching, and will automatically call close on the Phidget at the end of the block.

=====Non Block Programming=====

To simply create and open a Phidget of a certain type - in this case an Interface Kit - use this structure:

<div class="source">
<syntaxhighlight lang=ruby>
device = Phidgets::InterfaceKit.new
</syntaxhighlight>
</div>

The object name for any type of Phidget is listed in the API manual. Here we use the Phidget Interface Kit (the Phidget with digital inputs, outputs, and analog sensor ports), but if you have a different Phidget like a Motor Controller, or a Temperature Sensor, or a Spatial, you would use the software object for your specific Phidget. Every type of Phidget also inherits functionality from the Phidget base class.

=====Options for Open=====

Options can be added to the Open constructor to connect to the first Phidget (of a certain type) that it finds, based on its serial number, label, or even connect across the network. [http://rubydoc.info/gems/phidgets-ffi/0.1.1/frames Rubydocs API documentation] lists all of the available modes that the constructor provides.

For example, the following will try to connect to the first Phidget it finds:

<div class="source">
<syntaxhighlight lang=ruby>
device= Phidgets::InterfaceKit.new
</syntaxhighlight>
</div>

The following will try to connect to a Phidget over the Phidget WebService with a serial number of {{Code|99999}}, and a server id of {{Code|myserver}}:
<div class="source">
<syntaxhighlight lang=ruby>
options = {:serial_number => 99999, :server_id => ‘myserver’, :password => nil}
device= Phidgets::InterfaceKit.new(options)
</syntaxhighlight>
</div>

One important thing to remember is that when working with Phidgets, a local connection will reserve the device until closed. This prevents any other instances from retrieving data from the Phidget, including other programs. The one connection per device limit does not apply when exclusively using the [[Phidget WebService]].

{{Code|Phidgets::InterfaceKit.new}} will tell the program to continuously try to connect to a Phidget, based on the options given (if any), and will even try to reconnect if it gets disconnected.

====Step Two: Wait for Attachment (plugging in) of the Phidget====

To use the Phidget, it must be plugged in (attached). Like the create ("new") call above, there are blocking and non-blocking methods of detecting and handling attachment. Attachment in software must be handled for all Phidgets. We can handle it by using event driven programming and tracking the {{Code|on_attach}} and {{Code|on_detach}} events, or by calling: {{Code|wait_for_attachment}}.

=====Block Programming=====

If you are programming inside a block, {{Code|wait_for_attachment}} is automatically called. By default, it will halt the program and try to connect to the Phidget for up to 1000 milliseconds. Afterwards, the block will yield. Finally, close is not needed as it is automatically called once the block has finished.

<div class="source">
<syntaxhighlight lang=ruby>
options = {:timeout => 2000)
Phidgets::InterfaceKit.new(options) do |device|
...
end
</syntaxhighlight>
</div>

=====Non Block Programming=====

For the non block programming method, simply calling the constructor does not guarantee you can use the Phidget immediately. The {{Code|wait_for_attachment}} call will block indefinitely until a connection is made to the Phidget, or an optional timeout is exceeded.

<div class="source">
<syntaxhighlight lang=ruby>
device= Phidgets::InterfaceKit.new
device.wait_for_attachment 2000 #halt the program for up 2000 milliseconds or until the Phidget is connected
</syntaxhighlight>
</div>

Please also remember to call close at the end or the program to free any locks on the Phidget

<div class="source">
<syntaxhighlight lang=ruby>
device.close
</syntaxhighlight>
</div>

=====Event Programming=====

Sometimes, it makes more sense to handle the attachment via an event. This would be in instances where the Phidget is being plugged and unplugged, and you want to handle these incidents. Or, when you want to use event-driven programming because you have a GUI-driven program. In these cases, you would use the non-blocking method of creating and opening the Phidget ("new"), and use an event driven function to handle the attach event when thrown. An event-driven code snippet to handle the attachment might look something like this:

<div class="source">
<syntaxhighlight lang=ruby>
device.on_attach do |device, obj|
puts "Id: #{device.id}"
puts "Serial number: #{device.serial_number}"
end
</syntaxhighlight>
</div>

====Step Three: Do Things with the Phidget====

You can read data and interact with your Phidget both by polling it for its current state (or to set a state), or by catching events that trigger when the data changes.

For our [{{SERVER}}/products.php?product_id=1018 Phidget Interface Kit], the polling method of getting the current sensor state and setting an output state looks something like this:

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

# Get a data point from Analog Port 0
puts "Sensor value[0]: #{device.sensors[0].to_i}"

# Set digital output port 0 to be on
device.outputs[0].state = true

</syntaxhighlight>
</div>

To catch data changes via events, you would use something like this:

<div class="source">
<syntaxhighlight lang=ruby>
device.on_sensor_change do |device, input, value, obj|
puts "Sensor #{input.index}'s value has changed to #{value}"
end
</syntaxhighlight>
</div>

====Step Four: Close====

If you are using the block programming method, you do not need to worry about closing the Phidget; it is already taken care of when the block ends. However, if you are using the non block programming method, then you will need ensure that the Phidget is closed. At the end of your program, call {{Code|close}} to free any locks on the Phidget that the Phidget constructor call put in place!

<div class="source">
<syntaxhighlight lang=ruby>
device.close
</syntaxhighlight>
</div>

{{MoreHowTos}}

The ''complete'' set of functions you have available for all Phidgets can be found in the [http://rubydoc.info/gems/phidgets-ffi/0.1.1/frames Ruby API]. You can also find more description on any device-specific function in the Device API page for your specific Phidget, which can be found in its [[:Category:UserGuide|user guide]].

====Raw FFI====

As an alternative to programming with the method as outlined in this document, you can also program making straight C calls through FFI. Please refer to the files in {{Code|Ruby Gems Directory/phidgets-ffi-x.x.x/lib/phidgets-ffi/ffi}} to see a list of available methods, and the [{{SERVER}}/documentation/Phidget21_C_Doc.zip C API] for usage. There are raw ffi examples in {{Code|Ruby Gems directory/phidgets-ffi-x.x.x/examples/raw-ffi}}.

==Common Problems and Solutions/Workarounds==

None at this time.

OS - Phidget SBC

2017-05-24T19:10:21Z

Patrick:

[[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|SBC3 Getting Started Guide]] right out of the box.

*[[Software License]]

'''For PhidgetSBC (1070):'''
*[{{SERVER}}/downloads/phidgetsbc/1070/changelog.txt changelog]
*[{{SERVER}}/downloads/phidgetsbc/1070/phidgetsbc-minimal.bin Minimal Firmware]
*[{{SERVER}}/downloads/phidgetsbc/1070/phidgetsbc-full.bin Full Firmware]
*[{{SERVER}}/downloads/phidgetsbc/1070/buildroot-phidgetsbc.tar.gz Buildroot/Kernel Sources]
'''For PhidgetSBC2 (1072):'''
*[{{SERVER}}/downloads/phidgetsbc/1072/changelog.txt changelog]
*[{{SERVER}}/downloads/phidgetsbc/1072/phidgetsbc2.bin SBC2 Firmware]
*[{{SERVER}}/downloads/phidgetsbc/1072/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package] (How-to and patch file)
'''The PhidgetSBC3 has different firmware packages based on the kernel version. In order to determine the device version of your SBC3, see the [[1073_User_Guide#SBC_Web_Interface|web configuration page]].'''

[[File:sbcver.jpg|thumb|562px|link=|The system information table is found on the Status -> System tab of the '''[[1073_User_Guide#SBC_Web_Interface|web configuration page]]''' of the SBC.]]
'''For PhidgetSBC3 (1073) kernel version 3.6.3:'''
*[{{SERVER}}/downloads/phidgetsbc/1073/changelog.txt changelog]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.6.3/phidgetsbc3.bin SBC3 Firmware]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.6.3/phidgetsbc3-kerneldev.tar.gz SBC3 Kernel Development Package]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.6.3/phidgetsbc3-upgrade_3.6.3_3.14.27.tar.gz SBC3 Kernel upgrade package (3.6.3 -> 3.14.27)]
'''For PhidgetSBC3 (1073) kernel version 3.14.27:'''
*[{{SERVER}}/downloads/phidgetsbc/1073/changelog.txt changelog]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.14.27/phidgetsbc3.bin SBC3 Firmware]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.14.27/phidgetsbc3-update_3.14.27.tar.gz SBC3 Kernel update package (3.14.27)]
*[{{SERVER}}/downloads/phidgetsbc/1073/linux-3.14.27/phidgetsbc3-kerneldev.tar.gz SBC3 Kernel Development Package]

Note that, instead of using the firmware to update your SBC, updates should normally be done via the System -> Packages page on your SBC3 web interface. It is rarely necessary to completely re-flash your device..
<br clear = all>

==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. If the installation fails because it can't find python, you need to enable the full repository as described in [[#Getting Started_-_The_SBC_(Debian_Linux)|this section]], and then perform an apt-get update.

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

====For SBC2:====

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

====For SBC3:====

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r $ROOTFS/ system_ubifs.img
ubinize -o system_ubi.img -m 4KiB -p 256KiB 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=83MiB
# 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.

===Saving a file system to flash to multiple SBC's===
You may want to create a complete backup of your SBC root filesystem, which can then be flashed to other SBCs. This is how it could be done:

You will need a USB drive - we have had issues using cheap flash drives, so a real USB drive is recommended. Make sure it's empty, as it will be reformatted.

All of these commands are executed on your SBC, while logged in over SSH.

First, re-format the USB drive as ext3. Assuming the USB drive is sda and has a single partition:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
mkfs.ext3 /dev/sda1
mount -t ext3 /dev/sda1 /media/usb0
</syntaxhighlight>
</div>

Then, remount / as readonly, so it doesn't change as we're copying it. To do this, we need to kill all running processes except sshd:

<div class="source">
<syntaxhighlight lang=bash>
service udev stop
service ifplugd stop
service rsyslog stop
service avahi-daemon stop
service phidgetwebservice stop
service ntp stop
service busybox-httpd stop
service dbus stop
service cron stop
pkill dhclient
mount -o remount,ro /
</syntaxhighlight>
</div>

If the remount says that / is busy, do a 'ps auxww' and 'pkill' anything else that may be running until it remounts properly.

Then, copy / to the flash drive:

<div class="source">
<syntaxhighlight lang=bash>
mkdir /media/usb0/root
mount --bind / /mnt/
cp -a /mnt/* /media/usb0/root/
</syntaxhighlight>
</div>

Then, clean up the copy - removing files specific to this board. We also remove the APT cache to save space.

<div class="source">
<syntaxhighlight lang=bash>
find /media/usb0/root/var/log -type f -print0 | xargs -0 rm -f
rm -rf /media/usb0/root/var/lib/apt/lists/*
mkdir /media/usb0/root/var/lib/apt/lists/partial
rm -f /media/usb0/root/var/cache/apt/*.bin
rm /media/usb0/root/etc/udev/rules.d/70-persistent-net.rules
rm /media/usb0/root/etc/ssh/ssh_host_*
</syntaxhighlight>
</div>

then, create the ubinize.cfg file:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=83MiB
vol_type=dynamic
vol_name=rootfs0
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=64128KiB
vol_type=dynamic
vol_name=rootfs
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

NOTE: you may need to increase vol_size if your filesystem is larger.

then, create the UBI image from the copy:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 4KiB -p 256KiB ubinize.cfg
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -m 2KiB -e 126KiB -c 4050 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 2KiB -p 128KiB -s 512 ubinize.cfg
</syntaxhighlight>
</div>

then, unmount the drive to ensure everything is written out properly:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
</syntaxhighlight>
</div>

Then, you can remove the /root/ folder and system_ubifs.img. system_ubi.img can be flashed to other SBCs using the recovery system.

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

MediaWiki:Common.js

2017-04-12T18:36:00Z

Patrick:

/**
* Redirect User:Name/skin.js and skin.css to the current skin's pages
* (unless the 'skin' page really exists)
* @source: http://www.mediawiki.org/wiki/Snippets/Redirect_skin.js
* @rev: 2
*/
if ( mw.config.get( 'wgArticleId' ) == 0 && mw.config.get( 'wgNamespaceNumber' ) == 2 ) {
var titleParts = mw.config.get( 'wgPageName' ).split( '/' );
// Make sure there was a part before and after the slash
// And that the latter is 'skin.js' or 'skin.css'
if ( titleParts.length == 2 ) {
var userSkinPage = titleParts.shift() + '/' + mw.config.get( 'skin' );
if ( titleParts.slice(-1) == 'skin.js' ) {
window.location.href = mw.util.wikiGetlink( userSkinPage + '.js' );
} else if ( titleParts.slice(-1) == 'skin.css' ) {
window.location.href = mw.util.wikiGetlink( userSkinPage + '.css' );
}
}
}

// Book specific
var wgBookName = ( mw.config.get( 'wgPageName' ).split( '/', 1)[0] || '' ).split( ':', 2 ).join( ':' );
importStylesheet('MediaWiki:Common.css/' + wgBookName);

// Imported scripts
importScript('MediaWiki:Common.js/Relics.js');
importScript('MediaWiki:Common.js/ExtraTools.js');
importScript('MediaWiki:Common.js/CollapseElements.js');
importScript('MediaWiki:Common.js/NavigationTabs.js');
importScript('MediaWiki:Common.js/Displaytitle.js');
importScript('MediaWiki:Common.js/RandomBook.js');
importScript('MediaWiki:Common.js/Perbook.js');
importScript('MediaWiki:Common.js/tabs.js');
importScript('MediaWiki:Common.js/top.js');
importScript('MediaWiki:Common.js/review.js');
importScript('MediaWiki:Common.js/Categories.js');
importScript('MediaWiki:Common.js/use.js');

if ( mw.config.get( 'wgCanonicalSpecialPageName' ) == 'Watchlist' ) {
importScript('MediaWiki:Common.js/WatchlistNotice.js');
} else if ( $.inArray( mw.config.get( 'wgAction' ), ['edit', 'submit', 'upload'] ) != -1 ) {
importScript('MediaWiki:Common.js/Special_characters.js');
importScript('MediaWiki:Common.js/Toolbox.js');
}

// Load sysop-specific JavaScript/CSS from [[MediaWiki:Common.js/Sysop.js]] and [[MediaWiki:Common.css/Sysop.css]]
if ( $.inArray( 'sysop', mw.config.get('wgUserGroups')) > -1 ) {
importStylesheet('MediaWiki:Common.css/Sysop.css');
if ( !window.disableSysopJS ) {
$(function(){
importScript('MediaWiki:Common.js/Sysop.js');
});
}
}

MediaWiki:Common.css

2016-10-31T10:19:29Z

Patrick:

/*////////////////////////////////////////////////////////////////////////////////////////////////////////
// Hides the title for specific pages
*/
body.page-Main_Page h1.firstHeading { display:none; }
body.page-RTD_Ad_Landing_Page h1.firstHeading { display:none; }
body.page-Temperature_and_Humidity_Ad_Landing_Page h1.firstHeading { display:none; }
body.page-Ambient_Temperature_Ad_Landing_Page h1.firstHeading { display:none; }
body.page-IR_Temperature_Ad_Landing_Page h1.firstHeading { display:none; }
body.page-Thermocouple_Ad_Landing_Page h1.firstHeading { display:none; }
body.page-Temperature_Ad_Landing_Page h1.firstHeading { display:none; }

/*////////////////////////////////////////////////////////////////////////////////////////////////////////
// Hides category links at bottom of pages
*/
#catlinks { display: none; }
#mw-normal-catlinks { display: none; }

/*////////////////////////////////////////////////////////////////////////////////////////////////////////
// Hides the thumbnail magnify link and the "powered by mediawiki" icon.
*/
.magnify {display: none}
//#footer-poweredbyico { display: none; }

/*////////////////////////////////////////////////////////////////////////////////////////////////////////
// Makes the level 4 header italic so it looks different from level 3.
*/

h4{
font-style: italic;
}

/*///////////////////////////////////////////////////////////////////////////////////////////////////////*/

/*////////////////////////////////////////////////////////////////////////////////////////////////////////
// The following code enables numberless tables of contents.
// When <div class="nonumtoc"> is used on the table of contents, the ToC will display without numbers.
*/

.nonumtoc .tocnumber { display: none; }
.nonumtoc #toc ul,
.nonumtoc .toc ul {
line-height: 1.5em;
list-style: none;
margin: .3em 0 0;
padding: 0;
}
.nonumtoc #toc ul ul,
.nonumtoc .toc ul ul {
margin: 0 0 0 2em;
}

/* Allow limiting of which header levels are shown in a TOC;
<div class="toclimit-3">, for instance, will limit to
showing ==headings== and ===headings=== but no further
(as long as there are no =headings= on the page, which
there shouldn't be according to the MoS). */
.toclimit-2 .toclevel-1 ul,
.toclimit-3 .toclevel-2 ul,
.toclimit-4 .toclevel-3 ul,
.toclimit-5 .toclevel-4 ul,
.toclimit-6 .toclevel-5 ul,
.toclimit-7 .toclevel-6 ul {
display: none;
}

/*////////////////////////////////////////////////////////////////////////////////////////////////////////*/

/*//////////////////////////////////////////////////////////////////////////////////////////
// Makes the typical source code div container
*/

div.source {
background-color: #f3f3f3;
/*border-color: #1c9edb;*/
/*Fake border:*/
font-size: 10pt;
border-color: #555555;
border-width:2px;
border-style: dashed;
padding:6px;
}

/* Hide edit links */
.mw-editsection { display:none!important; }
.editsection { display:none!important; }

Driver Changelog

2016-09-21T22:29:30Z

Patrick:

[[Category:Administrative]]
__NOTOC__
===2.1.8.20160921===
*macOS release
**Fixed USB bug where devices plugged in before boot were inaccessible until unplugged/re-plugged, under OS X 10.11.

===2.1.8.20160202===
*Windows release
**Labview 7.1 support

===2.1.8.20160107===
*Windows release
**Don't throw an exception on EncoderPositionChangeEventArgs.Time in the .Net library when time it unknown - just return 0x7fffffff

===2.1.8.20160104===
*Mac/Windows release
**New firmware for 1042 and 1044, fixing digital gyro
===2.1.8.20151217===
*Fixed 1045 bug where it will display an unknown ambient temperature sometimes
*Fixed a crash in the windows control panel

===2.1.8.20151020===
*Windows release
**Fixed an issue where the examples would error when trying to run them from the control panel.

===2.1.8.20151009===
*OS X and Windows release
**Upgraded firmware for 1024, 1032, 1041, 1042, 1043, 1044 and 1067 to address issues with these Phidgets on OS X El Capitan
*SBC release
**Support for multiple webcams
===2.1.8.20150821===
*OS X-only release
**Support OS X 10.11 El Capitan
===2.1.8.20150805===
*OS X-only release
**Preliminary support for OS X 10.11 El Capitan
===2.1.8.20150410===
*Linux-only release
**Fixed Makefile phidget21.h target issues
===2.1.8.20150326===
*Windows-only release
**Fixed issue with webservice buttons not being visible in the control panel
===2.1.8.20150323===
*Windows-only release
**Updated icons with new company logo
===2.1.8.20150227===
*Linux-only release
**Added copyright/licence headers to source code files
**Updated cvtutf files to a newer version
===2.1.8.20150109===
*Windows-only
**Fixed examples for Labview 8.5
===2.1.8.20141209===
*OS X-only release
**Added support for armv7s and arm64 to the iOS library. Dropped support for armv6. Requires iOS 5.1.1 or later.
===2.1.8.20141202===
*Windows-only release
**Labview release to support older versions
===2.1.8.20141119===
*OS X-only release
**Fixed an issue with the 2.1.8.20141117 release where nothing was actually installed.
===2.1.8.20141117===
*OS X-only release
**Fixed a code-signing issue that make the installer appear unsigned on OS X 10.10
**Dropped support for OS X 10.4
===2.1.8.20140905===
*Windows-only release
**Added an IA32 folder to the windows libraries download - this supports Windows on the Intel Galileo platform
===2.1.8.20140428===
*Windows-only release
**Fixes to C# Stepper GUI Example
===2.1.8.20140319===
*CPhidget_getDeviceClass can now be called on handle before it is attached.
*Added support for 64-bit Max/MSP (Version 6.1+) on both OS X and Windows.
===2.1.8.20140227===
*Deals with 1046 bug in v100 and v101 firmware.
**No longer reports bad values that appear right after a channel is enabled.
**Fixes issue where changing the gain while channel 0 is disabled would sometimes cause bad readings.

===2.1.8.20131105===
* Fixed a defect in the Flash examples for the 1012 (Outputs 11-16 were not addressed properly).

===2.1.8.20130926===
*Windows-only release
**Support setting label on 1067 from Windows
===2.1.8.20130820===
*Windows-only release
**Added logging option to control panel / C# full examples
===2.1.8.20130802===
*Windows-only release
**Fix for Windows 8 issue where only 'Uninitialized Phidget Handle' would show up in the Manager, and Phidgets could not be opened.
===2.1.8.20130723===
*Improvement to java: we don't attach/detach our native threads for each event, just one attach, then detach before the thread exits.
**This increases performance, esp. when debugging on Android.
*Improvement to Android: We reuse the UsbRequest object rather then creating a new one for each transfer. This reduces logcat messages tremendously, and increases performance.
===2.1.8.20130710===
*Android-only release
**Added extra android target architectures: x86, MIPS, armeabi-v7a
===2.1.8.20130618===
*Changed setCompassCorrectionParameters() API call so that compass calibration parameters are written out to non-volatile storage on 1042/1044, so that they persist across power cycles. Previously, calibration data would need to be re-programmed at each attach.
*Changes to C# Spatial example:
**Compass calibration parameter set dialog removed from for 1042/1044 because parameters are set by the calibration software - and thus do not need setting in the example.
**Stores/restores parameters for 1056 based on serial number, so multiple different calibrations can be maintained.
===2.1.8.20130607===
*Windows-only release
**Fixes to compass calibration software for 1042/1044
===2.1.8.20130419===
*Windows-only release
**Fixed setCompassCorrectionParameters in the COM library
===2.1.8.20130327===
*Windows-only release
**Changed Windows installer to stop virus-scanner false positives
**Dropped support for Windows 2000
===2.1.8.20130320===
*Added EPHIDGET_NOTFOUND exception to Dictionary.getKey() for when the key is not found.
*Added exceptions back into the Java library - they have been missing since 2.1.8.20121015 release.
===2.1.8.20130313===
*Updates to Matlab support
**Works properly on Matlab 7+, on Windows, Mac, Linux without needing changes to .m files.
===2.1.8.20130221===
*Windows-only release
**Encoder Index event added to C and .NET libraries
===2.1.8.20121218===
*Webservice version: 1.0.10
**Support for 1024, 1032
*Support for 1024, 1032
*fixed bug where if one half of a composite device is open, and PHIDGET_USB_ERROR_FLAG gets set, the device may never re-attach.
===2.1.8.20121015===
*Windows-only release
**Support for new pressure/light sensors in example.
===2.1.8.20120914===
*Windows-only release
**Improved firmware upgrading in control panel - it was giving some false-errors on some machines.
===2.1.8.20120912===
*Fixed bug where 1065 could fail to attach when opened over webservice
*Fixed bug where close() could deadlock on Phidgets opened over the webservice
*Changed LED64 LED Brightness from int to double
**this may cause issues when controlling the LED64 over the webservice and library/webservice are not the same version
**the old setDiscreteLED call will remain, deprecated, with an int argument for compatibility.
===2.1.8.20120716===
*Linux-Only Release
**Fixed a bug where opening a device in two program at once would cause an attach-detach cycle as they fight each other for control.
===2.1.8.20120713===
*Mac-Only Release
**Added signing of the Mac installer, so Mountain Lion (OS X 10.8) doesn't refuse to run it.
===2.1.8.20120615===
*Windows-only release
**Fixed a bug that caused java to crash on events introduced in 2.1.8.20120612
===2.1.8.20120612===
*Windows-only release
**Fixed another bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120606===
*Windows-only release
**Fixed a bug that will cause Unity3D to hang on exit after having used Phidgets.
===2.1.8.20120525===
*Windows-only release
**Fixed PhidgetIR sendRawData bug in .NET on 64-bit machines.
===2.1.8.20120514===
*Linux-only release
**Fixed a bug that causes a segfault with libusb-1.0 under 64-bit Linux.
===2.1.8.20120507===
*Mac/Linux-only release
**Fixes a setLabel bug introduced in 2.1.8.20120503
===2.1.8.20120503===
*Fixed some spelling mistakes
*Moved to libusb-1.0
**This resolves a bug where having a webcam plugged in caused a memory leak in the webservice.
*Fixed bug with advanced servo where setting acceleration to accelerationMax would cause an exception for some servo types
===2.1.8.20120216===
*Fixed bug with RFID Reader on OS X and Linux, as well as .NET over the webservice
*Fixed bug that could cause the Java Phidget Manager to crash during garbage collection.
===2.1.8.20120131===
*Fixed RFID Reader bug that caused tag event to not get thrown in .NET Applications
*Changed compass bearing calculations in spatial C# example
===2.1.8.20120123===
*Added support for 1061 v300+
*Fixed a bug where the firmware version could be mis-reported over Bonjour
===2.1.8.20111220===
*Fixed a bug in AppleScript where closing a Phidget opened via label would give a 'Connection Invalid' error.
*Fixed a bug where the webservice may fail to start on Linux systems that don't support IPv6 (ie. SBC2).
*Fixed issue where ratiometric state on newest interfacekit wouldn't be read back properly if it was false during attach.
*Fixed webservice issue where ratiometric state would not be reported properly for newest interfacekits
*Increased the number of overrun errors ignored during initial attach for InterfaceKit.
*Fixed an issue with the iPhone library and header
===2.1.8.20111219===
*fixed various other webservice stability/performance/memory leak bugs
*Faster connection to SBC-connected Phidgets from Mac OS
*Don't report packetlost or overrun errors that happen during early initialization - these are just noise.
*Fixed a bug in the webservice tree removal function that could cause memory leaks.
*Fixed bug where Webservice would crash on Linux if the chosen serverID was already under use on the network
*Stopped sending hardware Error Events before the Attach event - they are now queued up and sent after Attach
*Fixed a crash in the [[Phidget Control Panel]]
*Added ability to remove dictionary keys from a key change listener
*Reduced the number of false 'pending command not finished' error events on Close()
*Fixed a webservice bug where exceptions/false attach events could occur when close() is called soon after open
*Fixed bug where closing a PhidgetRFID soon after attach could cause a crash
*Fixed webservice but on MacOS where client could exit with SIG_PIPE error
*Fixed webservice bug where the server would sometimes exit(1) after many connect/disconnect cycles
*Fixed webservice bug where client could deadlock during close()
*Fixed webservice bug where opening a single remote phidget multiple times from the same application would fail
*Fixed a webservice bug where sockets weren't being closed properly sometimes
*Fixed a webservice bug where pre-attach error events wouldn't get through
*Fixed a bug where the webservice running on Linux would stop responding to clients after ~300 connect/disconnect cycles
*Fixed bug where a Phidget would become inaccessible until the app is restarted if a thread creation failed
*Fixed webservice bug where connect is slow on Windows when multiple clients are running simultaneously
*Fixed webservice bug where authentication would fail on a valid password
*Fixed webservice bug where attach may never happen, and would require a close()/open()

===2.1.8.20111121===
*Added support for new servo types to all libraries
*Fixed min/max position/velocity causing invalid arg exception on servo/advservo
*IPv6 support on MacOS
*Fixed some memory leaks
*Fixed hostname lookup issue on Mac OS with Back To My Mac enabled.
===2.1.8.20111028===
*Fixed Applescript bugs and released examples
*Added openLabel to .NET, Java, COM
*Setting change trigger to 0 on interfacekit will not set event mode.
**Previously setting change trigger to 0 after setting data rate would supersede the data rate setting, which is probably unexpected.
===2.1.8.20110630 - MacOS Only===
*handle USB bug introduced in MacOS 10.6.8
===2.1.8.20110615===
*Added error event when trying to open Phidgets with an unsupported version
===2.1.8.20110614 - Windows Only===
*Fixed bug in C# Spatial example
*Added support for negative gains in 1056
===2.1.8.20110601 - MacOS Only===
*Fixed AppleScript issues
===2.1.8.20110527===
*Fixed AS3.0 library (Flash/Flex) - wouldn't connect to webservice as of last release
*Fixed bug where webservice doesn't release a closed Phidget
*Fixed bug where devices that don't support label didn't show up on MacOS
*Fixed iPhone library issues
===2.1.8.20110524===
*AppleScript support added
*fixed problem with Spatial in .NET on 64-bit Windows
*Added remote setLabel to mac preference pane.
*fixed a bug where label characters 7,8,9 would be read back corrupted on certain devices.
**labels >7 characters that exhibit this bug will now be truncated to 7 characters when being read back
**call setLabel again using this library or newer to support 10 character labels.
**To maintain compatibility with older library versions, limit labels to <=7 characters on these devices.
*fixed bug on MacOS where serial number and/or label strings could be read wrong.
*better support for recovering misbehaving devices in Linux
*fixed a deadlock on linux when Avahi is installed but not running
*clear list of attached devices when closing remote manager
*Added support for Unicode labels
**To maintain compatibility with older library versions, limit labels to ASCII.
*Added open by label
*Webservice protocol version up to 1.0.9 (for open by label)
*Made opening multiple device is one application faster.
*TextLCD changes:
**cursor is disabled while writing to the display or setting a custom character to prevent display artifacts
**cursor is disabled when a full line is written so it doesn't go to the start of another line
**1204 should be stable
**setDisplayCharacter supports 0x00-0xff
*stopped property reflected more accurately in the C# stepper example
*Added error events to mac examples
===2.1.8.20110329 - Windows only===
*Fixed problem with control panel encoder example where enable wouldn't work
*Fixed issue with SpatialData, GPSPositionChange, PHChange and WeightChange events in Labview 64-bit
===2.1.8.20110322===
*Fixed [[Phidget Control Panel]] memory leak when Bonjour in installed but not running
*Fixed current sense formula on 1061_0 v200
*Fixed bug in webservice protocol while using the PhidgetAdvancedServo
*Fixed bug in old PhidgetTemperatureSensor

===2.1.8.20110310===
*Fixed bug in webservice protocol while using the PhidgetServo
*Fixed some Labview bugs
*Added some Java and VB.NET examples
===2.1.8.20110301===
*Full Support for 1002, 1011, 1040, 1046, 1054, 1065, 1204
*New webservice version - 1.0.8
**Support for new devices
**Support for error events
===2.1.7.20110203===
*fixed crash on close of remote Phidget on MacOS
*C# ifkit example bugfix - crashed on 1015/1016
*webservice improvements
*Switch to IP address for SBC config in browser
*Faster IP lookup for SBCs in control panel
===2.1.7.20101222 / 2.1.7.20101223===
*fixed getServerID on Linux
*removed report ack
**this was causing some bad side effects
*manual .local lookups on Windows
**much faster then letting Windows do it itself
*Support for new Labview library
*Fixed PhidgetIR bug where library would crash if repeat code is longer then IR_MAX_REPEAT_LENGTH
===2.1.7.20101103===
*Decreased Phidget Webservice event latency on Windows
*Preliminary support for 1002, 1011, 1040, 1045, 1046, 1054, 1065, 1204 (C, .NET)
*Webservice version updated to 1.0.7
**support for 1045, 1011, 1204
*Fixed a bug where webservice connections could be unexpectedly lost
*Bugfix: couldn't set interfacekit data rate over webservice.
*Fixed some memory leaks in the Mac library
*Fixed bug where blocking for >2 seconds in an events handler when opening remotely could cause a crash.
===2.1.7.20100803===
*Windows only release
*fixed setLabel in WindowsCE
*fixed getHashCode in .NET library - needed for working with Phidgets in Labview via .NET
===2.1.7.20100621===
*Linux only release - autotools updates
**call ldconfig automatically
**remove old phidget21 library (pre-autotools) when installing new one.
===2.1.7.20100620===
*Linux only release - added version.sh for autoreconf
===2.1.7.20100618===
*Linux only release - added udev/hotplug files
===2.1.7.20100617===
*Linux only release
*Transitioned to autotools in linux for phidget21 / webservice
*phidget21 library and webservice are now separate downloads
===2.1.7.20100525===
*full support for PhidgetSpatial and PhidgetIR in all libraries
*fixed 1031 not attaching in AS3.0
*Better error messages in JNI
*Updated error codes, device ID/Class lists in Java, Flash, COM, etc.
*Fixed TemperatureSensor version 200,201,202 bug - ambient sensor would not report negative temperatures.
*Revised temperaturesensor API to report tempMin/tempMax and errors more accurately.
*Added initial events for encoder digital inputs
*full support for 1047
*Added new device support to WindowsCE
*Updated mac examples for 1047, 1048
===2.1.6.20100504===
*Windows only Release
**Added 1131 and 1132 to InterfaceKit example in MSI
===2.1.6.20100428===
*limit data rate maximum to 16ms over the webservice for devices that expose dataRate (InterfaceKit, Spatial)
*fixed bug where TextLCD 8/8/8 would stay in Bonjour list after webservice is shutdown
*set/get Brightness for 1203_2
*Support 1048 in C# example
*webservice version incremented to 1.0.6
**TextLCD set/get brightness
**PhidgetIR support
**PhidgetSpatial support
**1047 support (enable, index)
===2.1.6.20100406===
*Support for 1018_2 (dataRate)
*Webservice version incremented to 1.0.5
===2.1.6.20100401===
*Updated InterfaceKit example with new sensors
*make Windows connect cancelable
*make pending zeroconf lookups cancelable during close
===2.1.6.20100318===
*Mac only release
**Added WillSleep and Wakeup events to give user control of Phidgets immediately before and after a system sleep (MacOS Only).
===2.1.6.20100317===
*Windows only release
**Some of the examples were being built using an out of date .NET library
===2.1.6.20100310===
*MaxMSP fix - 2.1.6.20100126 introduced a bug for some Phidgets where openremote/open by serial didn't work and MaxMSP would sometimes crash.
**No code changes to any of the other libraries.
===2.1.6.20100304===
*stopped property changes trigger events over webservice so they are noticed.
**more compatible with how local open works
*added 5 new servos
*fixed bug where remote close would not set detached so a subsequent open would not always connect.
*handle UninitializeZeroconf better - shut down thread before closing handles, fixes hang on SBC
*fixed bug on Mac where detaching 2 or more Phidgets at the same time caused a crash
*fixed close blocking because of a pending connect (mac, linux)
*Final support for 1031 in all libraries.
===2.1.6.20100129===
*Implemented initial events in Flash
**Flash behaviour should now be identical to C library local and remote.
*Fix RFID issue where close could cause crash
*increment webservice version to 1.0.4
*fixed RFID remote open
**Flash would never get an attach event if the reader had been previously opened
**Initial tag event would not be fired when a tag was present and the antenna was enabled prior to open
*fixed openRemote failing on Mac
*fixed deadlock in webservice which could be hit by opening/closing a device over and over again.
*fixed bug in stepper, which caused seg fault on SBC on position change events.
===2.1.6.20100126===
*added network open support in Max/MSP
===2.1.6.20100115===
*Increased network performance for Linux/MacOS
*Added five servo types
===2.1.6.20091215===
*Fixed busy loop in Linux openRemote
*JNI Library relocated to /Library/Java/Extensions on MacOS
===2.1.6.20091211===
*Heartbeat now works on Linux as well (had to make sockets non-blocking)
===2.1.6.20091130===
*Added heartbeat to webservice (client side)
**Better detects network failures by using active polling timeouts
*Fixed 0/8/8 over webservice
===2.1.6.20091020===
*Fixed 1052 counting issue on 1070 (-1 reported as 255)
*Fixed issue where Phidget21 would try to reinstall from a limited user account or when the Control Panel was disabled.
*64-bit kernel support in Snow Leopard
===2.1.6.20090928===
*Support for PhidgetSBC (1070)
*zeroconf can handle starting up before the mdns daemon, and will keep trying to connect.
*fixed 1066 not showing up on Mac
*added advanced servo example to mac pref pane
*implemented proper error handling in COM
**default behavious remains the same, enable proper error handling with 'EnableVerboseErrors'
*implemented error events in Java
===2.1.6.20090917===
*Updated webservice protocol version to 1.0.3
*Fixed stepper under AS3.0
*added setServoType, getServoType, setServoParameters to PhidgetServo and PhidgetAdvancedServo
*possible race condition fixed in webservice (pdictclient.c:907)
===2.1.6.20090902 (mac only release)===
*Support MacOSX 10.6, drop support for 10.3.9, require 10.4 or newer
**Fully 64-bit compliant, library supports ppc, i386, x86_64
===2.1.6.20090806===
*Added 1049 support
*Fixed RFID tag events over webservice
===2.1.6.20090804===
*Added 1051_2 support
*Fixed various small initialization issues - stepper, adv servo, rfid
*Added 32-bit library install to 64-bit installer
**VB6.0, etc. need the 32-bit COM library on 64-bit windows
===2.1.6.20090717===
*?
===2.1.6.20090708===
*Added DeviceID to zeroconf
*fixed RFID.LastTag in .NET
*Changed the error codes returned by error events; error events now have their own set of error codes rather then sharing the function return codes.
*Added support for 1047, 1048
*Added error event codes rather then trying to reuse the EPHIDGET return codes.
*fixed TextLCD issue where display could get corrupted during a detach/attach
*made mac more reliable on attach
*more error logging on mac
===2.1.6.20090525===
*fixed RFID not attaching via webservice if a tag is present.
*bugfix related to double free on detach event.
*Implemented getKey
*Added MIPS II support to Windows CE
===2.1.6.20090430===
*Added ActiveX interface to COM library
*Added stepper and advancedServo to Flex .swc library
===2.1.6.20090417===
*added PhidgetIR prototype support to C library
*properly handles sleeping on OSX
*fixed some webservice field initializations in Flash and C
*fixed security exceptions in [[Phidget Control Panel]] under Vista
*added [[Phidget Control Panel]] to start menu

===2.1.6.20090318 (Examples/AS3.0 only release)===
*Fixed AdvancedServo in Flash - wouldn't attach
===2.1.6.20090317===
*[[Phidget Control Panel]] properly supports Vista UAC and Limited user accounts in XP, etc.
*Added 64-bit release of Phidget21.msi for Windows

===2.1.6.20090312===
*added 1064, 1059 to WindowsCE
*fixed opening 1051 over webservice
*fixed opening 1015/1016 over webservice broken in last release
===2.1.6.20090302===
*Advanced servo bugfix: stopped would stop being true if min/max was set to exclude current position.
*linux USB improvements when many Phidgets are attached and opened at once.
*1031 support in phidget21, webservice, .NET - hidden until product release
**CPhidgetLED_setVoltage
**CPhidgetLED_getVoltage
**CPhidgetLED_setCurrentLimit
**CPhidgetLED_getCurrentLimit
*unknown timechange == PUNK_INT in encoder position change event
**1st position change event
**> 30 seconds time change
*AS3 updates
**updated to 1.0.2 webservice
**encoder position change events report relative change rather then absolute position
**encoder adds getTimeChange function for timing encoder changes
*webservice updated to 1.0.2
**Authorization is asynchronous
**Doesn't match the old version checking, so errors will not be nice when trying to connect to an old webservice
**Sends out all initial data, so it's just like opening locally
**supports interfacekit Raw sensor value
**supports labels on remoteIP managers
*avahi bugfix
*webservice more stable against forcefully closed clients
*closing a network Phidget won't block - ever.
**no longer using quit, just closing the socket
*added libavahi-client.so.3 reference to linux library.
*Fixed bug with opening one phidget with serial and no serial at the same time over the webservice
===2.1.5.20090105===
*[[Phidget Control Panel]] stability improvements
*added CPhidgetSBC_getHostname
*advanced servo 1 motor current sense equation - support should now be complete
*webservice and network code bugfixes - crash / deadlock during close, problems with concurrent connections, etc.
*fixed close on remote and remoteIP managers
*name of RFID changed from "Phidget RFID 4-output" to "Phidget RFID 2-output" - updated anything referencing old name.

===2.1.5.20081023===
*added advanced servo and stepper examples to VB6.0, VB.NET and C
*added deviceClass and deviceID
*updated Mac examples
*webservice protocol version enforcement
*internal fix/rework of device id's etc.
*Fixed memory leaks in webservice and phidget21 network code.
*Dictionary and network stability improvements.
*duplicate calls to open or close are now silently ignored.
===2.1.4.20080924===
*Old TextLCD 0/8/8's can now have both halves open at the same time on Windows
*fixed bug with composite devices on linux
*fixed manager on linux to better deal with unique devices
===2.1.4.20080922===
*Updated Delphi files
*TextLCD can display 0x80-0xFF characters from Java
*getAttachedDevices works for mdns managers
*fixed a deadlock in the webservice
*better network error handling / password support for windows C# examples
*waitForAttachment will return EPHIDGET_CLOSED if the handle is closed while it is waiting.
*added EPHIDGET_CLOSED
*joining central threads checks whether they are trying to be joined by themselves first (avoid deadlocks).
*changed context of error event to be free from locks (can call close, open, etc. from them).
===2.1.4.20080821===
*zeroconf threads exit cleanly on last _close (apple zeroconf)
*Added advanced servo and stepper to Max
===2.1.4.20080811 (mac only release)===
*Fixed manager on Mac (wasn't working at all since 2.1.4.20080808)
===2.1.4.20080808===
*added CPhidgetSBC and CPhidgetSBCManager to the c library - these interfaces are hidden from users and meant to be used internally (for now).
*CPhidgetManager_open no longer blocks to send out initial attach events. These initial events are sent from the CentralThread context like all other attach events.
*fixed CThread_wait_on_event on Linux
*added CPhidgetGeneric interface for prototyping to C, .NET libraries. product ID is 0x99. These are only visible in debug releases, only to be used internally.
===2.1.4.20080715===
*udev rules fixed for product IDs with alpha-hex values
*blocking in an attach event does not block calls to open anymore
*RFID tag event handlers can now handle blocking - tag lost is timed after the tag handler exits.
===2.1.4.20080623===
*Flex .swc library was out of sync
*fixed CPhidgetManager_getAttachedDevices for network managers
*Added CPhidgetManager_freeAttachedDevicesArray
===2.1.4.20080613===
*Max/MSP RFID fixed
*0/0/8 and advanced servo added to CE
*fixed flash policy file server in webservice
*webservice with password and asynchronous together work now
===2.1.4.20080602===
*phidget21.h -> phidget21int.h so as not to be confused with generated phidget21.h
*some changes to Makefile fro crosscompiling
*no more vbscript in msi
===2.1.4.20080513===
*removed long long from COM - not supported by VB6.0
*added LastTag to RFID in .NET
===2.1.4.20080428===
*support Mac OS X 10.3.9 again
*Rev up to 2.1.4
*finalize Phidget Stepper API - Phidget Stepper requires 2.1.4 as a minimum
*fixed serverConnect and serverDisconnect handlers for manager and dictionary in COM
*Changed:
**PhidgetStepper and PhidgetAdvancedServo
***MotorPosition -> Position
***MotorOn -> Engaged
***MotorStopped -> Stopped
*Added:
**CPhidgetStepper_getCurrentLimit
**CPhidgetEncoder_getPosition
**CPhidgetEncoder_setPosition
**CPhidgetMotorControl_getVelocity
**CPhidgetMotorControl_setVelocity
**CPhidgetMotorControl_set_OnVelocityChange_Handler
**CPhidgetServo_setEngaged
**CPhidgetServo_getEngaged
**CPhidgetServo_getPosition
**CPhidgetServo_setPosition
**CPhidgetServo_set_OnPositionChange_Handler
**CPhidgetServo_getPositionMax
**CPhidgetServo_getPositionMin
**Count functions
*Deprecated:
**CPhidgetEncoder_getEncoderPosition
**CPhidgetEncoder_setEncoderPosition
**CPhidgetMotorControl_getMotorSpeed
**CPhidgetMotorControl_setMotorSpeed
**CPhidgetMotorControl_set_OnMotorChange_Handler
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
**CPhidgetServo_getMotorPosition
**CPhidgetServo_setMotorPosition
**CPhidgetServo_set_OnMotorPositionChange_Handler
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**Num functions
*Added ability to deprecate funcitons in the C library - compiler will issue a warning when they are used.
*added names to some arguments in phidget21.h
*fixes to the webservice for initial state stuff - now it behaves almost like non-webservice, with guaranteed initial events, but we don't guarantee initial state in the attach event yet. Min/Max, Num motors, inputs, etc. are all guaranteed in the attach handler.
*Finalized support for Phidget Stepper
===2.1.3.20080402===
*Fixed windows BUG - Device Type was showing up wrong
*CPhidgetStepper_getPosition -> CPhidgetStepper_getCurrentPosition
===2.1.3.20080327===
*added:
**CPhidgetAdvancedServo_setMotorPositionMax
**CPhidgetAdvancedServo_setMotorPositionMin
**CPhidgetAdvancedServo_getMotorStopped
*changes to API
**CPhidgetStepper_setMotorPosition -> CPhidgetStepper_setTargetMotorPosition
**added CPhidgetStepper_getTargetMotorPosition
**Stepper MotorSpeed -> Velocity
**Stepper and AdvancedServo MaxVelocity -> VelocityLimit
*add waitForAttachment to COM
*COM getbool (not indexed) will now return FALSE on false (rather then always returning true)
*fixed write thread timeouts - was setting attached after starting write thread so write thread would see a detached device and exit immediately
===2.1.3.20080206===
*changed long long to __int64, to be happy in borland C++
*added:
**CPhidgetStepper_getMaxMotorSpeed
**CPhidgetStepper_setMotorOn
**CPhidgetStepper_getMotorOn
**CPhidgetStepper_getMotorStopped
**CPhidgetStepper_setCurrentMotorPosition
*removed CPhidgetStepper_setVelocity
*added CPhidgetStepper_setMaxVelocity, CPhidgetStepper_getMaxVelocity
===2.1.3.20080114===
*Added new functions to Flash API
*Added new functions to Webservice Protocol
*Added new functions to COM Library
*Added new functions to Java Library
*All device fiels in C library cleaned up and made consistent
*Open in windows is exclusive - this needs to be tested for stability
*No data will be returned / accepted if it lies outside of max/min range
*if a data value is unknown, user variable is set to PUNK_INT, PUNK_DBL, or PUNK_BOOL, and return value is EPHIDGET_UNKNOWNVAL
*Proper Device initializations on Attach:
**triggers are set to defaults on attach
**device state is read in and preserved on attach
**during attach event, all sensor data, etc. is provided if available
**no data events until after the attach event returns
**everything initialized by the time waitForAttachment returns
**after attach event returns, a full set of initial state data events are thrown
*.NET collections are readonly, and never NULL (but empty when phidget detached)
*.NET callbacks no longer catch and hide all exceptions
**make sure to use try/catch blocks especially in Attach when accessing properties that may not be initialized.
*added min/max functions:
**CPhidgetAccelerometer_getAccelerationMax
**CPhidgetAccelerometer_getAccelerationMin
**CPhidgetAdvancedServo_getAccelerationMax
**CPhidgetAdvancedServo_getAccelerationMin
**CPhidgetAdvancedServo_getVelocityMax
**CPhidgetAdvancedServo_getVelocityMin
**CPhidgetAdvancedServo_getMotorPositionMax
**CPhidgetAdvancedServo_getMotorPositionMin
**CPhidgetMotorControl_getAccelerationMax
**CPhidgetMotorControl_getAccelerationMin
**CPhidgetPHSensor_getPHMax
**CPhidgetPHSensor_getPHMin
**CPhidgetPHSensor_getPotentialMax
**CPhidgetPHSensor_getPotentialMin
**CPhidgetServo_getMotorPositionMax
**CPhidgetServo_getMotorPositionMin
**CPhidgetStepper_getAccelerationMax
**CPhidgetStepper_getAccelerationMin
**CPhidgetStepper_getMotorSpeedMax
**CPhidgetStepper_getMotorSpeedMin
**CPhidgetStepper_getMotorPositionMax
**CPhidgetStepper_getMotorPositionMin
**CPhidgetTemperatureSensor_getPotentialMax
**CPhidgetTemperatureSensor_getPotentialMin
**CPhidgetTemperatureSensor_getAmbientTemperatureMax
**CPhidgetTemperatureSensor_getAmbientTemperatureMin
**CPhidgetTemperatureSensor_getTemperatureMax
**CPhidgetTemperatureSensor_getTemperatureMin
*Added functions:
**CPhidgetTemperatureSensor_getAmbientTemperature
**CPhidgetTemperatureSensor_getThermocoupleType
**CPhidgetTemperatureSensor_setThermocoupleType
**CPhidget_set_OnServerConnectHandler
**CPhidget_set_OnServerDisconnectHandler
**CPhidgetDictionary_set_OnServerConnectHandler
**CPhidgetDictionary_set_OnServerDisconnectHandler
**CPhidgetManager_set_OnServerConnectHandler
**CPhidgetManager_set_OnServerDisconnectHandler
**CPhidgetDictionary_getServerID
**CPhidgetDictionary_getServerAddress
**CPhidgetDictionary_getServerStatus
**CPhidgetManager_getServerID
**CPhidgetManager_getServerAddress
**CPhidgetManager_getServerStatus
**CPhidgetServo_setMotorOn
**CPhidgetServo_getMotorOn
*Removed functions:
**CPhidgetServo_setMotorOff
*TemperatureSensor:
**Ambient sensor is accessed with it's own function
**first thermocouple is Index 0 everywhere
**no ambient sensor events
*getServerID is implemented
*changed the internal network structure (added CPhidgetRemote)
*reworked the USB code (mostly on Windows)
**Better handles closing, ESD events, timeouts
**fixed issues with Encoder, RFID stopping reading after a certain time.
**added USB error flag
*openRemote functions have been implemented
**these require bonjour (mac / windows) or avahi (linux) to be installed on both the client and server
**if they are not, you get EPHIDGET_UNSUPPORTED when you call them
*openRemoteIP functions are asynchronous and persistent
*include cphidgetconstants.h in phidget21.h for users
===2.1.2.20071108===
*start of chagelog

OS - Phidget SBC

2016-08-11T17:52:49Z

Patrick: /* Quick Downloads */

[[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|SBC3 Getting Started Guide]] right out of the box.

*[[Software License]]

'''For PhidgetSBC (1070):'''
*[{{SERVER}}/downloads/sbc/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc-minimal.bin Minimal Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc-full.bin Full Firmware]
*[{{SERVER}}/downloads/libraries/buildroot-phidgetsbc.tar.gz Buildroot/Kernel Sources]
'''For PhidgetSBC2 (1072):'''
*[{{SERVER}}/downloads/sbc2/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc2.bin SBC2 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package] (How-to and patch file)
'''The PhidgetSBC3 has different firmware packages based on the kernel version. In order to determine the device version of your SBC3, see the [[1073_User_Guide#SBC_Web_Interface|web configuration page]].'''

[[File:sbcver.jpg|thumb|562px|link=|The system information table is found on the Status -> System tab of the '''[[1073_User_Guide#SBC_Web_Interface|web configuration page]]''' of the SBC.]]
'''For PhidgetSBC3 (1073) kernel version 3.6.3:'''
*[{{SERVER}}/downloads/sbc3/changelog changelog]
*[{{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]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-upgrade_3.6.3_3.14.27.tar.gz SBC3 Kernel upgrade package (3.6.3 -> 3.14.27)]
'''For PhidgetSBC3 (1073) kernel version 3.14.27:'''
*[{{SERVER}}/downloads/sbc3/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc3_1.0.2.20160425.bin SBC3 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-update_3.14.27.tar.gz SBC3 Kernel update package (3.14.27)]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-kerneldev_1.0.2.20160425.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 SBC3 web interface. It is rarely necessary to completely re-flash your device..
<br clear = all>

==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. If the installation fails because it can't find python, you need to enable the full repository as described in [[#Getting Started_-_The_SBC_(Debian_Linux)|this section]], and then perform an apt-get update.

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

====For SBC2:====

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

====For SBC3:====

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r $ROOTFS/ system_ubifs.img
ubinize -o system_ubi.img -m 4KiB -p 256KiB 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=83MiB
# 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.

===Saving a file system to flash to multiple SBC's===
You may want to create a complete backup of your SBC root filesystem, which can then be flashed to other SBCs. This is how it could be done:

You will need a USB drive - we have had issues using cheap flash drives, so a real USB drive is recommended. Make sure it's empty, as it will be reformatted.

All of these commands are executed on your SBC, while logged in over SSH.

First, re-format the USB drive as ext3. Assuming the USB drive is sda and has a single partition:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
mkfs.ext3 /dev/sda1
mount -t ext3 /dev/sda1 /media/usb0
</syntaxhighlight>
</div>

Then, remount / as readonly, so it doesn't change as we're copying it. To do this, we need to kill all running processes except sshd:

<div class="source">
<syntaxhighlight lang=bash>
service udev stop
service ifplugd stop
service rsyslog stop
service avahi-daemon stop
service phidgetwebservice stop
service ntp stop
service busybox-httpd stop
service dbus stop
service cron stop
pkill dhclient
mount -o remount,ro /
</syntaxhighlight>
</div>

If the remount says that / is busy, do a 'ps auxww' and 'pkill' anything else that may be running until it remounts properly.

Then, copy / to the flash drive:

<div class="source">
<syntaxhighlight lang=bash>
mkdir /media/usb0/root
mount --bind / /mnt/
cp -a /mnt/* /media/usb0/root/
</syntaxhighlight>
</div>

Then, clean up the copy - removing files specific to this board. We also remove the APT cache to save space.

<div class="source">
<syntaxhighlight lang=bash>
find /media/usb0/root/var/log -type f -print0 | xargs -0 rm -f
rm -rf /media/usb0/root/var/lib/apt/lists/*
mkdir /media/usb0/root/var/lib/apt/lists/partial
rm -f /media/usb0/root/var/cache/apt/*.bin
rm /media/usb0/root/etc/udev/rules.d/70-persistent-net.rules
rm /media/usb0/root/etc/ssh/ssh_host_*
</syntaxhighlight>
</div>

then, create the ubinize.cfg file:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=83MiB
vol_type=dynamic
vol_name=rootfs0
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=64128KiB
vol_type=dynamic
vol_name=rootfs
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

NOTE: you may need to increase vol_size if your filesystem is larger.

then, create the UBI image from the copy:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 4KiB -p 256KiB ubinize.cfg
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -m 2KiB -e 126KiB -c 4050 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 2KiB -p 128KiB -s 512 ubinize.cfg
</syntaxhighlight>
</div>

then, unmount the drive to ensure everything is written out properly:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
</syntaxhighlight>
</div>

Then, you can remove the /root/ folder and system_ubifs.img. system_ubi.img can be flashed to other SBCs using the recovery system.

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

2016-08-11T17:52:35Z

Patrick: /* Quick Downloads */

[[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|SBC3 Getting Started Guide]] right out of the box.

*[[Software License]]

'''For PhidgetSBC (1070):'''
*[{{SERVER}}/downloads/sbc/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc-minimal.bin Minimal Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc-full.bin Full Firmware]
*[{{SERVER}}/downloads/libraries/buildroot-phidgetsbc.tar.gz Buildroot/Kernel Sources]
'''For PhidgetSBC2 (1072):'''
*[{{SERVER}}/downloads/sbc2/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc2.bin SBC2 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package] (How-to and patch file)
'''The PhidgetSBC3 has different firmware packages based on the kernel version. In order to determine the device version of your SBC3, see the [[1073_User_Guide#SBC_Web_Interface|web configuration page]].'''

[[File:sbcver.jpg|thumb|562px|link=|The system information table is found on the Status -> System tab of the '''[[1073_User_Guide#SBC_Web_Interface|web configuration page]]''' of the SBC.]]
'''For PhidgetSBC3 (1073) kernel version 3.6.3:'''
*[{{SERVER}}/downloads/sbc3/changelog changelog]
*[{{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]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-upgrade_3.6.3_3.14.27.tar.gz SBC3 Kernel upgrade package (3.6.3 -> 3.14.27)]
'''For PhidgetSBC3 (1073) kernel version 3.14.27:'''
*[{{SERVER}}/downloads/sbc3/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc3_1.0.2.20160425.bin SBC3 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-update_3.14.27.tar.gz SBC3 Kernel upgrade package (3.14.27)]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-kerneldev_1.0.2.20160425.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 SBC3 web interface. It is rarely necessary to completely re-flash your device..
<br clear = all>

==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. If the installation fails because it can't find python, you need to enable the full repository as described in [[#Getting Started_-_The_SBC_(Debian_Linux)|this section]], and then perform an apt-get update.

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

====For SBC2:====

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

====For SBC3:====

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r $ROOTFS/ system_ubifs.img
ubinize -o system_ubi.img -m 4KiB -p 256KiB 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=83MiB
# 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.

===Saving a file system to flash to multiple SBC's===
You may want to create a complete backup of your SBC root filesystem, which can then be flashed to other SBCs. This is how it could be done:

You will need a USB drive - we have had issues using cheap flash drives, so a real USB drive is recommended. Make sure it's empty, as it will be reformatted.

All of these commands are executed on your SBC, while logged in over SSH.

First, re-format the USB drive as ext3. Assuming the USB drive is sda and has a single partition:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
mkfs.ext3 /dev/sda1
mount -t ext3 /dev/sda1 /media/usb0
</syntaxhighlight>
</div>

Then, remount / as readonly, so it doesn't change as we're copying it. To do this, we need to kill all running processes except sshd:

<div class="source">
<syntaxhighlight lang=bash>
service udev stop
service ifplugd stop
service rsyslog stop
service avahi-daemon stop
service phidgetwebservice stop
service ntp stop
service busybox-httpd stop
service dbus stop
service cron stop
pkill dhclient
mount -o remount,ro /
</syntaxhighlight>
</div>

If the remount says that / is busy, do a 'ps auxww' and 'pkill' anything else that may be running until it remounts properly.

Then, copy / to the flash drive:

<div class="source">
<syntaxhighlight lang=bash>
mkdir /media/usb0/root
mount --bind / /mnt/
cp -a /mnt/* /media/usb0/root/
</syntaxhighlight>
</div>

Then, clean up the copy - removing files specific to this board. We also remove the APT cache to save space.

<div class="source">
<syntaxhighlight lang=bash>
find /media/usb0/root/var/log -type f -print0 | xargs -0 rm -f
rm -rf /media/usb0/root/var/lib/apt/lists/*
mkdir /media/usb0/root/var/lib/apt/lists/partial
rm -f /media/usb0/root/var/cache/apt/*.bin
rm /media/usb0/root/etc/udev/rules.d/70-persistent-net.rules
rm /media/usb0/root/etc/ssh/ssh_host_*
</syntaxhighlight>
</div>

then, create the ubinize.cfg file:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=83MiB
vol_type=dynamic
vol_name=rootfs0
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=64128KiB
vol_type=dynamic
vol_name=rootfs
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

NOTE: you may need to increase vol_size if your filesystem is larger.

then, create the UBI image from the copy:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 4KiB -p 256KiB ubinize.cfg
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -m 2KiB -e 126KiB -c 4050 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 2KiB -p 128KiB -s 512 ubinize.cfg
</syntaxhighlight>
</div>

then, unmount the drive to ensure everything is written out properly:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
</syntaxhighlight>
</div>

Then, you can remove the /root/ folder and system_ubifs.img. system_ubi.img can be flashed to other SBCs using the recovery system.

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

2016-08-11T16:20:54Z

Patrick: /* Quick Downloads */

[[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|SBC3 Getting Started Guide]] right out of the box.

*[[Software License]]

'''For PhidgetSBC (1070):'''
*[{{SERVER}}/downloads/sbc/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc-minimal.bin Minimal Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc-full.bin Full Firmware]
*[{{SERVER}}/downloads/libraries/buildroot-phidgetsbc.tar.gz Buildroot/Kernel Sources]
'''For PhidgetSBC2 (1072):'''
*[{{SERVER}}/downloads/sbc2/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc2.bin SBC2 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package] (How-to and patch file)
'''The PhidgetSBC3 has different firmware packages based on the kernel version. In order to determine the device version of your SBC3, see the [[1073_User_Guide#SBC_Web_Interface|web configuration page]].'''

[[File:sbcver.jpg|thumb|562px|link=|The system information table is found on the Status -> System tab of the '''[[1073_User_Guide#SBC_Web_Interface|web configuration page]]''' of the SBC.]]
'''For PhidgetSBC3 (1073) kernel version 3.6.3:'''
*[{{SERVER}}/downloads/sbc3/changelog changelog]
*[{{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]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-upgrade_3.6.3_3.14.27.tar.gz SBC3 Kernel upgrade package (3.6.3 -> 3.14.27)]
'''For PhidgetSBC3 (1073) kernel version 3.14.27:'''
*[{{SERVER}}/downloads/sbc3/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc3_1.0.2.20160425.bin SBC3 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-upgrade_3.14.27.tar.gz SBC3 Kernel upgrade package (3.14.27)]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-kerneldev_1.0.2.20160425.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 SBC3 web interface. It is rarely necessary to completely re-flash your device..
<br clear = all>

==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. If the installation fails because it can't find python, you need to enable the full repository as described in [[#Getting Started_-_The_SBC_(Debian_Linux)|this section]], and then perform an apt-get update.

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

====For SBC2:====

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

====For SBC3:====

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r $ROOTFS/ system_ubifs.img
ubinize -o system_ubi.img -m 4KiB -p 256KiB 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=83MiB
# 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.

===Saving a file system to flash to multiple SBC's===
You may want to create a complete backup of your SBC root filesystem, which can then be flashed to other SBCs. This is how it could be done:

You will need a USB drive - we have had issues using cheap flash drives, so a real USB drive is recommended. Make sure it's empty, as it will be reformatted.

All of these commands are executed on your SBC, while logged in over SSH.

First, re-format the USB drive as ext3. Assuming the USB drive is sda and has a single partition:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
mkfs.ext3 /dev/sda1
mount -t ext3 /dev/sda1 /media/usb0
</syntaxhighlight>
</div>

Then, remount / as readonly, so it doesn't change as we're copying it. To do this, we need to kill all running processes except sshd:

<div class="source">
<syntaxhighlight lang=bash>
service udev stop
service ifplugd stop
service rsyslog stop
service avahi-daemon stop
service phidgetwebservice stop
service ntp stop
service busybox-httpd stop
service dbus stop
service cron stop
pkill dhclient
mount -o remount,ro /
</syntaxhighlight>
</div>

If the remount says that / is busy, do a 'ps auxww' and 'pkill' anything else that may be running until it remounts properly.

Then, copy / to the flash drive:

<div class="source">
<syntaxhighlight lang=bash>
mkdir /media/usb0/root
mount --bind / /mnt/
cp -a /mnt/* /media/usb0/root/
</syntaxhighlight>
</div>

Then, clean up the copy - removing files specific to this board. We also remove the APT cache to save space.

<div class="source">
<syntaxhighlight lang=bash>
find /media/usb0/root/var/log -type f -print0 | xargs -0 rm -f
rm -rf /media/usb0/root/var/lib/apt/lists/*
mkdir /media/usb0/root/var/lib/apt/lists/partial
rm -f /media/usb0/root/var/cache/apt/*.bin
rm /media/usb0/root/etc/udev/rules.d/70-persistent-net.rules
rm /media/usb0/root/etc/ssh/ssh_host_*
</syntaxhighlight>
</div>

then, create the ubinize.cfg file:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=83MiB
vol_type=dynamic
vol_name=rootfs0
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=64128KiB
vol_type=dynamic
vol_name=rootfs
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

NOTE: you may need to increase vol_size if your filesystem is larger.

then, create the UBI image from the copy:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 4KiB -p 256KiB ubinize.cfg
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -m 2KiB -e 126KiB -c 4050 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 2KiB -p 128KiB -s 512 ubinize.cfg
</syntaxhighlight>
</div>

then, unmount the drive to ensure everything is written out properly:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
</syntaxhighlight>
</div>

Then, you can remove the /root/ folder and system_ubifs.img. system_ubi.img can be flashed to other SBCs using the recovery system.

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

2016-04-25T16:08:35Z

Patrick: /* Quick Downloads */

[[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|SBC3 Getting Started Guide]] right out of the box.

*[[Software License]]

'''For PhidgetSBC (1070):'''
*[{{SERVER}}/downloads/sbc/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc-minimal.bin Minimal Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc-full.bin Full Firmware]
*[{{SERVER}}/downloads/libraries/buildroot-phidgetsbc.tar.gz Buildroot/Kernel Sources]
'''For PhidgetSBC2 (1072):'''
*[{{SERVER}}/downloads/sbc2/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc2.bin SBC2 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package] (How-to and patch file)
'''The PhidgetSBC3 has different firmware packages based on the kernel version. In order to determine the device version of your SBC3, see the [[1073_User_Guide#SBC_Web_Interface|web configuration page]].'''

[[File:sbcver.jpg|thumb|562px|link=|The system information table is found on the Status -> System tab of the '''[[1073_User_Guide#SBC_Web_Interface|web configuration page]]''' of the SBC.]]
'''For PhidgetSBC3 (1073) kernel version 3.6.3:'''
*[{{SERVER}}/downloads/sbc3/changelog changelog]
*[{{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]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-upgrade_3.6.3_3.14.27.tar.gz SBC3 Kernel upgrade package (3.6.3 -> 3.14.27)]
'''For PhidgetSBC3 (1073) kernel version 3.14.27:'''
*[{{SERVER}}/downloads/sbc3/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc3_1.0.2.20160425.bin SBC3 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-kerneldev_1.0.2.20160425.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 SBC3 web interface. It is rarely necessary to completely re-flash your device..
<br clear = all>

==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. If the installation fails because it can't find python, you need to enable the full repository as described in [[#Getting Started_-_The_SBC_(Debian_Linux)|this section]], and then perform an apt-get update.

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

====For SBC2:====

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

====For SBC3:====

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r $ROOTFS/ system_ubifs.img
ubinize -o system_ubi.img -m 4KiB -p 256KiB 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=83MiB
# 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.

===Saving a file system to flash to multiple SBC's===
You may want to create a complete backup of your SBC root filesystem, which can then be flashed to other SBCs. This is how it could be done:

You will need a USB drive - we have had issues using cheap flash drives, so a real USB drive is recommended. Make sure it's empty, as it will be reformatted.

All of these commands are executed on your SBC, while logged in over SSH.

First, re-format the USB drive as ext3. Assuming the USB drive is sda and has a single partition:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
mkfs.ext3 /dev/sda1
mount -t ext3 /dev/sda1 /media/usb0
</syntaxhighlight>
</div>

Then, remount / as readonly, so it doesn't change as we're copying it. To do this, we need to kill all running processes except sshd:

<div class="source">
<syntaxhighlight lang=bash>
service udev stop
service ifplugd stop
service rsyslog stop
service avahi-daemon stop
service phidgetwebservice stop
service ntp stop
service busybox-httpd stop
service dbus stop
service cron stop
pkill dhclient
mount -o remount,ro /
</syntaxhighlight>
</div>

If the remount says that / is busy, do a 'ps auxww' and 'pkill' anything else that may be running until it remounts properly.

Then, copy / to the flash drive:

<div class="source">
<syntaxhighlight lang=bash>
mkdir /media/usb0/root
mount --bind / /mnt/
cp -a /mnt/* /media/usb0/root/
</syntaxhighlight>
</div>

Then, clean up the copy - removing files specific to this board. We also remove the APT cache to save space.

<div class="source">
<syntaxhighlight lang=bash>
find /media/usb0/root/var/log -type f -print0 | xargs -0 rm -f
rm -rf /media/usb0/root/var/lib/apt/lists/*
mkdir /media/usb0/root/var/lib/apt/lists/partial
rm -f /media/usb0/root/var/cache/apt/*.bin
rm /media/usb0/root/etc/udev/rules.d/70-persistent-net.rules
rm /media/usb0/root/etc/ssh/ssh_host_*
</syntaxhighlight>
</div>

then, create the ubinize.cfg file:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=83MiB
vol_type=dynamic
vol_name=rootfs0
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=64128KiB
vol_type=dynamic
vol_name=rootfs
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

NOTE: you may need to increase vol_size if your filesystem is larger.

then, create the UBI image from the copy:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 4KiB -p 256KiB ubinize.cfg
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -m 2KiB -e 126KiB -c 4050 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 2KiB -p 128KiB -s 512 ubinize.cfg
</syntaxhighlight>
</div>

then, unmount the drive to ensure everything is written out properly:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
</syntaxhighlight>
</div>

Then, you can remove the /root/ folder and system_ubifs.img. system_ubi.img can be flashed to other SBCs using the recovery system.

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

2015-09-01T17:26:00Z

Patrick: /* Saving a file system to flash to multiple SBC's */

[[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|SBC3 Getting Started Guide]] right out of the box.

*[[Software License]]

'''For PhidgetSBC (1070):'''
*[{{SERVER}}/downloads/sbc/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc-minimal.bin Minimal Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc-full.bin Full Firmware]
*[{{SERVER}}/downloads/libraries/buildroot-phidgetsbc.tar.gz Buildroot/Kernel Sources]
'''For PhidgetSBC2 (1072):'''
*[{{SERVER}}/downloads/sbc2/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc2.bin SBC2 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package] (How-to and patch file)
'''The PhidgetSBC3 has different firmware packages based on the kernel version. In order to determine the device version of your SBC3, see the [[1073_User_Guide#SBC_Web_Interface|web configuration page]].'''

[[File:sbcver.jpg|thumb|562px|link=|The system information table is found on the Status -> System tab of the '''[[1073_User_Guide#SBC_Web_Interface|web configuration page]]''' of the SBC.]]
'''For PhidgetSBC3 (1073) kernel version 3.6.3:'''
*[{{SERVER}}/downloads/sbc3/changelog changelog]
*[{{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]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-upgrade_3.6.3_3.14.27.tar.gz SBC3 Kernel upgrade package (3.6.3 -> 3.14.27)]
'''For PhidgetSBC3 (1073) kernel version 3.14.27:'''
*[{{SERVER}}/downloads/sbc3/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc3_1.0.1.20150108.bin SBC3 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-kerneldev_1.0.1.20150108.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 SBC3 web interface. It is rarely necessary to completely re-flash your device..
<br clear = all>

==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. If the installation fails because it can't find python, you need to enable the full repository as described in [[#Getting Started_-_The_SBC_(Debian_Linux)|this section]], and then perform an apt-get update.

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

====For SBC2:====

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

====For SBC3:====

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r $ROOTFS/ system_ubifs.img
ubinize -o system_ubi.img -m 4KiB -p 256KiB 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=83MiB
# 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.

===Saving a file system to flash to multiple SBC's===
You may want to create a complete backup of your SBC root filesystem, which can then be flashed to other SBCs. This is how it could be done:

You will need a USB drive - we have had issues using cheap flash drives, so a real USB drive is recommended. Make sure it's empty, as it will be reformatted.

All of these commands are executed on your SBC, while logged in over SSH.

First, re-format the USB drive as ext3. Assuming the USB drive is sda and has a single partition:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
mkfs.ext3 /dev/sda1
mount -t ext3 /dev/sda1 /media/usb0
</syntaxhighlight>
</div>

Then, remount / as readonly, so it doesn't change as we're copying it. To do this, we need to kill all running processes except sshd:

<div class="source">
<syntaxhighlight lang=bash>
service udev stop
service ifplugd stop
service rsyslog stop
service avahi-daemon stop
service phidgetwebservice stop
service ntp stop
service busybox-httpd stop
service dbus stop
service cron stop
pkill dhclient
mount -o remount,ro /
</syntaxhighlight>
</div>

If the remount says that / is busy, do a 'ps auxww' and 'pkill' anything else that may be running until it remounts properly.

Then, copy / to the flash drive:

<div class="source">
<syntaxhighlight lang=bash>
mkdir /media/usb0/root
mount --bind / /mnt/
cp -a /mnt/* /media/usb0/root/
</syntaxhighlight>
</div>

Then, clean up the copy - removing files specific to this board. We also remove the APT cache to save space.

<div class="source">
<syntaxhighlight lang=bash>
find /media/usb0/root/var/log -type f -print0 | xargs -0 rm -f
rm -rf /media/usb0/root/var/lib/apt/lists/*
mkdir /media/usb0/root/var/lib/apt/lists/partial
rm -f /media/usb0/root/var/cache/apt/*.bin
rm /media/usb0/root/etc/udev/rules.d/70-persistent-net.rules
rm /media/usb0/root/etc/ssh/ssh_host_*
</syntaxhighlight>
</div>

then, create the ubinize.cfg file:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=83MiB
vol_type=dynamic
vol_name=rootfs0
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=64128KiB
vol_type=dynamic
vol_name=rootfs
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

NOTE: you may need to increase vol_size if your filesystem is larger.

then, create the UBI image from the copy:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 4KiB -p 256KiB ubinize.cfg
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -m 2KiB -e 126KiB -c 4050 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 2KiB -p 128KiB -s 512 ubinize.cfg
</syntaxhighlight>
</div>

then, unmount the drive to ensure everything is written out properly:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
</syntaxhighlight>
</div>

Then, you can remove the /root/ folder and system_ubifs.img. system_ubi.img can be flashed to other SBCs using the recovery system.

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

2015-09-01T17:23:17Z

Patrick: /* Saving a file system to flash to multiple SBC's */

[[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|SBC3 Getting Started Guide]] right out of the box.

*[[Software License]]

'''For PhidgetSBC (1070):'''
*[{{SERVER}}/downloads/sbc/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc-minimal.bin Minimal Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc-full.bin Full Firmware]
*[{{SERVER}}/downloads/libraries/buildroot-phidgetsbc.tar.gz Buildroot/Kernel Sources]
'''For PhidgetSBC2 (1072):'''
*[{{SERVER}}/downloads/sbc2/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc2.bin SBC2 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc2-kerneldev.tar.gz SBC2 Kernel Development Package] (How-to and patch file)
'''The PhidgetSBC3 has different firmware packages based on the kernel version. In order to determine the device version of your SBC3, see the [[1073_User_Guide#SBC_Web_Interface|web configuration page]].'''

[[File:sbcver.jpg|thumb|562px|link=|The system information table is found on the Status -> System tab of the '''[[1073_User_Guide#SBC_Web_Interface|web configuration page]]''' of the SBC.]]
'''For PhidgetSBC3 (1073) kernel version 3.6.3:'''
*[{{SERVER}}/downloads/sbc3/changelog changelog]
*[{{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]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-upgrade_3.6.3_3.14.27.tar.gz SBC3 Kernel upgrade package (3.6.3 -> 3.14.27)]
'''For PhidgetSBC3 (1073) kernel version 3.14.27:'''
*[{{SERVER}}/downloads/sbc3/changelog changelog]
*[{{SERVER}}/downloads/libraries/phidgetsbc3_1.0.1.20150108.bin SBC3 Firmware]
*[{{SERVER}}/downloads/libraries/phidgetsbc3-kerneldev_1.0.1.20150108.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 SBC3 web interface. It is rarely necessary to completely re-flash your device..
<br clear = all>

==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. If the installation fails because it can't find python, you need to enable the full repository as described in [[#Getting Started_-_The_SBC_(Debian_Linux)|this section]], and then perform an apt-get update.

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

====For SBC2:====

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

====For SBC3:====

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r $ROOTFS/ system_ubifs.img
ubinize -o system_ubi.img -m 4KiB -p 256KiB 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=83MiB
# 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.

===Saving a file system to flash to multiple SBC's===
You may want to create a complete backup of your SBC root filesystem, which can then be flashed to other SBCs. This is how it could be done:

You will need a USB flash drive - at least 2GB is recommended. Make sure it's empty, as it will be reformatted.

All of these commands are executed on your SBC, while logged in over SSH.

First, re-format the USB drive as ext3. Assuming the USB drive is sda and has a single partition:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
mkfs.ext3 /dev/sda1
mount -t ext3 /dev/sda1 /media/usb0
</syntaxhighlight>
</div>

Then, remount / as readonly, so it doesn't change as we're copying it. To do this, we need to kill all running processes except sshd:

<div class="source">
<syntaxhighlight lang=bash>
service udev stop
service ifplugd stop
service rsyslog stop
service avahi-daemon stop
service phidgetwebservice stop
service ntp stop
service busybox-httpd stop
service dbus stop
service cron stop
pkill dhclient
mount -o remount,ro /
</syntaxhighlight>
</div>

If the remount says that / is busy, do a 'ps auxww' and 'pkill' anything else that may be running until it remounts properly.

Then, copy / to the flash drive:

<div class="source">
<syntaxhighlight lang=bash>
mkdir /media/usb0/root
mount --bind / /mnt/
cp -a /mnt/* /media/usb0/root/
</syntaxhighlight>
</div>

Then, clean up the copy - removing files specific to this board. We also remove the APT cache to save space.

<div class="source">
<syntaxhighlight lang=bash>
find /media/usb0/root/var/log -type f -print0 | xargs -0 rm -f
rm -rf /media/usb0/root/var/lib/apt/lists/*
mkdir /media/usb0/root/var/lib/apt/lists/partial
rm -f /media/usb0/root/var/cache/apt/*.bin
rm /media/usb0/root/etc/udev/rules.d/70-persistent-net.rules
rm /media/usb0/root/etc/ssh/ssh_host_*
</syntaxhighlight>
</div>

then, create the ubinize.cfg file:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=83MiB
vol_type=dynamic
vol_name=rootfs0
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
cd /media/usb0
cat > ubinize.cfg << EOF
[rootfs]
mode=ubi
image=/media/usb0/system_ubifs.img
vol_id=0
vol_size=64128KiB
vol_type=dynamic
vol_name=rootfs
vol_flags=autoresize
EOF
</syntaxhighlight>
</div>

NOTE: you may need to increase vol_size if your filesystem is larger.

then, create the UBI image from the copy:

For SBC3:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -F -m 4KiB -e 248KiB -c 4000 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 4KiB -p 256KiB ubinize.cfg
</syntaxhighlight>
</div>

For SBC2:

<div class="source">
<syntaxhighlight lang=bash>
mkfs.ubifs -m 2KiB -e 126KiB -c 4050 -r /media/usb0/root /media/usb0/system_ubifs.img
ubinize -o /media/usb0/system_ubi.img -m 2KiB -p 128KiB -s 512 ubinize.cfg
</syntaxhighlight>
</div>

then, unmount the drive to ensure everything is written out properly:

<div class="source">
<syntaxhighlight lang=bash>
umount /dev/sda1
</syntaxhighlight>
</div>

Then, you can remove the /root/ folder and system_ubifs.img. system_ubi.img can be flashed to other SBCs using the recovery system.

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

Wire Transfer Bank Information

2015-06-03T16:15:27Z

Patrick:

Wire Transfer Bank Information CAD

2015-06-03T16:11:22Z

Patrick:

===Wire transfers are only accepted for orders over $200 (excluding shipping charges)===

Please e-mail accounting@phidgets.com when a wire transfer has been sent; let us know the amount of the transfer and which invoice(s) you are paying.

'''Any fees charged by the sending bank are your responsibility. Please make sure that the amount sent to us covers the invoice(s) total amount due.'''

If you have any questions call us at 403.282.7335, send us a fax at 403.282.7332, or e-mail us at accounting@phidgets.com.

Here is the information that you must provide your bank to transfer '''Canadian funds''' to our CAD bank account.

{| style="border:1px solid darkgray;" cellpadding="7px;"
|-style="background: #d1d1d1" align=center
|-
| align="center" style="background:#d1d1d1;" colspan=2|[[File:cdn_flag.gif|link=]] '''Transfers in CANADIAN CURRENCY'''
|-
|style="background: #f0f0f0" align=center| Swift Code:
|style="background: #f0f0f0" align=center| HKBCCATT
|-
|style="background: #f0f0f0" align=center| Bank Name:
|style="background: #f0f0f0" align=center| HSBC Bank Canada
|-
|style="background: #f0f0f0" align=center| Branch Address
|style="background: #f0f0f0" align=center| 347 58 Ave SE, Calgary, Alberta T2H 0P3
|-
|style="background: #f0f0f0" align=center| Branch Transit:
|style="background: #f0f0f0" align=center| 10019
|-
|style="background: #f0f0f0" align=center| Institution:
|style="background: #f0f0f0" align=center| 016
|-
|style="background: #f0f0f0" align=center| Beneficiary Account Number:
|style="background: #f0f0f0" align=center| 057377-001
|-
|style="background: #f0f0f0" align=center| Beneficiary Name:
|style="background: #f0f0f0" align=center| Phidgets Inc.
|-
|style="background: #f0f0f0" align=center| Beneficiary Address:
|style="background: #f0f0f0" align=center| Unit #1 6115 4th St. S.E. <br />Calgary, AB, Canada T2H2H9
|-
|style="background: #f0f0f0" align=center| Bank Phone:
|style="background: #f0f0f0" align=center| 1.403.517.3063
|}
'''Note:''' If your bank requires our "14-digit account number" use: 10019057377001

Wire Transfer Bank Information CAD

2015-06-03T16:11:04Z

Patrick:

===Wire transfers are only accepted for orders over $200 (excluding shipping charges)===

Please e-mail accounting@phidgets.com when a wire transfer has been sent; let us know the amount of the transfer and which invoice(s) you are paying.

'''Any fees charged by the sending bank are your responsibility. Please make sure that the amount sent to us covers the invoice(s) total amount due.'''

If you have any questions call us at 403.282.7335, send us a fax at 403.282.7332, or e-mail us at accounting@phidgets.com.

Here is the information that you must provide your bank to transfer '''Canadian funds''' to our CAD bank account.

{| style="border:1px solid darkgray;" cellpadding="7px;"
|-style="background: #d1d1d1" align=center
|-
| align="center" style="background:#d1d1d1;" colspan=2|[[File:cdn_flag.gif|link=]] '''Transfers in CANADIAN CURRENCY'''
|-
|style="background: #f0f0f0" align=center| Swift Code:
|style="background: #f0f0f0" align=center| HKBCCATT
|-
|style="background: #f0f0f0" align=center| Bank Name:
|style="background: #f0f0f0" align=center| HSBC Bank Canada
|-
|style="background: #f0f0f0" align=center| Branch Address
|style="background: #f0f0f0" align=center| 347 58 Ave SE, Calgary, Alberta T2H 0P3
|-
|style="background: #f0f0f0" align=center| Branch Transit:
|style="background: #f0f0f0" align=center| 10019
|-
|style="background: #f0f0f0" align=center| Institution:
|style="background: #f0f0f0" align=center| 016
|-
|style="background: #f0f0f0" align=center| Beneficiary Account Number:
|style="background: #f0f0f0" align=center| 057377-001
|-
|style="background: #f0f0f0" align=center| Beneficiary Name:
|style="background: #f0f0f0" align=center| Phidgets Inc.
|-
|style="background: #f0f0f0" align=center| Beneficiary Address:
|style="background: #f0f0f0" align=center| Unit #1 6115 4th St. S.E. <br />Calgary, AB, Canada T2H2H9
|-
|style="background: #f0f0f0" align=center| Bank Phone:
|style="background: #f0f0f0" align=center| 1.403.517.3063
|}
'''Note:''' If you bank requires our "14-digit account number" use: 10019057377001

Wire Transfer Bank Information CAD

2015-06-03T16:10:46Z

Patrick: Created page with "===Wire transfers are only accepted for orders over $200 (excluding shipping charges)=== Please e-mail accounting@phidgets.com when a wire transfer has been sent; let us know..."

===Wire transfers are only accepted for orders over $200 (excluding shipping charges)===

Please e-mail accounting@phidgets.com when a wire transfer has been sent; let us know the amount of the transfer and which invoice(s) you are paying.

'''Any fees charged by the sending bank are your responsibility. Please make sure that the amount sent to us covers the invoice(s) total amount due.'''

If you have any questions call us at 403.282.7335, send us a fax at 403.282.7332, or e-mail us at accounting@phidgets.com.

Here is the information that you must provide your bank to transfer '''Canadian funds''' to our CAD bank account.

{| style="border:1px solid darkgray;" cellpadding="7px;"
|-style="background: #d1d1d1" align=center
|-
| align="center" style="background:#d1d1d1;" colspan=2|[[File:cdn_flag.gif|link=]] '''Transfers in CANADIAN CURRENCY'''
|-
|style="background: #f0f0f0" align=center| Swift Code:
|style="background: #f0f0f0" align=center| HKBCCATT
|-
|style="background: #f0f0f0" align=center| Bank Name:
|style="background: #f0f0f0" align=center| HSBC Bank Canada
|-
|style="background: #f0f0f0" align=center| Branch Address
|style="background: #f0f0f0" align=center| 347 58 Ave SE, Calgary, Alberta T2H 0P3
|-
|style="background: #f0f0f0" align=center| Branch Transit:
|style="background: #f0f0f0" align=center| 10019
|-
|style="background: #f0f0f0" align=center| Institution:
|style="background: #f0f0f0" align=center| 016
|-
|style="background: #f0f0f0" align=center| Beneficiary Account Number:
|style="background: #f0f0f0" align=center| 057377-001
|-
|style="background: #f0f0f0" align=center| Beneficiary Name:
|style="background: #f0f0f0" align=center| Phidgets Inc.
|-
|style="background: #f0f0f0" align=center| Beneficiary Address:
|style="background: #f0f0f0" align=center| Unit #1 6115 4th St. S.E. <br />Calgary, AB, Canada T2H2H9
|-
|style="background: #f0f0f0" align=center| Bank Phone:
|style="background: #f0f0f0" align=center| 1.403.517.3063
|}
'''Note:''' If you bank requires our "14-digit account number" use: 10019057377001