ABle's Documentation
====================

About
+++++

Welcome to the documentation for ABle (Allthenticate's BLE Library). The mission of this project is to create a
developer friendly and platform agnostic implementation of BLE Sockets with a simple and powerful API.

The library supports a GATT peripheral server that can be initialized with preconfigured advertisements. The server
produces centrals which handle abstraction for communicating and supports communicating directly with multiple connected centrals.

The abstraction barriers in the top level classes defined in the API Reference utilize platform specific backends
meaning that the same code will run on Linux, Mac and Windows machines with Bluetooth capabilities, with the goal
of greatly simplifying the BLE development process.

.. note:: This project is actively under development and we welcome any suggestions to improve these docs! Let us
    know with an email, notion card or an issue on the repo.

Abstraction
+++++++++++

See below image for a visual for the abstraction that is core to how ABle works. The three main classes expose ABle's Core API to developers
which is platform agnostic. These classes utilize platform specific API's with their own implementations such that
the core API behaves the same on all supported platforms.

.. figure:: ../reference/ABle_Arch.png
   :scale: 75 %
   :alt: Something bad happened :/

.. tip:: Note that this excludes the classes essential for configuring the GATT table on the peripheral `ABleCharacteristic`
    and `ABleService`, see the programming guide and the API reference for more on configuring the GATT table with ABle.

We will soon be releasing a short video series on how different components of ABle work as well as working through
some of the main examples used.

Table Of Contents
+++++++++++++++++

.. list-table::
    :widths: 15 35
    :header-rows: 1
    :stub-columns: 1

    * - Section
      - Description
    * - Programming Guide
      - Here you will find examples to get started and even get into some of the weeds of working
        with ABle. We suggest you look here first.
    * - Core API
      - The core classes and their methods are documented here.
    * - Platform Backends
      - For those who like getting their hands dirty, here are the different backends API's that the core classes
        use. *hic sunt BLE dracones*
    * - Development
      - For anyone interested in contributing to the project, check out these files to get started!

.. toctree::
   :maxdepth: 1
   :caption: Programming Guide

    Introduction<programming_guide/index.rst>
    Getting Started<programming_guide/getting_started.rst>
    Advertising<programming_guide/advertising.rst>
    GATT Setup<programming_guide/gatt.rst>
    Connections<programming_guide/connections.rst>
    Communications<programming_guide/communications.rst>

..  toctree::
    :maxdepth: 1
    :caption: Core API

    ABleAdvertisement<api_reference/advertisement.rst>
    ABlePeripheral<api_reference/peripheral.rst>
    ABleCentral<api_reference/central.rst>
    ABleService<api_reference/service.rst>
    ABleCharacteristic<api_reference/characteristic.rst>

..  toctree::
    :maxdepth: 2
    :caption: Platform Backends

    BluezDbus<bluezdbus/index.rst>
    CoreBluetooth<corebluetooth/index.rst>
    WinRT<winrt/index.rst>

..  toctree::
    :maxdepth: 1
    :caption: Development

    Troubleshooting<development/troubleshooting.rst>
    Contributing<development/index.rst>
    Developers<development/developers.rst>
    Testing<development/testing.rst>

Puns
++++

We readily welcome any puns on the ABle name to be sent to `help@allthenticate.net` to be featured in the repo (eg.
this project en*able*s faster BLE development for more st*able* projects with read*able* documentation). Credit
for the A+ name goes to Evan Blasband.


Moreover, we humbly think the name is hilarious because when you refer to an instance of an advertisement as `ABleAdvertisement`, you are
calling it it's class name but also what it is, a-ble-advertisement, we find this hilarious and hope you do to.

Indices and tables
++++++++++++++++++

* :ref:`genindex`
* :ref:`modindex`