## package lightblue

    LightBlue - a simple bluetooth library.

## Sub-modules

## module lightblue.obex

Provides an OBEX client class and convenience functions for sending and receiving files over OBEX.

## Classes & Types

### Socket objects

A Bluetooth socket object has the same interface as a socket object from the Python standard library <socket> module.

### exception BluetoothError (`exceptions.IOError`)

Generic exception raised for Bluetooth errors.

## Functions

- finddevices(getnames=True, length=10)
- findservices(addr=None, name=None, servicetype=None)
- finddevicename(address, usecache=True)
- selectdevice()
- selectservice()
- gethostaddr()
- gethostclass()
- socket(proto=RFCOMM)
- advertise(name, sock, servicetype)
- stopadvertise(sock)
- splitclass(classofdevice)

#### finddevices(getnames=True, length=10)

        Performs a device discovery and returns the found devices as a list of
        (address, name, class-of-device) tuples. Raises BluetoothError if an error
        occurs.

        Arguments:
            - getnames=True: True if device names should be retrieved during
              discovery. If false, None will be returned instead of the device
              name.
            - length=10: the number of seconds to spend discovering devices
              (this argument has no effect on Python for Series 60)

        Do not invoke a new discovery before a previous discovery has finished.
        Also, to minimise interference with other wireless and bluetooth traffic,
        and to conserve battery power on the local device, discoveries should not
        be invoked too frequently (an interval of at least 20 seconds is
        recommended).

#### findservices(addr=None, name=None, servicetype=None)

        Performs a service discovery and returns the found services as a list of
        (device-address, service-port, service-name) tuples. Raises BluetoothError
        if an error occurs.

        Arguments:
            - addr=None: a device address, to search only for services on a
              specific device
            - name=None: a service name string, to search only for a service with a
              specific name
            - servicetype=None: can be RFCOMM or OBEX to search only for RFCOMM or
              OBEX-type services. (OBEX services are not returned from an RFCOMM
              search)

        If more than one criteria is specified, this returns services that match
        all criteria.

        Currently the Python for Series 60 implementation will only find RFCOMM and
        OBEX services.

#### finddevicename(address, usecache=True)

        Returns the name of the device with the given bluetooth address.
        finddevicename(gethostaddr()) returns the local device name.

        Arguments:
            - address: the address of the device to look up
            - usecache=True: if True, the device name will be fetched from a local
              cache if possible. If False, or if the device name is not in the
              cache, the remote device will be contacted to request its name.

        Raise BluetoothError if the name cannot be retrieved.

#### selectdevice()

        Displays a GUI which allows the end user to select a device from a list of
        discovered devices.

        Returns the selected device as an (address, name, class-of-device) tuple.
        Returns None if the selection was cancelled.

        (On Python For Series 60, the device selection will fail if there are any
        open bluetooth connections.)

#### selectservice()

        Displays a GUI which allows the end user to select a service from a list of
        discovered devices and their services.

        Returns the selected service as a (device-address, service-port, service-
        name) tuple. Returns None if the selection was cancelled.

        (On Python For Series 60, the device selection will fail if there are any
        open bluetooth connections.)

        Currently the Python for Series 60 implementation will only find RFCOMM and
        OBEX services.

#### gethostaddr()

        Returns the address of the local bluetooth device.

        Raise BluetoothError if the local device is not available.

#### gethostclass()

        Returns the class of device of the local bluetooth device.

        These values indicate the device's major services and the type of the
        device (e.g. mobile phone, laptop, etc.). If you google for
        "assigned numbers bluetooth baseband" you might find some documents
        that discuss how to extract this information from the class of device.

        Raise BluetoothError if the local device is not available.

#### socket(proto=RFCOMM)

        socket(proto=RFCOMM) -> socket object

        Returns a new socket object.

        Arguments:
            - proto=RFCOMM: the type of socket to be created - either L2CAP or
              RFCOMM.

        Note that L2CAP sockets are not available on Python For Series 60, and
        only L2CAP client sockets are supported on Mac OS X and Linux (i.e. you can
        connect() the socket but not bind(), accept(), etc.).

#### advertise(name, sock, servicetype)

        Starts advertising a service with the given name, using the given server
        socket. Raises BluetoothError if the service cannot be advertised.

        Arguments:
            - name: name of the service to be advertised
            - sock: the socket object that will serve this service. The socket must
              be already bound to a channel. If a RFCOMM service is being
              advertised, the socket should also be listening.
            - servicetype: the type of service to advertise - either RFCOMM or
              OBEX. (L2CAP services are not currently supported.)

        (If the servicetype is RFCOMM, the service will be advertised with the
        Serial Port Profile; if the servicetype is OBEX, the service will be
        advertised with the OBEX Object Push Profile.)

#### stopadvertise(sock)

        Stops advertising the service on the given socket. Raises BluetoothError if
        no service is advertised on the socket.

        This will error if the given socket is already closed.

#### splitclass(classofdevice)

        Splits the given class of device to return a 3-item tuple with the
        major service class, major device class and minor device class values.

        These values indicate the device's major services and the type of the
        device (e.g. mobile phone, laptop, etc.). If you google for
        "assigned numbers bluetooth baseband" you might find some documents
        that discuss how to extract this information from the class of device.

        Example:
            >>> splitclass(1057036)
            (129, 1, 3)
            >>>

## Data

#### L2CAP = 10

#### RFCOMM = 11

#### OBEX = 12