<commit_before>BlueZ settings storage
**********************

Purpose
=======

The purpose of this document is to describe the directory structure of BlueZ
settings storage. In effect, this document will serve as the primary, up to
date source of BlueZ storage information.  It is intended for developers,
managers and users needing to understand the storage directory.

Adapter and remote device info are read form the storage during object
initialization.
Write to storage is performed immediately on every value change.

Default storage directory is /var/lib/bluetooth.

All files are in ini-file format.

Storage directory structure
===========================

There is one directory per adapter, named by its bluetooth address, which
contains:
 - a settings file for the local adapter
 - an attributes file containing attributes of supported LE services
 - a cache directory containing:
    - one file per device, named by remote device address, which contains
    device name
 - one directory per remote device, named by remote device address, which
   contains:
    - an info file
    - an attributes file containing attributes of remote LE services

So the directory structure is:
    /var/lib/bluetooth/<adapter address>/
        ./settings
        ./attributes
        ./cache/
            ./<remote device address>
            ./<remote device address>
            ...
        ./<remote device address>/
            ./info
            ./attributes
        ./<remote device address>/
            ./info
            ./attributes
        ...

Settings file format
====================

Settings file contains one [General] group with adapter info like:

  Name			String		Friendly name advertised for
					this adapter

  Discoverable		Boolean		Discoverability of the adapter

  Connectable		Boolean		Connectability of the adapter

  Pairable		Boolean		Can the adapter accept pairing
					request ?

  Powered		Boolean		Is the adapter powered ?

  PairableTimeout	Integer		How long to stay in pairable mode
					before going back to non-pairable.
					The value is in seconds.
					0 = disable timer, i.e. stay
					pairable forever

  DiscoverableTimeout	Integer		How long to stay in discoverable mode
					before going back to non-discoverable.
					The value is in seconds.
					0 = disable timer, i.e. stay
					discoverable forever

Sample:
  [General]
  Name=<NAME>
  Discoverable=false
  Connectable=true
  Pairable=true
  Powered=true
  DiscoverableTimeout=0

Attributes file format
======================

The attributes file lists all attributes supported by the local adapter or
remote device.

Attributes are stored using their handle as group name (decimal format).

Each group contains:

  UUID		String		128-bit UUID of the attribute

  Value		String		Value of the attribute as hexadecimal encoded
				string

Sample:
  [1]
  UUID=00002800-0000-1000-8000-00805f9b34fb
  Value=0018

  [4]
  UUID=00002803-0000-1000-8000-00805f9b34fb
  Value=020600002A

  [6]
  UUID=00002a00-0000-1000-8000-00805f9b34fb
  Value=4578616D706C6520446576696365

Cache directory file format
============================

Each file, named by remote device address, contains one [General] group.
This general group contains:

  Name		String		Remote device friendly name

  ShortName	String		Remote device shortened name

Info file format
================

Info file may includes multiple groups (General, Device ID, Link key and
Long term key) related to a remote device.

[General] group contains:

  Name			String		Remote device friendly name

  Alias			String		Alias name

  Class			String		Device class in hexadecimal,
					i.e. 0x000000

  Features		String		Bluetooth device features in
					hexadecimal, i.e. 0x0000000000000000

  AddressType		String		An address can be "static" or "public"

  Trusted		Boolean		True if the remote device is trusted

  Profiles		List of		List of profiles advertised by remote,<commit_msg>doc: Update settings-storage.txt<commit_after>BlueZ settings storage
**********************

Purpose
=======

The purpose of this document is to describe the directory structure of BlueZ
settings storage. In effect, this document will serve as the primary, up to
date source of BlueZ storage information.  It is intended for developers,
managers and users needing to understand the storage directory.

Adapter and remote device info are read form the storage during object
initialization.
Write to storage is performed immediately on every value change.

Default storage directory is /var/lib/bluetooth.

All files are in ini-file format.

Storage directory structure
===========================

There is one directory per adapter, named by its bluetooth address, which
contains:
 - a settings file for the local adapter
 - an attributes file containing attributes of supported LE services
 - a cache directory containing:
    - one file per device, named by remote device address, which contains
    device name
 - one directory per remote device, named by remote device address, which
   contains:
    - an info file
    - an attributes file containing attributes of remote LE services

So the directory structure is:
    /var/lib/bluetooth/<adapter address>/
        ./settings
        ./attributes
        ./cache/
            ./<remote device address>
            ./<remote device address>
            ...
        ./<remote device address>/
            ./info
            ./attributes
        ./<remote device address>/
            ./info
            ./attributes
        ...

Settings file format
====================

Settings file contains one [General] group with adapter info like:

  Name			String		Friendly name advertised for
					this adapter

  Discoverable		Boolean		Discoverability of the adapter

  Connectable		Boolean		Connectability of the adapter

  Pairable		Boolean		Can the adapter accept pairing
					request ?

  Powered		Boolean		Is the adapter powered ?

  PairableTimeout	Integer		How long to stay in pairable mode
					before going back to non-pairable.
					The value is in seconds.
					0 = disable timer, i.e. stay
					pairable forever

  DiscoverableTimeout	Integer		How long to stay in discoverable mode
					before going back to non-discoverable.
					The value is in seconds.
					0 = disable timer, i.e. stay
					discoverable forever

Sample:
  [General]
  Name=My PC
  Discoverable=false
  Connectable=true
  Pairable=true
  Powered=true
  DiscoverableTimeout=0

Attributes file format
======================

The attributes file lists all attributes supported by the local adapter or
remote device.

Attributes are stored using their handle as group name (decimal format).

Each group contains:

  UUID		String		128-bit UUID of the attribute

  Value		String		Value of the attribute as hexadecimal encoded
				string

Sample:
  [1]
  UUID=00002800-0000-1000-8000-00805f9b34fb
  Value=0018

  [4]
  UUID=00002803-0000-1000-8000-00805f9b34fb
  Value=020600002A

  [6]
  UUID=00002a00-0000-1000-8000-00805f9b34fb
  Value=4578616D706C6520446576696365

Cache directory file format
============================

Each file, named by remote device address, contains one [General] group.
This general group contains:

  Name		String		Remote device friendly name

  ShortName	String		Remote device shortened name

Info file format
================

Info file may includes multiple groups (General, Device ID, Link key and
Long term key) related to a remote device.

[General] group contains:

  Name			String		Remote device friendly name

  Alias			String		Alias name

  Class			String		Device class in hexadecimal,
					i.e. 0x000000

  SupportedTechnologies	List of		List of technologies supported by
			strings		device, separated by ";"
					Technologies can be BR/EDR or LE

  AddressType		String		An address can be "static" or "public"

  Trusted		Boolean		True if the remote device is trusted

  Blocked		Boolean		True if the remote device is blocked

  Profiles		List of		List of profiles advertised by remote,
{'fraction_non_alphanumeric': 0.07761755485893417, 'fraction_numerical': 0.0367398119122257, 'mean_word_length': 3.20231822971549, 'pattern_counts': {'":': 0, '<': 14, '<?xml version=': 0, '>': 14, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 1, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2231711', 'n_tokens_mistral': 2456, 'n_tokens_neox': 2081, 'n_words': 938}