.. module:: ble_beacons

***********
BLE Beacons
***********

This module implements utility functions to implement and scan iBeacons and Eddystone beacons.

Refer to BLE examples for usage.


================
Module Functions
================


    
.. function:: eddy_encode_tlm(battery, temperature, count, time)

    Return a bytearray representing an encoded Eddystone payload of type tlm (not encrypted).

    According to the specifications:

    * :samp:`battery` is the battery charge in mV
    * :samp:`temperature` is the beacon temperature in degrees. If None is give, temperature is set to -128
    * :samp:`count` is the pdu count, the number of advertised packets
    * :samp:`time` is the time in seconds since beacon power up


    
.. function:: eddy_encode_uid(namespace, instance, txpower)

    Return a bytearray representing an encoded Eddystone payload of type uid (not encrypted).

    According to the specifications:

    * :samp:`namespace` is a sequence of bytes of maximum length 10 (if less, it is zero padded to the right) representing the namespace of the uid
    * :samp:`instance` is a sequence of bytes of maximum lengtth 6 (if less, it is zero padded to the right) representing the instance of the uid
    * :samp:`txpower` is the power calibration measurement of the beacon (used to calculate distances)

    
.. function:: eddy_encode_url(url, txpower)

    Return a bytearray representing an encoded Eddystone payload of type url (not encrypted).

    According to the specifications:

    * :samp:`url` is a string representing an URL to be encoded in the Eddystone format
    * :samp:`txpower` is the power calibration measurement of the beacon (used to calculate distances)

    
.. function:: eddy_decode_type(packet)

    Given :samp:`packet` as a bytes or bytearray return the type of the Eddystone packet or raises :samp:`ValueError` if it is not an Eddystone packet.

    Return values are:

    * :samp:`EDDY_LTM` for ltm packets
    * :samp:`EDDY_UID` for uid packets
    * :samp:`EDDY_URL` for url packets

    
.. function:: eddy_decode(packet)

    Given :samp:`packet` as a bytes or bytearray return a tuple with the packet decoded fields or raises :samp:`ValueError` in case :samp:`packet` is not Eddystone.

    Return values are:

    * a tuple with namespace, instance and txpower for uid packets
    * a tuple with url and txpower for url packets
    * a tuple with battery, temperature, count and time for tlm packets

    
.. function:: ibeacon_encode(uuid, major, minor, txpower, manufacturer=0x4c00)

    Return a bytearray representing an encoded iBeacon payload.

    According to the specifications:

    * :samp:`uuid` is a 16 bytes unique identifier
    * :samp:`major` is the major version as integer
    * :samp:`minor` is the minor version as integer
    * :samp:`txpower` is the power calibration measurement of the beacon (used to calculate distances)
    * :samp:`manufacturer` is set to Apple, but can be changed if needed

    
.. function:: ibeacon_decode(packet)

    Given :samp:`packet` as a bytes or bytearray return a tuple with the packet decoded fields or raises :samp:`ValueError` in case :samp:`packet` is not iBeacon.

    Return value is a tuple with uuid, major, minor and txpower