1.1. Licenses and Warranty

Some software components are licensed under the terms and conditions of an open source license. Details can be found in Appendix C. Upon request, Bluegiga will distribute a complete machine-readable copy of the source of the aforementioned open source software components during a period of three (3) years from the order date of the product. Delivery costs of the source code will be charged from the party requesting the source code.

The Bluegiga WRAP Product Limited Warranty Statement is located in the file \doc\warranty.pdf on the WRAP Access Server SDK CD-ROM.

1.2. Bluegiga Technologies Contact Information

Please see https://www.bluegiga.com/ for news and latest product offers. For more information, contact <[email protected]>.

Please check https://www.bluegiga.com/techforum/for software and documentation updates.

Please contact <[email protected]> if you need more technical support. To speed up the processing of your support request, please include as detailed information on your product and your problem situation as possible.

Please begin your email with the following details:

• Access Server product type

• Access Server product serial number

• Access Server software version

• End customer name

• Date of purchase

2.1. Powering Up

To get started with the WRAP Access Server, connect it to your local area network (LAN) using an Ethernet cable and connect the power adapter. The Access Server will power up and retrieve the network settings from your network's DHCP server.

The WRAP Access Server will also use Zeroconf (also known as Zero Configuration Networking or Automatic Private IP Addressing) to get an unique IP address in the 169.254.x.x network. Most operating systems also support this. So, you can connect your controlling laptop with a cross-over Ethernet cable to the WRAP Access Server, then power up the Access Server, and the devices will automatically have unique IP addresses in 169.254.x.x network.

Locations of the physical interfaces of the Access Server are described in Figure 2-1 and Figure 2-2.

All the blue status LEDs are turned off when the boot procedure is finished and the Access Server is ready to be connected.

2.2. WWW Interface

Most WRAP Access Server functionality can be controlled via the WWW interface using any standard WWW browser.

The wrapfinder application (see Figure 2-3), available for Windows operating system from Bluegiga Techforum (https://www.bluegiga.com/techforum/) provides easy-to-use interface for finding the WRAP Access Servers (with SW version 2.1.0 or later) in the local area network.

The wrapfinder automatically identifies the broadcast address of the network it runs in and shows the IP addresses, serial numbers and WRAP Access Server device types it could find using UDP broadcast when it was launched.

You can change the broadcast address used for finding the Access Servers. A new scan can be done by clicking Rescan.

Select an Access Server (by clicking its IP address) and click Details to see more information (like the Bluetooth addresses and friendly names) of the Access Server. See Figure 2-4 for details.

Click Connect or double-click an IP address to connect to the selected Access Server using a WWW browser.

Click Exit to close the program.

The WWW interface is accessed at http://wrap-ip/, where wrap-ip is the IP address of the WRAP Access Server (see Figure 2-5).

From the top-level page, click Setup to log in to the configuration interface. The default username is root and the default password is buffy (see Figure 2-6).

After logging in, you can configure several WRAP Access Server settings (see Figure 2-7). These are discussed in detail in Section 2.4.

2.3. Shell Prompt Access

Shell prompt access may be needed for advanced controlling operations that cannot be performed using the WWW interface.

You can get to the shell prompt using either SSH or the management console. The management console over a serial cable should only be needed to change the network configuration settings in the case were the network configuration using DHCP or Zeroconf is not possible. All further controlling activities can be performed remotely using SSH sessions over Ethernet or Bluetooth LAN/PAN connection.

If you can make SSH connection from a device that has Bluetooth LAN Access or PAN profile support, you don't need the management console. Just connect to the Access Server using LAN Access or PAN profile. The Access Server can be seen in Bluetooth inquiries as "Wserialno_n", where "serialno" is the serial number of the device and "n" is the number of the Bluetooth radio in question (model 2293 has three Bluetooth radios, any of which can be connected). After you have connected (no PIN code, username or password needed), connect using SSH to the device in the other end of the connection, typically 192.168.160.1. You can also use the wrapfinder application to find the IP address (see Section 2.2 for details).

        [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
      

2.4. Introduction to Configuration

When the WRAP Access Server is installed and powered up for the first time, the default configuration settings are being used. With these settings, the Access Server automatically configures its network settings assuming that the board is connected to a LAN network with a DHCP server running. Additionally, the Access Server also uses Zero Configuration Networking (also known as Automatic Private IP Addressing) to connect to the 169.254.x.x network, which can be used if the network has no DHCP server.

After booting, you can use the Access Server as a Bluetooth PAN access point to the network without any changes in configuration. Also, the Serial Port Profile is enabled by default in listening mode. You can also use Object Push and File Transfer Profiles to send files to/from the Access Server.

Most of the settings of the WRAP Access Server are configurable using the setup application. It has a WWW interface at http://wrap-ip/setup but it can also be run at the command line.

All configurable settings in the setup application are listed in Appendix B with their help.

2.5. Using the Setup WWW Interface

The easiest way to change the Access Server settings is to use the WWW interface. Accessing the WWW interface is instructed in Section 2.2.

Typical WWW configuration page example is shown in Figure 2-8 (This page can be found at Setup → Security settings)

The different parts of a WWW Setup page are discussed in the following:

• Changes have been saved. -line

  This line comes visible when the user saves the changes by clicking the Save button (or by clicking a toggling Yes/No link). It confirms that the changes have been saved into permanent storage.

  If invalid values were entered into one or more fields, an error message is shown at this line (see Figure 2-9).

  Figure 2-9. Trying to Save an Invalid Input

  Note: Rebooting of the Access Server is typically necessary to take changes into use. This can be done via the WWW interface (Advanced settings menu).

• Number or text entry fields

  Most of the configurable settings are text (or number) entry fields. For some fields (like IP address or netmask), there are restrictions on the input format. Setup validates the input at save time and accepts only valid data. The fields with errors are shown to the user so that mistakes can be fixed (see Figure 2-9).

• Help -link

  Clicking the Help link will retrieve the setup page again with requested help information displayed, like in like in Figure 2-10.

  Figure 2-10. Help Links in WWW Setup

  Note: If you have made changes to settings on the page before clicking Help and not saved them yet, they are lost.

• Yes and No radio buttons

  These buttons are used to configure typically a setting that can be either enabled or disabled, but that is not connected to another setting that would be hidden or shown according to the value of this one.

• Link to a configuration file

  Some of the configurable settings are actually editable configuration files, like /etc/httpd.conf for WWW passwords. Clicking the link will retrieve the file for editing in the browser window, or create a new file, if it does not exist. See Figure 2-11.

  Figure 2-11. Editing Files in WWW Setup

  Note: Any file can be edited via the WWW Setup, in page Setup → Advanced setting → Edit other configuration files.

• Reset -button

  Reset -button resets the fields to the values currently in use by the Access Server, i.e. it discards the changes that have not been saved yet.

  Note: This does not make a "factory reset".

• Save -button

  Save -button sends the WWW page for the setup application for validation. If the values in the fields are valid, they are saved to permanent storage and the page is refreshed with Changes have been saved. message at top and the accepted values in the fields.

  If there were errors in the fields, these are shown as in Figure 2-9.

  Note: Rebooting of the Access Server is typically necessary to take changes into use. This can be done via the WWW interface (Advanced settings menu).

• Back -link

  Returns to the previous level of the Setup menu hierarchy.

  Note: This does not save changes in the fields at the current page.

• Exit -link

  Quits the setup application and returns to the WRAP Access Server's main WWW page.

  Note: This does not save changes in the fields at the current page.

• Toggling Yes/No and on/off links

  Clicking Yes/No link (see Figure 2-12) immediately changes the setting and saves the change. Typically this is used with settings that require some other settings to come visible or to hide according to this setting.

  Figure 2-12. Yes / No links in WWW Setup

  The on/off links in Setup → Applications → Default bootup applications behave in a same way, making and saving the change immediately (see Figure 2-13).

  Figure 2-13. Selecting Default Bootup Applications in WWW Setup

• Upload links

  WWW Setup has settings that allow user to upload files to the Access Server, for example Setup → Advanced → Upload a software update (see Figure 2-14).

  Figure 2-14. Uploading files via WWW Setup

  Use Browse... button to select a file to be uploaded, and send it to the Access Server by clicking Upload.

• Browsing files

  Some WWW Setup pages allow users to browse the WRAP Access Server filesystem or part of it, like Setup → Advanced → Browse files (see Figure 2-15).

  Figure 2-15. Browsing files via WWW Setup

  Click the directory names to navigate in the filesystem.

  Click del to delete a file or an empty directory.

  Warning

  Deletion is not confirmed.

The WWW Setup has also menu items that run commands in the Access Server and then show the output in the browser window. Some commands, like rebooting the Access Server, are confirmed before execution.

2.6. Using the setup Command Line Application

The basic configuration settings can also be changed using the setup application at command line interface.

The setup application displays the settings in a hierarchical menu (see Figure 2-16). Navigating the menu is accomplished by entering the number or letter corresponding to the setting to be viewed and/or changed and pressing Enter. Pressing only Enter either accepts the previous value of the setting or returns to the previous level in the menu hierarchy.

2.7. Resetting Configuration

You can restore the default configuration with setup application and rebooting the board. When the system starts up, the default configuration settings are restored. If you have only changed the configuration by using the setup application, the following commands at the Access Server's command prompt will suffice:

      [root@wrap /]$ setup -r
      [root@wrap /]$ reboot
    

3.1. Network Interfaces

The network interface in the WRAP Access Servers are described in Table 3-1.

3.2. Bluetooth

The iWRAP servers (one in WRAP Access Server 2291, three in WRAP Access Server 2293) are started automatically at power-up. By default, the Serial Port, PAN and Object Push and File Transfer Profiles are activated. The iWRAP servers can be accessed and controlled (by applications or even interactively with a telnet client) using the iWRAP interface, described in section 9. Currently, there can be up to 14 simultaneous Bluetooth connections between a single master iWRAP server and up to 7 simultaneous slaves.

        [root@wrap /]$ /etc/init.d/bluetooth stop
        [root@wrap /]$ echo ABCD > /dev/bbreset
        [root@wrap /]$ sleep 1
        [root@wrap /]$ echo abcd > /dev/bbreset
        [root@wrap /]$ sleep 2
        [root@wrap /]$ /etc/init.d/bluetooth start
      

3.3. Compact Flash Cards

WRAP Access Server functionality can be extended using GSM/GPRS, WiFi and GPS Compact Flash cards. The supported compact flash cards are listed in Appendix D.

          eth1: Looks like an Intersil firmware version 1.7.4
      

3.4. USB Memory Dongles

Access Server's persistent memory storage can be extended using an USB memory dongle. The USB memory dongles are also used by the The WRAP Access Server Remote Management System (see Section 3.5.5) - each time a dongle is inserted, it is automatically mounted, scanned for management packets which are processed and unmounted.

To use the USB dongle for own applications it must be mounted manually with command

      [root@wrap /]$ mount -t vfat usbdevice /mnt/usb
    

The usbdevice parameter is a path to the USB dongle filesystem device. For the first dongle inserted after a reboot, it is /dev/scsi/host0/bus0/target0/lun0/part1, if the dongle is partitioned and and /dev/scsi/host0/bus0/target0/lun0/disc, if the dongle has no partition table. If you have used several dongles after reboot, the host0 part of the path must be changed to host1 or host2 and so on. Example of finding the correct device automatically can be seen in script /usr/sbin/hotplub.usb.

3.5. Servers

The Access Server server applications are started automatically at system power-up or when needed by the iWRAP server or the Internet services daemon. The servers and their purposes are described in Table 3-2.

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

3.6. Utilities

The Access Server is basically a small Linux system. Whether logged in from the management console or with SSH, your shell session starts as the root user in the root directory. After that, you have the option to use most of the standard Linux utilities, briefly listed and described in Table 3-3. Most of the commands have a small built-in usage help that can be seen by executing the command with the -h or --help parameter.

3.7. Real Time Clock

The system clock is read from the battery operated real time clock during boot. The time between the system time and the real time clock can synchronized using the hwclock application. Give command hwclock --help for more information.

3.8. Time Zone

The default time zone in the WRAP Access Server is UTC. You can change the timezone by replacing the file /etc/localtime with the correct file from your desktop Linux system (using your /etc/localtime or a wanted zone from /usr/share/zoneinfo).

3.9. System Re-Install and Upgrade

Access Server can be re-installed with the latest software version. The latest software updates and instructions are available at https://www.bluegiga.com/techforum/.

Most of the software updates are delivered as wpk file.

The easiest way to install these is:

1. Start Access Server.

2. Copy wpk file or files to an empty USB memory dongle.

3. Insert the dongle into Access Server

4. LEDs will turn on, and after 10-60 seconds they will turn off.

5. Remove the dongle and reboot Access Server.

6. All done.

See Section 3.5.5 for detailed description for other options and how to create your own wpk files.

4.1. Frequency Bands and Channel Arrangement

The Bluetooth system operates in the license-free 2.4 GHz ISM (Industrial Science Medial) band using frequency hopping spread spectrum (FHSS). In the vast majority of countries around the world this frequency band is 2400 - 2483.5 MHz. Some countries have, however, national limitations on the frequency range. In order to comply with these national limitations, special frequency hopping algorithms have been specified for these countries. It should be noted that products implementing the reduced frequency band will not work with products implementing the full band. Products implementing the reduced frequency band must therefore be considered local versions.

The Bluetooth frequency band is divided into distinct channels with 1 MHz channel spacing. In order to comply with out-of-band regulations in each country, a guard band is used at the lower and upper band edge. The frequency range is 2.400 - 2483.5 MHz, and the corresponding channels are f = 2402 + k MHz; k = 0 - 78. Transmission utilizes channel hopping over the specified range at 1600 kHz hop frequency. When operating in countries that permit the use of only a subset of the overall spectrum, transmission utilizes only the approved portions of the spectrum. The Bluetooth system utilizes Gaussian frequency shift keying (GFSK). The signaling rate is 1 Mbit/s.

4.2. Power Considerations

The Bluetooth system transceivers are classified into three power classes to support different link ranges.

• Power Class 1. Output power is 1 - 100 mW (0 - 20 dBm) with mandatory power control ranging from 4 to 20 dBm.

• Power Class 2. Output power is 0.25 - 2.5 mW (-6 - +4 dBm) with optional power control.

• Power Class 3. Output power is less than 1 mW (0 dBm) with optional power control.

Bluegiga's WRAP products support a 100 meter link range with Option 1 (Power Class 1).

4.3. Radio Frequency Propagation

The radio frequency signal propagates in free space as a spherical wave, from a point source to all directions equally. In reality, the actual signal source always differs from a theoretic isotropic signal source. The power distribution of wireless telecommunication equipment in space is determined by the antenna radiation pattern. In free space the signal propagates with the speed of light and attenuates with 1/r2 relation. In reality, the environment always differs from free space. The propagation environment of wireless telecommunication equipment is restricted by all obstacles.

The basic mechanism of radio propagation is attributed to reflection, diffraction, and scattering depending on existing obstacles. Since the radio frequency signal propagates omnidirectionally, the transmitted signal arrives at the receiver following multiple paths deformed by the aforementioned propagation mechanisms. The received signal is the superposition of attenuated and delayed replicas of the transmitted signal, leading to fading of the transmitted signal and broadening of the duration of the transmitted pulse. The transmitted pulse delay spread leads to inter-symbol interference (ISI) because the subsequent symbols interfere with each other. The ISI leads to a bit error probability (BIT) floor that is independent of the signal to noise ratio (SNR). Depending on the time delay spread of the transmitted pulse or the amount of widening that the transmitted pulse experiences across the radio channel, the multipath interference differs. When the time delay spread of the transmitted signal is very small with respect to the signaling time, the multipath interference essentially leads to the signal fading phenomena of the received signal. When the time delay spread of the transmitted signal is high with respect to the signaling time, the multipath interference leads to the symbol interference phenomena of the received signal as well.

A major difference between indoor and outdoor environments is that the former is considerably more sensitive to changes in the geometry of the environment than the latter. This is because of the differences in distance between obstacles. For example, a door being shut rather than open may have a major impact on an indoor environment whereas a comparable event in an outdoor environment may have a minor impact.

The Bluetooth standard has been designed to operate in noisy radio frequency environments. Transmission utilizes fast frequency hopping and short packages to make the link efficient and robust. Fast hopping and short packages limit the impact of interfering devices on the same frequency band.

5.1. Introduction to SDK

This manual describes how to create and use applications using the WRAP Access Server Software Development Environment. The relationships between the applications in the WRAP Access Server Software Platform are shown in Figure 5-1.

5.2. Installing SDK

        $ mount /dev/cdrom /mnt/cdrom
        $ (or mount -o loop /path/to/sdk2.iso /mnt/cdrom)
        $ cd /mnt/cdrom
        $ sh install