Partial implementation of BlueGiga's BGAPI for use with the BLE112/3 modules over UART.

Hi there! I recently started using BLE112 modules with the mbed LPC1768 MCU, and I realized there was no implementation of BlueGiga's BGAPI available for mbed. This library implements only a few commands, but if you're looking to get started, this is a good place to look.

This was developed against BGAPI v1.3.2. I make no guarantees as to how well it will work with newer revisions of the software.

Files at this revision

API Documentation at this revision

Comitter:
dishbreak
Date:
Tue May 19 05:49:00 2015 +0000
Parent:
5:7c7220a316ed
Child:
7:63daf39f20e1
Commit message:
Fixed up documentation. Added GAP Discover command.

Changed in this revision

BGLib.cpp Show annotated file Show diff for this revision Revisions of this file
BGLib.h Show annotated file Show diff for this revision Revisions of this file
api_datatypes.h Show annotated file Show diff for this revision Revisions of this file
callbacks.h Show annotated file Show diff for this revision Revisions of this file
--- a/BGLib.cpp	Tue May 19 05:01:10 2015 +0000
+++ b/BGLib.cpp	Tue May 19 05:49:00 2015 +0000
@@ -39,6 +39,12 @@
     mTimestampCallback = pCallback;
 }
 
+void BGLib::ble_cmd_gap_discover(gap_discover_mode mode) {
+    uint8_t bytes[] = {0x00, 0x01, 0x06, 0x02, 0x00};
+    bytes[4] = (uint8_t) mode;
+    send_bytes(bytes, 5);
+}
+
 void BGLib::parse() {
     mTimestampCallback();
     
--- a/BGLib.h	Tue May 19 05:01:10 2015 +0000
+++ b/BGLib.h	Tue May 19 05:49:00 2015 +0000
@@ -10,10 +10,8 @@
 * 
 * BGLib ble112(p9, p10, p7, p8);
 * 
-* uint8_t hello_msg[] = {0x00, 0x00, 0x00, 0x01};
-* 
 * void helloCallback() {
-*    //executed when code compiles.
+*    printf("BLE112 said hello!\r\n");
 * }
 * 
 * int main() {
@@ -35,6 +33,13 @@
     */
     BGLib(PinName tx, PinName rx, PinName rts, PinName cts);
     
+    /** GAP Discoverable modes */
+    enum gap_discover_mode {
+        gap_discover_limited = 0, ///< Discover only limited discoverable devices, that is, Slaves which have the LE Limited Discoverable Mode bit set in the Flags AD type of their advertisement packets.
+        gap_discover_generic = 1, ///<  Discover limited and generic discoverable devices, that is, Slaves which have the LE Limited Discoverable Mode or the LE General Discoverable Mode bit set in the Flags AD type of their advertisement packets.
+        gap_discover_observation = 2 ///< Discover all devices regardless of the Flags AD type, so also devices in non-discoverable mode will be reported to host.
+    };
+    
     /** Send a Hello command to the device. */
     void ble_cmd_system_hello();
     
@@ -51,7 +56,9 @@
     */
     void set_ble_rsp_system_get_info(get_info_callback_t pCallback);
     
-    /** Send a Reset command to the device. */
+    /** Send a Reset command to the device.
+    * @param args A struct containing the DFU flag.  
+    */
     void ble_cmd_system_reset(ble_msg_system_reset_t args);
     
     /** Set the callback for a Boot event. Invoked when the BLE112 is powered on or reset. 
@@ -59,17 +66,31 @@
     */
     void set_ble_evt_system_boot(boot_callback_t pCallback);
     
-    /** Set a "timestamping" callback. This is invoked whenever the mbed receives data on the UART interface.
+    /** Set a "timestamping" callback. This is invoked whenever the mbed receives <em>any</em> data on the UART interface.
     * @param pCallback Function pointer to the desired callback.
     */
     void set_timestamp_callback(timestamp_callback_t pCallback);
     
+    /** Send a Discover command to the device. 
+    * @param mode The mode that the device should do discovery in.
+    */
+    void ble_cmd_gap_discover(gap_discover_mode mode);
+        
+    
 private:
+    /** Function that handles parsing responses on the UART port. */
     void parse();
+    
+    /** Function that sends a specific number of bytes via the UART port.
+    * @attention This function doesn't do any bounds checking. Be careful with what you put in!
+    */
     void send_bytes(uint8_t bytes[], int length);
     
+    /** Serial Port object. */
     Serial mSerial;
     
+    
+    // Callbacks
     hello_callback_t mHelloCallback;
     get_info_callback_t mGetInfoCallback;
     boot_callback_t mBootCallback;
--- a/api_datatypes.h	Tue May 19 05:01:10 2015 +0000
+++ b/api_datatypes.h	Tue May 19 05:49:00 2015 +0000
@@ -1,31 +1,39 @@
 #ifndef API_DATATYPES_H
 #define API_DATATYPES_H
+/** @file api_datatypes.h
+* @brief Data structures that the API uses for responses and commands. */
 
 /** Data structure returned from Get Info command. */
 typedef struct {
- uint16_t major; /// Major version (e.g. 1)
- uint16_t minor; /// Minor version (e.g. 3)
- uint16_t patch; /// Patch version (e.g. 2)
- uint16_t build; /// Build number (e.g. 122)
- uint16_t ll_version; /// Link Layer Version
- uint8_t protocol_version; /// BGAPI Version
- uint8_t hw; /// Hardware Version
+ uint16_t major; ///< Major version (e.g. 1)
+ uint16_t minor; ///< Minor version (e.g. 3)
+ uint16_t patch; ///< Patch version (e.g. 2)
+ uint16_t build; ///< Build number (e.g. 122)
+ uint16_t ll_version; ///< Link Layer Version
+ uint8_t protocol_version; ///< BGAPI Version
+ uint8_t hw; ///< Hardware Version
 } ble_msg_system_get_info_rsp_t;
 
 
 /** Data structure passed into the Reset command. */
 typedef struct {
-    uint8_t boot_in_dfu; /// Determine whether or not to boot into Device Firmware Update (DFU) mode. 1 for booting into DFU, 0 otherwise.
+    uint8_t boot_in_dfu; ///< Determine whether or not to boot into Device Firmware Update (DFU) mode. 1 for booting into DFU, 0 otherwise.
 } ble_msg_system_reset_t;
 
+/** Data structure returned from Boot event. */
 typedef struct {
- uint16_t major; 
- uint16_t minor; 
- uint16_t patch;
- uint16_t build;
- uint16_t ll_version;
- uint8_t protocol_version;
- uint8_t hw;
+ uint16_t major; ///< Major version (e.g. 1)
+ uint16_t minor; ///< Minor version (e.g. 3)
+ uint16_t patch; ///< Patch version (e.g. 2)
+ uint16_t build; ///< Build number (e.g. 122)
+ uint16_t ll_version; ///< Link Layer Version
+ uint8_t protocol_version; ///< BGAPI Version
+ uint8_t hw; ///< Hardware Version
 } ble_msg_system_boot_evt_t;
 
+/** Data structure returned from Discover command. */
+typedef struct {
+    uint16_t result; ///< Result. Non-zero value indicates an error.
+} ble_msg_gap_discover_rsp_t;
+
 #endif
\ No newline at end of file
--- a/callbacks.h	Tue May 19 05:01:10 2015 +0000
+++ b/callbacks.h	Tue May 19 05:49:00 2015 +0000
@@ -2,18 +2,33 @@
 #ifndef CALLBACKS_H
 #define CALLBACKS_H
 
-/** @brief Function pointer for Hello response. 
+/** @file callbacks.h 
+* @brief Definitions of function callbacks that BGLib will invoke.
+* In order to take advantage of these callbacks, use the corresponding setter in the BGLib API.
+*/
+
+/** @brief Function pointer for Hello response handler. 
 * This is a pointer to a callback for the Hello response. It should point to a function that takes no arguments.
 */
 typedef void (*hello_callback_t)();
 
-/** Function pointer for Get Info response. */
+/** Function pointer for Get Info response handler. 
+* @param ble_msg_system_get_info_rsp_t A data structure containing the response. 
+*/
 typedef void (*get_info_callback_t)(ble_msg_system_get_info_rsp_t);
 
-/** Function pointer for System Boot. */
+/** Function pointer for System Boot event handler. 
+* @param ble_msg_system_boot_evt_t A data structure containing the data from the System Boot event.
+*/
 typedef void (*boot_callback_t)(ble_msg_system_boot_evt_t);
 
-/** Function pointer for timestamping */
+/** Function pointer for timestamping. This is a function that is intended to run whenever there is <em>any</em> data available on the UART.
+*/
 typedef void (*timestamp_callback_t)();
 
+/** Function pointer for Discover response handler.
+* @param ble_msg_gap_discover_rsp_t A data structure containing the response.
+*/
+typedef void (*discover_callback_t)(ble_msg_gap_discover_rsp_t);
+
 #endif
\ No newline at end of file