2.3.1. Management Console

If you do not have a Bluetooth LAN/PAN client and if Access Server is not connected to your LAN, or if you do not know the IP address given to Access Server, you can get the first shell prompt access by using the management console.

To setup the management console, proceed as follows:

1. Have a PC with a free COM port.

2. Power off Access Server.

3. Configure your terminal application, such as HyperTerminal in Windows, to use the settings below for your computer's free COM port

   Table 2-1. The Management Console Port Settings

   Setting	Value
   Speed	115200bps
   Data Bits	8
   Parity	None
   Stop Bits	1
   Flow Control	None

4. Connect the serial cable shipped with Access Server to your PC's free COM port.

5. Connect the serial cable to the management (user) port in Access Server (see Figure 2-2).

6. Power on Access Server.

7. Enter letter b in the terminal application during the first five seconds, while the blue LEDs in Access Server turn on one by one.

8. The management console is now activated and you can see the boot log in your terminal window.

   Note: The boot process may stop at the following U-Boot prompt:

   Hit any key to stop autoboot: 0 U-Boot>

   If this happens, enter command boot to continue to boot Linux.

9. Wait for the device to boot up and end with the following prompt:

   Please press Enter to activate this console.

10. Press Enter to activate the console. You will be logged in as root in directory /root:

    [root@wrap root]

11. You can now control Access Server from the management console.

2.3.2. Accessing Remotely

When Access Server is connected to a LAN, it tries to get the IP address by using DHCP and Zeroconf by default. You can then use the wrapfinder application to find the IP address (see Section 2.2).

If you cannot get the IP address by using the wrapfinder, another way to see the IP address of Access Server is to connect with a management console (see previous section), power on the unit and, after the system is up and running, give the ifconfig nap command. The inet addr field for the nap interface contains the IP address of Access Server. For example, in the following capture from the management console, the IP address is 192.168.42.3.

        [root@wrap /]$ ifconfig nap
        nap      Link encap:Ethernet  HWaddr 00:07:80:00:BF:01
                 inet addr:192.168.42.3  Bcast:192.168.42.255  Mask:255.255.255.0
                 inet6 addr: fe80::207:80ff:fe00:bf01/64 Scope:Link
                 UP BROADCAST MULTICAST  MTU:1500  Metric:1
                 RX packets:12635 errors:0 dropped:0 overruns:0 frame:0
                 TX packets:8 errors:0 dropped:0 overruns:0 carrier:0
                 collisions:0 txqueuelen:100
                 RX bytes:1686246 (1.6 MiB)  TX bytes:1640 (1.6 KiB)
                 Interrupt:24 Base address:0xc000
      

You can use this address to connect to Access Server remotely over SSH, SCP or SFTP.

2.3.3. Transferring Files to/from Access Server

You can transfer files to and from Access Server by using, for example:

• SCP (secure copy over SSH)

• SFTP (secure FTP connection over SSH)

• FTP (plain FTP connection)

  Note: FTP is disabled by default for security reasons. Use SFTP instead.

  Tip: If enabled, use the integrated FTP client on the Internet Explorer (type ftp://root:buffy@wrap-ip-address/ in the address bar)

• Bluetooth OBEX (Object Push and File Transfer Profiles) to/from directory /tmp/obex in Access Server

• NFS (mount an NFS share from a remote computer as a part of Access Server's file system)

• SSHFS (mount an Access Server directory over SSH as a part of any other Linux host file system)

  To download and install SSHFS, visit http://fuse.sourceforge.net/sshfs.html.

• CIFS (mount a Common Internet File System share from a remote computer as a part of Access Server's file system). A CIFS client, available in a separate installation packet, is required.

• USB memory dongle (see Section 3.4 for more information).

• Xmodem/Ymodem/Zmodem (use rz/rx/rb/sz/sx/sb commands from the management console)

For examples of transferring files, see Section 6.3.4.

3.2.1. iWRAP Password Protection

The access to iWRAP can be password protected. The default password is buffy, but it can be set off or changed with the setup application (see Section 2.4). The password is case sensitive. The password must be typed in as the first command after the server has replied with "READY."

3.2.2. LAN Access Profile

This profile is not automatically started at boot. The default settings can be changed with the setup application (see section Section 2.4), or runtime with the iWRAP interface (see Chapter 7).

Access Server can also act as a LAN Access Client, but in this case it must be controlled manually using iWRAP commands, as described in Chapter 7.

3.2.3. Serial Port Profile

This profile is not automatically started at boot. The default settings can be changed with the setup application (see section Section 2.4).

The Serial Port Profile is used to replace an RS-232 serial cable between two devices with a Bluetooth connection. The physical setup is shown in Figure 3-1.

State A) in the figure is the starting situation with a serial cable connecting the devices. This cable is to be replaced with a Bluetooth connection.

In state B) the long serial connection is replaced with a Bluetooth Serial Port Profile connection between the two Access Server devices. These Access Server devices are then locally connected to the user devices with (short) serial cables. The cable between user device A and Access Server device A must be a cross-over cable. The cable between user device B and Access Server device B must be similar (direct or cross-over) to the one used in state A).

If RTS/CTS handshaking is used to ensure correct data transfer, the serial cables must have these pins connected. Notice that this handshaking is "local": it takes place between the user device and Access Server. No handshaking between user device A and user device B on the other end of the Bluetooth connection is provided.

If RTS/CTS handshaking is not used, CTS must be connected to DTR.

DCD, DTR, and DSR signals are not supported. This also means that user devices A and B will not be able to tell whether or not the Bluetooth connection is up.

When the physical setup is ready, you can configure the Bluetooth Serial Port Profile settings. By default, the profile is listening in DevB mode, at 115200 bps, 8 data bits, no parity, 1 stop bit, and RTS/CTS enabled. To change these settings, use the setup application or the WWW Setup interface, as described in Section 2.4.

3.2.4. Object Push and File Transfer Profile

Access Server has two OBEX profiles, Object Push Profile (ObjP) and File Transfer Profile (FTP). You can use these profiles to transfer files between different Access Servers and other devices supporting ObjP or FTP.

	  obexput [parameters] bdaddr channel file(s)
	

	  obexget [parameters] bdaddr channel file(s)
	

	  obexsender-put parameters
	

	  regex <match1>
	  regex <match2>
	  file <fakename1> </path/to/file1>
	  file <fakename2> </path/to/file2>
	  exec </path/to/command1>
	  exec </path/to/command2>
	  regex <match3>
	  file <fakename3> </path/to/file3>
	  ...
	

	  regex Nokia.9500
	  file hello.jpg /usr/local/obexsender/files/communicator.jpg
	  regex .
	  file hello.jpg /usr/local/obexsender/files/unknown.jpg
	

	  obexsender-inquiry parameters
	

3.2.5. PAN Profiles

Access Server has support for all PAN profile modes: Personal Area Network User (PANU), Network Access Point (NAP) and Generic Networking (GN). Accepting incoming PAN connections to any of these modes is disabled by default for security reasons.

Access Server can be configured to accept incoming PAN connections and the default settings can be changed by using the setup application (see section Section 2.4).

The Network Access Point mode is the most useful PAN profile mode. You can enable it by sending the enable-pan.wpk file (available on-line at https://www.bluegiga.com/as/current/enable-pan.wpk) to Access Server by using the Bluetooth Object Push profile. Alternatively, you can copy the file to the root of a USB memory dongle and insert the dongle to Access Server's USB port.

The device creating the PAN connection decides upon the modes to be used. Access Server automatically handles incoming connections. Access Server can also act as a PAN client, but in this case it must be controlled manually by using the iWRAP interface, described in Chapter 7.

3.2.6. Changing the Bluetooth Range

The transmit power of Access Server is configurable. By default, class 1 (100 meter range) settings are used. The settings can be changed down to "class 2" (10 meter range) settings with the btclass 2 command, or even lower with the btclass 3 command. Class 1 settings can be restored with the btclass 1 command. You can find these command also in Setup → Advanced settings → Bluetooth commands menu in the WWW Setup interface.

After btclass # is given, it is recommended to reboot Access Server once to restart ObexSender and other applications connected to the iWRAP server(s).

3.2.7. btcli

You can send iWRAP commands from the command line by using the btcli application. See Section 7.4 for more information.

3.3.1. Compact Flash GPRS Cards

The operating system automatically identifies the Compact Flash GPRS card when it is inserted. Access Server can use the GPRS card to connect to the GPRS network, or to act as an SMS gateway to send and receive SMS messages.

You can enable the GPRS mode and configure its settings, such as the SIM card's PIN code, by using the setup application or its WWW interface. For more information, see Section 2.4 and documentation for Setup → Network settings → Enable GPRS interface in Appendix B.

GPRS, when enabled, is by default only turned on when needed. If Access Server can access the Internet (or any desired address) by using the default interface nap, it does not activate and use the GPRS (ppp0) interface.

The simplest way to test the GPRS interface is to configure the default interface nap to use dynamic network configuration (the default) and enable GPRS through the setup application, then to disconnect the ethernet cable, reboot the device with the management console enabled. After the boot, ping an IP address in the Internet, such as 194.100.31.45 (bluegiga.com).

The first five or so packets are lost, but after that the GPRS connection should be up. To enable the interface automatically, just enter ping -c 20 ip-in-internet to /etc/rc.d/rc.local.

Using WRAP SMS Gateway Server is documented in Section 3.5.3.

If needed for some special use, the Compact Flash GPRS card can also be accessed directly from /dev/ttyS0, a device file which exists if the GPRS card is successfully initialized.

3.3.2. Compact Flash GPS Card

The operating system automatically identifies the Compact Flash GPS card when it is inserted. At that time, the device file /dev/ttyS0 is created and the GPS card can be accessed by using that device with the serial port settings the GPS card uses.

The supported Compact Flash cards are listed in Appendix C.

3.3.3. Compact Flash Wi-Fi Cards

Access Server supports Prism II/III based CF Wi-Fi cards. The supported Compact Flash cards are listed in Appendix C.

By default, Access Server notices when a supported Wi-Fi card is inserted and tries to use it in the client mode, without encryption. So, if there is an open Wi-Fi Access Point in range, Access Server will automatically connect to it.

To configure Wi-Fi to the Access Point mode, or to change other Wi-Fi settings, use the setup application or its WWW interface at Setup → Network settings → Wi-Fi.

A standard set of command line wireless utilities is provided to fine-tune your Wi-Fi configuration:

• iwconfig

• iwlist

• iwpriv

For more information on these utilities, see: http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html

3.5.1. Finder

The Finder service is a small service, which listens for UDP broadcast queries from Access Server Finder applications and responses to those queries with identification information (IP address, model, serial number, etc.) about Access Server.

The finder command can be used to query Finder service information from Access Servers in the network. With no parameters, finder sends the query using the broadcast address of the default interface (nap). Broadcasting to networks of other interfaces can be done with --interface parameter, such as the zero configuration interface nap:9in the following example:

        [root@wrap root]$ finder --interface nap:9
        Access Server 2291 (S/N: 0402110112) (build: 3.1)
        - Hostname: wrap.localdomain
        - IP: 169.254.30.233 (nap:9), 192.168.161.1 (gn)
        - Ethernet MAC: 00:07:80:00:03:ed
        - iWRAP: 10101 00:07:80:80:0b:c3 bt1.2 (W0402110112_1)
        Access Server 2291 (S/N: 0606221029) (build: 3.1)
        - Hostname: wrap.localdomain
        - IP: 169.254.36.138 (nap:9), 192.168.161.1 (gn)
        - Ethernet MAC: 00:07:80:00:0d:44
        - iWRAP: 10101 00:07:80:80:0b:c4 bt1.2 (W0606221029_1)
        [root@wrap root]$
      

With parameter --send finder will send info once to a specified host, for example to inform that device has booted.

For information about the finder protocol, see Chapter 9.

3.5.2. ObexSender

The ObexSender application is automatically started in Access Server. Its purpose is to receive business cards (vCards), images, or other files, and analyze their content and send files back selecting them based on configured keywords found.

ObexSender can also make an inquiry for bluetooth devices, and automatically send one or more files to all new devices found.

ObexSender can be configured with the setup application or by editing the /etc/obexsender.conf file (see Section 2.4).

For detailed instructions on using ObexSender, see Chapter 5.

3.5.3. SMS Gateway Server

WRAP SMS Gateway Server supports Nokia 20, Nokia 30, or Wavecom WMOD2 compatible GSM terminals and the supported GSM/GPRS Compact Flash cards for sending and receiving SMS messages. By default, the Compact Flash card is used. The PIN code query of the SIM card at power-up must be disabled.

WRAP SMS Gateway Server is disabled by default. To enable it, use the setup application's WWW interface, as described in section Section 2.4. Enabling is done at Setup → Applications → Default startup applications → smsgw.

WRAP SMS Gateway Server can be configured to use a modem connected to the user serial port with the setup application or its WWW interface by changing the setting at Setup → Applications → SMS gateway settings → Modem device to /dev/ttyAT1 from the default /dev/ttyS0.

For further information on using smsgw, see the makesms example in Section 6.3.1.

3.5.4. User Level Watchdog

WRAP User Level Watchdog daemon listens on UDP port 4266 for "id timeout" messages. "id" is an ASCII string, without spaces. If "timeout" equals to 0 (zero), the "id" is removed from the list of processes to wait. If "timeout" is greater than 0 (zero), the "id" is added or updated.

When there is no message for "id" received within the "timeout" seconds, the user level watchdog dies and the kernel watchdog reboots Access Server.

The watchdog command can be used to send messages to the watchdog daemon. This is done through command watchdog id timeout. For example, watchdog test 5.

3.5.5. Remote Management

Access Server contains simple tools that provide means for full and secure remote management of the device.

The basic remote management can be performed using the WWW Setup interface, SSH command line access, and SCP and SFTP file transfer protocols.

In addition to those, Access Server contains WRAP Remote Management System for transferring management packets over different media to Access Server and automatically sending response packets back.

The management packets (*.wpk) are automatically processed when they are transferred to the autoinstall directory in Access Server (/tmp/obex by default, but configurable with the setup application or WWW interface at Setup → Applications → wpkgd settings). The easiest way to transfer a management packet to this directory is to upload it from WWW Setup at Setup → Advanced settings → Upload a software update.

          %wpkg-version: 2
          %wpkg-prepare:
          echo Hello world
        

          %wpkg-version: 2
          %wpkg-prepare:
          FOO=`pwd`
          cd /
          tar xzf ${FOO}/files.tar.gz
          echo Done.
        

          %wpkg-version: 2
          %wpkg-format:  vcf
          %wpkg-prepare:
          ipaddr() {
          echo `ifconfig nap | grep "inet addr" | awk -F [:] \
            \\{print\\$2\\} | awk \\{print\\$1\\}`
          }
          serialno() {
          echo `wrapid | grep Hardware | awk \\{print\\$5\\}`
          }
          echo -e "BEGIN:VCARD\r"
          echo -e "VERSION:2.1\r"
          echo -e "N:`serialno`\r"
          echo -e "TEL:`ipaddr`\r"
          echo -e "URL:`hostname`\r"
          echo -e "END:VCARD\r"
        

          %wpkg-version: 2
          %wpkg-reply:   none
          %wpkg-prepare:
          echo A > /dev/led
          sleep 1
          echo a > /dev/led
        

3.5.6. FTP

If you enable the FTP server, users can use it to log in anonymously to the /tmp/obex directory with download access or as root with password buffy to the root directory with full access. The password and other settings can be changed on Access Server with the setup application or by editing the /etc/ftpd.conf file (see Section 2.4).

3.5.7. Web Server

The integrated web server in Access Server supports HTTP/1.0 methods GET and POST, and has light user authentication capabilities. The content can be either static or dynamic - the WWW server is CGI/1.1 compatible.

The web server is always running and the content (http://wrap-ip-address/) is located in the /var/www/html/ directory in Access Server's file system.

The web server is configured to protect the WWW Setup interface with a username and password. The default username and password can be changed as instructed in Section 2.4. For further information about using the web server for your own applications, see the web examples in Section 6.3.1.

3.5.8. SNMP

A separate software update package is available from Bluegiga Techforum (https://www.bluegiga.com/techforum/). This update adds the Net-SNMP suite of applications to Access Server. The current Net-SNMP implementation for Access Server is limited and will be extended in the future. However, it can be used to poll the basic status of Access Server.

Configuration details can be found and altered in configuration file /etc/snmp/snmpd.conf, which is accessible as described in Section 2.4.

For more information about the Net-SNMP suite, see http://net-snmp.sourceforge.net/

3.5.9. OpenVPN

A separate software update package is available from Bluegiga Techforum (https://www.bluegiga.com/techforum/). This update adds the OpenVPN™, a full-featured SSL VPN solution, to Access Server.

For detailed instructions on using OpenVPN with Access Server, see Section 10.4.

For more information about the OpenVPN™, see http://openvpn.net/.

3.5.10. SSH

By default, users can use SSH to log in (or SCP and SFTP to transfer files) as user root with password buffy. The password can be changed on Access Server by using command passwd or with the setup application.

3.5.11. Telnet

If you enable telnet, users can log in over telnet as user root with password buffy. The password can be changed on Access Server using the command passwd or with the setup application.

3.5.12. NTP

The ntpd service uses the standard Network Time Protocol (NTP) to keep Access Server system time automatically in sync using a random selection of eight public stratum 2 (NTP secondary) time servers. The service is also configured to answer NTP requests from other devices.

The NTP server configuration can be altered by editing its configuration file /etc/ntpd.conf.

4.1.1. Standard Operation

With the standard configuration, SPP-over-IP works as described below:

• Listens for incoming Serial Port Profile (SPP) connections

• Takes control of all incoming connections

• Opens a TCP connection to the defined IP address and TCP port

• Forwards all incoming data from the SPP device to the established TCP connection and vice versa

All the server computer needs to do is to listen for incoming TCP connections from Access Server to a specified TCP port and receive/send the application data.

4.1.2. Repeater Operation

The SPP-over-IP application can also be used in a so-called repeater mode. This feature is useful when all Access Servers can not be directly connected to the TCP/IP network, but they can be connected to other Access Servers by using Bluetooth PAN-connection. PAN enables transmitting TCP/IP packets wirelessly over Bluetooth. The figure below illustrates this configuration:

4.1.3. SPP-over-IP over GPRS

SPP-over-IP software can also be used over GPRS instead of wired Ethernet connection. This requires that Access Server is equipped with a working GSM/GPRS compact flash card. See Appendix C for supported cards.

Notice when using GPRS:

• Data upload rate is around 8-12kbps (depending on GPRS card)

• Data download rate is around 32-48kbps (depending on GPRS card)

• Data transmission delays can be very high, sometimes even seconds

• GPRS connection may be unreliable and break easily. This should be taken account when designing the system. If GPRS connection breaks, all the TCP and Bluetooth connections will also be closed.

4.1.4. Opening Connections from Access Server

In the basic SPP-over-IP use case, Access Server is in passive mode and only accepts incoming connections. Using connector service, Access Server can open and maintain outgoing Bluetooth connections to defined Bluetooth devices

4.1.5. SPP-over-IP and COM Ports

SPP-over-IP can also be used together with Tactical Software's Serial/IP�? software. Serial/IP software simply converts the TCP connections into virtual COM ports on the host computer. This is very useful in applications, which do not have support for TCP/IP but support COM ports instead.

An evaluation version of Serial/IP can be downloaded from: http://www.tacticalsoftware.com/products/serialip.htm

4.2.1. Forwarding Incoming Connections

The basic SPP-over-IP operation, listening incoming Bluetooth connections and forwarding them to a TCP/IP socket on a remote host (or a local application), is configured at Setup → iWRAP settings → Bluetooth profiles → Connection forwarding. For details of the settings, see Section B.5.1.5

4.2.2. Maintaining and Forwarding Outgoing Connections

The SPP-over-IP connector, which opens and maintains outgoing Bluetooth connections and forwards them to a TCP/IP socket on a remote host (or a local application), is configured at Setup → Applications → Connector. For details of the settings, see Section B.4.1

4.2.3. Repeater Configuration

If you want to configure Access Server also to act as a repeater (see Figure 4-2) you must make some additional configurations. Add the line below to your Bluetooth startup script, editable at Setup → iWRAP settings → Edit startup script. Line starting with # is comment which can be left out:

# Automatically connect to Access Server with PAN-NAP enabled using baseband 1
10101 SET CONTROL AUTOEXEC CALL 00:07:80:bf:01 PAN-NAP
        

You must replace the Bluetooth address used in the example (00:07:80:80:bf:01) with the Bluetooth address of the Access Server, on which you want to receive the PAN connection.

The Bluetooth PIN codes must be the same in both Access Servers.

In the example configuration (Figure 4-6) connection forwarding has already been configured using the WWW Setup (two lines above the SET CONTROL AUTOEXEC line).

4.2.4. Wi-Fi Configuration

If Access Servers must be connected to Wi-FI (WLAN) instead of physical Ethernet connection, you also need to make additional configurations through the WWW setup.

See Section 3.3.3 for more information.

4.2.5. GPRS Configuration

If Access Servers must be connected to GPRS network instead of physical Ethernet or Wi-Fi connection, you also need to make additional configurations through the WWW setup.

See Section 3.3.1 for more information.

5.2.1. Content Push

This is the standard functionality in ObexSender. In content push mode, ObexSender is scanning for devices and pushing it to clients who belong to the target group (not opted out by filtering).

5.2.2. Content Pull

ObexSender can also be configured into a content pull mode. In this mode, the transaction is initiated by the user. The user can send any file to the server or alternatively a file containing some specific string such as "MP3" or "NOKIA N73". The server parses the received file and as a response pushes a corresponding file to the user if such exists.

5.3.1. Uploading Files

ObexSender needs content (files) to be send for users. These can easily be uploaded by navigating to Setup → Applications → ObexSender settings → Upload a new file. All you need to do is browse for the file you want to upload and click Upload. You will see a confirmation note, for example "File /usr/local/obexsender/files/pic.jpg uploaded" .

At the moment, you can only upload to /usr/local/obexsender/files directory from ObexSender main menu. If you would like to upload to another directory, you can do it from Setup → Advanced settings → Browse all files menu.

You can also use secure FTP to transfer files (normal FTP is disabled by default in Access Server for security reasons). For example WinSCP, available from http://www.winscp.org, is a good application for secure FTP file transmissions.

5.3.2. Configuring Content Rules

Specifying the content (files) to be sent by ObexSender is done by adding send and reply directives to ObexSender configuration file /etc/obexsender.conf. The file is editable at Setup → Applications → ObexSender settings → Edit configuration file and also contains usage examples of both directives.

5.3.3. How to Store Files Sent to Access Server

By default, all files sent over Object Push to Access Server are stored to the /tmp/obex directory and deleted after they have been processed. It is however possible to save a copy of the file to another directory before it is deleted. This is configured by adding the --fork with cp command to the Optional parameters for server setting in Setup → iWRAP Settings → Bluetooth profiles → Object push profile settings menu, following the example of parameters below:

--bdaddr $b --prefix $b-$P- --fork '/bin/cp $$t /tmp/$$p$$d-$$T'
          

Now, after reboot, all incoming files are copied to /tmp directory. The format of the files is bdaddr-btserverport-timestamp-filename.ext.

6.2.1. Access Server Software Development Kit System Requirements

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

6.2.2. Questions Asked by the Install Script

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.

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.

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.

6.3.1. Application Examples

To demonstrate the software development features of Access Server, the Access Server Software Development Kit comes with several example applications.

6.3.2. Creating a New Project

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.

6.3.3. Building from the Command Line

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:

1. Tools are prefixed with arm-linux-, so for calling the gcc C-compiler, you must call arm-linux-gcc, and so on.

2. Tools are located in /usr/local/arm/3.4.5/bin/ directory, which is not in PATH by default.

6.3.4. Transferring an Application to Access Server

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.

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

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

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

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

6.3.5. Running an Application Transferred to Access Server

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.

          [root@wrap /] cd /tmp
          [root@wrap /tmp] chmod 755 testapp
          [root@wrap /tmp] ./testapp
        

6.3.6. Using GNU Project Debugger (GDB)

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:

1. Start gdbserver on Access Server. For example:

   gdbserver :6789 /tmp/hello

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

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

6.3.7. Native SDK

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.

7.3.1. Forklistener

This is a standard program reading data from standard input and writing output to standard output. See the SDK directory examples/forkserver/ for an example of this kind of program.

Pros:

• Easy to write.

• Very robust for simple services.

• You do not have to understand Bluetooth or iWRAP.

Cons:

• Your program is started and stopped for every incoming connection.

• If there are multiple connections, it is not possible to communicate to an external program through one socket.

• You cannot use stdout for debugging; you must use syslog or a log file.

• iWRAP's advanced features are not available: powermodes, MSC, SDP, inquiry, ...

To setup a forklistener, see the SET command.

7.3.2. iWRAP Client

iWRAP client is a program communicating with the iWRAP server through control and data sockets. See the SDK directory examples/btserver/ for an example of this kind of program.

Pros:

• The cons with forklistener do not apply.

Cons:

• More complex than forklistener.

• You must have basic knowledge about Bluetooth and iWRAP.

• If you have multiple iWRAP clients (which is usually the case), some kind of IPC is usually needed. For example, if client #1 uses CALL command, client #2 may not do the same before client #1 receives RINGING reply. The easiest way to do this is to use LOCK command.

10.4.1. Prerequisites

First, download OpenVPN from http://openvpn.se/. A normal OpenVPN version using plain command line interface is available in http://openvpn.net/download.html. The basic instructions naturally apply for both versions, since the actual software is the same. OpenVPN GUI is only available for Windows OS.

For Access Server, you must download the OpenVPN installation packet from https://www.bluegiga.com/techforum/. If you do not have access to the Tech forum, you can apply for access in the same site. In the Tech forum, go to Access Server -> Downloads, where you can find the installation packet called openvpn-2.0.8-1.wpk. Access Server is a Linux system, and only command line interface is provided at this point.

This guide relies on material provided in http://openvpn.net/. If you want more specific information on features described here or other features OpenVPN provides, please visit http://openvpn.net/howto.html.

10.4.2. Installing OpenVPN

In Windows, execute the installation file and wait until it is complete. There should be no need for reboot. After this, the OpenVPN icon appears in the system tray. Right-click the icon and you can see the available options

In Access Server, the easiest way to install OpenVPN is through the WWW setup. See Section 2.2 for instructions on how use it.

When in WWW setup, go to Setup → Advanced settings → Upload a software update. There you can choose the openvpn-2.0.8-1.wpk installation packet and upload it to the server. After this you can go to Setup → Advanced settings → System information → List installed software components. If you can see openvpn in this list, the installation is complete.

10.4.3. Creating Certificates and Keys

In this chapter, we create the necessary files to ensure privacy in the VPN, i.e. we will establish a Public Key Infrastructure (PKI). The PKI consists of:

• A master Certificate Authority (CA) certificate and key which is used to sign each of the server and client certificates.

• A separate certificate (also known as a public key) and private key for the server and each client.

OpenVPN uses bi-directional authentication, which means that both server and client will authenticate each other using certificates before connection is considered safe.

To create the files we will use a set of scripts bundled with OpenVPN for Windows. To see how the same thing is done in Linux, see http://openvpn.net/howto.html#pki.

In Windows, open up a Command Prompt window and go to \Program Files\OpenVPN\easy-rsa. Run the following batch file to copy configuration files into place (this will overwrite any existing vars.bat and openssl.cnf files):

init-config
      

Now, edit the vars file (called vars.bat on Windows) and set the KEY_COUNTRY, KEY_PROVINCE, KEY_CITY, KEY_ORG, and KEY_EMAIL parameters. Do not leave any of these parameters blank.

vars
clean-all
build-ca
      

The build-ca builds the certificate authority (CA) certificate and key by invoking the interactive openssl command:

ai:easy-rsa # ./build-ca
Generating a 1024 bit RSA private key
............++++++
...........++++++
writing new private key to 'ca.key'
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [FI]:
State or Province Name (full name) [NA]:
Locality Name (eg, city) [ESPOO]:
Organization Name (eg, company) [OpenVPN-TEST]:
Organizational Unit Name (eg, section) []:
Common Name (eg, your name or your server's hostname) []:OpenVPN-CA
Email Address [[email protected]]:
      

Next, we will generate a certificate and private key for the server:

build-key-server server
      

As in the previous step, most parameters can be defaulted. When the Common Name is queried, enter "server". Two other queries require positive responses, "Sign the certificate? [y/n]" and "1 out of 1 certificate requests certified, commit? [y/n]".

Generating client certificates is very similar to the previous step:

build-key client
      

If you want to use many clients, then you could use, for example, the following commands:

build-key client1
build-key client2
build-key client3
      

In this case, remember that for each client, make sure to type the appropriate Common Name when prompted, i.e. "client1", "client2", or "client3". Always use a unique common name for each client.

Next we'll create Diffie Hellman parameters that must be generated for the OpenVPN server:

build-dh
      

The output is as follows:

ai:easy-rsa # ./build-dh
Generating DH parameters, 1024 bit long safe prime, generator 2
This is going to take a long time
.................+...........................................
...................+.............+.................+.........
......................................
      

Now you can find the generated keys and certificates in the keys subdirectory. The final step in the key generation process is to copy all files to the machines which need them, taking care to copy secret files (server.key and client.key) over a secure channel.

10.4.4. Creating Configuration Files

Both the server and client devices must have certain configuration files for OpenVPN to determine, for example, which IP addresses to use. In this chapter, we will create a basic configuration file for OpenVPN server and client. We'll make the PC as server and Access Server as the client. An example configuration files can be found here: http://openvpn.net/howto.html#examples. In our example, we use most of the setting described in these files.

port 1194
proto udp
dev tun
ca "C:\\Program Files\\OpenVPN\\config\\ca.crt"
cert "C:\\Program Files\\OpenVPN\\config\\server.crt"
key "C:\\Program Files\\OpenVPN\\config\\server.key"
dh "C:\\Program Files\\OpenVPN\\config\\dh1024.pem"
server 172.30.203.0 255.255.255.0
ifconfig-pool-persist C:\\Program Files\\OpenVPN\\config\\Logs\\ipp.txt
keepalive 10 120
persist-key
persist-tun
status C:\\Program Files\\OpenVPN\\config\\Logs\\openvpn-status.log
verb 3
tls-timeout 4
	  

port 1194
    

proto udp
    

dev tun
    

ca "C:\\Program Files\\OpenVPN\\config\\ca.crt"
    

cert "C:\\Program Files\\OpenVPN\\config\\server.crt"
    

key "C:\\Program Files\\OpenVPN\\config\\server.key"
    

dh "C:\\Program Files\\OpenVPN\\config\\dh1024.pem"
    

server 172.30.203.0 255.255.255.0
    

ifconfig-pool-persist C:\\Program Files\\OpenVPN\\config\\Logs\\ipp.txt
    

keepalive 10 120
    

persist-key
    

persist-tun
    

status C:\\Program Files\\OpenVPN\\config\\Logs\\openvpn-status.log
    

verb 3
    

tls-timeout 4
    

client
dev tun
proto udp
remote 192.168.42.1 1194
resolv-retry infinite
nobind
persist-key
persist-tun
ca /usr/local/openvpn/ca.crt
cert /usr/local/openvpn/conf/client1.crt
key /usr/local/openvpn/conf/client1.key
verb 3
	  

client
    

dev tun
    

proto udp
    

remote 192.168.42.1 1194
    

resolv-retry infinite
    

nobind
    

persist-key
    

persist-tun
    

ca /usr/local/openvpn/conf/ca.crt
    

cert /usr/local/openvpn/conf/client.crt
    

key /usr/local/openvpn/conf/client.key
    

verb 3
    

10.4.5. Starting up VPN

First, place the configuration files in the client and server. Like in the examples, the location for these files can be, for example, C:\Program Files\OpenVPN\config in Windows and /usr/local/openvpn/config in Linux. Next, copy the authentication files ( ca.crt, server.crt, server.key, client.crt and client.key) into the same directories.

openvpn [server_config_file]
    

Sun Feb  6 20:46:38 2005 OpenVPN 2.0_rc12 i686-suse-linux [SSL] [LZO] [EPOLL] built on Feb  5 2005
Sun Feb  6 20:46:38 2005 Diffie-Hellman initialized with 1024 bit key
Sun Feb  6 20:46:38 2005 TLS-Auth MTU parms [ L:1542 D:138 EF:38 EB:0 ET:0 EL:0 ]
Sun Feb  6 20:46:38 2005 TUN/TAP device tun1 opened
Sun Feb  6 20:46:38 2005 /sbin/ifconfig tun1 10.8.0.1 pointopoint 10.8.0.2 mtu 1500
Sun Feb  6 20:46:38 2005 /sbin/route add -net 10.8.0.0 netmask 255.255.255.0 gw 10.8.0.2
Sun Feb  6 20:46:38 2005 Data Channel MTU parms [ L:1542 D:1450 EF:42 EB:23 ET:0 EL:0 AF:3/1 ]
Sun Feb  6 20:46:38 2005 UDPv4 link local (bound): [undef]:1194
Sun Feb  6 20:46:38 2005 UDPv4 link remote: [undef]
Sun Feb  6 20:46:38 2005 MULTI: multi_init called, r=256 v=256
Sun Feb  6 20:46:38 2005 IFCONFIG POOL: base=10.8.0.4 size=62
Sun Feb  6 20:46:38 2005 IFCONFIG POOL LIST
Sun Feb  6 20:46:38 2005 Initialization Sequence Completed
    

openvpn [client_config_file]
    

ping 10.8.0.1