Cronocide/ESP32-ANCS-Notifications
1
0
Fork 0
mirror of https://github.com/Smartphone-Companions/ESP32-ANCS-Notifications.git synced 2025-01-22 11:28:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improved documentation.

Browse Source
This commit is contained in:
James Hudson 2019-12-28 11:06:19 +11:00
parent 40189e5a15
commit 4de50f84ce
3 changed files with 114 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
README.md
View File

@ -29,9 +29,28 @@ Then you should see the examples and be able to include the library in your proj
## Usage
See the ble_connection example.
This works like a standard Arduino library. Here's a minimal example:
Also, for a real-world example, the project https://github.com/jhud/hackwatch uses this library.
```
// Create an interface to the BLE notification library at the top of your sketch
BLENotifications notifications;
// Start looking for a device connection
notifications.begin("BLEConnection device name");
// Setup a callback for when a notification arrives
void onNotificationArrived(const Notification * notification) {
Serial.println(notification->title.c_str());
}
// Register the callback to be informed when a notification arrives
notifications.setConnectionStateChangedCallback(onBLEStateChanged);
notifications.setNotificationCallback(onNotificationArrived);
```
See the ble_connection example for a more fully-featured example.
To see a real-world project, https://github.com/jhud/hackwatch uses this library.
## History / Acknowledgements

70
examples/ble_connection/ble_connection.ino
View File

@ -23,10 +23,14 @@
#error Hardware buttons not supported!
#endif
// Create an interface to the BLE notification functionality
//////////
// Example code begins
// Create an interface to the BLE notification library
BLENotifications notifications;
// The incoming call's ID number, or zero if no notification
// Holds the incoming call's ID number, or zero if no notification
uint32_t incomingCallNotificationUUID;
// This callback will be called when a Bluetooth LE connection is made or broken.
@ -39,10 +43,10 @@ void onBLEStateChanged(BLENotifications::State state) {
case BLENotifications::StateDisconnected:
Serial.println("StateDisconnected - disconnected from a phone or tablet");
/* We need to startAdvertising on disconnection, otherwise the ESP 32 will now be invisible.
IMO it would make sense to put this in the library to happen automatically, but some people in the Espressif forums
were requesting that they would like manual control over re-advertising.*/
notifications.startAdvertising();
/* We need to startAdvertising on disconnection, otherwise the ESP 32 will now be invisible.
IMO it would make sense to put this in the library to happen automatically, but some people in the Espressif forums
were requesting that they would like manual control over re-advertising.*/
notifications.startAdvertising();
break;
}
}
@ -50,25 +54,25 @@ void onBLEStateChanged(BLENotifications::State state) {
// A notification arrived from the mobile device, ie a social media notification or incoming call.
void onNotificationArrived(const Notification * notification) {
Serial.print("Got notification: ");
Serial.println(notification->title.c_str());
Serial.println(notification->message.c_str());
Serial.println(notification->type.c_str());
Serial.println(notifications.getNotificationCategoryDescription(notification->category));
Serial.println(notification->categoryCount);
if (notification->category == CategoryIDIncomingCall) {
incomingCallNotificationUUID = notification->uuid;
Serial.println("--- INCOMING CALL: PRESS A TO ACCEPT, C TO REJECT ---");
}
else {
incomingCallNotificationUUID = 0; // Make invalid - no incoming call
}
Serial.print("Got notification: ");
Serial.println(notification->title.c_str()); // The title, ie name of who sent the message
Serial.println(notification->message.c_str()); // The detail, ie "be home for dinner at 7".
Serial.println(notification->type.c_str()); // Which app sent it
Serial.println(notifications.getNotificationCategoryDescription(notification->category)); // ie "social media"
Serial.println(notification->categoryCount); // How may other notifications are there from this app (ie badge number)
if (notification->category == CategoryIDIncomingCall) {
// If this is an incoming call, store it so that we can later send a user action.
incomingCallNotificationUUID = notification->uuid;
Serial.println("--- INCOMING CALL: PRESS A TO ACCEPT, C TO REJECT ---");
}
else {
incomingCallNotificationUUID = 0; // Make invalid - no incoming call
}
}
// A notification was cleared
void onNotificationRemoved(const Notification * notification) {
Serial.print("Removed notification: ");
Serial.println(notification->title.c_str());
Serial.println(notification->message.c_str());
@ -100,21 +104,17 @@ void setup() {
}
void checkButtons() {
if (digitalRead(BUTTON_A) == LOW) {
Serial.println("Positive action.");
notifications.actionPositive(incomingCallNotificationUUID);
}
else if (digitalRead(BUTTON_C) == LOW) {
Serial.println("Negative action.");
notifications.actionNegative(incomingCallNotificationUUID);
}
}
// Standard Arduino function that is called in an endless loop after setup
void loop() {
void loop() {
if (incomingCallNotificationUUID > 0) {
checkButtons();
// Check to see if the user has pressed an action button
if (digitalRead(BUTTON_A) == LOW) {
Serial.println("Positive action.");
notifications.actionPositive(incomingCallNotificationUUID);
}
else if (digitalRead(BUTTON_C) == LOW) {
Serial.println("Negative action.");
notifications.actionNegative(incomingCallNotificationUUID);
}
}
}

109
src/esp32notifications.h
View File

@ -13,69 +13,76 @@
*/
class BLENotifications {
public:
/**
* State of the BLE connection.
*/
enum State {
StateConnected, /**< A device connected to the ESP32. */
StateDisconnected /**< A device disconnected from the ESP32. Note that you should call startAdvertising after this message.*/
};
/**
* Callback for a state change of the BLE connection.
* Use this to modify the UI to notify the user if a connection is available.
*/
/**
* State of the BLE connection.
*/
enum State {
StateConnected, /**< A device connected to the ESP32. */
StateDisconnected /**< A device disconnected from the ESP32. Note that you should call startAdvertising after this message.*/
};
/**
* Callback for a state change of the BLE connection.
* Use this to modify the UI to notify the user if a connection is available.
*/
typedef void (*ble_notifications_state_changed_t)(State state);
public:
BLENotifications();
/**
* Setup the device to receive BLE notifications.
* Will also automatically start advertising.
* @param name the device name, as it will appear in a BLE scan.
*/
/**
* Setup the device to receive BLE notifications.
* Will also automatically start advertising.
* @param name the device name, as it will appear in a BLE scan.
*/
bool begin(const char * name);
/**
* Make this device visible in scans as available for connection.
* Will stop the current advertisement if it is running.
*/
void startAdvertising();
/**
* Shutdown BLE and free memory.
* Note that currently the BLE library internals do not seem to restore state properly, so the BLE library
* cannot be used after a stop.
*
*/
bool stop();
/**
* Make this device visible in scans as available for connection.
* Will stop the current advertisement if it is running.
*/
void startAdvertising();
/**
* Shutdown BLE and free memory.
* Note that currently the BLE library internals do not seem to restore state properly, so the BLE library
* cannot be used after a stop.
*
*/
bool stop();
/**
* Set this to a callback for when the BLE connects or disconnects.
*/
void setConnectionStateChangedCallback(ble_notifications_state_changed_t);
/**
* Set this to a callback for when a notification arrives.
*/
void setNotificationCallback(ble_notification_arrived_t);
void setRemovedCallback(ble_notification_removed_t);
void setRemovedCallback(ble_notification_removed_t);
void actionPositive(uint32_t uuid);
void actionNegative(uint32_t uuid);
/**
* Given a category, return a description of the category in English
*/
const char * getNotificationCategoryDescription(NotificationCategory category) const;
/**
* Given a category, return a description of the category in English
*/
const char * getNotificationCategoryDescription(NotificationCategory category) const;
private:
ble_notifications_state_changed_t cbStateChanged;
ble_notification_arrived_t cbNotification;
ble_notification_removed_t cbRemoved;
class BLEServer* server;
class ANCSBLEClient* client;
bool isAdvertising;
friend class MyServerCallbacks; //Allow internal handlers to access the callbacks of the main class
private:
ble_notifications_state_changed_t cbStateChanged;
ble_notification_arrived_t cbNotification;
ble_notification_removed_t cbRemoved;
class BLEServer* server;
class ANCSBLEClient* client;
bool isAdvertising;
friend class MyServerCallbacks; //Allow internal handlers to access the callbacks of the main class
};
#endif // ESP32NOTIFICATIONS_H_