Source

PyOBEX / README.html

Full commit
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.4.1: http://docutils.sourceforge.net/" />
<title>PyOBEX Python Package</title>
<meta name="author" content="David Boddie" />
<meta name="date" content="2009-01-18" />
</head>
<body>
<div class="document" id="pyobex-python-package">
<h1 class="title">PyOBEX Python Package</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td><a class="first last reference" href="mailto:david&#64;boddie.org.uk">David Boddie</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2009-07-18</td></tr>
<tr><th class="docinfo-name">Version:</th>
<td>0.24</td></tr>
</tbody>
</table>
<p><em>Note: This text is marked up using reStructuredText formatting. It should be
readable in a text editor but can be processed to produce versions of this
document in other formats.</em></p>
<div class="contents topic">
<p class="topic-title first"><a id="contents" name="contents">Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#introduction" id="id1" name="id1">Introduction</a></li>
<li><a class="reference" href="#installation" id="id2" name="id2">Installation</a></li>
<li><a class="reference" href="#locating-the-bluetooth-device" id="id3" name="id3">Locating the Bluetooth device</a></li>
<li><a class="reference" href="#using-the-pyobex-package" id="id4" name="id4">Using the PyOBEX package</a></li>
<li><a class="reference" href="#resources" id="id5" name="id5">Resources</a></li>
<li><a class="reference" href="#notes-on-the-sony-ericsson-k750i" id="id6" name="id6">Notes on the Sony Ericsson K750i</a></li>
<li><a class="reference" href="#license" id="id7" name="id7">License</a></li>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" id="introduction" name="introduction">Introduction</a></h1>
<p>The Object Exchange (<a class="reference" href="http://bluetooth.com/Bluetooth/Technology/Works/OBEX.htm">OBEX</a>) 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 &quot;profiles&quot;.</p>
<p>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 (<a class="reference" href="http://www.irda.org/">IrDA</a>). Non-members of this
association must pay a fee to obtain a copy of the specification document.</p>
<p>Most applications and libraries that provide connectivity between, for example,
desktop computers and mobile phones use the <a class="reference" href="http://dev.zuckschwerdt.org/openobex/">OpenOBEX</a> library to communicate
using the OBEX protocol.</p>
<p>This package provides a simple <a class="reference" href="http://www.python.org/">Python</a> implementation of aspects of the OBEX
protocol based on the information available in freely available
<a class="reference" href="http://bluetooth.com/Bluetooth/Technology/Building/Specifications/Default.htm">Bluetooth specifications</a> and other openly accessible online resources.
It is not intended to be a complete, accurate, or fully functioning
implementation of the protocol.</p>
<p>This package depends on Bluetooth support in the standard Python <tt class="docutils literal"><span class="pre">socket</span></tt>
module. Users of Linux and Windows XP systems may also find the <a class="reference" href="http://code.google.com/p/pybluez/">PyBluez</a>
package useful; this provides the <tt class="docutils literal"><span class="pre">bluetooth</span></tt> module described below.</p>
</div>
<div class="section">
<h1><a class="toc-backref" id="installation" name="installation">Installation</a></h1>
<p>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 <tt class="docutils literal"><span class="pre">setup.py</span></tt> script and install it by typing the
following:</p>
<pre class="literal-block">
python setup.py install
</pre>
<p>You may need to become the root user or administrator to do this.</p>
</div>
<div class="section">
<h1><a class="toc-backref" id="locating-the-bluetooth-device" name="locating-the-bluetooth-device">Locating the Bluetooth device</a></h1>
<p>Low level discovery of Bluetooth devices and services is provided by the
<tt class="docutils literal"><span class="pre">bluetooth</span></tt> module, distributed as part of the <a class="reference" href="http://code.google.com/p/pybluez/">PyBluez</a> package. You need to
use the following calls to determine the address of the device you wish to
connect to.</p>
<p>Discover the devices available by calling:</p>
<pre class="literal-block">
devices = bluetooth.discover_devices()
</pre>
<p>Look up names by calling:</p>
<pre class="literal-block">
bluetooth.lookup_name(device_address)
</pre>
<p>on each device in the devices list.</p>
<p>Find out about the services provided by a device by calling:</p>
<pre class="literal-block">
bluetooth.find_service(address=device_address)
</pre>
<p>The file transfer service has the service ID, &quot;E006&quot;, 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:</p>
<pre class="literal-block">
services = bluetooth.find_service(uuid=&quot;E006&quot;, address=device_address)
</pre>
<p>The list returned contains dictionaries corresponding to each service. The port
used by a service can be obtained from the &quot;port&quot; 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:</p>
<pre class="literal-block">
port = services[0][&quot;port&quot;]
</pre>
<p>This integer value will be required when connecting to the service.</p>
</div>
<div class="section">
<h1><a class="toc-backref" id="using-the-pyobex-package" name="using-the-pyobex-package">Using the PyOBEX package</a></h1>
<p>The PyOBEX package contains the following modules:</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">__init__.py</span></tt></dt>
<dd>Package file for the PyOBEX Python package.</dd>
<dt><tt class="docutils literal"><span class="pre">common.py</span></tt></dt>
<dd>Classes providing common facilities for other modules.</dd>
<dt><tt class="docutils literal"><span class="pre">client.py</span></tt></dt>
<dd>Client classes for sending OBEX requests and handling responses.</dd>
<dt><tt class="docutils literal"><span class="pre">headers.py</span></tt></dt>
<dd>Classes encapsulating OBEX headers.</dd>
<dt><tt class="docutils literal"><span class="pre">requests.py</span></tt></dt>
<dd>Classes encapsulating OBEX requests.</dd>
<dt><tt class="docutils literal"><span class="pre">responses.py</span></tt></dt>
<dd>Classes encapsulating OBEX responses.</dd>
</dl>
<p>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.</p>
<p>Using appropriate values for <tt class="docutils literal"><span class="pre">device_address</span></tt> and <tt class="docutils literal"><span class="pre">port</span></tt> obtained using the
<tt class="docutils literal"><span class="pre">bluetooth</span></tt> module, or alternative tools on your system, the following code
can be used to list the files in the root directory on a device:</p>
<pre class="literal-block">
from PyOBEX.client import BrowserClient
client = BrowserClient(device_address, port)
client.connect()
client.listdir()
client.disconnect()
</pre>
<p>Other methods of the <tt class="docutils literal"><span class="pre">BrowserClient</span></tt> 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.</p>
</div>
<div class="section">
<h1><a class="toc-backref" id="resources" name="resources">Resources</a></h1>
<p>Listing services under Linux:</p>
<pre class="literal-block">
sdptool browse &lt;device address&gt;
</pre>
<p>A list of services is available in the OpenOBEX Trac site:</p>
<ul class="simple">
<li><a class="reference" href="http://www.openobex.org">http://www.openobex.org</a></li>
<li><a class="reference" href="http://dev.zuckschwerdt.org/openobex/wiki/ObexFtpServices">http://dev.zuckschwerdt.org/openobex/wiki/ObexFtpServices</a></li>
</ul>
</div>
<div class="section">
<h1><a class="toc-backref" id="notes-on-the-sony-ericsson-k750i" name="notes-on-the-sony-ericsson-k750i">Notes on the Sony Ericsson K750i</a></h1>
<p>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.</p>
</div>
<div class="section">
<h1><a class="toc-backref" id="license" name="license">License</a></h1>
<p>The contents of this package are licensed under the GNU General Public License
(version 3 or later):</p>
<pre class="literal-block">
PyOBEX, a Python package implementing aspects of the Object Exchange (OBEX) protocol.
Copyright (C) 2007 David Boddie &lt;david&#64;boddie.org.uk&gt;

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 &lt;http://www.gnu.org/licenses/&gt;.
</pre>
</div>
</div>
</body>
</html>