Wiki

Clone wiki

PyOBEX / Home

PyOBEX API Guide

This guide contains recipes for developers using PyOBEX. Some of these are included in the README.txt and README.html files.

Locating the Bluetooth device

Low level discovery of Bluetooth devices and services is provided by the bluetooth module, distributed as part of the PyBluez package. You need to use the following calls to determine the address of the device you wish to connect to.

Discover the devices available by calling:

devices = bluetooth.discover_devices()

This should return a list of device addresses, each of which is a string, and put the result in the devices variable.

With an address stored in the device_address variable, we can look up the name of the corresponding device by calling:

bluetooth.lookup_name(device_address)

This returns a human-readable string.

Find out about the services provided by a device by calling:

bluetooth.find_service(address=device_address)

On my phone, the file transfer service has the service ID, "E006", so we can find out the port on the device that we need to connect to when using the BrowserClient from the PyOBEX.client module:

services = bluetooth.find_service(uuid="E006", address=device_address)

The list returned contains dictionaries corresponding to each service. The port used by a service can be obtained from the "port" dictionary entry. Assuming that the previous line of code returned a list containing a single item, we can obtain the port using the following code:

port = services[0]["port"]

This integer value will be required when connecting to the service.

Connecting to a device

Using appropriate values for device_address and port obtained using the bluetooth module, or alternative tools on your system, the following code can be used to connect to a device:

from PyOBEX.client import BrowserClient
client = BrowserClient(device_address, port)
client.connect()

If successful, the return value should be a ConnectSuccess instance, like the following:

<PyOBEX.responses.ConnectSuccess instance at 0xb77260cc>

Listing files

To list the files in the root directory on a device, call the client's listdir() method:

client.listdir()

This returns a tuple containing the OBEX headers returned by the device and a string containing an XML description of the directory's contents, like this:

([<PyOBEX.headers.Connection_ID instance at 0xb772514c>], '<?xml version="1.0" encoding="UTF-8"?>\r\n<!DOCTYPE folder-listing SYSTEM "obex-folder-listing.dtd">\r\n<!--\r\n XML Coder, Apr 10 2006, 21:03:28, (C) 2001 Sony Ericsson Mobile Communications AB \r\n-->\r\n<folder-listing version="1.0"><folder name="Phone memory"/>\r\n</folder-listing>\r\n')

Changing directory

To enter a directory on the device, making it the current directory, call the client's setpath() method with the name of the directory to enter, like this:

client.setpath("Phone memory")

If successful, this method returns a Success instance:

<PyOBEX.responses.Success instance at 0xb77355ac>

To navigate to the parent directory, use the method in the following way:

client.setpath(to_parent = True)

Note that you cannot pass complete paths to the method. You must pass individual directory names one at a time.

Getting files from a device

To get a file from a device, call the client's get() method, like this:

headers, data = client.get("Beam.thm")

This method returns a tuple containing a list of headers and a string containing the file data. It is up to you how you store this data.

Putting files on a device

To put a file on a device, call the client's put() method, like this:

client.put("Python.txt", "ABC")

If successful, this method returns a Success object:

<PyOBEX.responses.Success instance at 0xb76ab5ec>

Deleting files and directories

To delete a file or directory, call the client's delete() method, like this:

client.delete("Python.txt")

If successful, this method returns a Success object:

<PyOBEX.responses.Success instance at 0xb773560c>

Disconnecting from a device

client.disconnect()

If successful, this method returns a Success object:

<PyOBEX.responses.Success instance at 0xb772518c>

Using Multiple Bluetooth Devices

Some developers want to use multiple Bluetooth adapters (USB dongles, for example) to communicate with devices. To do this, you first need to identify the Bluetooth addresses of the adapters. On a Linux-based system, you can use the hcitool utility to find out this information:

hcitool dev

As before, a client object is created for communication with the device:

from PyOBEX.client import BrowserClient
client = BrowserClient(device_address, port)

Instead of connecting immediately, a Bluetooth socket is created and bound to the address of one of the adapters. The socket is passed to the client object's set_socket() method, and it will be used instead of a default socket created by the client:

s = BluetoothSocket(bluetooth.RFCOMM)
s.bind((adapter_address, 0))
client.set_socket(s)
client.connect()

Here, the bluetooth module's BluetoothSocket class is used. For Python installations with a Bluetooth-enabled socket module, the following code should also work:

s = socket.socket(socket.AF_BLUETOOTH, socket.SOCK_STREAM, socket.BTPROTO_RFCOMM)
s.bind((adapter_address, 0))
client.set_socket(s)
client.connect()

By bindings sockets to different adapter addresses, it should be possible to communicate with different devices with specific adapters.

Wiki features

This wiki uses the Creole syntax, and is fully compatible with the 1.0 specification.

The wiki itself is actually a hg repository, which means you can clone it, edit it locally/offline, add images or any other file type, and push it back to us. It will be live immediately.

Go ahead and try:

$ hg clone http://bitbucket.org/dboddie/pyobex/wiki/

Wiki pages are normal files, with the .wiki extension. You can edit them locally, as well as creating new ones.

Updated

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.