Author: David Boddie_ Date: 2015-01-22 Version: 0.26

Python 3 porting: Fabio Manganiello_ Date: 2019-12-11 Version: 0.28

The Object Exchange (OBEX_) protocol is a widely used protocol for network communication between Bluetooth and infra-red devices that provides the foundation for a number of common tasks, such as file transfer and data synchronization via the use of "profiles".

Although Bluetooth communication is well-supported on the most popular operating systems, support for OBEX is limited by the restricted amount of information freely available on the protocol. The specification of the protocol is published by the Infrared Data Association (IrDA_). Non-members of this association must pay a fee to obtain a copy of the specification document.

Most applications and libraries that provide connectivity between, for example, desktop computers and mobile phones use the OpenOBEX_ library to communicate using the OBEX protocol.

This package provides a simple Python_ implementation of aspects of the OBEX protocol based on the information available in freely available Bluetooth specifications_ and other openly accessible online resources. It is not intended to be a complete, accurate, or fully functioning implementation of the protocol. Developers may wish to build upon this package to implement support for more of the protocol, or to create user-friendly tools. See the Projects section below for links to projects that use PyOBEX.

This package depends on Bluetooth support in the standard Python socket module. Users of Linux and Windows XP systems may also find the PyBluez_ package useful; this provides the bluetooth module described below.

To install the package alongside other packages and modules in your Python installation, unpack the contents of the archive. At the command line, enter the directory containing the setup.py script and install it by typing the following::

 python setup.py install

You may need to become the root user or administrator to do this.

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()

Look up names by calling::

bluetooth.lookup_name(device_address)

on each device in the devices list.

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.

The PyOBEX package contains the following modules:

• __init__.py Package file for the PyOBEX Python package.
• common.py Classes providing common facilities for other modules.
• client.py Client classes for sending OBEX requests and handling responses.
• headers.py Classes encapsulating OBEX headers.
• requests.py Classes encapsulating OBEX requests.
• responses.py Classes encapsulating OBEX responses.

For most people, the client module is the most useful module because it provides a reasonably high level API that can be used to interact with a Bluetooth 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 list the files in the root directory on a device::

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

Other methods of the BrowserClient object can be used to get and put files, set the current directory and delete files. Use the interactive help facilities to find out more or read the docstrings in the source code.

Projects that use or extend PyOBEX are described in their own words in this section.

SyncBlue_: "SyncBlue is an open-source project with the aim of developing a utility for keeping files and folders synchronized across devices of various platforms without relying on the cloud."

Listing services under Linux::

sdptool browse

A list of services is available in the OpenOBEX Trac site:

• http://www.openobex.org
• http://dev.zuckschwerdt.org/openobex/wiki/ObexFtpServices

In file browsing mode, you may be able to obtain low level information about the directory structure on the phone by calling the client's get() method with an empty string.

The contents of this package are licensed under the GNU General Public License (version 3 or later)::

PyOBEX, a Python package implementing aspects of the Object Exchange (OBEX) protocol. Copyright (C) 2007 David Boddie [email protected]

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

.. _IrDA: http://www.irda.org/

.. _OBEX: http://bluetooth.com/Bluetooth/Technology/Works/OBEX.htm

.. _Bluetooth specifications: http://bluetooth.com/Bluetooth/Technology/Building/Specifications/Default.htm

.. _OpenOBEX: http://dev.zuckschwerdt.org/openobex/

.. _PyBluez: http://code.google.com/p/pybluez/

.. _Python: http://www.python.org/

.. _David Boddie: mailto:[email protected]

.. _SyncBlue: http://www.syncblue.eu/