INSTALL TO INSTALL RUN: perl Makefile.PL make make test make install Once installed, run 'perldoc Net::Bluetooth' for more information. If you have any problems or questions please email me at IGuthrie@aol.com with "Net::Bluetooth" in the subject line. If you run into a build problem, please include the output of the install commands, the version of Perl you are using (perl -v), and what operating system you are using. If you are using BlueZ, please make sure it is installed and working on your system properly. You can use the utilities that are bundled with it to show remote devices and services (hciconfig, hcitool, sdptool, etc). If you are using Windows, please make sure you have Service Pack 2 installed. Also please make sure the "$win_include" variable at the top of Makfile.PL is set properly. This needs to point to the include directory for SP2. NAME Net::Bluetooth - Perl Bluetooth Interface SYNOPSIS use Net::Bluetooth; #### list all remote devices in the area my $device_ref = get_remote_devices(); foreach $addr (keys %$device_ref) { print "Address: $addr Name: $device_ref->{$addr}\n"; } #### search for a specific service (0x1101) on a remote device my @sdp_array = sdp_search($addr, "1101", ""); #### foreach service record foreach $rec_ref (@sdp_array) { #### Print all available information for service foreach $key (keys %$rec_ref) { print "Key: $key Value: $rec_ref->{$key}\n"; } } #### Create a RFCOMM client $obj = Net::Bluetooth->newsocket("RFCOMM"); if($obj->connect($addr, $port) != 0) { print "connect error: $!\n"; exit; } #### create a Perl filehandle for reading and writing *SERVER = $obj->perlfh(); $amount = read(SERVER, $buf, 256); close(SERVER); #### create a RFCOMM server $obj = Net::Bluetooth->newsocket("RFCOMM"); #### bind to port 1 if($obj->bind(1) != 0) { print "bind error: $!\n"; exit; } #### listen with a backlog of 2 if($obj->listen(2) != 0) { print "listen error: $!\n"; exit; } #### register a service #### $obj must be a open and bound socket my $service_obj = Net::Bluetooth->newservice($obj, "1101", "GPS", "GPS Receiver"); unless(defined($service_obj)) { #### couldn't register service } #### accept a client connection $client_obj = $obj->accept(); unless(defined($client_obj)) { print "client accept failed: $!\n"; exit; } #### get client information my ($caddr, $port) = $client_obj->getpeername(); #### create a Perl filehandle for reading and writing *CLIENT = $client_obj->perlfh(); print CLIENT "stuff"; #### close client connection close(CLIENT); #### stop advertising service $service_obj->stopservice(); #### close server connection $obj->close(); DESCRIPTION This module creates a Bluetooth interface for Perl. Net::Bluetooth works with the BlueZ libs as well as with Microsoft Windows. If you are going to be using a Unix system, the Bluez libs can be obtained at www.bluez.org. Please make sure these are installed and working properly before you install the module. Depending on your system BlueZ maybe already installed, or you may have to build it yourself and do some configuration. You can verify BlueZ can detect devices and services with the utilities that come with it (hciconfig, sdptool, hcitool, etc). If you are using Windows, make sure you have Service Pack 2 installed. The module should actually work with Service Pack 1, but I have not tested with it. There is also a good chance you will have to tell the module where to look for the SP include files. You can do this by setting the $win_include variable at the top of Makefile.PL. This is where the module will look for all the bluetooth header files (ws2bth.h, etc). FUNCTIONS get_remote_devices() Searches for remote Bluetooth devices. The search will take approximately 5 - 10 seconds (This will be a configurable value in the future.). When finished, it will return a hash reference that contains the device address and name. The address is the key and the name is the value. sdp_search($addr, $uuid, $name) This searches a specific device for service records. The first argument is the device address which is not optional. The uuid argument can be a valid uuid or "0". The name argument can be a valid service name or "". It will return services that match the uuid or service name if supplied, otherwise it will return all public service records for the device. The return value is a list which contains a hash reference for each service record found. The key/values for the hash are as follows: SERVICE_NAME: Service Name SERVICE_DESC: Service Description SERVICE_PROV: Service Provider RFCOMM: RFCOMM Port L2CAP: L2CAP Port UNKNOWN: Unknown Protocol Port If any of the values are unavailable, the keys will not exist. If $addr is "local" the call will use the local SDP server. (BlueZ only) SOCKET OBJECT The bluetooth socket object is used to create bluetooth sockets and interface with them. There are two types of sockets supported, RFCOMM and L2CAP. The methods are listed below. newsocket("RFCOMM") This constructs a socket object for a RFCOMM socket or L2CAP socket. connect($addr, $port) This calls the connect() system call with address and port you supply. You can use this to connect to a server. Returns 0 on success. bind($port) This calls the bind() system call with the port you provide. You can use this to bind to a port if you are creating a server. Returns 0 on success. As a side note, RFCOMM ports can only range from 1 - 31. listen($backlog) This calls the listen() system call with the backlog you provide. Returns 0 on success. accept() This calls the accept() system call and creates a new bluetooth socket object which is returned. On failure it will return undef. perlfh() This call returns a Perl filehandle for a open socket. You can use the Perl filehandle as you would any other filehandle, except with Perl calls that use the socket address structure. This provides a easy way to do socket IO instead of doing it through the socket object. Currently this is the only way to do socket IO, although soon I will provide read/write calls through the object interface. close() This closes the socket object. This can also be done through the Perl close() call on a created Perl filehandle. getpeername() This returns the address and name for a open bluetooth socket. (BlueZ only for now) SERVICE OBJECT The service object allows you to register a service with your local SDP server. The methods are as follows: newservice($obj, $service_uuid, $service_name, $service_desc) This registers a service with your local SDP server. The first argument is a open and bound socket that you created with newsocket(). The second argument is the service uuid. The third argument is the service name. The fourth argument is the service description. The return value is a new service object. This will be undefined if there was an error. stop_service() This unregisters your service with the local SDP server. The service will be unregistered without this call when the application exits. NOTES All uuids used with this module can either be 128 bit values: "00000000-0000-0000-0000-000000000000" or 16 bit values: "0000". All values must be represented as strings (enclosed in quotes), and must be hexadecimal values. Some helpful resources are the O'Reilly book "Linux Unwired". The BlueZ site www.bluez.org Intro to Bluetooth programming: http://people.csail.mit.edu/albert/bluez-intro/index.html REQUIREMENTS You need BlueZ or Microsoft Service Pack 2 installed. AUTHOR Ian Guthrie IGuthrie@aol.com Copyright (c) 2006 Ian Guthrie. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. SEE ALSO perl(1).