Merge pull request #18 from seanngpack/macos

Template support, better logging, bug fixes, better documentation

Author: seanngpack

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "external/googletest"]
+	path = external/googletest
+	url = https://github.com/google/googletest.git

.travis.yml

@@ -5,6 +5,7 @@ branches:
     - gh-pages
     - master
     - macos
+    - logging-support
 
 matrix:
   include:

CMakeLists.txt

@@ -2,7 +2,7 @@ cmake_minimum_required(VERSION 3.17)
 set(CMAKE_CXX_STANDARD 17)
 
 project(feeling-blue
-        VERSION 1.0
+        VERSION 1.02
         DESCRIPTION "mylib description")
 
 include(GNUInstallDirs)
@@ -18,6 +18,11 @@ option(BUILD_DOCUMENTATION "Create the API documentation" OFF)
 option(BUILD_TESTS "Build the tests" OFF)
 option(VERBOSE_MODE "NSLog what your bluetooth device is doing" ON)
 
+# --------------------------------------------------------------------------------
+#                          Include directories
+# --------------------------------------------------------------------------------
+
+include_directories(${PROJECT_SOURCE_DIR}/include)
 
 # --------------------------------------------------------------------------------
 #                          Public headers API
@@ -31,16 +36,9 @@ set(macOS_PUBLIC_HEADERS
         )
 
 set(macOS_PRIVATE_HEADERS
-
+        ./include/detail/conversions.h
         )
 
-# --------------------------------------------------------------------------------
-#                          Enable Testing
-# --------------------------------------------------------------------------------
-
-include(CTest)
-enable_testing()
-
 
 # --------------------------------------------------------------------------------
 #                          Subdirectories
@@ -49,8 +47,10 @@ enable_testing()
 add_subdirectory(macOS)
 
 if (BUILD_TESTS)
+    include(CTest)
+    enable_testing()
     message("enabled building tests")
-    add_subdirectory(${PROJECT_SOURCE_DIR}/external/googletest-release-1.10.0)
+    add_subdirectory(${PROJECT_SOURCE_DIR}/external/googletest)
     add_subdirectory(test)
 endif()
 

README.md

@@ -88,10 +88,10 @@ int main() {
 
     current_temp_char->set_notify(print_temp); // will call print_temp() whenever device notifies
     
-    std::string units = units_char.read_string();
+    std::string units = units_char.read<std::string>();
     std::cout << "the current temperature unit is: " << units << std::endl
-    units_char->write_without_response("kelvin");
-    units = units_char.read_string();
+    units_char->write_without_response<std::string>("kelvin"); // set new temperature unit to device
+    units = units_char->read<std::string>();
     std::cout << "the new temperature unit is: " << units << std::endl
 
     while (true) {
@@ -107,7 +107,6 @@ int main() {
 
 ## Upcoming features:
 - methods to get status of peripherals, characteristics, etc
-- better error logging
 - Windows support
 
 ## Help & bug reports

docs/demo/demo.rst

@@ -148,61 +148,57 @@ Reading characteristic value
 ============================
 
 Let's get some data! To read the value of your characteristic, call the ``read()`` method. This method blocks
-the calling thread until the data has been read from your characteristic and assigned to your variable.
+the calling thread until the data has been read from your characteristic and assigned to your variable. The read method
+is templated and supports multiple types described in the :ref:`supported-template-types`.
 
 .. code:: c++
 
-    std::vector<std::byte> data = characteristic->read();
+    std::vector<std::byte> data = characteristic->read<std::byte>();
 
-There are additional read methods available to convert the payload into human-readable datatypes. If your device is sending
-four bytes representing an integer, you can it directly as an integer instead of doing the conversion yourself:
+If you want something more human-readable, and you know your device's characteristic is represented in four bytes in
+little-endian order, you just just read your data as an integer:
 
 .. code:: c++
 
-    int data = characteristic->read_int();
-
+    int data = characteristic->read<int>();
 
+By default, you should read in your data into ``std::vector<std::byte>`` unless you know for sure your device is outputting
+convertible types.
 
 
 Writing to characteristic
 =========================
 
 There are two main options to write to your device. First we can ``write_without_response()`` which writes to your
 devices asynchronously and does not block your calling thread. If your write fails, you will not get a message
-telling you that it failed. You must provide this method the data as a ``std::vector<std::byte>``
+telling you that it failed. This method is templated and supports multiple types described in the :ref:`supported-template-types`.
 
 .. code:: c++
 
-    characteristic->write_without_response(data);
+    std::vector<std::byte> data = {...};
+    characteristic->write_without_response<std::byte>(data);
 
 
 And if you write with a response, then the method will block your calling thread and wait until your data has been
 successfully written to the device.
 
 .. code:: c++
 
-    rotate_char->write_with_response(data);
-
-There are convenience overloaded methods to write to your device if you'd rather send a human-readable datatype rather
-than a vector of bytes. If you use these convenience methods, just make on the other end, your device is configured to handle
-this information. These convenience methods assume little-endian ordering of bytes.
-
-.. code:: c++
+    std::vector<std::byte> data = {...};
+    rotate_char->write_with_response<std::byte>(data);
 
-    std::string data = "Celcius";
-    switch_units_char->write_with_response(data);
+Like the read() method, you can write to your device using different formats that will end up being converted to byte arrays.
 
 
 Notifying characteristic
 ========================
 
-
 If your device and characteristic supports notifications, then let's use it. First, just double check that your characteristic
 has notification support and that it's enabled. So now when your device sends your computer notifications with a data payload you can capture
 that payload and write your own function to do something with it!
 
 Non-member function event handler
-----------------------------
+---------------------------------
 
 Let's write a callback event handler that takes in a ``std::vector<std::byte>`` and enable notifications, passing the function as a parameter.
 
@@ -220,7 +216,7 @@ IMPORTANT! All event handlers must follow this signature: ``void (std::vector<st
 
 
 Member function event handler
-------------------------
+-----------------------------
 
 member functions are a little trickier to write, but you just have to bind their class to std::function
 and add a placeholder parameter, then pass it like normal.
@@ -248,4 +244,12 @@ and add a placeholder parameter, then pass it like normal.
 Passing member functions is really powerful because you can do things such as update an instance variable when notified.
 
 If you're passing the same function to multiple characteristic notifications, then just make sure your function contents are
-thread-safe, this applies to both member and non-member functions.
+thread-safe, this applies to both member and non-member functions.
+
+.. _supported-template-types:
+
+.. include:: ../template_types.rst
+
+
+
+

docs/index.rst

@@ -23,8 +23,8 @@
     :maxdepth: 4
     :hidden:
 
-    API/API
     API/central
     API/peripheral
     API/service
-    API/characteristic
+    API/characteristic
+    template_types

docs/template_types.rst

@@ -0,0 +1,14 @@
+Supported Template Types
+========================
+
+Primitive:
+
+- uint8_t
+- int
+- float
+- double
+
+Non Primitive:
+
+- std::string
+- std::vector<std::byte>

examples/arduino_temperature_device.ino

@@ -13,16 +13,14 @@ const char * battery_level_uuid = "19B10001-E8F2-537E-4F6C-D104768A1214";
 const char * temp_units_uuid = "19B10002-E8F2-537E-4F6C-D104768A1214";
 const char * current_temp_uuid = "19B10003-E8F2-537E-4F6C-D104768A1214";
 // create battery characteristic that relays current battery level
-BLECharacteristic battery_level_char(battery_level_uuid, BLERead, 20u);
+BLECharacteristic battery_level_char(battery_level_uuid, BLERead | BLENotify, 20u);
 // create String type characteristic that sets the units of the temperature. Can read or write.
 // This characteristic converts byte data to string. We're using this to demonstrate that you don't have to always
 // deal in bytes with the ArduinoBLE library.
 BLEStringCharacteristic temp_units_char(temp_units_uuid, BLERead | BLEWrite, 20u);
 // create temperature characteristic that has notifications enabled
 BLECharacteristic current_temp_char(current_temp_uuid, BLERead | BLENotify, 20u);
 
-char* default_unit = "fahrenh";
-
 // how often the current_temp_char will update
 const unsigned long interval = 1000; // in ms
 unsigned long start_time;
@@ -59,8 +57,13 @@ void setup() {
     temp_units_char.setEventHandler(BLERead, tempCharacteristicRead);
 
     // set an initial value for characteristics
-    battery_level_char.setValue((char*)int_to_bytes(100));
-    Serial.println(battery_level_char.valueLength());
+    uint8_t batt_value[4];
+    int_to_bytes(100, batt_value);
+    battery_level_char.writeValue(batt_value, 4);
+    Serial.println(battery_level_char.value()[0]);
+    Serial.println(battery_level_char.value()[1]);
+    Serial.println(battery_level_char.value()[2]);
+    Serial.println(battery_level_char.value()[3]);
     temp_units_char.setValue("fahrenheit");
     current_temp_char.setValue(0);
 
@@ -94,8 +97,10 @@ void updateTemp(BLECharacteristic characteristic) {
         currentTemp = currentTempF;
     }
 
+    uint8_t temp_array[4];
+    float_to_bytes(currentTemp, temp_array);
     // this should trigger a notify
-    characteristic.writeValue(float_to_bytes(currentTemp), sizeof(float));
+    characteristic.writeValue(temp_array, sizeof(float));
 }
 
 /*******************
@@ -139,22 +144,31 @@ void tempCharacteristicRead(BLEDevice central, BLECharacteristic characteristic)
  *
  *******************/
 
-uint8_t *float_to_bytes(float f) {
-    uint8_t *swag = reinterpret_cast<uint8_t*>(&f);;
-    return swag;
+
+/**
+ * Convert 4-byte float to array of uint8_t. Caller manages array memory.
+ */
+uint8_t *float_to_bytes(float f, uint8_t array[]) {
+    uint8_t *temp = reinterpret_cast<uint8_t*>(&f);
+    array[0] = temp[0];
+    array[1] = temp[1];
+    array[2] = temp[2];
+    array[3] = temp[3];
+    return array;
 }
 
+
 float bytes_to_float(const uint8_t* bytes) {
     float f;
     memcpy(&f, bytes, sizeof(f));
     return f;
 }
 
-const uint8_t *int_to_bytes(int data) {
-    uint8_t *byte_vector;
-    byte_vector[0] = data & 0xff;
-    byte_vector[1] = (data>> 8) & 0xff;
-    byte_vector[2] = (data>> 16) & 0xff;
-    byte_vector[3] = (data>> 24) & 0xff;
-    return byte_vector;
-}
+// Convert 4 byte long to bytes. Caller manages array memory.
+uint8_t* int_to_bytes(long data, uint8_t array[]) {
+    array[3] = data & 0xff;
+    array[2] = (data>> 8) & 0xff;
+    array[1] = (data>> 16) & 0xff;
+    array[0] = (data>> 24) & 0xff;
+    return array;
+}

examples/temperature_device.cpp

@@ -59,22 +59,22 @@ int main() {
     current_temp_char->notify(print_data);
 
     // or read it without waiting for updates
-    std::cout << "the current temperature is: " << current_temp_char->read_float() << std::endl;
+    std::cout << "the current temperature is: " << current_temp_char->read<float>() << std::endl;
 
     // read the battery level
-    std::vector<std::byte> a = battery_level_char->read();
+    std::vector<std::byte> a = battery_level_char->read<std::vector<std::byte>>();
     std::cout << "printing bytes of battery" <<std::endl;
     for (auto &x: a) {
         std::cout << " " << (int)x;
     }
     std::cout << std::endl;
-    std::cout << "the battery level is: " << battery_level_char->read_int() << std::endl;
+    std::cout << "the battery level is: " << battery_level_char->read<int>() << std::endl;
 
     // current value is "fahrenheit"
-    std::string unit = temp_units_char->read_string();
+    std::string unit = temp_units_char->read<std::string>();
     std::cout << "the current unit is: " << unit << std::endl;
     // write to the characteristic to change units.
-    temp_units_char->write_with_response("celsius");
+    temp_units_char->write_with_response<std::string>("celsius");
 
 
     using namespace std::chrono_literals;

examples/temperature_device_class.cpp

@@ -61,15 +61,15 @@ class SomeClass {
     }
 
     int read_temp() {
-        return current_temp_char->read_int();
+        return current_temp_char->read<int>();
     }
 
     void set_temp_units(const std::string &units) {
-        temp_units_char->write_with_response(units);
+        temp_units_char->write_with_response<std::string>(units);
     }
 
     std::string get_temp_units() {
-        return temp_units_char->read_string();
+        return temp_units_char->read<std::string>();
     }