-
Notifications
You must be signed in to change notification settings - Fork 4
Home
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
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
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
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. Anid
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 propertiesmandatory
andoptional
, 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 of0000,0001
in binary, then the Characteristic Value does only have thecounter
field in it. If the flags is0000,1110
in binary, then the Characteristic Value does have thedInPolarity
,debouncePeriod
, andedgeSelection
fields in it.
- The
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' }
// ]
// }
// }
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 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.