Home

1. Overview

bipso is a dictionary for developers to query the UUIDs and Characteristic definitions defined by BIPSO. With BIPSO, firmware developers can organize Characteristics in an IPSO way to make their BLE devices/products IPSO-compatible.

Please see BIPSO Specification to learn more about why BIPSO and what it is doing.

## 2. Installation

$ npm install bipso --save

## 3. Usage

bipso provides you with only five APIs:

• .ou(): Get the BIPSO-defined Characteristic UUID by an Smart Object ID (oid).
• .uo(): Get the oid by an BIPSO-defined Characteristic UUID.
• .spec(): Get the definition of an BIPSO-defined Characteristic. The returned definition is a data object to show you what possible fields should be in the BIPSO-defined Characteristic Value.
• .frame(): Generate the raw packet of a BIPSO-defined Characteristic Value.
• .parse(): Parse a raw buffer into a BIPSO-defined Characteristic Value.

var bipso = require('bipso');

// Get the BIPSO-defined UUID from an oid  
bipso.ou('dIn');
// Get the oid from a BIPSO-defined UUID  
bipso.uo('0xcc00');

// Get the definition of a BIPSO-defined Characteristic:
bipso.spec('0xcc00');   // (1) from a BIPSO-defined UUID
bipso.spec('dIn');      // (2) from an oid

// Build a buffer of BIPSO-defined Characteristic:
bipso.frame('0xcc00', { "flags": 0, "id": 1, "dInState": false });
// Parse a buffer into BIPSO-defined Characteristic:
bipso.parse('0xcc00', new Buffer([0x00, 0x01, 0x00]), function (err, result) {...});

## 4. APIs

.ou(oid)

Get the BIPSO-defined Characteristic UUID by an Smart Object ID (oid).

Arguments:

• oid(String | Number): Smart Object ID. oid can be given with a string or a number. Notice that a numbered string will be recognized as a number, e.g. '128' is equal to 128.

Returns:

• (String | Undefined): Returns the Characteristic UUID, or undefined if cannot be transformed.

Example:

bipso.ou('dIn');     // '0xcc00'
bipso.ou('3200');    // '0xcc00'
bipso.ou(3200);      // '0xcc00'

bipso.ou('1234');    // undefined
bipso.ou('xxxx');    // undefined

---

.uo(uuid)

Get the oid by an BIPSO-defined Characteristic UUID.

Arguments:

• uuid(String | Number): Characteristic UUID defined in BIPSO Specification.

Returns:

• (String | Undefined): Returns the oid in string, or undefined if cannot be transformed.

Example:

bipso.uo('0xcc00');     // 'dIn'
bipso.uo(0xcc00);       // 'dIn'
bipso.uo(52224);        // 'dIn'

bipso.uo('0x6300');     // undefined
bipso.uo(0x6300);       // undefined
bipso.uo(25344);        // undefined

---

.spec(id)

Get the BIPSO Characteristic definition by an UUID or an oid. This API only accepts an id in string. An id starts with '0x' will be taken as an UUID, otherwiese it will be recognized as an oid.

Arguments:

• id(String): An UUID or an oid to find its BIPSO spec for. An id prefixed with '0x' will be taken as an UUID, otherwiese it will be taken as an oid.

Returns:

• (Object): The spec object of BIPSO Characteristic definition. This object has the following properties:

Property	Type	Description
oid	String	Smart Object ID in string
uuid	String	BIPSO-defined Characteristic ID in string
fields	Object	An object to show what possible fields should be in a Characteristic Value

• The fields object has two properties mandatory and optional, each is an array of field names and field types.
  • The mandatory property tells what fields a Characteristic Value must have.
  • The optional property tells what fields a Characteristic Value can have.
  • The mandatory field flags is a bit-vector to tell which optional fields does a Characteristic Value have. The following exmaple gives the spec of a 'dIn' Object, let's say if the flags has a value of 0000,0001 in binary, then the Characteristic Value does only have the counter field in it. If the flags is 0000,1110 in binary, then the Characteristic Value does have the dInPolarity, debouncePeriod, and edgeSelection fields in it.

Property	Type	Description
mandatory	Array	Each element is an object of { name, type }, and the Characteristic Value must have this field in it
optional	Array	Each element is an object of { name, type }, and the Characteristic Value can have this field in it

Example

// Get the definition of a BIPSO-defined Characteristic:
bipso.spec('0xcc00');   // (1) from a BIPSO-defined UUID
bipso.spec('dIn');      // (2) from an oid

// Returned object from (1) and (2)  
// {
//     oid: 'dIn',
//     uuid: '0xcc00',
//     fields: {
//          mandatory: [
//              { name: 'id',             type: 'uint8'   },
//              { name: 'flags',          type: 'uint8'   },
//              { name: 'dInState',       type: 'boolean' }
//          ],
//          optional: [
//              { name: 'counter',        type: 'uint8'   },
//              { name: 'dInPolarity',    type: 'boolean' },
//              { name: 'debouncePeriod', type: 'uint16'  },
//              { name: 'edgeSelection',  type: 'uint8'   },
//              { name: 'counterReset',   type: 'buffer'  },
//              { name: 'appType',        type: 'string'  },
//              { name: 'sensorType',     type: 'string'  }
//         ]
//     }
// }

---

.frame(uuid, charVal)

Generate the raw packet of a BIPSO-defined Characteristic Value.

Arguments:

• uuid(String | Number): Characteristic UUID defined in BIPSO Specification.
• charVal(Object): A BIPSO-defined Characteristic Value.

Returns:

• (Buffer): Raw buffer of given Characteristic Value.

Example:

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

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

---

.parse(uuid, buf, callback)

Parse a raw buffer into a BIPSO-defined Characteristic Value.

Arguments:

• uuid(String | Number): Characteristic UUID defined in BIPSO Specification.
• buf(Buffer): Raw buffer to be parsed.
• callback(Function): function (err, result) {...}. Get called when the buffer is parsed.

Returns:

• (None)

Example:

var genericUuid = '0xcc04',
    rawBuf = new Buffer([00, 81, 00, 00, 00, 00, 03, 70, 70, 6d, 03, 4d, 51, 37]);

bipso.parse(genericUuid, rawBuf, function (err, result) {
    if (err)
        console.log(err);
    else
        console.log(result);

    // Result object 
    //     {
    //         id: 0,
    //         flags: 129,
    //         sensorValue: 0,
    //         units: ppm,
    //         sensorType: MQ7
    //     }
});

## 5. Supported Data Types

Data types BIPSO supports are listed in the following table.

Data Class	Supported Data Types
String	'string' (should have a length byte at the beginning)
Integer	'int8', 'uint8', 'int16', 'uint16', 'int32', 'uint32', 'int64', 'uint64'
Float	'float' (32-bit), 'double' (64-bit)
Boolean	'boolean' (1 for true, and 0 for false)
Opaque	'buffer' (should have a length byte at the beginning)
Time	'time' (Unix time, an int32 number representing seconds since Jan 1, 1970)
None	'none' (A field with this data type may be an Excutable Resource)

[Important!!]

• A 'string' data should be an UTF-8 string. In firmware, it should have a length byte precedes the string in Characteristic Value raw data to indicate how long the string is.
• Integer and Float values are all little-endian.
• One should be noticed that, in firmware, it should have a length byte precedes the buffer in Characteristic Value raw data to indicate how many bytes the buffer is.