OBEXSender 2. User Guide. Version 2.4. M o n d a y, February 0 5,

Transcription

1 OBEXSender 2 User Guide Version 2.4 M o n d a y, February 0 5,

2 Copyright Bluegiga Technologies All rights reserved. Bluegiga Technologies assumes no responsibility for any errors, which may appear in this manual. Furthermore, Bluegiga Technologies reserves the right to alter the hardware, software, and/or specifications detailed herein at any time without notice, and does not make any commitment to update the information contained herein. Bluegiga Technologies products are not authorized for use as critical components in life support devices or systems. The WRAP is a registered trademark of Bluegiga Technologies The Bluetooth trademark is owned by the Bluetooth SIG Inc., USA, and is licensed to Bluegiga Technologies. All other trademarks listed herein are owned by their respective owners.

3 Contents: 1. Introduction Use Cases Content push Content pull Scan Configuration Getting started Activating OBEXSender OBEXSender configuration Uploading files OBEXSender configuration file Creating content rules Examples How to store files sent to the access server Monitoring OBEXSender Bluetooth device database Database location and structure Updating Bluetooth device database Troubleshooting & Known issues...33 List of Figures: Figure 1: OBEXSender functionality...6 Figure 2: Push mode operation...8 Figure 3: Pull mode...9 Figure 4: Scan mode Figure 5: WRAPFinder Figure 6: Access server WWW setup Figure 7: WWW setup main view Figure 8: Default startup applications Figure 9: OBEXSender configuration page

4 Figure 10: Summary log view Figure 11: OBEXSender log detailed view Figure 12: Bluetooth device database Figure 13: Building BluID manually Figure 14: Parsing BluIDs from the OBEXSender log file

5 VERSION HISTORY Version: Author: Comments: 1.0 MSa Initial version 1.1 JP Added missing functions 1.2 MSa User guide rewritten 1.3 JP Added new features 1.4 MSa Minor fixes 2.0 MSa OBEXSender 2 updates 2.1 MSa New screen captures with MSa DB info and build updates 2.3 JP Spell checking 2.4 MSa Beta release manual TERMS & ABBREVIATIONS Term or Abbreviation: Explanation: AS Access Server Bluetooth Set of technologies providing audio and data transfer over shortrange radio connections DHCP Dynamic Host Configuration Protocol EDR Enhanced Data Rate GPRS General Packet Radio Service 4

6 HTTP Hypertext Transfer Protocol IP Internet Protocol LAN Local Area Network OBEX Object Exchange OPP Object Push Profile PAN Personal Area Networking PDA Personal Digital Assistant TCP Transmission Control Protocol Wi-Fi Wireless Fidelity WLAN Wireless LAN VPN Virtual Private Network WRAP Wireless Remote Access Platform WWW World Wide Web 5

7 1. INTRODUCTION OBEXSender is one of the built-in applications in the access server. It s dedicated for example to Bluetooth proximity marketing, content distribution or location based services. Access server plus the OBEXSender provide the user with a ready platform to start content distribution including all the necessary Bluetooth functions from discovering the devices to transmitting the content. The user needs to only focus on what, when and to whom to send the content - rest is handled by the OBEXSender application. The figure below illustrates a simplified OBEXSender network: KEY FEATURES: Figure 1: OBEXSender functionality Automatic device discovery and content push over a Bluetooth connection Bluetooth device recognition matches found Bluetooth device to a local device data base Device based content push Optimized content can be sent to different Bluetooth devices 18 simultaneous Bluetooth connections with one Access server 2293 Upload speed even up to 75KB/sec with Bluetooth 2.0+EDR Content can be stored locally with external memory even up to 2GB space Wide networking support: Bluetooth, Ethernet, Wi-Fi, GPRS and EDGE Secure remote connections over Virtual Private Networking Remote file system support Lot s of filtering options, like: device type, distance from the access server 6

8 Extensive logging Interaction between several access servers Content time stamping 7

9 2. USE CASES In this chapter some possible OBEXSender use cases are described. 2.1 Content push This is the standard functionality in OBEXSender. In content push mode OBEXSender is scanning for nearby Bluetooth devices and pushing content to clients who belong to the target group. OBEXSender also enables device based content pushing since during the scan phase it recognizes the model of the Bluetooth device and then tries to send specific content to recognized devices. Figure 2: Push mode operation 8

10 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 like MP3 or NOKIA N73 for example. The server processes the received file and sends a corresponding file back to the user, if such exists. Figure 3: Pull mode 9

11 2.3 Scan In the scan mode the access server simply scans for nearby Bluetooth devices and logs the number of devices found as well some other basic information about them. The scan mode is useful if one just wants to discover how many Bluetooth devices are nearby or pass the access server. The device recognition feature can also be used in the scan mode, since the OBEXSender can be configured to search and recognize the found devices. This can be used for example to map the Bluetooth device propagation. Figure 4: Scan mode 0

12 3. CONFIGURATION This chapter contains the instructions from the basic OBEXSender configuration to the more advanced use cases. 3.1 Getting started The easiest and fastest way to configure OBEXSender is via the WWW setup. To do this your access server must be connected to the same network as your PC or alternatively you can also use a direct Ethernet cross cable or Bluetooth PAN connection. By default the access server uses DHCP, so if you connect it to your LAN it must support DHCP as well. 1. Once you have successfully connected the access server, start the WRAPFinder application. WRAPFinder lists all the Access servers in the same network as your PC. If the access server does not show up immediately, you may need to push the Rescan button a couple of times. Figure 5: WRAPFinder 2. As a next step you need to select the correct Access server and press Connect button in the WRAPFinder user interface. An internet browser window should open up with the IP-address of the Access server in the address bar. 1

13 Figure 6: Access server WWW setup 3. Follow the setup link and a login screen should show up. Enter a correct user name and password Figure 7: WWW setup main view 2

14 Note: 4. After a successful login you get access to the WWW setup main view At this point you should check your access server software version. OBEXSender 2 works only with software version 3.2 and newer. At the bottom of the screen you should see a line saying: Access Server, S/N (3.2) Copyright Bluegiga Technologies Inc, If the version is older than 3.2 you should first update your Access server. Latest software releases and instructions can be found from 3

15 3.2 Activating OBEXSender By default the OBEXSender application is disabled, so as a first task you should enable it. This is quite simple from the following page in the WWW setup (Figure 8): Access Server - Setup - Applications - Default startup applications 1. If it does NOT say ON right after OBEXSender, please enable it by clicking OFF once. After a reboot OBEXSender will be enabled. However if you have not completed rest of the configuration, do it first before rebooting the server. Figure 8: Default startup applications NOTE: If the OBEXSender is not configured properly, i.e. you have not defined any files to be sent, it will not be started even if you enable it via the configuration menu. See chapters: for more information about the configuration. 4

16 3.3 OBEXSender configuration In this chapter you will learn how to do basic OBEXSender configuration. As a first step please go the to the WWW setup page: Access Server - Setup - Applications OBEXSender settings You should see a view like in Figure 9: Figure 9: OBEXSender configuration page On this page you can configure the basic OBEXSender settings. Use the Help links to get some basic information about each configuration. More detailed descriptions you can find below: 5

17 Bluetooth friendly name [string] This name is the Bluetooth friendly name shown to other Bluetooth devices. For example when OBEXSender is used in push mode this name is shown as a sender in the mobile phone screen. With meta tags you can for example include the radio number in the name. Please click Help link for more information about tags Delay between inquiries [seconds] OBEXSender uses a standard Bluetooth inquiry (device discovery) to find nearby Bluetooth devices. This configuration defines the time interval between inquiries i.e. how frequently new devices are being searched for. Delay between reply scans [seconds] This value determines how often OBEX in-folder (/tmp/obex) is scanned for remote requests. A low value increases CPU usage. If previous was ok, timeout before sending again [seconds] If a file has been successfully sent to a device, this timeout defines when content can be sent again to the same device. If previous was reject, timeout before trying again [seconds] If a file transmission to a device has failed or user has declined the file, this timeout defines when OBEXSender can send content to the same device again. Delay between retrying call [seconds] When user doesn t accept or reject the file, OBEXSender will try to send the file again. This setting determines the timeout before resend occurs. This is useful in case user doesn t notice the incoming Bluetooth transmission. Default value is 120 seconds, because many mobile phones tend to keep the Bluetooth link open for 120 seconds before closing it. If you wish to disable this feature you can use the same value as in ok delay or reject delay, i.e. the two previous settings. Delay after scanning [seconds] When a remote request from user has been received, this setting determines how long OBEXSender will wait until the response file is sent back to the user. Default value is 5 seconds, because some mobile phones are not able to receive files over Bluetooth until at least 5 seconds has passed from sending. Tester delay [seconds] This delay defines how often a file is sent to a tester Bluetooth device. 6

18 Minimum RSSI value before sending [integer] The working range of OBEXSender can be configured or limited with this setting. RSSI or Receiver Signal Strength Indicator defines the distance to the receiving device in dbm. This value ranges from 128 to = maximum range -65 = medium range -30 = minimum range Notice that most of the Bluetooth devices, especially mobile phones are so-called Class 2 devices, meaning that their range is approximately meters. So even if the WRAP Access Sever is a Class 1 device ( meters) RSSI value -128 does not mean that it can serve all devices within meter range, but it rather means that it can serve all devices within meter range. Whitelist RSSI [integer] If RSSI of a Bluetooth device is less then this value it will be removed from the block list i.e. device can be brought close to an access server to be served again. Log file name [string or IP-address] This configuration defines the path and name of the OBEXSender log file (for example /usr/local/obexsender/obexsender.log ). Log file contains information about successful and unsuccessful transmissions, timestamps and information about sent files. You can also use an IP address of a log server as a parameter. Type - to use syslog. Log prefix [string] This prefix is put in front of every event in the log file. Type "-" for none (default). Tip: If syslog is used for logging the prefix is an easy way to separate OBEXSender from other application logs. If sending was failure, log it too [selection] If this is enabled failed transmissions will be logged too. Register to watchdog daemon [selection] If this is enabled, OBEXSender will make access server reboot automatically if Bluetooth radios have stopped responding. Delete non-matching requests [selection] If this is enabled, OBEXSender will delete request files from the access server that do not match any filters. Verbosity [integer] Logging level. Values can vary from 0 to 4. 7

19 0 = Minimum amount of log generated 4 = Maximum amount of log generated Notice that the log file can quickly fill the access servers file system. Full logging should only be used for testing / development purposes. It s strongly recommended that in production only verbose 0 or 1 is used. Edit configuration file [link] This link opens the raw OBEXSender configuration file (/etc/obexsender.conf by default) and allows you to edit it manually. It also allows you to change some advanced settings that are not included in the basic configuration. Please see chapter OBEXSender configuration for more information. Upload a new file [link] This link allows you to upload files into the OBEXSender file system. List files [link] This link allows you to browse files on the OBEXSender file system. View log [link] This link allows you to view the OBEXSender log file if it exists. By default a summary of the logged events is displayed. Detailed information is available by clicking the date links. Delete log [link] This link will delete the current log file. 3.4 Uploading files You can easily upload new content (files) for OBEXSender by selecting Upload a new file in the OBEXSender main menu. All you need to do is browse for the file you want to upload and then click Upload. You will see a confirmation note, for example File /usr/local/obexsender/bike.jpg uploaded. At the moment you can only upload to /usr/local/obexsender directory from WWW-setup. If you would like to upload to some other directory, you ll need to use secure FTP to accomplish that. This is because normal FTP is disabled by default in the Access server. Good software for secure file transmission for Windows is WinSCP. 8

20 3.5 OBEXSender configuration file From the configuration file you can alter all the settings available for OBEXSender. It includes all the settings that are available in the WWW setup but contains also additional settings. This chapter covers only the settings that can be configured only from the obexsender.conf file, since basic configuration was already covered in the previous chapter. NOTE: Lines beginning with # character are comments and OBEXSender will ignore them. baseband [IP-addr] [port] This configuration allows you to choose which Bluetooth radios are used to send files. By default all radios are in use, but you can change the configuration by commenting the unnecessary lines. Default configuration: baseband baseband baseband baseband Baseband can only be used for testing purposes and does not affect functionality. ignore [BD_ADDR] With this configuration you can define the Bluetooth addresses that you want to block from OBEXSender i.e. devices that OBEXSender does not send to. In the default configuration OBEXSender, will block the address range of Bluegiga Technologies, so that the access servers do not send files to each other. Default configuration: ignore 00:07:80: tester [BD_ADDR] OBEXSender will always send to devices defined with this setting. Tester timeout configuration will define how often file is sent to tester devices. Default configuration: #tester 00:07:80:80:00:bf scandir [path] This configuration defines the folder OBEXSender scans for remote request. This folder should be the same directory where the files received over OBEX are stored. Default configuration: scandir /tmp/obex broadcast [target] This configuration defines to where OBEXSender sends information about the Bluetooth devices it has served. This configuration can be used within an access server network if one wants to prevent the same files from being sent from several access servers to same Bluetooth devices. Target can be a unicast or broadcast IP- 9

21 address or a network interface name. Default configuration: broadcast nap 3.6 Creating content rules This chapter instructs you how to configure the content that OBEXSender sends out. The rules to send out content are defined with a very simple structure that is described below. Send structure: send { match <BluID> (optional) time <timestamp> (optional) file <filename> <target file> } BluID tells the target device or group that the send structure matches to. BluID must match to one of the groups defined in the OBEXSedner device database. BluID is extended regular expression (regex) and is also case-sensitive. Several match lines can be used inside one send structure. Timestamp can be a Weekday (Mon, Tue, Wed, Thu, Fri, Sat, Sun) or alternatively hour:minutes (for example "01:00-02:23", "19:30-20:30"). Timestamps can be also combined: "10:00-11:30" (works every day between 10:00 and 11:30), "Mon 01:00-02:23" (works on Mondays between 01:00 and 02:23), "Wed,Fri 19:30-20:30" (works on Wednesdays and Fridays between 19:30 and 20:30) File on the other hand defines the file or files that OBEXSender tries to send to matched devices or groups. Several files can be used inside one send structure. You can have multiple "match", "time" and "file" lines inside one "send" structure. REPLY feature allows you to request specific content from OBEXSender. The reply works in a way that when a file is sent to a server, OBEXSender processes it and check for a corresponding response. If one is found OBEXSender will send it to a device where the file was received from. 0

22 Reply structure: reply { keyword <keyword> match <BluID> (optional) time <timestamp> (optional) file <filename> <target> } Keyword is matched for content of the file from user. Also header information of the file is parsed. Keyword is extended regular expression (regex) and case-non-sensitive. Phone recognition and timestamps work similarly as in the previous section. For example: GIF JFIF This will match GIF-picture header. This will match JPEG-picture header.. This will match everything. foo.*bar This will match file with text "foo" and "bar". 1

23 3.6.1 Examples This trivial example will send Bluegiga.gif file to all discovered Bluetooth devices. send { } file /usr/local/obexsender/bluegiga.gif The following example sends Bluegiga.gif to all remote devices, but the file will be renamed to My_company.gif. File will be sent only between 14:25 and 15:15: send { } time 14:25-15:15 file /usr/local/obexsender/bluegiga.gif My_company.gif The following example shows how to send Bluegiga.gif only to Nokia 9500 mobile phones. Note: You will need to have proper BluID information in the OBEXSender device database. send { } match ^Nokia_9500 file /usr/local/obexsender/bluegiga.gif The following example shows how to send a file for whole Monday, but on Tuesday only between 10:00 and 11:30. send { } time Mon time Tue 10:00-11:30 file /usr/local/obexsender/bluegiga.gif 2

24 The following example shows how to send two files simultaneously and only on business days. send { } time Mon, Tue, Wed, Thu, Fri file /usr/local/obexsender/bluegiga.gif file /usr/local/obexsender/contacts.vcf All of the above rules can be combined. The following example shows how to send a file to Nokia 9500 and Samsung SGH-D820 mobiles. The file will be sent on Tuesdays and Fridays between 12:00 and 15:15: send { } match ^Nokia_9500 match ^Samsung_SGH-D820 time Tue,Fri 12:00-15:15 file /usr/local/obexsender/bluegiga.gif The following example will make OBEXSender send Bluegiga.jpg to anyone who sends a GIF file to the access server: reply { } keyword GIF file /usr/local/obexsender/bluegiga.jpg In the following example user has to send a JPG file to access server in order to receive Bluegiga.jpg. In this case reply will work only between 01:00 and 02:23. reply { } keyword JFIF time 01:00-02:23 file /usr/local/obexsender/bluegiga.jpg The following example sends Bluegiga.jpg to anyone who sends any file to access server via Bluetooth. In this case REPLY will work only on Mondays and Tuesdays. 3

25 reply { } keyword. time Mon,Tue file /usr/local/obexsender/bluegiga.jpg In the following example user has to send a file containing text "foo" and "bar" to Access server in order to receive Bluegiga.jpg. User has to be using Nokia 9500 mobile and send his file on Monday, since both phone recognition and timestamp are in use. reply { } keyword foo.*bar match ^Nokia_9500 time Mon file /usr/local/obexsender/bluegiga.jpg 4

26 3.7 How to store files sent to the access server By default all files sent over OPP to Access server are stored to /tmp/obex folder and deleted after they have been processed. It is however possible to save the files to another directory. The following procedure shows how to automatically copy these files to an example folder /mnt/remote_request (NOTE: you must first create this folder first!): 1. Create a copier script /usr/local/bin/copier. You can do it for example via WWW-setup -> Advanced settings -> Edit other configuration files and typing here /usr/local/bin/copier. Put the following script into the file: #!/bin/sh # to be called from OBEXSender: --fork /usr/local/bin/copier # This directory must exist! SAVEDIR="/mnt/remote_request" /bin/cp "$1" "${SAVEDIR}/$3`/bin/date "+%s"`-`echo $1 /usr/bin/cut -f 2 -d-`" 2. Make it executable by giving command chmod a+rx /usr/local/bin/copier at command line interface. 3. Edit /etc/bluetooth.conf and add the following line: SET BLUETOOTH LISTEN 3 "/usr/sbin/obexserver --bdaddr $b --prefix $b-$p- --fork usr/local/bin/copier" Save changes and restart Access server Now all incoming files are copied to /mnt/remote_request directory. The format of the files is bdaddr-btserverport-timestamp-filename.ext. 5

27 4. MONITORING OBEXSENDER OBEXSender creates log into a file whenever it s functional. By default no log file is specified, so you should do this first with instructions provided in chapter OBEXSender configuration. When you choose View log in OBEXSender menu, you can see only the summary of OBEXSender actions, i.e. how many successes, failures and retries have occurred. When you select the date or Total in the summary view, you will see more details. You will see basically to which Bluetooth address the content was sent and if the transmission was failure or success, or if transmission will be retried later. See example logging in figure below: Figure 10: Summary log view 6

28 Figure 11: OBEXSender log detailed view If you want to see even more details about how OBEXSender is performing, you can add the verbosity level of logging. 7

29 5. BLUETOOTH DEVICE DATABASE OBEXSender 2 uses a special Bluetooth device database for recognizing the Bluetooth devices. This database contains the BluID (or fingerprint) information of the Bluetooth devices as well as alternative rules for device recognition. The chapter describes the database format and discusses some basic guidelines how to use the device database. 5.1 Database location and structure The Bluetooth device database is located in the file system of the access server: /var/lib/obexsender/obexsender.hash It s in ASCII format and can be viewed or edited with standard shell commands like more or e. Or more easily in WWW-setup -> Advanced settings -> Edit other configuration files and then type the above path. An example of the Bluetooth device database is presented below: Figure 12: Bluetooth device database 8

30 The database is structured like this: <Device name/group> <BluID> Where <Device name/group>: This field contains the device name or group where it belongs to. In Figure 12 this field contains the manufacturer and model of the Bluetooth device and in some cases a higherlevel group (like Symbian). This field can be divided into section separated with comma as is done for example in Figure 12. In the example device are named uniquely but some Nokia device are categorized into a higher-level group: Symbian60. Grouping can be done freely as long as the syntax of the filed remains the same. The idea behind grouping is that some Bluetooth devices share same features such as screen size, operating system, manufacturer and they support same file types. Therefore it may be feasible to combine them into a higher-level group. An example of grouping could be Nokia_N70, Nokia_N_Series, Symbian60 Nokia_N72, Nokia_N_Series, Symbian60 Nokia_N73, Nokia_N_Series, Symbian60 Nokia_N80, Nokia_N_Series, Symbian60 Nokia_N90, Nokia_N_Series, Symbian60 Nokia_6600, Symbian60 The device name/group is used on obexsender.conf file to decide which file to send to these devices. So as an example to send to all above phones (except Nokia 6600) one could use: send { } <BluID>: match ^Nokia_N_Series file /usr/local/obexsender/nokianseries.jpg This field contains the device identification data. The BluIDs are divided into three sections based on the information quality: This is the most reliable information and means that the device can be unambiguously identified. This is medium level information and means that the device is likely to be identified. 9

31 3. The last column contains so called educated guesses i.e. the information presented here does not quarantine that the device is identified, but in practice it may still work well. 6. UPDATING BLUETOOTH DEVICE DATABASE OBEXSender 2 will automatically create the BluID fingerprints, but will not add them into the database but it needs to be done manually. In normal operation BluIDs are stored into OBEXSender log file and BluIDs can be manually moved from there into the Bluetooth device database. Note: you need to have verbosity level 2 in use. BluIDs can also be manually created using an application in the access server s command line. The tool is called obexsender-put and is used as instructed below: obexsender-put --hash BD_ADDR For example: Figure 13: Building BluID manually 0

32 Figure 14: Parsing BluIDs from the OBEXSender log file 1

33 NOTE: Since the quality of OBEXSender database will radically affect the performance and recognition accuracy of OBEXSender it is recommended that the database is updated carefully and only recognition information, which is absolutely correct is added into the database. Therefore Bluegiga Technologies strongly recommends the following policy: 1. When you manually build BluIDs a. Execute obexsender-put --hash BD_ADDR b. Turn your phones Bluetooth on and off c. Execute obexsender-put --hash BD_ADDR d. Take your mobile s battery out and put it back and start the phone e. Execute obexsender-put --hash BD_ADDR f. If you can enable / or disable some Bluetooth profiles in your phone repeat steps a-e with the profile enabled or disabled g. Save all the BluID s, mobile phones manufacturer and model information and information about the phones state (which BluID was after Bluetooth reset, which after battery reset etc.) 2. Send an to support@bluegiga.com with BluID submission on the subject line and include all the above information in the Bluegiga Technologies will then provide you with the latest Bluetooth device database 2

34 7. TROUBLESHOOTING & KNOWN ISSUES Troubleshooting: OBEXSender is not sending anything? Make sure you have at least one content file specified in the OBEXSender configuration file. Notice that configuration file needs to use correct casing. Also check that OBEXSender is activated in the default startup applications. Make sure the RSSI limit is not too small. Mobiles receive files only between meters. Isn t OBEXSender supposed to work up to 100 meters? Almost all mobile phones are so-called class 2 devices, which means that their maximum range is about meters. So even if access server works up to 100 meters, the phones do not. Known issues: If you enter a non-existing path in Log file name configuration OBEXSender will fail to start. If you have entered a password for the iwrap (Bluetooth) interface and the same password is not set in the OBEXSender configuration, OBEXSender will fail to start. If several log files are defined in obexsender.conf, OBEXSender will fail to start Logging does not work, if you have defined two separate log files in the OBEXSender configuration file Support Latest software build can be found from Latest User s and Developer s guide can be found from: Access Server Users and Developers Guide Technical support can be contacted by sending to support@bluegiga.com Include the following information in the if possible o o o o WWW-setup -> Advanced settings -> System information -> Collect info for support request OBEXSender configuration file OBEXSender log file A detailed description of the problem 3