bluetooth_numbers package#

bluetooth-numbers: Python package with a wide set of numbers related to Bluetooth.

This project offers a Python package with company IDs, service, characteristic and descriptor UUIDs and OUIs, so Python projects can easily use these numbers.

Get the description of a company ID:

>>> from bluetooth_numbers import company
>>> company[0x0499]
'Ruuvi Innovations Ltd.'

Get the description of a service UUID:

>>> from bluetooth_numbers import service
>>> from uuid import UUID
>>> service[0x180F]
'Battery Service'
>>> service[UUID("6E400001-B5A3-F393-E0A9-E50E24DCCA9E")]
'Nordic UART Service'

Get the description of a characteristic UUID:

>>> from bluetooth_numbers import characteristic
>>> from uuid import UUID
>>> characteristic[0x2A37]
'Heart Rate Measurement'
>>> characteristic[UUID("6E400002-B5A3-F393-E0A9-E50E24DCCA9E")]
'UART RX Characteristic'

Get the description of a descriptor UUID:

>>> from bluetooth_numbers import descriptor
>>> descriptor[0x2901]
'Characteristic User Descriptor'

Get the description of an OUI:

>>> from bluetooth_numbers import oui
>>> oui["58:2D:34"]
'Qingping Electronics (Suzhou) Co., Ltd'

Submodules#

bluetooth_numbers.dicts module#

Module with specialized dictionary classes for UUIDs, CICs and OUIs.

class bluetooth_numbers.dicts.CICDict[source]#

Bases: Dict[int, str]

Dictionary class to hold 16-bit company codes and their names.

You can use this class as a dict with the following differences:

If you check for a key that doesn’t exist, this raises an UnknownCICError.
If you check for a key that isn’t a 16-bit unsigned integer, this raises a No16BitIntegerError.

Examples

>>> from bluetooth_numbers import company
>>> company[0x004C]
'Apple, Inc.'
>>> company[-1]
Traceback (most recent call last):
bluetooth_numbers.exceptions.No16BitIntegerError: -1
>>> company[65534]
Traceback (most recent call last):
bluetooth_numbers.exceptions.UnknownCICError: 65534

class bluetooth_numbers.dicts.OUIDict[source]#

Bases: Dict[str, str]

Dictionary class to hold OUIs and their names.

You can use this class as a dict with the following differences:

You can check for an OUI in the formats “xx:yy:zz”, “xx-yy-zz” or “xxyyzz”. Both lowercase and uppercase letters are supported.
If you check for a key that doesn’t exist, this raises an UnknownOUIError.
If you check for a key that doesn’t have one of the supported formats, this raises a WrongOUIFormatError.

Examples

>>> from bluetooth_numbers import oui
>>> oui["98:E7:43"]
'Dell Inc.'
>>> oui["c4-29-96"]
'Signify B.V.'
>>> oui["A44519"]
'Xiaomi Communications Co Ltd'
>>> oui["FOOBAR"]
Traceback (most recent call last):
bluetooth_numbers.exceptions.WrongOUIFormatError: 'FOOBAR'
>>> oui["AB:CD:EF"]
Traceback (most recent call last):
bluetooth_numbers.exceptions.UnknownOUIError: AB:CD:EF

class bluetooth_numbers.dicts.UUIDDict[source]#

Bases: Dict[Union[UUID, int], str]

Dictionary class to hold 16-bit and 128-bit standard UUID keys and descriptions.

You can use this class as a dict for Bluetooth UUIDs, with the following differences:

If you check for a 128-bit standard UUID and this UUID doesn’t exist in the dictionary, it will check for the corresponding 16-bit UUID.
If you check for a UUID that doesn’t exist, this raises an UnknownUUIDError.
If you check for a key that isn’t a 16-bit unsigned integer, this raises a No16BitIntegerError.

Examples

>>> from bluetooth_numbers import service
>>> from uuid import UUID
>>> service[UUID("0000180F-0000-1000-8000-00805F9B34FB")]
'Battery Service'
>>> service[0x180F]
'Battery Service'
>>> service[0]
Traceback (most recent call last):
bluetooth_numbers.exceptions.UnknownUUIDError: 0
>>> service[6.5]
Traceback (most recent call last):
bluetooth_numbers.exceptions.No16BitIntegerError: 6.5

bluetooth_numbers.exceptions module#

Module with exceptions raised by this library.

exception bluetooth_numbers.exceptions.BluetoothNumbersError[source]#

Bases: Exception

Base class for all exceptions raised by this library.

exception bluetooth_numbers.exceptions.No16BitIntegerError[source]#

Bases: BluetoothNumbersError

Exception raised when an integer is not a 16-bit number.

exception bluetooth_numbers.exceptions.NonStandardUUIDError[source]#

Bases: BluetoothNumbersError

Exception raised when a 128-bit UUID is not a standard Bluetooth UUID.

exception bluetooth_numbers.exceptions.UnknownCICError[source]#

Bases: BluetoothNumbersError

Exception raised when a CIC is not known.

exception bluetooth_numbers.exceptions.UnknownOUIError[source]#

Bases: BluetoothNumbersError

Exception raised when an OUI is not known.

exception bluetooth_numbers.exceptions.UnknownUUIDError[source]#

Bases: BluetoothNumbersError

Exception raised when a UUID is not known.

exception bluetooth_numbers.exceptions.WrongOUIFormatError[source]#

Bases: BluetoothNumbersError

Exception raised when a string isn’t a supported format for an OUI.

bluetooth_numbers.utils module#

Module with utility functions for Bluetooth numbers.

bluetooth_numbers.utils.BASE_UUID: UUID = UUID('00000000-0000-1000-8000-00805f9b34fb')#: Base UUID defined by the Bluetooth SIG.

bluetooth_numbers.utils.is_normalized_oui(oui: str) → bool[source]#

Check whether the argument is a normalized OUI.

A normalized OUI is a string with format “XX:YY:ZZ” where XX, YY and ZZ are uppercase hexadecimal digits.

Parameters:: oui (str) – The string to check.
Returns:: True if oui is a normalized OUI, False otherwise.
Return type:: bool

Examples

>>> from bluetooth_numbers.utils import is_normalized_oui
>>> is_normalized_oui("98-e7-43")
False
>>> is_normalized_oui("98:E7:43")
True
>>> is_normalized_oui("FOOBAR")
False

bluetooth_numbers.utils.is_standard_uuid128(uuid128: UUID) → bool[source]#

Check whether a 128-bit Bluetooth UUID is a standard UUID.

Parameters:: uuid128 (UUID) – A 128-bit Bluetooth UUID.
Returns:: True if uuid128 is a standard Bluetooth UUID, False otherwise.
Return type:: bool

Examples

>>> from bluetooth_numbers.utils import is_standard_uuid128
>>> from uuid import UUID
>>> is_standard_uuid128(UUID('00001800-0000-1000-8000-00805f9b34fb'))
True
>>> is_standard_uuid128(UUID('bfc46884-ea75-416b-8154-29c5d0b0a087'))
False

New in version 1.1.0.

bluetooth_numbers.utils.is_uint16(number: int) → bool[source]#

Check whether a number is a 16-bit unsigned integer.

Parameters:: number (int) – The number to check.
Returns:: True if number is a 16-bit unsigned integer, False otherwise.
Return type:: bool

Examples

>>> from bluetooth_numbers.utils import is_uint16
>>> is_uint16(0x1800)
True
>>> is_uint16(-1)
False

bluetooth_numbers.utils.normalize_oui(oui: str) → str[source]#

Normalize an OUI.

This changes the letters in decimal digits to uppercase and places a colon between the OUI’s bytes.

Parameters:: oui (str) – The OUI to normalize.
Raises:: WrongOUIFormatError – If oui doesn’t have the right format.
Returns:: oui as a normalized OUI.
Return type:: str

Examples

>>> from bluetooth_numbers.utils import normalize_oui
>>> normalize_oui("98-e7-43")
'98:E7:43'
>>> normalize_oui("98e743")
'98:E7:43'
>>> normalize_oui("FOOBAR")
Traceback (most recent call last):
bluetooth_numbers.exceptions.WrongOUIFormatError: 'FOOBAR'

bluetooth_numbers.utils.uint16_to_hex(number: int) → str[source]#

Convert a 16-bit UUID or Company ID to a hexadecimal string.

Parameters:: number (int) – A 16-bit number.
Raises:: No16BitIntegerError – If number is not an integer from 0 to 65535.
Returns:: A hexadecimal string representation of number.
Return type:: str

Example

>>> from bluetooth_numbers.utils import uint16_to_hex
>>> uint16_to_hex(0xFD6F)
'0xfd6f'

bluetooth_numbers.utils.uuid128_to_uuid16(uuid128: UUID) → int[source]#

Convert a 128-bit standard Bluetooth UUID to a 16-bit UUID.

Parameters:: uuid128 (UUID) – A 128-bit Bluetooth UUID.
Raises:: NonStandardUUIDError – If uuid128 is not a 128-bit standard Bluetooth UUID.
Returns:: A 16-bit UUID that is the short UUID of uuid128.
Return type:: int

Example

>>> from bluetooth_numbers.utils import uuid128_to_uuid16, uint16_to_hex
>>> from uuid import UUID
>>> uint16_to_hex(uuid128_to_uuid16(UUID('00001800-0000-1000-8000-00805f9b34fb')))
'0x1800'

bluetooth_numbers.utils.uuid16_to_uuid128(uuid16: int) → UUID[source]#

Convert a 16-bit UUID to a 128-bit UUID with the Bluetooth base UUID.

Parameters:: uuid16 (int) – A 16-bit UUID.
Raises:: No16BitIntegerError – If uuid16 is not an integer from 0 to 65535.
Returns:: A 128-bit UUID that is the full UUID of uuid16.
Return type:: UUID

Example

>>> from bluetooth_numbers.utils import uuid16_to_uuid128
>>> uuid16_to_uuid128(0x1800)
UUID('00001800-0000-1000-8000-00805f9b34fb')