Basic documentation structure.

README.rst

@@ -1,67 +1,11 @@
 SimpleBLE
 ==========
 
-The ultimate fully-fledged cross-platform library for Bluetooth Low Energy (BLE).
+The ultimate fully-fledged cross-platform library and bindings for Bluetooth Low Energy (BLE).
 
 |Latest Documentation Status|
 
-Overview
---------
-
-SimpleBLE is a C++ fully cross-platform BLE library designed for simplicity
-and ease of use. All specific operating system quirks are handled to provide
-a consistent behavior across all platforms. Each major version of the library
-will have a stable API that will be fully forwards compatible. 
-
-If you want to use SimpleBLE and need help. **Please do not hesitate to reach out!**
-
-* Visit our `ReadTheDocs`_ page. 
-* Join our `Discord`_ server.
-* Contact me: ``kevin at dewald dot me``
-
-Are you using SimpleBLE on your own project? Reach out and I'll add a link to it below!
-
-Supported platforms
--------------------
-=========== ============= =================================== =====
-Windows     Linux         MacOS                               iOS
-=========== ============= =================================== =====
-Windows 10+ Ubuntu 20.04+ 10.15+ (except 12.0, 12.1 and 12.2) 15.0+
-=========== ============= =================================== =====
-
-Vendorization
--------------
-If you are interested in using SimpleBLE as a dependency in your project,
-there is currently first-class support for vendorization of all 3rd-party
-dependencies. Currently, the following libraries are included as part of
-SimpleBLE:
-
-* `fmtlib`_
-* `SimpleBluez`_
-* `SimpleDBus`_
-
-Please visit our **Security** page for more information on how to vendorize
-3rd-party libraries for SimpleBLE.
-
-License
--------
-
-All components within this project that have not been bundled from
-external creators, are licensed under the terms of the `MIT Licence`_.
-
-.. Links
-
-.. _MIT Licence: LICENCE.md
-
-.. _fmtlib: https://github.com/fmtlib/fmt
-
-.. _Discord: https://discord.gg/N9HqNEcvP3
-
-.. _ReadTheDocs: https://simpleble.readthedocs.io/en/latest/
-
-.. _SimpleBluez: https://github.com/OpenBluetoothToolbox/SimpleBluez
-
-.. _SimpleDBus: https://github.com/OpenBluetoothToolbox/SimpleDBus
+.. include:: docs/overview.rst
 
 .. |Latest Documentation Status| image:: https://readthedocs.org/projects/simpleble/badge?version=latest
-   :target: http://simpleble.readthedocs.org/en/latest
+   :target: http://simpleble.readthedocs.org/en/latest

cmake/find/Findfmt.cmake

@@ -3,7 +3,7 @@
 
 include(FetchContent)
 
-if (LIBFMT_VENDORIZE)
+if(LIBFMT_VENDORIZE)
 
     # Load default parameters passed in through the command line.
     if(NOT LIBFMT_GIT_REPOSITORY)
@@ -33,4 +33,6 @@ if (LIBFMT_VENDORIZE)
     # https://cmake.org/cmake/help/latest/manual/cmake-developer.7.html
     set(fmt_FOUND 1)
 
+else()
+    find_package(fmt CONFIG REQUIRED)
 endif()

cmake/find/Findsimplebluez.cmake

@@ -1,45 +0,0 @@
-include(FetchContent)
-
-if (SIMPLEBLUEZ_VENDORIZE)
-
-    # Load default parameters passed in through the command line.
-    if(NOT SIMPLEBLUEZ_GIT_REPOSITORY)
-        set(SIMPLEBLUEZ_GIT_REPOSITORY "https://github.com/OpenBluetoothToolbox/SimpleBluez.git")
-    endif()
-    if(NOT SIMPLEBLUEZ_GIT_TAG)
-        set(SIMPLEBLUEZ_GIT_TAG "feature/next")
-    endif()
-
-    if(NOT SIMPLEBLUEZ_LOCAL_PATH)
-        FetchContent_Declare(
-            simplebluez
-            GIT_REPOSITORY ${SIMPLEBLUEZ_GIT_REPOSITORY}
-            GIT_TAG ${SIMPLEBLUEZ_GIT_TAG}
-            GIT_SHALLOW YES
-        )
-
-        # Note that here we manually do what FetchContent_MakeAvailable() would do,
-        # except to ensure that the dependency can also get what it needs, we add
-        # custom logic between the FetchContent_Populate() and add_subdirectory()
-        # calls.
-        FetchContent_GetProperties(simplebluez)
-        if(NOT simplebluez_POPULATED)
-            FetchContent_Populate(simplebluez)
-            list(APPEND CMAKE_MODULE_PATH "${simplebluez_SOURCE_DIR}/cmake/find")
-            add_subdirectory("${simplebluez_SOURCE_DIR}" "${simplebluez_BINARY_DIR}")
-        endif()
-
-    else()
-        list(APPEND CMAKE_MODULE_PATH "${SIMPLEBLUEZ_LOCAL_PATH}/cmake/find")
-        add_subdirectory(${SIMPLEBLUEZ_LOCAL_PATH} ${CMAKE_CURRENT_BINARY_DIR}/simplebluez)
-    endif()
-
-    # Because we are in a find module, we are solely responsible for resolution.
-    # Setting this *_FOUND variable to a truthy value will signal to the calling
-    # find_package() command that we were successful.
-    # More relevant info regarding find modules and what variables they use can be
-    # found in the documentation of find_package() and
-    # https://cmake.org/cmake/help/latest/manual/cmake-developer.7.html
-    set(simplebluez_FOUND 1)
-
-endif()

docs/index.rst

@@ -1,15 +1,44 @@
 .. include:: ../README.rst
+.. include:: overview.rst
+
+.. toctree::
+   :maxdepth: 1
+   :caption: General
+
+   overview
 
 .. toctree::
    :maxdepth: 2
-   :caption: The Basics
+   :caption: SimpleBLE
 
-   installation
-   usage
-   architecture
-   security
-   changelog
+   simpleble/usage
+   simpleble/architecture
+   simpleble/installation
+   simpleble/security
+   simpleble/changelog
 
+.. toctree::
+   :maxdepth: 2
+   :caption: SimplePyBLE
+
+   simplepyble/usage
+
+.. toctree::
+   :maxdepth: 2
+   :caption: SimpleBluez
+
+   simplebluez/usage
+   simplebluez/installation
+   simplebluez/security
+   simplebluez/changelog
+
+.. toctree::
+   :maxdepth: 2
+   :caption: SimpleDBus
+
+   simpledbus/usage
+   simpledbus/api
+   simpledbus/changelog
 
 Indices and tables
 ==================

docs/overview.rst

@@ -0,0 +1,57 @@
+Overview
+--------
+
+The SimpleBLE project aims to provide fully cross-platform BLE libraries and bindings
+for Python and C++, designed for simplicity and ease of use with a licencing scheme
+chosen to be friendly towards commercial use. All specific operating system quirks
+are handled internally to provide a consistent behavior across all platforms. The
+libraries also provide first-class support for vendorization of all third-party
+dependencies, allowing for easy integration into existing projects.
+
+This repository offers the source code for the following related libraries:
+
+* **SimpleBLE:** C++ cross-platform BLE library.
+* **SimplePyBLE:** Python bindings for SimpleBLE. See `SimplePyBLE`_ PyPI page for more details.
+* **SimpleBluez:** C++ abstraction layer for BlueZ over DBus. (Linux only)
+* **SimpleDBus:** C++ wrapper for libdbus-1 with convenience classes to handle DBus object hierarchies effectively. (Linux only)
+
+If you want to use SimpleBLE and need help. **Please do not hesitate to reach out!**
+
+* Visit our `ReadTheDocs`_ page.
+* Join our `Discord`_ server.
+* Contact me: ``kevin at dewald dot me``
+
+Are you using SimpleBLE on your own project and would like to see it featured here?
+Reach out and I'll add a link to it below!
+
+Supported platforms
+-------------------
+=========== ============= =================================== =====
+Windows     Linux         MacOS                               iOS
+=========== ============= =================================== =====
+Windows 10+ Ubuntu 20.04+ 10.15+ (except 12.0, 12.1 and 12.2) 15.0+
+=========== ============= =================================== =====
+
+Contributing
+------------
+Pull requests are welcome. For major changes, please open an issue first to discuss
+what you would like to change.
+
+License
+-------
+
+All components within this project that have not been bundled from
+external creators, are licensed under the terms of the `MIT Licence`_.
+
+.. Links
+
+.. _SimplePyBLE: https://pypi.org/project/simplepyble/
+
+.. _MIT Licence: https://github.com/OpenBluetoothToolbox/SimpleBLE/blob/main/LICENCE.md
+
+.. _fmtlib: https://github.com/fmtlib/fmt
+
+.. _Discord: https://discord.gg/N9HqNEcvP3
+
+.. _ReadTheDocs: https://simpleble.readthedocs.io/en/latest/
+

docs/simpleble/usage.rst

@@ -1,3 +1,7 @@
+=================
+SimpleBLE Usage
+=================
+
 Usage
 =====
 

docs/simplebluez/changelog.rst

@@ -0,0 +1,126 @@
+Changelog
+=========
+
+All notable changes to this project will be documented in this file.
+
+The format is based on `Keep a Changelog`_, and this project adheres to
+`Semantic Versioning`_.
+
+[0.6.0] - 2022-XX-XX
+--------------------
+
+**Important:** From this version onwards, the CMake target that should be consumed
+               by downstream projects is ``simplebluez::simplebluez``.
+
+**Added**
+
+-  Support for characteristic descriptors. *(Thanks Symbitic!)*
+
+**Changed**
+
+-  Selection of build type is now based on the  ``BUILD_SHARED_LIBS`` setting.
+-  Consumable CMake target is now ``simplebluez::simplebluez``.
+
+**Removed**
+
+-  CMake target ``simplebluez-static`` was removed in favour of ``BUILD_SHARED_LIBS``.
+
+**Fixed**
+-  Accessing the ``Paired`` property of ``Device1`` would only use the cached value.
+-  Using the correct CMake functionality to export headers for all targets.
+
+
+[0.5.0] - 2022-06-12
+--------------------
+
+**Added**
+
+-  Log forwarding based on ``logfwd``.
+
+**Changed**
+
+-  Updated libfmt to version 8.1.1.
+-  Cleaned up dependency management for libfmt and SimpleDBus.
+
+
+[0.4.0] - 2022-04-07
+--------------------
+
+**Added**
+
+-  ``RSSI`` property to ``Device`` class.
+-  Adapters can now return a list of all paired devices.
+
+
+[0.3.1] - 2022-04-02
+--------------------
+
+**Changed**
+
+-  By default, all pairing options will succeed.
+
+
+[0.3.0] - 2022-03-25
+--------------------
+
+**Added**
+
+-  ``Agent`` and ``AgentManager`` classes to handle pairing.
+-  Pair and Notify examples.
+
+**Changed**
+
+-  Migrated to using safe callbacks from external vendor (kvn::safe_callback).
+
+
+[0.2.1] - 2022-02-13
+--------------------
+
+**Changed**
+
+-  Minor renaming of function for style consistency.
+
+
+[0.2.0] - 2022-02-12
+--------------------
+
+**Added**
+
+-  Support for the ``Battery1`` interface. *(Thanks ptenbrock!)*
+
+
+[0.1.1] - 2021-12-28
+--------------------
+
+**Added**
+
+-  Function to access currently cached value from characteristics.
+-  ``Notifying`` property on ``Characteristic1``.
+-  Added ``OnDisconnected`` callback to ``Device1``.
+-  Added ``ServicesResolved`` callback to ``Device1``.
+-  Address and Thread sanitization options.
+
+**Changed**
+
+-  All proxy and interface manipulation is now done through helper functions.
+-  Access to all interface properties is now thread-safe.
+
+**Fixed**
+
+-  Removed unnecessary ``<iostream>`` includes.
+-  Made sure all classes have proper virtual destructors.
+
+
+[0.1.0] - 2021-12-14
+--------------------
+
+Reimplementation of the library based on the SimpleDBus v2.0.0-alpha.2 API.
+
+
+[0.0.1] - 2021-11-09
+--------------------
+
+First working implementation post migration, following the SimpleDBus v2.0.0-alpha API.
+
+.. _Keep a Changelog: https://keepachangelog.com/en/1.0.0/
+.. _Semantic Versioning: https://semver.org/spec/v2.0.0.html

docs/simplebluez/installation.rst

@@ -0,0 +1,60 @@
+Installation
+------------
+
+SimpleBluez should work on any Linux environment. Make sure you have the
+necesary dependencies from SimpleDBus installed.
+
+A set of helper scripts are provided to simplify the process of building
+the library, but are not required.
+
+Standalone build from source
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+   cd <path-to-simplebluez>
+   mkdir build && cd build
+   cmake ..
+   make
+   sudo make install # Not available yet.
+
+Build as part of another project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you want to add SimpleDBus to your project without any external
+dependencies, just clone the repository and link to it on your
+``CMakeLists.txt`` file.
+
+::
+
+   add_subdirectory(<path-to-simplebluez> ${CMAKE_BINARY_DIR}/simplebluez)
+
+Build examples
+~~~~~~~~~~~~~~
+
+::
+
+   cd <path-to-simplebluez>
+   mkdir build && cd build
+   cmake ../examples
+   make
+
+Build tests
+~~~~~~~~~~~
+
+To build and run unit and integration tests, the following packages are
+required: ``sudo apt install libgtest-dev libgmock-dev python3-dev``
+
+Address Sanitizer
+^^^^^^^^^^^^^^^^^
+
+In order to run tests with Address Sanitizer, CMake needs to be called
+with the following option: ``-DSIMPLEBLUEZ_SANITIZE=Address``. It is also
+important to set the environment variable ``PYTHONMALLOC=malloc`` to
+prevent Python's memory allocator from triggering false positives.
+
+Thread Sanitizer
+^^^^^^^^^^^^^^^^
+
+In order to run tests with Thread Sanitizer, CMake needs to be called
+with the following option: ``-DSIMPLEBLUEZ_SANITIZE=Thread``.

docs/simplebluez/security.rst

@@ -0,0 +1,37 @@
+Security
+========
+
+One key security feature of the library is it allows the user to specify
+the URLs and tags of all internal dependencies, thus allowing compilation
+from internal or secure sources without the risk of those getting compromised.
+
+Vendorization
+-------------
+Currently, the following libraries are included as part of SimpleBluez, with 
+the following CMake options available:
+
+* `fmtlib`_
+
+  * ``LIBFMT_VENDORIZE``: Enable vendorization of fmtlib. *(Default: True)*
+
+  * ``LIBFMT_GIT_REPOSITORY``: The git repository to use for fmtlib.
+
+  * ``LIBFMT_GIT_TAG``: The git tag to use for fmtlib. *(Default: v8.1.1)*
+
+  * ``LIBFMT_LOCAL_PATH``: The local path to use for fmtlib. *(Default: None)*
+
+* `SimpleDBus`_
+
+  * ``SIMPLEDBUS_VENDORIZE``: Enable vendorization of SimpleDBus. *(Default: True)*
+
+  * ``SIMPLEDBUS_GIT_REPOSITORY``: The git repository to use for SimpleDBus.
+
+  * ``SIMPLEDBUS_GIT_TAG``: The git tag to use for SimpleDBus. *(Default: 2.2.0)*
+
+  * ``SIMPLEDBUS_LOCAL_PATH``: The local path to use for SimpleDBus. *(Default: None)*
+
+.. Links
+
+.. _fmtlib: https://github.com/fmtlib/fmt
+
+.. _SimpleDBus: https://github.com/OpenBluetoothToolbox/SimpleDBus

docs/simplebluez/usage.rst

@@ -0,0 +1,8 @@
+Usage
+=====
+
+To learn how to use SimpleBluez, please refer to the `examples`_ provided
+in the repository. 
+
+.. _examples: https://github.com/OpenBluetoothToolbox/SimpleBluez/tree/main/examples
+

docs/simpledbus/api.rst

@@ -0,0 +1,39 @@
+=============
+API Reference
+=============
+
+Examples
+========
+
+To learn how to use SimpleDBus, please refer to the `examples`_ provided
+in the repository.
+
+
+Architecture
+============
+
+The following notes provide an overview of the architecture of some of
+the higher-level classes in the library, as to facilitate their
+understanding.
+
+Interface
+----------
+
+-  In order to simplify the routing of messages, all interfaces are
+   assumed to have properties, thus skipping the need to have a special
+   implementation of org.freedesktop.DBus.Properties.
+-  All properties are stored in the holder in which they came from. This
+   is not the most efficient way of handling properties, but it is the
+   one that minimizes the necessary code for children of the Interface
+   class.
+
+Proxy
+-----
+
+-  Messages for org.freedesktop.DBus.Properties are automatically
+   handled by the Proxy class.
+
+
+.. Links
+
+.. _examples: https://github.com/OpenBluetoothToolbox/SimpleDBus/tree/main/examples

docs/simpledbus/changelog.rst

@@ -0,0 +1,101 @@
+Changelog
+=========
+
+All notable changes to this project will be documented in this file.
+
+The format is based on `Keep a Changelog`_, and this project adheres to
+`Semantic Versioning`_.
+
+
+[2.3.0] - 2022-XX-XX
+--------------------
+
+**Important:** From this version onwards, the CMake target that should be consumed
+               by downstream projects is ``simpledbus::simpledbus``.
+
+**Added**
+
+-  Installation interface for the ``simpledbus`` library.
+
+**Changed**
+
+-  Selection of build type is now based on the  ``BUILD_SHARED_LIBS`` setting.
+-  Consumable CMake target is now ``simpledbus::simpledbus``.
+
+**Fixed**
+
+-  Using the correct CMake functionality to export headers for all targets.
+
+**Removed**
+
+-  CMake target ``simpledbus-static`` was removed in favour of ``BUILD_SHARED_LIBS``.
+-  The dependency of ``pkg-config`` for installation has been removed.
+
+
+[2.2.0] - 2022-06-12
+--------------------
+
+**Added**
+
+-  Log forwarding based on ``logfwd``.
+
+**Changed**
+
+-  Updated libfmt to version 8.1.1.
+-  Cleaned up dependency management for libfmt.
+-  Moved ``kvn::safe_callback`` into the ``simpledbus`` include directory.
+
+**Fixed**
+
+-  Made the manipulation of ``SimpleDBus::Connection`` thread-safe.
+
+
+[2.1.0] - 2022-03-25
+--------------------
+
+**Added**
+
+-  (Message) Enable the creation of response messages to method calls.
+-  (Message) Enable the creation of error messages.
+-  (Connection) Provide interface to query the unique name of the connection.
+-  (Proxy) Provide interface to directly append a child.
+
+**Changed**
+
+-  Migrated to using safe callbacks from external vendor (kvn::safe_callback).
+
+**Fixed**
+
+-  (Interface) Messages are now passed by reference.
+
+
+[2.0.0] - 2021-12-28
+--------------------
+
+**Added**
+
+-  Testing framework.
+-  Exceptions for error detection and handling.
+-  Proxy object to generalize path and message handling.
+-  Interface object with advanced features to generalize common
+   functionality.
+-  Generic callback class to generalize callback functionality.
+
+**Changed**
+
+-  Log levels use now a sane naming convention.
+-  Default logging level can be set during build time.
+-  Holders containing dictionaries can now support any generic key type.
+-  Message types are now part of the class and not a separate enum.
+
+**Removed**
+
+-  Legacy implementations of Property and Introspection.
+
+**Fixed**
+
+-  Interface access is now thread-safe.
+-  Proxy access is now thread-safe.
+
+.. _Keep a Changelog: https://keepachangelog.com/en/1.0.0/
+.. _Semantic Versioning: https://semver.org/spec/v2.0.0.html

docs/simpledbus/usage.rst

@@ -0,0 +1,195 @@
+================
+SimpleDBus Usage
+================
+
+SimpleDBus should work on any Linux environment supporting DBus. To install
+the necessary dependencies on Debian-based systems, use the following command: ::
+
+  sudo apt install libdbus-1-dev
+
+
+Building the Library (Source)
+=============================
+
+The included CMake build script can be used to build SimpleDBus.
+CMake is freely available for download from https://www.cmake.org/download/. ::
+
+   cd <path-to-simpledbus>
+   mkdir build && cd build
+   cmake .. -DSIMPLEDBUS_LOG_LEVEL=[VERBOSE|DEBUG|INFO|WARNING|ERROR|FATAL]
+   cmake --build . -j7
+
+To build a shared library set the ``BUILD_SHARED_LIBS`` CMake variable to ``TRUE`` ::
+
+  cmake -DBUILD_SHARED_LIBS=TRUE ...
+
+
+Installing the Library
+======================
+
+After building the library you can install it by running :command:`sudo make install`.
+
+
+Usage with CMake (Installed)
+============================
+
+Once SimpleDBus has been installed, it can be consumed from within CMake::
+
+   find_package(simpledbus REQUIRED CONFIG)
+   target_link_libraries(<your-target> simpledbus::simpledbus)
+
+
+Usage with CMake (Local)
+=============================
+
+You can add the ``simpledbus`` library directory into your project and include it in
+your ``CMakeLists.txt`` file ::
+
+   add_subdirectory(<path-to-simpledbus> ${CMAKE_BINARY_DIR}/simpledbus)
+   target_link_libraries(<your-target> simpledbus::simpledbus)
+
+
+Usage with CMake (Vendorized)
+=============================
+
+If you want to use a vendorized copy of SimpleDBus, you can do so by using FetchContent
+and specifying the location from where SimpleDBus should be consumed from. ::
+
+   include(FetchContent)
+   FetchContent_Declare(
+       simpledbus
+       GIT_REPOSITORY <simpledbus-git-repository>
+       GIT_TAG <simpledbus-git-tag>
+       GIT_SHALLOW YES
+   )
+
+   # Note that here we manually do what FetchContent_MakeAvailable() would do,
+   # except to ensure that the dependency can also get what it needs, we add
+   # custom logic between the FetchContent_Populate() and add_subdirectory()
+   # calls.
+   FetchContent_GetProperties(simpledbus)
+   if(NOT simpledbus_POPULATED)
+       FetchContent_Populate(simpledbus)
+       list(APPEND CMAKE_MODULE_PATH "${simpledbus_SOURCE_DIR}/cmake/find")
+       add_subdirectory("${simpledbus_SOURCE_DIR}" "${simpledbus_BINARY_DIR}")
+   endif()
+
+You can put this code inside ``Findsimpledbus.cmake`` and add it to your CMake
+module path, as depicted in `cmake-init-fetchcontent`_.
+
+Once vendorized using the above approach, you can consume SimpleDBus from
+within CMake as you'd normally do ::
+
+   find_package(simpledbus REQUIRED)
+   target_link_libraries(<your-target> simpledbus::simpledbus)
+
+One key security feature of SimpleBLE is that it allows the user to specify
+the URLs and tags of all internal dependencies, thus allowing compilation
+from internal or secure sources without the risk of those getting compromised.
+
+Currently, the following libraries are included as part of SimpleDBus, with
+the following CMake options available:
+
+- `fmtlib`_
+
+  - ``LIBFMT_VENDORIZE``: Enable vendorization of fmtlib. *(Default: True)*
+
+  - ``LIBFMT_GIT_REPOSITORY``: The git repository to use for fmtlib.
+
+  - ``LIBFMT_GIT_TAG``: The git tag to use for fmtlib. *(Default: v8.1.1)*
+
+  - ``LIBFMT_LOCAL_PATH``: The local path to use for fmtlib. *(Default: None)*
+
+
+Generate Documentation
+======================
+
+To build documentation for SimpleDBus, you first need to install Sphynx,
+using the following commands: ::
+
+   sudo apt install python3-sphinx
+   pip3 install sphinx_rtd_theme
+
+Once all dependencies have been installed, HTML documentation can be built
+by calling the following commands: ::
+
+   cd <path-to-simpledbus>/docs
+   make html
+
+
+Build Examples
+==============
+
+Use the following instructions to build the provided SimpleDBus examples: ::
+
+   cd <path-to-simpledbus>
+   mkdir build && cd build
+   cmake -DSIMPLEDBUS_LOCAL=ON ../examples
+   make -j7
+
+
+=======
+Testing
+=======
+
+To build and run unit and integration tests, the following packages are
+required: ::
+
+   sudo apt install libgtest-dev libgmock-dev python3-dev
+   pip3 install -r <path-to-simpledbus>/test/requirements.txt
+
+
+Unit Tests
+==========
+
+To run the unit tests, run the following command: ::
+
+   cd <path-to-simpledbus>
+   mkdir build_test && cd build_test
+   cmake -DCMAKE_BUILD_TYPE=Debug ../test
+   make -j7
+   ./simpledbus_test
+
+
+Coverage Tests
+==============
+
+To run coverage tests, run the following command: ::
+
+   cd <path-to-simpledbus>
+   mkdir build_coverage && cd build_coverage
+   cmake -DCMAKE_BUILD_TYPE=Debug -DSIMPLEDBUS_COVERAGE=ON ../test
+   make -j7 simpledbus_test_coverage
+
+
+Address Sanitizer Tests
+=======================
+
+To run the address sanitizer tests, run the following command: ::
+
+   cd <path-to-simpledbus>
+   mkdir build_asan && cd build_asan
+   cmake -DCMAKE_BUILD_TYPE=Debug -DSIMPLEDBUS_SANITIZE=Address ../test
+   make -j7
+   PYTHONMALLOC=malloc ./simpledbus_test
+
+It's important for PYTHONMALLOC to be set to malloc, otherwise the tests will
+fail due to Python's memory allocator from triggering false positives.
+
+
+Thread Sanitizer Tests
+=======================
+
+To run the thread sanitizer tests, run the following command: ::
+
+   cd <path-to-simpledbus>
+   mkdir build_tsan && cd build_tsan
+   cmake -DCMAKE_BUILD_TYPE=Debug -DSIMPLEDBUS_SANITIZE=Thread ../test
+   make -j7
+   ./simpledbus_test
+
+
+.. Links
+
+.. _cmake-init-fetchcontent: https://github.com/friendlyanon/cmake-init-fetchcontent
+.. _fmtlib: https://github.com/fmtlib/fmt

docs/simplepyble/usage.rst

@@ -0,0 +1,3 @@
+=================
+SimplePyBLE Usage
+=================