| Access Server: User's and Developer's Guide | ||
|---|---|---|
| <<< Previous | Next >>> | |
This chapter describes how to create and use applications by using Access Server's Software Development Kit.
The software running in Access Server can be divided to following categories:
Linux kernel and boot loader.
Bluegiga Access Server kernel device drivers (led, io, bbreset).
Bluegiga iWRAP Bluetooth stack, profiles (SPP, PAN, ObjP, FTP) and applications (for example ObexSender, connector and btcli).
Bluegiga servers (for example finder, smsgw and wpkgd) and applications (for example setup and chkconfig).
GPLed applications (for example BusyBox, OpenSSH and bash).
Applications written with Software Development Kit.
Note: The Software Development Kit can only be installed on a Personal Computer (PC) running the Linux operating system.
The following hardware and software are required to run the Access Server Development Kit:
A PC with:
CD-ROM drive
i386 Linux operating system (SDK has been tested with Foobar Linux 5, RedHat Enterprise Linux 5, Fedora Core 6 and above; SuSE and Ubuntu (Feisty) are reported to work too). SDK has not been tested on x86_64 platform.
gcc, autoconf, make, bison, byacc, flex, gawk and ncurses must be installed
Devel libraries (especially glibc-devel, zlib-devel, openssl-devel, e2fsprogs-devel, readline-devel and ncurses-devel) must be installed
300MB of available hard disk space
An Ethernet connection to a Local Area Network (also connected to Access Server) is highly recommended.
Mount the Access Server SDK CD-ROM or ISO image, change the current working directory to where it is mounted, and run the install script. If the user running install does not have privileges to create the directory for the toolchain, normally /usr/local/arm, the install script prompts for root's password.
Example (user input is printed like this):
$ mount /dev/cdrom /mnt/cdrom
$ (or mount -o loop /path/to/sdk2.iso /mnt/cdrom)
$ cd /mnt/cdrom
$ sh install
|
During the installation, the system will prompt you with some questions (described below) regarding the components to install and the paths to install them to. If you are not familiar with Linux, just press enter to these questions to accept the default values. The default values are suitable for most users and systems.
Access Server toolchain directory (default: /usr/local/arm)
This is the path where you want the Access Server Software Development tools (arm-linux-gcc, etc.) to be installed.
Note: If you change this value, the Access Server tools and libc must be recompiled. The recompilation process is complicated and lengthy, and it can also fail, depending on your system. Recompilation is automatically done by the install script, if necessary.
Development directory (default: [home_of_current_user]/asdk)
This is the path where you want the Access Server Software Development Kit to be installed.
Development directory owner (default: [current_user])
(Asked only if run as root.) This is the development directory owner's username.
Note: If this is not the username of the developer for whom the Software Development Kit is being installed, the user will not have rights to use the development files and therefore can not develop any Access Server software.
Install toolchain sources (default: no - unless the tools directory was changed)
This value indicates whether the toolchain sources will be installed. The sources are only required if the Access Server tools directory was changed from the default target location in step 1.
Compile image after installation (default: yes)
If set to yes, the install script will compile the Access Server filesystem image to test that the installation was successful and that the Development Kit is working correctly.
The fastest way to start developing Access Server applications is to study, change, and recompile the example files in the asdk/examples directory.
To demonstrate the software development features of Access Server, the Access Server Software Development Kit comes with several example applications.
The compiled example files are located in WPK packets on the Access Server SDK tree in subdirectories of directory asdk/examples.
The examples can be manually uploaded and installed on Access Server by sending them to the /tmp/obex directory. The wpkgd server automatically installs them. Uploading can be done over Bluetooth, SCP, SFTP or WWW Setup → Advanced → Upload a software update (see Figure 2-14).
The examples, with their usage and purpose, are described in Table 6-1.
Table 6-1. Examples, Their Usage and Purpose
| Example | Usage | Purpose |
|---|---|---|
| helloworld | /usr/bin/helloworld | The "Hello, world!" application. |
| serial | /usr/bin/serial /dev/ttyAT1 | "Hello, world!" to the serial port. Notice that /dev/ttyAT1 must be free (no WRAP SMS Gateway or Bluetooth Serial Port Profile is using it). |
| forkserver | SET BLUETOOTH LISTEN 11 /usr/bin/forkserver | This is the simplest Bluetooth RFCOMM server example. Use, for example, btserver as a client to test this example. This example waits for a full line from the client, echoes is back and then exits. |
| btlogger | SET BLUETOOTH LISTEN 11 /usr/bin/btlogger /tmp/logfile | This is a simple Bluetooth RFCOMM server example, which logs lines received from the connected client, and answers with "ACK". Use, for example, btserver as a client to test this example. |
| btserver | /usr/bin/btserver - for server mode (if no forkserver is running), /usr/bin/btserver <bdaddr of btserver in server mode or forkserver> 11 for client mode | This is an advanced iWRAP client example, which can run both as an RFCOMM server, when it works as forkserver, or as a client, when it sends "YooHoo" to remote server, waits, displays the response, and quits). |
| ledtest | /usr/bin/ledtest | I/O: LED example. |
| m2n | echo testmessage | /usr/bin/m2n | This is a Machine-2-Network (M2N) example. For actual remote connection, syslog must be configured to log to a remote syslog server. |
| www | Browse to http://wrap-ip-address/example.html | Demonstration of the web server capabilities. |
| makesms | Browse to http://wrap-ip-address/send.html. Notice that this example assumes that WRAP SMS Gateway is up and running (see Section 3.5.3). | This example demonstrates WRAP SMS Gateway by sending SMS messages with it. |
| setup-helloworld | Install the generated WPK and navigate in WWW Setup | This example demonstrates how to add a new helloworld submenu to the WWW Setup, with two menu items that change the variables in /etc/sysconfig/helloworld file. |
| lottery | Install the generated WPK and uncomment exec example in /etc/obexsender.conf | This example demonstrates the how ObexSender responses can be generated from an application. |
To start a new project, you must create a new subdirectory in your Development Kit's directory (asdk/) and add your application source files and Makefile to that directory.
A project skeleton can be automatically created by using the Access Server Project AppWizard. Just give the make appwiz APP=dir/to/newapp command in the Development Kit's top level directory (asdk/). A "hello world" example ANSI C project is then created.
To use C++ compiler, replace $(do_link) with $(do_link_cc) in Makefile.
The details of the compile process and variables you may need
to modify before compiling your application, such as
CFLAGS, LDFLAGS and
CXXFLAGS, can be seen in file
asdk/Rules.mak.
Now you have a new project waiting for coding. To compile the project, run make in the asdk/dir/to/newapp directory.
The build system also creates the installation packet (hello-timestamp.wpk), which can be transferred to the /tmp/obex directory of Access Server from where it is installed automatically.
The Access Server Development Kit uses the ARM port of the GNU bintools and compilers to build applications. If you are not familiar with Linux development, use the method explained in the previous section instead of writing your own makefiles.
If you still want to use your own development environment, there are two minor issues to remember:
Tools are prefixed with arm-linux-, so for calling the gcc C-compiler, you must call arm-linux-gcc, and so on.
Tools are located in /usr/local/arm/3.4.5/bin/ directory, which is not in PATH by default.
To run an application on Access Server, it must first be transferred to it. There are several ways of doing this (see Section 2.3.3). The most convenient ways in conjunction with software development are discussed in the following subsections.
An SCP transfer is done with a single command. In the following example, myapp is transferred to the /tmp directory in Access Server:
$ scp myapp root@<wrap-ip-address>:/tmp
root@<wrap-ip-address>'s password: buffy (not echoed back)
/path/to/myapp/myapp 100% 20KB 20.0KB/s 00:00
$
|
An SFTP transfer is almost similar, but the command procedure resembles an FTP session (FTP can also be used if the FTP server is enabled):
$ sftp root@<wrap-ip-address>
Connecting to <wrap-ip-address>...
root@<wrap-ip-address>'s password: buffy (not echoed back)
sftp> cd /tmp
sftp> put myapp
Uploading myapp to /dev/shm/tmp/myapp
/path/to/myapp/myapp 100% 20KB 20.0KB/s 00:00
sftp> quit
$
|
With SSHFS, the Access Server filesystem can be securely mounted to be a part of the development host's filesystem.
To download and install SSHFS, visit http://fuse.sourceforge.net/sshfs.html. After installation you can mount the whole filesystem and copy the myapp application to the /tmp directory in Access Server by using the following commands:
$ mkdir mnt
$ sshfs root@<wrap-ip-address>: mnt
root@<wrap-ip-address>'s password: buffy (not echoed back)
$ cp myapp mnt/tmp
$ fusermount -u mnt
$
|
If your Access Server is not connected to a LAN, you can use terminal software of your choice to transfer data to Access Server.
Access Server contains an X/Y/Zmodem protocol application, which allows you to transfer data over the console using almost any terminal software available:
Connect your computer to the Access Server management UART using a cross-over serial cable, and start your terminal software (use settings: 115 200bps, 8 data bits, no parity, 1 stop bit).
Change your working directory to where you want to upload your application, and run the Xmodem application with your application name as a parameter.
Start Xmodem send from your terminal software.
Example 6-1. Transfering Files with Xmodem
[root@wrap /] cd /tmp
[root@wrap /tmp] rx testapp
rx: ready to receive testapp.
now start xmodem (checksum, not CRC) send from your terminal
[root@wrap /tmp]
|
If you want to save the application to /usr/local/bin (on the flash file system), you will have to replace cd /tmp with cd /usr/local/bin (and possibly create the directory, if it does not exist). To examine Access Server directory structure, please see Appendix A.
To use NFS mount, have a NFS share prepared in your development PC and mount the directory by using command mount -o nolock <dev-pc-ipaddress>:/nfsshare /mnt/nfs. After this, you can access the share in directory /mnt/nfs.
When the share is not needed, unmount it with command umount /mnt/nfs
To use CIFS mount, have a CIFS share (for example a shared folder in Windows) available in you PC and cifs-client.wpk installed to Access Server. Mount the directory by using command mount.cifs //ipaddr-of-pc/sharename /mnt/nfs -o username. You will then be prompted for password for the username you specified. After entering correct password, you can access the share in directory /mnt/nfs.
When the share is not needed, unmount it with command umount /mnt/nfs
To run the application you just transferred to Access Server, you need access to the Access Server console, either using terminal software connected to the Access Server management UART or using the SSH connection (log in as user root and the root password, which is buffy by default).
Having established a connection to Access Server, change the directory to where your application is located and change file permissions so that it can be executed, then run it.
You can use GDB, the GNU Project debugger, to debug applications in Access Server. This requires that you install gdbserver-*.wpk package to Access Server. You can find it from SDK CD or from asdk/arch/arm/gpl/gdbserver/ directory on your development PC.
To debug an application it has to be compiled with debugging
options enabled and stripping disabled. This can be done by
overriding the default CFLAGS variable. You
can do this by modifying the Makefile for
your project:
# Makefile
SDKBASE=/home/user/asdk
include $(SDKBASE)/Rules.mak
CFLAGS=-Wall -Os -ggdb -I$(SDKBASE)/include -L$(SDKBASE)/lib
ifdef SDKINSTALL
...
|
After you have compiled your application with these options and transferred it to Access Server, you can start debugging the application as follows:
Start gdbserver on Access Server. For example:
gdbserver :6789 /tmp/hello |
Start arm-linux-gdb on development PC. For example:
/usr/local/arm/3.4.5/bin/arm-linux-gdb \ -ex 'set solib-absolute-prefix /usr/local/arm/3.4.5/arm-linux' \ -ex 'target extended-remote Access_Server_IP:6789' \ hello |
Run the application by using continue command.
You can also use Data Display Debugger (DDD), a graphical front-end to GDB. Start it as:
ddd --debugger "/usr/local/arm/3.4.5/bin/arm-linux-gdb \ -ex 'set solib-absolute-prefix /usr/local/arm/3.4.5/arm-linux' \ -ex 'target extended-remote Access_Server_IP:6789'" \ hello |
It is also possible compile applications for Access Server using native toolchain. To use it, copy files sdk.iso and sdkmount.wpk from directory lib in the Access Server SDK CD-ROM (or ISO image) to the root directory of an USB memory dongle, and insert it to Access Server's USB port. (You can also use Compact Flash memory card for this purpose in similar manner). The native SDK is automatically mounted and you can start using the compiler (gcc) in Access Server. All tools now available can be found in directory /usr/sdk/bin.
| <<< Previous | Home | Next >>> |
| Obexsender | iWRAP - The Bluetooth API |