Home

1. Overview

The ble-packet is the packet builder and parser used for process BLE attributes if they are GATT Specifications-defined ones or BIPSO Specifications-defined ones.

## 2. GATT Specifications

In BLE, an attributes is the smallest data entity defined by GATT (Generic Attributes). Attributes are used to describe the hierarchical data organization, such as Services and Characteristics, and pieces of the user data. A Service conceptually groups all the related Characteristics together, and each Characteristic always contain at least two attributes: Characteristic Declaration and Characteristic Value.

## 3. Installation

$ npm install ble-packet --save

## 4. Usage

Require the module:

var blePacket = require('ble-packet');

Using .frame() and .parse() methods to build and parse BLE attributes is quite simple. Here are some quick examples:

• Build a Characteristic raw buffer

var connParamsVal = {
        minConnInterval: 100,
        maxConnInterval: 500,
        latency: 0,
        timeout: 2000
    },
    charBuf = blePacket.frame('0x2a04', connParamsVal);

• Parse a Characteristic raw packet into an object

var charPacket = new Buffer([ 0x00, 0x00, 0x02, ... ]);

blePacket.parse('0x2a04', charPacket, function (err, result) {
    if (!err)
        console.log(result);  // The parsed result
});

## 5. APIs

.frame(uuid, value)

Generate the raw packet of a GATT-defined or BIPSO-defined attribute value.

Arguments:

1. uuid (String | Number): UUID defined in GATT Specifications or BIPSO Specification.
2. value (Object): A GATT-defined or BIPSO-defined attribute value.

Returns

• (Buffer | Object): Raw buffer of BLE attribute value, the given value will be returned if uuid is unrecognized.

Example:

// GATT-defined attribute
var dayDateUuid = '0x2a0a',
    dayDateVal = {
        year: 1945,
        month: 7,
        day: 19,
        hours: 9,
        minutes: 0,
        seconds: 0,
        dayOfWeek: 2
    };

blePacket.frame(dayDateUuid, dayDateVal);   // <Buffer 99 07 07 13 09 00 00 02>

// BIPSO-defined attribute
var genericUuid = '0xcc04',
    genericSensorValue = {            
        flags: 129,
        id: 0,
        sensorValue: 0,
        units: ppm,
        sensorType: MQ7
    };

blePacket.frame(genericUuid, genericSensorValue);    // <Buffer 81 00 00 00 00 00 03 70 70 6d 03 4d 51 37>

// Unrecognized attribute
var privateUuid = '0xff00',
    privateValue = {
        x: 0,
        y: 1
    };

blePacket.frame(privateUuid, privateValue);    // { x: 0, y: 1 }

---

.parse(uuid, buf, callback)

Parse a raw buffer into a GATT-defined or BIPSO-defined attribute value.

Arguments:

1. uuid (String | Number): UUID defined in GATT Specifications or BIPSO Specification.

2. buf (Buffer): Raw buffer to be parsed.

3. callback (Function): function(err, result) {...}. Get called along with the parsed value..

   • 'err' (Error) - Error Object
   • 'result' (Object | Buffer): result is a data object, or the given buf if uuid is unrecognized

Returns

• (None)

Example:

// GATT-defined attribute
var dayDateUuid = '0x2a0a',
    dayDateBuf = new Buffer([ 153, 7, 07, 19, 09, 00, 00, 02 ]);

blePacket.parse(dayDateUuid, dayDateBuf, function(err, result) {
    if (err)
        console.log(err);
    else
        console.log(result);

    /*    
    {
        year: 1945,
        month: 7,
        day: 19,
        hours: 9,
        minutes: 0,
        seconds: 0,
        dayOfWeek: 2
    }
    */
});

// Unrecognized attribute
var privateUuid = '0xff00',
    privateBuf = new Buffer([0, 1])

blePacket.parse(privateUuid, privateBuf, function(err, result) {
    if (err)
        console.log(err);
    else
        console.log(result);

    // <Buffer 0 1>
});