Another pass at documentation and READMEs. (#327)

.readthedocs.yaml

@@ -21,7 +21,7 @@ build:
     post_install:
       - echo "Command run at 'post_install' step"
       # NOTE: Apparently sphinx_rtfd_theme==1.0.0 is not compatible with Sphinx 5.2
-      - pip install breathe==4.34.0 sphinx_rtd_theme==1.0.0 sphinx==5.1.1
+      - pip install breathe==4.34.0 sphinx_rtd_theme==1.0.0 sphinx==5.1.1 sphinxcontrib-mermaid==0.9.2
     pre_build:
       - echo "Command run at 'pre_build' step"
     post_build:

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to SimpleBLE
+
+This document outlines the process for contributing to the project and provides some guidelines to ensure a smooth collaboration.
+
+## Contributor License Agreement
+
+Before we can accept your contribution, you must sign our Contributor License Agreement (CLA). This agreement ensures that the project has the necessary rights to use and distribute your contributions.
+
+- If you are contributing as an individual, please sign the Individual CLA.
+- If you are contributing on behalf of your employer, please have your employer sign the Corporate CLA.
+
+<!-- You can find the appropriate CLA forms on our website or by contacting our legal team at [email@email.com](mailto:email@email.com). -->
+
+**Please note:** We cannot accept any contributions without a signed CLA.
+
+## Coding Guidelines
+
+- Follow the existing code style and conventions used in the project.
+- Write clear, readable, and well-documented code.
+- Include unit tests for new features or bug fixes where applicable.
+- Ensure your code works on all supported platforms (Linux, Windows, macOS, iOS, and Android).
+
+## Submitting a Pull Request
+
+1. Ensure you have signed the CLA before submitting your pull request.
+2. Provide a clear and detailed description of your changes in the pull request.
+3. Reference any related issues in your pull request description.
+4. Be prepared to make changes if requested by the maintainers.
+
+## Reporting Issues
+
+- Use the GitHub issue tracker to report bugs or suggest features.
+- Before creating a new issue, please check if a similar issue already exists.
+- Provide as much detail as possible, including steps to reproduce for bugs.
+
+## Community Guidelines
+
+- Be respectful and considerate in all interactions.
+- Help others if you can.
+
+## Questions?
+
+If you have any questions about contributing, feel free to open an issue or contact the team directly.
+
+Thank you for contributing to SimpleBLE! Your efforts help make this project better for everyone.

README.rst

@@ -9,38 +9,55 @@ Overview
 --------
 
 The SimpleBLE project aims to provide fully cross-platform BLE libraries and bindings
-for Python, Rust 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.
+for C++, Python, Rust and other languages, designed for simplicity and ease of use.
+All specific operating system quirks are handled internally to provide a consistent behavior
+and API across all platforms. The libraries also provide first-class support for vendorization
+of all third-party dependencies, allowing for easy integration into existing projects.
 
 **NOTICE: Since February 20, 2024 the license terms of SimpleBLE have changed. Please make sure to read and understand the details below.**
 
+Below you'll find a list of components that are part of SimpleBLE:
+
 * **SimpleBLE:** C++ cross-platform BLE library.
 * **SimplePyBLE:** Python bindings for SimpleBLE. See the `SimplePyBLE`_ PyPI page for more details.
-* **SimpleRsBLE:** Rust bindings for SimpleBLE. See the `SimpleRsBLE`_ Crates.io page for more details.
+* **SimpleDroidBLE:** Android-specific package following the SimpleBLE API. (Still in Alpha, more to come)
+* **SimpleRsBLE:** Rust bindings for SimpleBLE (LEGACY - Big refactor coming soon). See the `SimpleRsBLE`_ Crates.io 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`` (Dedicated consulting services available)
-
-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!
+* Contact us: ``contact at simpleble dot org``
+* Visit our `website`_ for more information.
 
 Supported platforms
 -------------------
-=========== ============= =================================== =====
-Windows     Linux         MacOS                               iOS
-=========== ============= =================================== =====
-Windows 10+ Ubuntu 20.04+ 10.15+ (except 12.0, 12.1 and 12.2) 15.0+
-=========== ============= =================================== =====
 
-**NOTE:** WSL does not support Bluetooth.
+.. list-table::
+   :header-rows: 1
+
+   * - Platform
+     - Versions
+     - Notes
+   * - Windows
+     - Windows 10+
+     - • WSL does not support Bluetooth.
+       • Only a single adapter is supported by the OS backend.
+   * - Linux
+     - Ubuntu 20.04+
+     - • Other distros using Bluez as their Bluetooth backend should work.
+   * - MacOS
+     - 10.15+ (Catalina and newer)
+     - • MacOS 12.0, 12.1, and 12.2 have a bug where the adapter won't return any peripherals after scanning.
+       • Only a single adapter is supported by the OS backend.
+   * - iOS
+     - 15.0+
+     - • Older versions of iOS might work but haven't been formally tested.
+   * - Android (Alpha)
+     - API 31+
+     - • Older APIs are missing certain features of the JVM API that are required by SimpleBLE.
 
 Projects using SimpleBLE
 ------------------------
@@ -62,19 +79,23 @@ Since February 15th 2024, SimpleBLE is now available under the GNU General Publi
 version 3 (GPLv3), with the option for a commercial license without the GPLv3 restrictions
 available for a fee.
 
-**More information on pricing and commercial terms of service will be available soon.**
-
-To enquire about a commercial license, please contact us at ``contact at simpleble dot org``.
-
-**NOTICE:** The following projects are allowed to use SimpleBLE under a GNU Lesser General Public
-License version 3 (LGPLv3), due to their past contributions: `BrainFlow`_, `InsideBlue`_, `NodeWebBluetooth`_.
+**You can find more information on pricing and commercial terms of service on our `website`_.**
 
-Likewise, if you are using SimpleBLE in an open-source project and would like to request
-a free commercial license or if you have any other questions, please reach out at ``contact at simpleble dot org``.
+For further enquiries, please contact us at ``contact at simpleble dot org``.
 
 Licensing FAQ
 -------------
 
+I'm already using SimpleBLE. What happens to my project?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Please reach out at ``contact at simpleble dot org`` and we can discuss the specifics of your
+situation. It is my intention to make this transition as smooth as possible for existing users,
+and I'm open to finding a solution that works for everyone.
+
+If you are using SimpleBLE in an open-source project and would like to request
+a free commercial license or if you have any other questions, do not hesitate to reach out.
+
 Why are you making this change?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -84,44 +105,23 @@ of products that have been built around it, in particular around notable names i
 and industrial sectors, which has been both surprising and encouraging. Providing robust support for
 these diverse and critical use cases is a resource-intensive endeavor which can't be achieved on
 goodwill alone, especially so when the underlying APIs are also evolving and life having its own
-plans. By introducing a commercial license, I'm opening a pathway to dedicate more resources to
+plans. By introducing a commercial license, we're opening a pathway to dedicate more resources to
 enhance SimpleBLE. Some of the things on the roadmap include:
+
 - Bindings into more languages and frameworks.
 - Hardware-in-the-loop test infrastructure.
 - Offering bounties and revenue sharing with other developers who contribute.
 - Providing more comprehensive documentation and tutorials.
 
-Despite this transition, I remain firmly committed to the open-source philosophy. SimpleBLE was grown
+Despite this transition, We remain firmly committed to the open-source philosophy. SimpleBLE was grown
 a lot thanks to the feedback of the open-source community, and that foundation will always be a part
 of the project. The GPLv3 license option ensures continued accessibility for open-source projects,
-and I pledge to actively contribute to and collaborate with the community whenever possible.
+and we pledge to actively contribute to and collaborate with the community whenever possible.
 
-Ultimately, the success of SimpleBLE has been fueled by its open nature, and I believe this
+Ultimately, the success of SimpleBLE has been fueled by its open nature, and we believe this
 dual-licensing model strengthens that success by enabling both community-driven growth and
 targeted enhancements that benefit everyone.
 
-
-I'm already using SimpleBLE. What happens to my project?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Please reach out at ``contact at simpleble dot org`` and we can discuss the specifics of your
-situation. It is my intention to make this transition as smooth as possible for existing users,
-and I'm open to finding a solution that works for everyone.
-
-
-What do you consider "commercial use"?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Commercial use in the context of SimpleBLE refers to any usage of the SimpleBLE or any of its
-language bindings in a commercial setting where it contributes, either directly or indirectly,
-to financial gain. This includes, but is not limited to, incorporating SimpleBLE into commercial
-software products, using it in the development of services offered for a fee, or deploying it
-within internal tools or software in a for-profit organization where it adds business value.
-The key factor is the use of the library as a component in a revenue-generating or
-business-advancing context, irrespective of whether the library itself is sold or offered as
-a standalone product.
-
-
 What does the GPLv3 license imply for my commercial project?
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 The GPLv3 license ensures that end users have the freedom to run, study, share, and modify the software.
@@ -133,6 +133,8 @@ You can find the full text of the GPLv3 license at https://www.gnu.org/licenses/
 
 .. Links
 
+.. _website: https://simpleble.org
+
 .. _SimplePyBLE: https://pypi.org/project/simplepyble/
 
 .. _SimpleRsBLE: https://crates.io/crates/simplersble

docs/extras.rst

@@ -1,6 +1,9 @@
-======================
+Extras
+======
+
 Building documentation
-======================
+----------------------
+
 
 To build documentation for the projects in this repository,
 you first need to install Sphynx, using the following commands: ::
@@ -13,10 +16,8 @@ by calling the following commands: ::
    cd <path-to-repository>/docs
    make html
 
-
-=================
 Release checklist
-=================
+-----------------
 
 Before releasing a new version of the project, the following steps should be
 performed:

docs/index.rst

@@ -1,5 +1,5 @@
 SimpleBLE
-==========
+=========
 
 The ultimate fully-fledged cross-platform library and bindings for Bluetooth Low Energy (BLE).
 
@@ -15,6 +15,7 @@ Table of Contents
    :caption: General
 
    overview
+   licensing_faq
    changelog
    extras
 
@@ -34,6 +35,12 @@ Table of Contents
    simplepyble/usage
    simplepyble/api
 
+.. toctree::
+   :maxdepth: 2
+   :caption: SimpleDroidBLE
+
+   simpledroidble/usage
+
 .. toctree::
    :maxdepth: 2
    :caption: SimpleBluez