Nibbling Perfect Macaroni
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »

    bluetooth-serial-portpublic

    Bluetooth serial port communication for Node.js

    Build Status Build status

    This node module lets you communicate over Bluetooth serial port with devices using Node.js. The goal is have an easy to use API. This module is great for communicating with Bluetooth enabled Arduino devices.

    If you have any problems make sure to checkout the FAQ.

    New in the last release

    • Fixes an issue in the typescript definitions.
    • Fixes an issue where, on Windows, listPairedDevices is showing unpaired devices.

    Check the release notes for an overview of the change history.

    Pre-requests on Linux

    • Needs Bluetooth development packages to build

    apt-get install build-essential libbluetooth-dev

    Note on RFCOMM Server Sockets

    As the initial implementation of the RFCOMM server sockets is based on BlueZ4, in order to work with SDP we need to change the bluetoothd service configuration file by modifing the systemd unit file: bluetooth.service:

    (Debian based distro)

    sudo vim /lib/systemd/system/bluetooth.service

    (RedHat based distro)

    sudo vim /usr/lib/systemd/system/bluetooth.service

    and adding the --compat flag to the ExecStart value:

    ExecStart=/usr/lib/bluetooth/bluetoothd--compat

    Finally, restart the service:

    sudo systemctl daemon-reload
    sudo systemctl restart bluetooth

    Pre-request on macOS

    • Needs Xcode and Xcode command line tools installed.

    Pre-request on Windows

    • Needs Visual Studio (Visual C++) and its command line tools installed.
    • Needs Python 2.x installed and accessible from the command line path.

    Install

    npm install bluetooth-serial-port

    Test build Linux using docker

    docker build -t bluetooth-serial-port .

    Documentation

    Basic client usage

     
    var btSerial = new (require('bluetooth-serial-port')).BluetoothSerialPort();
     
    btSerial.on('found', function(address, name) {
        btSerial.findSerialPortChannel(address, function(channel) {
            btSerial.connect(address, channel, function() {
                console.log('connected');
     
                btSerial.write(new Buffer('my data', 'utf-8'), function(err, bytesWritten) {
                    if (err) console.log(err);
                });
     
                btSerial.on('data', function(buffer) {
                    console.log(buffer.toString('utf-8'));
                });
            }, function () {
                console.log('cannot connect');
            });
     
            // close the connection when you're ready
            btSerial.close();
        }, function() {
            console.log('found nothing');
        });
    });
     
    btSerial.inquire();
     

    Basic server usage (only on Linux)

    var server = new(require('bluetooth-serial-port')).BluetoothSerialPortServer();
     
    var CHANNEL = 10; // My service channel. Defaults to 1 if omitted.
    var UUID = '38e851bc-7144-44b4-9cd8-80549c6f2912'; // My own service UUID. Defaults to '1101' if omitted
     
    server.listen(function (clientAddress) {
        console.log('Client: ' + clientAddress + ' connected!');
        server.on('data', function(buffer) {
            console.log('Received data from client: ' + buffer);
     
            // ...
     
            console.log('Sending data to the client');
            server.write(new Buffer('...'), function (err, bytesWritten) {
                if (err) {
                    console.log('Error!');
                } else {
                    console.log('Send ' + bytesWritten + ' to the client!');
                }
            });
        });
    }, function(error){
        console.error("Something wrong happened!:" + error);
    }, {uuid: UUID, channel: CHANNEL} );

    API

    BluetoothSerialPort

    Event: ('data', buffer)

    Emitted when data is read from the serial port connection.

    • buffer - the data that was read into a Buffer object.

    Event: ('closed')

    Emitted when a connection was closed either by the user (i.e. calling close or remotely).

    Event: ('failure', err)

    Emitted when reading from the serial port connection results in an error. The connection is closed.

    Event: ('found', address, name)

    Emitted when a bluetooth device was found.

    • address - the address of the device
    • name - the name of the device (or the address if the name is unavailable)

    Event: ('finished')

    Emitted when the device inquiry execution did finish.

    BluetoothSerialPort.inquire()

    Starts searching for bluetooth devices. When a device is found a 'found' event will be emitted.

    BluetoothSerialPort.inquireSync()

    Starts searching synchronously for bluetooth devices. When a device is found a 'found' event will be emitted.

    BluetoothSerialPort.findSerialPortChannel(address, callback[, errorCallback])

    Checks if a device has a serial port service running and if it is found it passes the channel id to use for the RFCOMM connection.

    • callback(channel) - called when finished looking for a serial port on the device.

    • errorCallback - called the search finished but no serial port channel was found on the device. Connects to a remote bluetooth device.

    • bluetoothAddress - the address of the remote Bluetooth device.

    • channel - the channel to connect to.

    • [successCallback] - called when a connection has been established.

    • [errorCallback(err)] - called when the connection attempt results in an error. The parameter is an Error object.

    BluetoothSerialPort.close()

    Closes the connection.

    BluetoothSerialPort.isOpen()

    Check whether the connection is open or not.

    BluetoothSerialPort.write(buffer, callback)

    Writes a Buffer to the serial port connection.

    • buffer - the Buffer to be written.
    • callback(err, bytesWritten) - is called when the write action has been completed. When the err parameter is set an error has occured, in that case err is an Error object. When err is not set the write action was successful and bytesWritten contains the amount of bytes that is written to the connection.

    BluetoothSerialPort.listPairedDevices(callback)

    NOT AVAILABLE ON LINUX

    Lists the devices that are currently paired with the host.

    • callback(pairedDevices) - is called when the paired devices object has been populated. See the pull request for more information on the pairedDevices object.

    BluetoothSerialPortServer

    BluetoothSerialPortServer.listen(callback[, errorCallback, options])

    Listens for an incoming bluetooth connection. It will automatically advertise the server via SDP

    • callback(address) - is called when a new client is connecting.
    • errorCallback(err) - is called when an error occurs.
    • options - An object with these properties:
      • uuid - [String] The UUID of the server. If omitted the default value will be 1101 (corresponding to Serial Port Profile UUID). Can be a 16 bit or 32 bit UUID.

      • channel - [Number] The RFCOMM channel the server is listening on, in the range of 1-30. If omitted the default value will be 1.

        Example: var options = { uuid: 'ffffffff-ffff-ffff-ffff-fffffffffff1', channel: 10 }

    BluetoothSerialPortServer.write(buffer, callback)

    Writes data from a buffer to a connection.

    • buffer - the buffer to send over the connection.
    • callback(err, len) - called when the data is send or an error did occur. error contains the error is appropriated. len has the number of bytes that were written to the connection.

    BluetoothSerialPortServer.close()

    Stops the server

    BluetoothSerialPortServer.isOpen()

    Checks is a server is listening or not.

    Event: ('data', buffer)

    Emitted when data is read from the serial port connection.

    • buffer - the data that was read into a Buffer object.

    Event: ('closed')

    Emitted when a connection was closed either by the user (i.e. calling close or remotely).

    Event: ('failure', err)

    Emitted when reading from the serial port connection results in an error. The connection is closed.

    Typescript support

    The type script declaration file is bundled with this module so you can use it without needing to npm install @types/bluetooth-serial-port

    import btSerial = require("bluetooth-serial-port");
     
    btSerial.findSerialPortChannel(addressstring, (channel: number) => {
        btSerial.connect(addressstring, channelnumber, () => {
            btSerial.write(new Buffer("yes"), (err) => {
            if (err) {
                    console.error(err);
                }
            });
        }, (err?: Error) => {
                if (err) {
                    console.error(err);
                }
            });
            btSerial.on("data", (buffer: Buffer) => console.log(buffer.toString("ascii")));
    }, () => {
            console.error("Cannot find channel!");
    });

    LICENSE

    This module is available under a FreeBSD license, see the LICENSE file for details.

    install

    npm i bluetooth-serial-port

    Downloadsweekly downloads

    192

    version

    2.1.6

    license

    BSD-2-Clause

    repository

    githubgithub

    last publish

    collaborators

    • avatar
    • avatar