Document simple-ble

simple-ble/README.md

@@ -0,0 +1,18 @@
+Simple BLE Library
+==================
+
+A library for simplifying interactions with a BLE radio. So far, this library
+helps serialize GAP advertizing data as defined in the Bluetooth Core
+Specification Supplement (CSS).
+
+Using `simple-ble` in Tock
+--------------------
+
+To use `simple-ble`, add the following include to the application's
+Makefile:
+
+    EXTERN_LIBS += $(TOCK_USERLAND_BASE_DIR)/simple-ble
+
+To make sure the library is compiled when compiling your process, you can also add:
+
+    include $(TOCK_USERLAND_BASE_DIR)/simple-ble/Makefile

simple-ble/gap.c

@@ -19,6 +19,7 @@ int gap_add_flags(AdvData_t *adv_data, uint8_t flags) {
     adv_data->buf[adv_data->offset + 1] = GAP_FLAGS;
     adv_data->buf[adv_data->offset + 2] = flags;
     adv_data->offset = new_len;
+    // always writes 3 bytes
     return 3;
   } else {
     return -1;
@@ -41,7 +42,7 @@ int gap_add_adv_data_field(AdvData_t *adv_data, GapAdvertisementData_t type,
   adv_data->buf[adv_data->offset + 1] = type;
   memcpy(&adv_data->buf[adv_data->offset + 2], data, data_len);
   adv_data->offset = new_length;
-  return 0;
+  return 2 + data_len;
 }
 
 int gap_add_device_name(AdvData_t *adv_data, const uint8_t *device_name, uint8_t len) {

simple-ble/include/gap.h

@@ -66,33 +66,48 @@ typedef struct AdvData {
 // len                 - length of the advertisment data
 AdvData_t gap_adv_data_new(uint8_t* buf, int len);
 
+// Add flags field
+//
+// adv_data            - advertisement data structure to insert `device name` into
+// flags               - Bitmap of GAP flags
+//
+// Returns the number of bytes written to the `adv_data` buffer.
 int gap_add_flags(AdvData_t *adv_data, uint8_t flags);
+
+// Add data field
+//
+// adv_data            - advertisement data structure to insert `device name` into
+// type                - Data field type
+// data                - field data
+// data_len            - length of field data
+//
+// Returns the number of bytes written to the `adv_data` buffer.
 int gap_add_adv_data_field(AdvData_t *adv_data, GapAdvertisementData_t type,
                                     const uint8_t *data, uint8_t data_len);
 
-// configure advertisement name
+// Add device name field
 //
 // adv_data            - advertisement data structure to insert `device name` into
 // device_name         - device named to be used in the advertisement
 // len                 - length of device name
 int gap_add_device_name(AdvData_t *adv_data, const uint8_t *device_name, uint8_t len);
 
-// configure list of 16 bit uuids
+// Add UUID16 service field
 //
 // adv_data             - advertisement data structure to insert to `uuid16` into
 // uuid16               - 16 bit uuid identifier of service
 // len                  - length of uuid16 service identifier
 int gap_add_service_uuid16(AdvData_t *adv_data, const uint16_t *uuid16, uint8_t len);
 
-// configure service data
+// Add service data field
 //
 // adv_data             - advertisement data structure to insert `service data` into
 // uuid16               - 16 bit uuid to be associated with the data
 // data                 - service data
 // len                  - length of service data
 int gap_add_service_data(AdvData_t *adv_data, uint16_t uuid16, uint8_t *data, uint8_t len);
 
-// configure manufacturer specific data
+// Add manufacturer specific data field
 //
 // adv_data             - advertisement data structure to insert `manufacturer specific data` into
 // data                 - manufacturer specific data