Skip to content

Latest commit

 

History

History
101 lines (79 loc) · 6 KB

README.md

File metadata and controls

101 lines (79 loc) · 6 KB
Raw

Maven Central Build Status Coverage Status Codacy Badge Join the chat at https://gitter.im/sputnikdev/bluetooth-gatt-parser

bluetooth-gatt-parser

A simple library/framework to work with Bluetooth Smart (BLE) GATT services and characteristics.

Have a look at an example of parsing a standard characteristic (Battery Level 0x2A19) value:

BluetoothGattParserFactory.getDefault().parse("2A19", new byte[] {51}).get("Level").getInteger(null);

This would print 51.

Features:

  1. Supports 99% of the existing/standard GATT services and characteristics specifications.
  2. Parse/read single and multi field characteristics into a user-friendly data format.
  3. Writing single and multi field characteristics.
  4. Validating input data whether it conforms to GATT specifications (format types and mandatory fields).
  5. Extensibility. User defined services and characteristics.
  6. Support for all defined format types.

Start using the library by including a maven dependency in your project:

<dependency>
  <groupId>org.sputnikdev</groupId>
  <artifactId>bluetooth-gatt-parser</artifactId>
  <version>X.Y.Z</version>
</dependency>

A more complex example of parsing multi-field characteristics (Heart Rate service):

// Getting a default implementation which is capable of reading/writing the standard GATT services and characteristics
BluetoothGattParser parser = BluetoothGattParserFactory.getDefault();

// Reading Body Sensor Location (0x2A38) characteristic (sigle field)
byte[] data = new byte[] {1}; // 1 == Chest
GattResponse response = parser.parse("2A38", data);
String sensorLocation = response.get("Body Sensor Location").getInteger(null); // prints 1 (Chest)

// Reading Heart Rate Measurement (0x2A37) characteristic (multi field)
byte[] data = new byte[] {20, 74, 13, 3};
GattResponse response = parser.parse("2A37", data);
String heartRateValue = response.get("Heart Rate Measurement Value (uint8)").getInteger(null); // prints 74
String rrIntervalValue = response.get("RR-Interval").getInteger(null); // prints 781

// Writing Heart Rate Control Point (0x2A39) characteristic
GattRequest request = parser.prepare("2A39");
request.setField("Heart Rate Control Point", 1); // control value to be sent to a bluetooth device
byte[] data = parser.serialize(request);

See more examples in the integration tests: GenericCharacteristicParserIntegrationTest

Extending the library with user defined services and characteristics

The gatt-parser library is designed to be able to add support for some new custom services/characteristics or to override an existing ("approved") service and characteristic. This can be done by just providing a new GATT XML file which specifies your service and characteristic (have a look at the standard definition for the Battery Level characteristic). The library will read your custom files and build internal rules/conditions for parsing and serialization of your custom characteristics. This means you don't have to write any code to parse/serialize simple or complex custom characteristics.

Loading XML GATT specification files (GATT-like specifications) from a folder:

BluetoothGattParser parser = BluetoothGattParserFactory.getDefault();
File extensionsFolderFile = new File(..);
gattParser.loadExtensionsFromFolder(extensions);

A custom parser can be added for a characteristic if you are not satisfied with the default one

See the default one for a hint and a reference: GenericCharacteristicParser

BluetoothGattParser parser = BluetoothGattParserFactory.getDefault();
CharacteristicParser customParser = new ...; // your own implementation
parser.registerParser(CHARACTERISTIC_UUID, customParser);

Contribution

You are welcome to contribute to the project, the project environment is designed to make it easy by using:

  • Travis CI to release artifacts directly to the Maven Central repository.
  • Code style rules to support clarity and supportability. The results can be seen in the Codacy.
  • Code coverage reports in the Coveralls to maintain sustainability. 100% of code coverage with unittests is the target.

The build process is streamlined by using standard maven tools.

To build the project with maven:

mvn clean install

To cut a new release and upload it to the Maven Central Repository:

mvn release:prepare -B
mvn release:perform

Travis CI process will take care of everything, you will find a new artifact in the Maven Central repository when the release process finishes successfully.