Template:UGsbc4

Advanced User's Guide

This section describes use of the PhidgetSBC outside of the web configuration, and basic opening of Phidgets over the network. This includes custom applications, using the included gcc compiler, using SSH, customizing the system, and building your own filesystem and/or kernel from sources. It is recommended that you have some experience with Linux before trying some of these tasks.

Custom Applications

The PhidgetSBC supports custom user application written in either Java or C. Custom applications are set up and managed using the configuration interface. Alternatively applications can also be created using the command line tool ‘createapp’ - the tool will guide you through the set up process.

Custom applications are created under the /mnt/userspace/userapps/(application name) directory and contain all application files. This must include at least the executable file.

Java applications must be compiled on a separate development machine, where they can also be tested before deployment. When coding, make sure to include the correct version of phidget21.jar file as part of the environment. You can use the link under Userspace: Applications page in the configuration interface to ensure that your Java program is synchronized with the version of phidget21 on the PhidgetSBC. When using Java packages, make sure to create the appropriate directory for them.

The PhidgetSBC also supports .jar files and you may find it easier to compile an upload a .jar instead of the all the necessary .class files. When your project is completed we recommend to compile the project as a .jar. This reduces the number of extra flies created into a single package that is easier to manage and can be executed from the command line, or even by double clicking the file if you operating system environment is configured properly.

Under the command line, you can use the jar utility from the Java SDK to package the .class and .java files. The process starts by going to the directory where your program is located and creating a manifest file. This manifest file tells the java jar compiler the version of the program and the name of the Main-Class which acts as the entry point for the application. The entry point is the class that contains the main method that is run when the program is started. You also want to add a line to specify the class-path which will point to the phidget21.jar file that contains the library for including into the jar.

Let’s assume we want to distribute our program MyProgram.java as an executable jar file. First, compile the program to generate the .class files. Now, create the manifest file MyProgram.mf which contains the following lines:

Manifest-Version: 1.0

Class-Path: phidget21.jar

Main-Class: MyProgram

Save the file and close it. Create the jar by running the following command from the command line:

jar cmf MyProgram.mf MyProgram.jar MyProgram.class MyProgram.java SupportClass.class SupportClass.java.

You should now have an executable jar file called MyProgram.jar that you can distribute easily as one package and run from anywhere very easily. To run the executable jar file you can either type the following into the command line:

java -jar MyProgram.jar

Or, you can double click the file in a visual operating system if your environment is configured properly.

Note: Some IDEs, such as Eclipse and Netbeans, automatically create jar files when you build your project. Simply look in your build output folders for your .jar file. Java applications can also be directly executed through SSH using jamvm.

i.e.: jamvm –jar MyProgram.ja

C programs can be compiled on the PhidgetSBC itself, via the SSH interface, or off-board using a cross compiler. Use of a cross compiler is not strictly documented here, but it is possible to build one from the buildroot distribution available on our web site. When developing C applications on the PhidgetSBC, it is recommended that you log in using the ‘user’ account instead of ‘root’. If you need to log data from a custom application, you can either log directly to the application directory with the size limits of the userspace in mind, or to /tmp if the data should be erased on reboot. Alternatively, you can use a flash drive, which are mounted automatically at /media/usb(0-9) when plugged in. Note that custom applications should not try to get user input, as stdin is closed before the application gets run.

GCC

The PhidgetSBC contains full GCC and associated build tools, as well as make and gdb for compiling C source. Use of these is the same as on full linux, just keep in mind that there is no swap space and userspace is limited. Compiling will also be slow for complicated programs. Simple programs are ideal for this environment. The C library used is uClibc. For most uses this should be similar to full libc, just much smaller. Also, when compiling a program that links with libphidget21.so, you need to add ‘-lphidget21 -ldl -lpthread -lm’ to the command line. Otherwise, you will get segfaults.

Phidget Dictionary

Communication between a custom application on the PhidgetSBC and the outside world can be facilitated by using the dictionary interface of the Phidget Webservice. The dictionary lets you set and listen for key/value pairs over the network, and take action accordingly. This could be used to post data or listen for commands over the network, while maintaining reliability and ultimate control on the PhidgetSBC itself in case of network failure. See the Phidget Programming manual for its use in your language of choice.

SSH

The built-in SSH Server can be enabled to allow console access to the PhidgetSBC. By default, this server is disabled. SSH access to the PhidgetSBC is enabled in the Network: Network configuration page on the PhidgetSBC. Projects on the PhidgetSBC should be stored in the user home directory (/home/user). Enabling the server for the first time can take several minutes as the encryption keys are generated. Once SSH is enabled, connect to the PhidgetSBC using its hostname or IP address (e.g. ‘ssh user@phidgetsbc.local’). You should login using the restricted ‘user’ account using the initial password set for the ‘root’ account. The password for the user account can be changed any time either through the unrestricted root account or directly through the user account. Files can be sent to the board using scp or by uploading through the web interface in Userspace: Userspace Browser. The SSH server does not support sftp. Text files (source code, etc.) can be edited using vi or with the web interface. On Windows, we recommend Putty for an SSH client. You can get this at http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html.

Customization

If you wish to customize the root filesystem, you have two options: customize locally on the board, or build a custom kernel and filesystem from source. If you mess up the firmware while customizing, you can always perform a board reset and start again. You may also want to to add new libraries or kernel extensions, add new Unix tools, update certain aspects, delete others, change the boot process, etc. All of this is possible, but it is also completely unsupported by Phidgets. In order to customize the root file system of a running PhidgetSBC, you will need to remount the filesystem as readwrite with the command: ‘mount -o remount,rw /’. At this point you can change any files in /, just keep in mind the amount of free space. Once the SBC is rebooted, / will again be mounted as read-only.

Custom Kernels and Filesystem

You can build the complete filesystem and kernel from the same codebase as Phidgets Inc. uses. The full Buildroot system can be downloaded from our website. Phidgets Inc. does not provide support for custom filesystems or kernels, nor do we provide advanced tutorials on the buildroot system. However, this basic information should be enough to get started. Buildroot works by building a full cross-compiler for the PhidgetSBC and then using that to build a full set of tools to create a root filesystem from scratch. It also handles building the kernel. You can use the cross compiler that it produces to build your own applications for the PhidgetSBC independently of the system, or integrate your code into the process. Buildroot downloads all of the source code it needs from open-source repositories, so the Buildroot distribution itself is fairly small. Buildroot needs to be run on Linux. Unpack the distribution and run the following commands to set everything up:

• `touch .config`
• `make BOARD=phidget_sbc getconfig`

You can build your filesystem by typing ‘make’ and change configuration options using ‘make menuconfig’. Output binaries are located in binaries/phidget_sbc - the .bin files are accepted by the PhidgetSBC upgrade system. Building the full filesystem relies on some packages which you will need to install into your Linux distribution, including but not limited to: libacl1-dev, zlib1g-dev, kaffe, liblzo2-dev. If you make changes to config files, source, etc., run ‘rm_root’ before running make, otherwise the filesystem may not be updated properly. Kernel patches are stored in: target/device/PhidgetSBC/. More information about Buildroot can be found here: http://buildroot.uclibc.org/docs.html