ABlePeripheral
==============

`ABlePeripheral` is the core class that ABle revolves around. This is the class which accepts advertisements [1]_ to advertise,
handles the GATT table [2]_ the peripheral will be using with `ABleService` and `ABleCharacteristic`, and operates as a socket
server, waiting for and returning `ABleCentral` instances once a central connects which can be communicated with
similarly to how a Berkeley socket would [3]_.

Class Definition
++++++++++++++++

.. autoclass:: able.peripheral.ABlePeripheralServer

Methods
+++++++

Initialization
**************

This must be ran before any other methods as it will handle all the underlying setup required on the platform
to be able to add advertisements, services, characteristics and more later on.

.. autofunction:: able.peripheral.ABlePeripheralServer.setup_peripheral_server

Setup
*****

These are used to do any setup before launching the server, setup the gatt table and configure advertisements
here.

.. autofunction:: able.peripheral.ABlePeripheralServer.add_advertisement
.. autofunction:: able.peripheral.ABlePeripheralServer.remove_advertisement
.. autofunction:: able.peripheral.ABlePeripheralServer.add_service
.. autofunction:: able.peripheral.ABlePeripheralServer.add_characteristic

State
*****

Run the `listen` method to start the peripheral server and `close` to stop it.

.. autofunction:: able.peripheral.ABlePeripheralServer.listen
.. autofunction:: able.peripheral.ABlePeripheralServer.close

Connections
***********

Just as you would with a berkeley socket, use the `accept` function to get `ABleCentral` once a connection has
been established, see the programming guide for the peripheral server for more.

.. autofunction:: able.peripheral.ABlePeripheralServer.accept

Broadcasting
************

On top of communicating with just one central, the peripheral can broadcast to all peripherals on a given
characteristic using `broadcast`

.. autofunction:: able.peripheral.ABlePeripheralServer.broadcast

References
++++++++++

.. [1] `Quickstart to BLE Advertisements <https://www.argenox.com/library/bluetooth-low-energy/ble-advertising-primer/>`_
.. [2] `Introduction to GATT Tables <https://www.bluetooth.com/bluetooth-resources/intro-to-bluetooth-gap-gatt/>`_
.. [3] `Berkeley Socket API <https://en.wikipedia.org/wiki/Berkeley_sockets>`_