Widcomm WBC-1000 BlueConnect User Manual manual

Widcomm, Inc. BlueConnect manual

manual

BlueConnect Development Kit User’s Guide Document Number: BCDK-UG-012401-1200 Revision 1.7 ________________________________________________ WIDCOMM, Inc. Wireless Internet and Data Communication © Copyright 2000-2001. All rights reserved. 9645 Scranton Road, Suite 205 San Diego, CA 92121 Voice: (858) 453-8400 Fax: (858) 453-5735 Email : info@WIDCOMM.com or support@WIDCOMM.com
FCC Statement Widcomm Inc. 9645 Scranton Road, Suite 205 San Diego, CA 92121 858-453-8400 BlueConnect WDC-WBC-1000 This device complies with part 15 of the FCC Rules. Operation is subject to the following two conditions: (1) This device may not cause harmful interference, and, (2) This device must accept any interference received including interference that may cause undesired operation. Per CFR 47, PART 15, Paragraph 15.21: User changes or modifications not expressly approved by the party responsible for compliance could void the users authority to operate the equipment. © Copyright 2000 – 2001, WIDCOMM, Inc. (“WIDCOMM”). All rights reserved. This documentation may be printed and copied solely in connection with developing products in accordance with the license agreement provided to you with this documentation. Only two (2) copies of this documentation may be made for archival and backup purposes. Except for the foregoing, no part of this documentation may be reproduced or transmitted in any form or by any means or used to make any derivative work (such as translation, transformation or adaptation) without the express written consent of WIDCOMM. WIDCOMM, the WIDCOMM logo, and BlueConnect are trademarks of WIDCOMM, Inc. Bluetooth is a trademark owned by the Bluetooth SIG, Inc., and used by WIDCOMM under license. Handspring and Visor are registered trademarks of Handspring, Inc. HotSync, Palm Computing, and Palm OS are registered trademarks of Palm, Inc. Microsoft and Windows are registered trademarks of Microsoft Corporation. Other brand and product names may be registered trademarks or trademarks of their respective holders.
Table of Contents 1 INTRODUCTION ............................................................................................................1 2 REQUIRED MATERIALS..............................................................................................2 3 INSTALLATION AND SETUP ......................................................................................2 3.1 INSERTING AND CONFIGURING THE BLUECONNECT MODULE .....................................2 3.2 CONNECTING TO A REMOTE DEVICE (INQUIRY AND DISCOVERY)................................4 3.2.1 Clients, Servers, and Services.............................................................................4 3.2.2 The Server Mode.................................................................................................5 3.2.3 The Client Mode..................................................................................................6 4 LAUNCHING APPLICATIONS ..................................................................................13 4.1 ON THE SERVER .........................................................................................................13 4.2 ON THE CLIENT..........................................................................................................13 5 CLOSING APPLICATIONS AND COMMUNICATIONS SHUTDOWN ..............14 6 TROUBLESHOOTING .................................................................................................15 6.1 ERROR MESSAGE: COULDN’T OPEN BLUETOOTH LIBRARY......................................15 6.2 BEHAVIOR: DEVICES NEVER CONNECT .....................................................................15 6.3 ERROR MESSAGE: (DURING DISCOVERY PROCESS) CONNECTION FAILED................15 6.4 BEHAVIOR: THE SERVER AND CLIENT DO NOT CONNECT...........................................15 6.5 BEHAVIOR: DISCOVER APPLICATION DOES NOT WORK .............................................15 6.6 BEHAVIOR: STALE ENTRIES ON “DEVICES” SCREEN ................................................17 6.7 BEHAVIOR: STALE ENTRIES ON “SERVICES” SCREEN ...............................................17 6.8 BEHAVIOR: FATAL ERROR WHEN THE REMOVING BLUECONNECT CARD .................18 6.9 BEHAVIOR: “UNABLE TO OPEN THE SERIAL COMMUNICATIONS LIBRARY”..............19
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 1 1 Introduction This document describes the basic procedures for proper use of the BlueConnect module for the Handspring Visor. is a part of the BlueConnect Development Kit and it describes the basic procedures for proper use of the BlueConnect module for the Handspring Visor. The BlueConnect module comes with code libraries and some applications already burned into ROM. The libraries are: • Bluetooth – The WIDCOMM Bluetooth API libraries. These appear as Bluetooth Library and Bluetooth Library 2 on the application info screen of your Visor. • Discover – The libraries for supporting device discovery. These appear as Discover Library and Discovery Database on the application info screen of your Visor. These libraries are loaded into the Visor’s RAM from the BlueConnect module ROM once the BlueConnect module is plugged into the Visor. Since these applications reside on the BlueConnect card, they will only show up on the application info screen of your Visor whenever the BlueConnect card is inserted. If you remove the BlueConnect card, your Visor will reset and the libraries will vanish. In addition to these libraries, the module also holds the following applications: • Bluetooth – allows the user to select serial port and debug options. • BT-Pong – an amusing game. • Discover – lets you find other Bluetooth devices and discover services on them. • WidChat – a sample chat application. The applications residing on the BlueConnect module ROM can be identified by the fact that their names have a square bullet icon next to them. An interesting example of this is the Discover application. The BlueConnect card comes with a Discover application burned into ROM. If you plug the card into your Visor, you will see an application with the following icon: The BlueConnect ROM-based version of Discover Notice the small square icon next to the word “Discover”. This indicates that the application resides on the BlueConnect module. The source code for the Discover application is also supplied in your BlueConnect development kit. You can compile this application, HotSync it to your visor, and the previous icon will be replaced by the following: The RAM-based version of Discover This does not mean that the application on the BlueConnect module ROM was erased. You have merely overwritten the copy of Discover that resided in the Visor RAM. The fact that there is no longer a box icon next to the word “Discover” indicates that this is an application
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 2 that resides solely in Visor RAM. Applications that reside on Visor RAM take precedence over the same applications that reside on the BlueConnect module’s ROM. You could easily restore the ROM resident copy of Discover by deleting the RAM resident copy using the Palm OS interface. Once the RAM resident application was removed, you would once more be able to see the ROM based application on your visor screen: . Deleting the RAM-based Discover will restore this 2 Required Materials The minimum requirements for use of the BlueConnect module are one BlueConnect module with firmware version 2.2 or higher, one Handspring Visor with 120K of available memory, and a second, suitable (Bluetooth enabled) device for remote connection. 3 Installation and Setup 3.1 Inserting and Configuring the BlueConnect Module Insert the BlueConnect module into the Handspring Visor Springboard slot. The BlueConnect card has two sides. The front of the card has two positioning ridges just below the curved top of the card. When holding the Visor with the screen facing you, the card must be inserted with Widcomm sticker facing you, and the beveled side away. The card should be seated firmly with the bottom of the beveled edge of the card touching the top of the Springboard expansion slot. Front view of the BlueConnect module Positioning ridges
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 3 Once the card is inserted, the applications and libraries that reside in the BlueConnect card’s ROM will be loaded into the RAM, which resides on your Visor. The BlueConnect welcome application will launch. This application allows the user to select serial port and debug options. The application will launch with the “All Others” option selected. This is the default and should be selected for normal operation. The Local and Modem HotSync options are for HotSync over Bluetooth. To HotSync the Visor to a PC using the Generic Serial service, select the Local HotSync option. To HotSync the Visor to a remote PC using the Dialup Networking service, select the Modem HotSync option. After selecting the desired options, tap the “Home” silkscreen to return to the Visor’s main menu. To return to this application at any time, tap the “Bluetooth” icon as shown below: The “Home” Silkscreen The “Bluetooth” Icon
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 4 3.2 Connecting to a Remote Device (Inquiry and Discovery) 3.2.1 Clients, Servers, and Services The term “Bluetooth wireless technology” refers to a standard for the wireless exchange of data between two devices. In order to exchange data, two Bluetooth devices must establish a connection to one another. There are two sides to every connection and two roles that every device can fulfill. Before a connection is established, one device must request the connection from another. It is just like two people starting a conversation. One person must initiate the conversation and the other person must respond. In the Bluetooth wireless technology world, the same rules apply. One device begins by requesting a connection from another device. The other device can then accept the connection or reject it. The device that initially requests a connection is known as the client. The device that accepts or rejects the connection is known as the server. An easy way to remember this is to think of a restaurant: the client comes in and requests services from the server. These roles are fundamental and important from an operational standpoint. A Bluetooth wireless technology device can act as either a client or a server – it depends on whether the device is prepared to take an active or passive role. By definition, the client takes an active role in any exchange of data. In order to be a client, a Bluetooth device must run a software program that will request a connection to another device as part of its normal operation. In other words, a client device must “do something” before any connection can be established. Becoming a client normally requires an active decision on the part of the device operator. The role of server, however, is passive. Every Bluetooth wireless device must be prepared to respond to connection requests at all times. As a result, there must be some kind of software that is always running on each Bluetooth device that is prepared to respond to connection requests from remote clients. The software that allows a device to act as a server is known as a service. Services run as a background task. To configure the Visor for use in a specified mode, tap the “Discover” icon. Upon launching this application for the first time, the Bluetooth software will self-initialize. This process will take about four seconds, after which the user will be presented with the devices screen.
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 5 3.2.2 The Server Mode 3.2.2.1 Bluetooth Device Addresses and Device Names The designers of the Bluetooth standard had to create a way of telling one Bluetooth device from another. In order to do this, they created a unique Bluetooth Device Address (BDA) that could be assigned to every Bluetooth device. This address consists of a forty-eight-bit binary value that is often displayed in hexadecimal format. This address is fixed when the device is manufactured and cannot be changed by the user. A valid BDA: 00D0B7032E9F This is fine when one Bluetooth device is talking to another, but it is not easy for us (as human beings) to relate to. Fortunately, the designers of the Bluetooth wireless technology standard supplied an alternative. Each Bluetooth device can also be assigned a user-friendly name that will distinguish it from the other Bluetooth devices in the vicinity. This name is fully programmable and you can select any name for your device that you wish. Here are some examples: A valid user-friendly name: Bob’s PC A valid user-friendly name: John Q. Public’s PDA These names make it easy for you to recognize the PCs belonging to your friends, acquaintances, and business associates. If you wanted to transfer a business card to an associate named John Q. Public, you could easily locate them in the list shown above. The “Setup” screen of the Discover application lets you set a valid-user friendly name for the Visor and also lets you see the Visor’s BDA. Tap the Discover icon to enter the discover application. Then tap the “Setup” button to enter the configuration screen.
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 6 Here, you can: • View the module’s Bluetooth Device (BD) address. “00-D0-B7-03-24-55” in the example shown above. • Enter a device name—a human readable name to identify the device. “My BlueConnect” in the example shown above. • Set the connection mode (Client or Server). The selected connection mode is viewed as white text on a black background. To change connection mode, tap within the desired mode box. If the device has been configured for server use, an alert will appear with the message “Visor started successfully as server.” This alert may also appear when launching the Discover application if the Visor was last used in Bluetooth Server mode. Clear the alert by tapping the “OK” button. Once your Visor has been configured as a server, no other action on your part is required. Your BlueConnect device will advertise its available services to all other Bluetooth units that are within range. These remote devices are then free to connect to the available services on your Visor. 3.2.3 The Client Mode If you receive the message “Visor started successfully as server” upon launching discover, the device is currently in server mode. You must return the device to client mode before you can attempt to initiate a connection to a remove device. Tap the “Setup” button and then tap “Client.” And alert will appear with the message “Visor closed as server. Client services only.” Clear the alert and tap the “Devices” button to return to the devices screen.
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 7 3.2.3.1 Inquiry (Displaying Nearby Bluetooth Devices) The devices screen displays a list of nearby Bluetooth devices that are within range of your unit. IMPORTANT NOTE: The Discover application stores the results of the last inquiry and discovery process, and these results will appear on the devices screen. To make sure that only currently available devices are displayed, tap the “Inquire” button. Depending on the number of available devices, a series of notices will appear showing the number of Bluetooth devices found, as well as displaying their BD addresses as shown below: After the inquiry process is complete, these addresses will be listed according to the order in which they were found.
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 8 3.2.3.2 Viewing devices by BD Address or Device Name In the devices screen you can choose to view devices by the BD Address or by the device name. To view the devices by their device names, tap on the “menu” silkscreen and from the “Options” menu bar select the “Get Name” item (to retrieve the name of the currently selected address) or the “Get All Names” item (to retrieve the device names of all of the devices on the display). The device names that correspond to the BD Addresses will be shown. If the device name could not be retrieved then only the BD Address will be shown. NOTE: These device names will be saved in the database and can be used when viewing services (see Section 3.2.3.6: Viewing Services by BD Address or Device Name).
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 9 3.2.3.3 Service Discovery To discover the available services on a remote Bluetooth device, tap the desired device address to highlight it, then tap “Discover.” If the device is available for discovery, a series of notices will appear, briefly displaying the names of available services. When the discovery process is complete, the display will change to the services screen.
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 10 Tap the desired service to highlight it and the client configuration process is complete. IMPORTANT NOTE: Selecting the remove service does not actually connect to the remote device at this point. You will not connect until you leave the client setup and run an application that attempts to access the remote unit using the generic serial service. 3.2.3.4 Clearing the Services Database Services remain in the service discovery database until you tap the “Clear” key. If you see services from devices other than the one that you originally selected, it would be wise to clear the database and rediscover the device.
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 11 3.2.3.5 Keeping Some Services While Clearing the Rest To keep the services that you want in the database, select the service and tap the menu silkscreen while on the “Services” screen. From the “Options” menu bar select the “Lock Service” menu. Locked services have a star, or asterik, (*) before the device name or device address. You can then press the “Clear” button. All services that are not locked are deleted from the Discover database. Services that are locked will remain in the database. To unlock a service, just select the service, tap the “menu” silkscreen and from the “Options” menu bar select the “Unlock Service” item.
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 12 3.2.3.6 Viewing Services by BD Address or Device Name In the services screen you can choose to view devices that host a particular service either by the device’s BD Address or by the device’s name. To view the devices by their device names, tap on the “menu” silkscreen and from the “Options” menu bar select the “View Device Names” menu. The device names that correspond to the BD Addresses will be shown if they are in the database. If the database does not contain a corresponding device name then only the BD Address will be shown. You can revert back to device addresses on the “Services” screen by selecting the “View BD Addresses” menu. In the example shown above, notice that some services are tagged with the device name and some with the BD address. IMPORTANT NOTE: The device names can only be displayed if they are currently stored in the Visor discovery database. To load the discovery database, use the “Get All Names” function from the “Devices” screen. See Section 3.2.3.2: Viewing devices by BD Address or Device Name for information on how to do this.
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 13 4 Launching Applications BlueConnect on the Visor is designed to operate using the Generic Serial profile. Applications which use the Handspring serial library to communicate through the default serial port can transfer data between two Bluetooth wireless technology devices just as if they where connected by a modem or other serial device. Any application that is capable of using regular Handspring serial I/O library calls may be used to talk to another Bluetooth device in this manner. You can communicate using BlueConnect by using the following sequence. 4.1 On the Server IMPORTANT NOTE: The Server device should start the application before the Client device. 1) Using the Discover application, configure your unit to the role of Server. 2) Tap the “Home” silkscreen to return to the main menu 3) Tap the icon of the desired application. For normal applications, a status window will appear with the message “Status: Waiting for Connection” (or similar – this is application specific) followed by a spinning activity character. At this point the client should try to connect. 4.2 On the Client IMPORTANT NOTE: The Server device should start the application before the Client device. 1) Using the Discover application, configure your unit to the role of client. Discover the Generic Serial service on the remote unit and select it on the Services screen. 2) Start the application on the remote server device. 3) On your local device (the client), tap the “Home” silkscreen to return to the main menu 4) Tap the icon of the desired application. A status window will appear with the message “Status: Waiting for Connection” (or similar – this is application specific) followed by a spinning activity character. At this point the two applications should connect. When the connection is established, the client device will emit a series of tones to signify a successful connection. Both devices will then be available for use of the application. For an example please refer to the BlueConnect Development Kit Quick Start Guide.
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 14 5 Closing Applications and Communications Shutdown The application may be terminated at any time by either device by tapping the “Home” silkscreen. The “Home” Silkscreen When no further Bluetooth communications are needed, it is recommended that power be removed from the device – since this powers down your BlueConnect card, it will preserve battery life on your Visor. This may be done by either removing the module from the Springboard slot or, if the module is to remain in the slot, by shutting down Bluetooth services. To shut down Bluetooth services, tap the “Discover” icon. Then tap the “Shutdown” button. The application will perform necessary tasks to power down the BlueConnect module and will then return to the main menu. This process takes approximately two seconds.
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 15 6 Troubleshooting 6.1 Error Message: Couldn’t Open Bluetooth Library Possible cause: A device has not been selected in the “Devices” screen of the Discover application. Or a service has not been selected in the “Services” screen of the Discover application. Solution: In the Discover application, tap “Inquire.” This will refresh the list of available devices. Select a device and tap “Discover.” Make sure a service is highlighted before returning to the main menu. 6.2 Behavior: Devices never connect Description: Both devices show “Status: Waiting for Connection” but never connect. Possible cause: The client application started before the server application Solution: Tap “Cancel” to end waiting (disregard the resulting serial library error) and retry. Start the server application first, and then start the client application. 6.3 Error Message: (During Discovery process) Connection Failed Possible causes: The remote Bluetooth device powered on but its Bluetooth software is not enabled. The remote device may not be configured for server operation. Solution: Make sure that remote Bluetooth device’s host computer has Bluetooth software installed and enabled. You may need to check the remote device’s software documentation to find out the correct procedure for installing and enabling Bluetooth software. Also, verify in Discover application’s setup screen that the remote device is configured for server operation. 6.4 Behavior: The server and client do not connect Possible causes: The incorrect service (or no service) is selected on the client Solution: Make sure that the service that the client is trying to connect to has been selected in the “Services” screen of the Discover application. Many devices may have the same service on them. You have to make sure that the service that you have chosen is on the device that you want to connect to. 6.5 Behavior: Discover Application does not work Possible causes: The correct version of the Discover application is not loaded into Visor RAM. Solution: The correct version of the Discover application needs to be loaded onto the Visor. To read the version number of the ROM-based Discover application that resides on the BlueConnect card, tap the “Menu” silkscreen in the main menu. In the “App” menu bar choose the “Info” menu. This will take you to the “Info…” screen. Choose “Card” from the pop - up trigger that by default shows “Internal”. Now, tap on the Version button to view the version numbers of all the software on the BlueConnect module. Look for the “Discover” entry.
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 16 Reading the version number of the BlueConnect ROM-based Discover To read the version number of the RAM-based Discover application that has been HotSynced to the Visor (if any), tap the “Menu” silkscreen in the main menu. In the “App” menu bar choose the “Info” menu. This will take you to the “Info…” screen. Choose “Internal” from the pop-up trigger that by default shows “Internal”. Now, tap on the Version button to view the version numbers of all the software on the BlueConnect module. Look for the “Discover” entry. Reading the version number of the Visor RAM-based Discover You can delete a RAM resident Discover application and return to the version of Discover that is already on the BlueConnect module ROM. To delete the application tap the “Menu” silkscreen in the main menu. In the “App” menu bar choose the “Delete” menu. This will take
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 17 you to the “Delete” screen. Select the Discover application and tap on the “Delete” button to delete it. An application that resides on Visor RAM takes precedence over the same application residing on BlueConnect module ROM. You can tell whether the Discover application that you are using has been HotSynced to the Visor is has been loaded from the BlueConnect ROM by examining the application icon: The RAM-based version of Discover . Deleting the RAM-based Discover will restore this Notice the small square icon next to the word “Discover”. This indicates that the application resides on the BlueConnect module. 6.6 Behavior: Stale Entries on “Devices” Screen Description: The “Devices” screen of the Discover application shows Bluetooth wireless technology devices that are no longer valid or no longer within range. Solution: Tap the “Inquire” button. These device addresses are stored in a database in your Visor and will not be cleared until you force the unit to re-inquire. 6.7 Behavior: Stale Entries on “Services” Screen Description: The “Services” screen of the Discover application shows Bluetooth services that are no longer valid or reside on devices other than the one that you performed the discovery operation on. Solution: Tap the “Clear” button. These services are stored in a database in your Visor. This database should be cleared before you discover services on another device. Once the display has been cleared, you can retry the discovery operation – this will result in a more accurate list of available services.
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 18 6.8 Behavior: Fatal Error when the Removing BlueConnect Card Description: When you are running the Discover application and remove the BlueConnect card from the slot, the Discover application generates a fatal run-time error. You see the following two displays: Cause: You are running the Discover sample application which you have HotSynced to your Visor. Reason: The Discovery and Inquiry routines have been extracted from the Discover application and now reside in the Discover Library. This library resides on the BlueConnect module ROM and is loaded into the Visor RAM when the card is inserted into the Visor. The library is unloaded when the card is removed from the Visor. In most cases, this behavior will not effect you. It does, however, have an effect when you are running the Discover sample application. Normally, you will use the Discover application that is loaded from the BlueConnect ROM. If you run this Discover application and pull the BlueConnect card from the slot, the application will disappear and the unit will immediately reset. This is not true if you HotSync your compiled sample Discover application onto your Visor. The sample application will override the version that is loaded from the BlueConnect ROM. When you remove the BlueConnect card from the slot, the RAM resident Discover application will not immediately disappear. Without access to the Discover Library that resides in BlueConnect ROM, the sample application will generate a fatal run-time error. This is an expected behavior and is not the result of a fault in your BlueConnect hardware or software. Solution: Delete the RAM resident copy of the Discover application. This will restore the ROM-resident application from your BlueConnect card and will prevent this problem from reoccurring.
BlueConnect Development Kit User’s Guide WIDCOMM, Inc. 19 6.9 Behavior: “Unable to Open the Serial Communications Library” Description: Insert the BlueConnect card into the Visor and run the BT-Pong sample application. The application hangs in the “Starting Pong” mode and then returns “BT-Pong IO Error, Unable to Open the Serial Communications Library”. Solution: You must run the “Discover” application must be run before using any of the sample applications. For further information, see the BlueConnect Development Kit Programmer’s Guide.

Navigation menu