### Install Pre-commit Hooks

Source: https://github.com/agittins/bermuda/blob/main/CONTRIBUTING.md

Install the pre-commit hooks to automatically run code style and linting checks before each commit.

```bash
$ pre-commit install
```

--------------------------------

### Private BLE Device Integration Setup

Source: https://context7.com/agittins/bermuda/llms.txt

Bermuda automatically integrates with Home Assistant's Private BLE Device integration. After configuring the device with an IRK in the integration, Bermuda will create sensors for it without further configuration.

```yaml
# IRK devices appear automatically in Bermuda's device list
# They track the device across all MAC address rotations (typically every 15 min)

# The IRK (Identity Resolving Key) is a 32-character hex string
# Example: "0123456789abcdef0123456789abcdef"

# Private BLE devices get automatic sensor creation:
sensor.<device_name>_area
sensor.<device_name>_distance
device_tracker.<device_name>_bermuda_tracker
```

--------------------------------

### Automating with iBeacon State Changes

Source: https://context7.com/agittins/bermuda/llms.txt

This automation triggers when an iBeacon changes its state, for example, when it leaves a defined area. Ensure the iBeacon is configured and recognized by Bermuda.

```yaml
automation:
  - alias: "Tile Beacon Left Office"
    trigger:
      - platform: state
        entity_id: sensor.tile_beacon_area
        from: "Office"
    action:
      - service: notify.mobile_app
        data:
          message: "Your keys left the office!"
```

--------------------------------

### Call bermuda.dump_devices Service

Source: https://github.com/agittins/bermuda/blob/main/README.md

Call the `bermuda.dump_devices` service to get a full dump of the internal data structures used by the Bermuda integration. This is useful for troubleshooting and understanding the integration's state. The `addresses` parameter can be used to filter the data by MAC address or iBeacon UUID.

```yaml
service: bermuda.dump_devices
```

```yaml
service: bermuda.dump_devices
  data:
    addresses: "AA:BB:CC:DD:EE:FF,123e4567-e89b-12d3-a456-426614174000"
```

--------------------------------

### Run Project Tests

Source: https://github.com/agittins/bermuda/blob/main/CONTRIBUTING.md

Execute the project's test suite from the root folder to verify the functionality of code modifications.

```bash
./scripts/test
```

--------------------------------

### Run All Pre-commit Tests

Source: https://github.com/agittins/bermuda/blob/main/CONTRIBUTING.md

Execute all pre-commit checks on the entire repository to ensure code style and linting compliance.

```bash
$ pre-commit run --all-files
```

--------------------------------

### Configure ESP32 BLE Tracker Settings

Source: https://github.com/agittins/bermuda/wiki/FAQ

Use these settings in your ESPHome proxies to optimize Bluetooth advertisement listening and minimize missed packets. Adjust 'interval' and 'window' based on your beacon's transmission frequency and network requirements.

```yaml
esp32_ble_tracker:
  interval: 320ms # default 320ms. Time spent per adv channel
  window: 290ms # default 30ms. Time spent listening during interval.
```

--------------------------------

### ESP32 Framework Configuration

Source: https://github.com/agittins/bermuda/wiki/ESPHome-Configurations

Configure the ESP32 variant and framework type. Ensure you select the correct ESP32 variant for your hardware. The esp-idf framework is recommended for better memory efficiency and Bluetooth proxying performance.

```yaml
esp32:
  variant: esp32  # Make sure you choose *your* esp type here (eg: esp32c3, esp32s3 etc)
  framework:
    type: esp-idf
```

--------------------------------

### Bermuda Configuration Options

Source: https://context7.com/agittins/bermuda/llms.txt

Key configuration options for the Bermuda integration, including defaults.

```APIDOC
## Configuration Options

Configuration is done through the Home Assistant UI in Settings > Devices & Services > Bermuda > Configure.

```yaml
# Key configuration options and their defaults:
max_area_radius: 20        # Maximum distance (meters) to consider device in an area
max_velocity: 3            # Max movement speed (m/s) - filters impossible readings
devtracker_nothome_timeout: 30  # Seconds before marking device as "Away"
update_interval: 10        # Seconds between sensor updates
smoothing_samples: 20      # Number of samples for distance smoothing
attenuation: 3            # Environmental signal attenuation factor
ref_power: -55.0          # Default RSSI at 1 metre distance
```
```

--------------------------------

### Bermuda Configuration Options

Source: https://context7.com/agittins/bermuda/llms.txt

Key configuration options for the Bermuda integration and their default values. Adjust these to fine-tune presence detection accuracy and behavior.

```yaml
# Key configuration options and their defaults:
max_area_radius: 20        # Maximum distance (meters) to consider device in an area
max_velocity: 3            # Max movement speed (m/s) - filters impossible readings
devtracker_nothome_timeout: 30  # Seconds before marking device as "Away"
update_interval: 10        # Seconds between sensor updates
smoothing_samples: 20      # Number of samples for distance smoothing
attenuation: 3            # Environmental signal attenuation factor
ref_power: -55.0          # Default RSSI at 1 metre distance
```

--------------------------------

### Service: bermuda.dump_devices

Source: https://context7.com/agittins/bermuda/llms.txt

Provides a comprehensive dump of all internal device data for debugging and troubleshooting.

```APIDOC
## Service: bermuda.dump_devices

The `bermuda.dump_devices` service provides a comprehensive dump of all internal device data including distances, RSSI values, and scanner information. This is useful for debugging, troubleshooting, and building custom template sensors.

### Method
POST

### Endpoint
/api/services/bermuda/dump_devices

### Parameters
#### Request Body
- **addresses** (string) - Optional - Comma-separated list of MAC addresses or iBeacon UUIDs to dump.
- **configured_devices** (boolean) - Optional - If true, only dump configured/tracked devices.
- **redact** (boolean) - Optional - If true, redact MAC addresses in the output.

### Request Example
```yaml
# Service call to dump all devices
service: bermuda.dump_devices
data: {}

# Dump specific devices by MAC address or iBeacon UUID
service: bermuda.dump_devices
data:
  addresses: "EE:E8:37:9F:6B:54 C7:B8:C6:B0:27:11"

# Dump only configured/tracked devices with redacted MAC addresses
service: bermuda.dump_devices
data:
  configured_devices: true
  redact: true
```

### Response
#### Success Response (200)
- **device_data** (object) - A dictionary containing detailed information about tracked devices.

#### Response Example
```json
{
  "ee:e8:37:9f:6b:54": {
    "name": "Living Room Beacon",
    "address": "ee:e8:37:9f:6b:54",
    "area_name": "Living Room",
    "area_distance": 2.3,
    "zone": "home",
    "last_seen": 1704067200.5,
    "adverts": {
      "ee:e8:37:9f:6b:54__aa:bb:cc:dd:ee:ff": {
        "scanner_address": "aa:bb:cc:dd:ee:ff",
        "rssi": -65,
        "rssi_distance": 2.3,
        "rssi_distance_raw": 2.8
      }
    }
  }
}
```
```

--------------------------------

### ESP32-C3 Module Configuration

Source: https://github.com/agittins/bermuda/wiki/ESPHome-Configurations

This configuration is recommended for ESP32-C3 devices to optimize Bluetooth and WiFi performance. It includes specific framework settings, SDK options for improved responsiveness, and API configurations for managing BLE tracking.

```yaml
esp32:
  variant: esp32c3
  framework:
    type: esp-idf  # This is important: the "arduino" framework does not perform well.
    sdkconfig_options:
      # @grigi found in testing that these options resulted in better responsiveness.
      # BLE 4.2 is supported by ALL ESP32 boards that have bluetooth, the original and derivatives.
      CONFIG_BT_BLE_42_FEATURES_SUPPORTED: y
      # Also enable this on any derivative boards (S2, C3 etc) but not the original ESP32.
      CONFIG_BT_BLE_50_FEATURES_SUPPORTED: y
      # Extend the watchdog timeout, so the device reboots if the device appears locked up for over 10 seconds.
      CONFIG_ESP_TASK_WDT_TIMEOUT_S: "10"

logger:
  baud_rate: 0  # 0 Enables logging, but disables serial-port logging to free CPU and memory

ota:
  platform: esphome
  password: !secret ota_password

api:

  # Only enable BLE tracking when wifi is up and api is connected
  # Gives single-core ESP32-C3 devices time to manage wifi and authenticate with api
  on_client_connected:
     - esp32_ble_tracker.start_scan:
        continuous: true
  # Disable BLE tracking when there are no api connections live
  on_client_disconnected:
    if:
      condition:
        not:
          api.connected:
      then:
        - esp32_ble_tracker.stop_scan:

esp32_ble_tracker:
  scan_parameters:
    # Don't auto start BLE scanning, we control it in the `api` block's automation.
    continuous: False
    
    active: True  # send scan-request packets to gather more info, like device name for some devices.

    interval: 320ms  # default 320ms - how long to spend on each advert channel
    window:   300ms  # default 30ms - how long to actually "listen" in each interval. Reduce this if device is unstable.
    # If the device cannot keep up or becomes unstable, reduce the "window" setting. This may be
    # required if your device is controlling other sensors or doing PWM for lights etc.

bluetooth_proxy:
  active: true  # allows outbound connections from HA to devices.

sensor:
  - platform: uptime
    # The uptime sensor is extremely helpful to know if your device is rebooting
    # when it shouldn't be. This might indicate your interval-to-window timing is
    # too tight, and the window needs to be reduced.
    name: "Uptime Sensor"
    update_interval: 60s

```

--------------------------------

### Template Sensor for Device Details

Source: https://context7.com/agittins/bermuda/llms.txt

Create a custom template sensor to display detailed location information for a specific device using data from the `dump_devices` service. This requires the device's MAC address to be present in the `devices` attribute of `sensor.bermuda_data`.

```yaml
template:
  - sensor:
      - name: "Phone Detailed Location"
        state: >
          {% set data = state_attr('sensor.bermuda_data', 'devices') %}
          {% if data and 'ee:e8:37:9f:6b:54' in data %}
            {{ data['ee:e8:37:9f:6b:54']['area_name'] }}
          {% else %}
            unknown
          {% endif %}
```

--------------------------------

### Configure BLE Tracker Scan Parameters

Source: https://github.com/agittins/bermuda/wiki/ESPHome-Configurations

Adjust `scan_parameters` for the `esp32_ble_tracker` to increase the frequency of listening for BLE advertisements. This is useful when you need to capture nearly all BLE adverts.

```yaml
esp32_ble_tracker:
  scan_parameters:
    active: True # Whether to send scan-request packets to devices to gather more info (like devicename)
    interval: 320ms # default 320ms
    window:   300ms # default 30ms
```

--------------------------------

### Purge and Repack Recorder History

Source: https://github.com/agittins/bermuda/wiki/Logs,-Recorder-and-Database-size

Use the `recorder.purge` service to remove historical data and reclaim disk space. Setting `repack: true` forces the database to rewrite its files, which is essential for freeing up space. This operation can be intensive.

```yaml
service: recorder.purge
data:
  keep_days: 10
  repack: true
  apply_filter: true
```

--------------------------------

### REST Command to Dump Bermuda Devices

Source: https://context7.com/agittins/bermuda/llms.txt

This REST command can be used to trigger the `dump_devices` service in Bermuda, which retrieves fresh device data. Ensure you have a `long_lived_token` secret configured for authentication.

```yaml
rest_command:
  get_bermuda_devices:
    url: "http://localhost:8123/api/services/bermuda/dump_devices"
    method: POST
    headers:
      authorization: !secret long_lived_token
    content_type: "application/json"
    payload: '{"configured_devices": true}'
```

--------------------------------

### Configure ESPHome for Active Bluetooth Scanning

Source: https://github.com/agittins/bermuda/wiki/Troubleshooting

Add this configuration to your ESPHome YAML to enable active scanning for Bluetooth devices, which may help in retrieving their names. Ensure this is distinct from the `bluetooth_proxy` active setting.

```yaml
esp32_ble_tracker:
  scan_parameters:
    active: True
```

--------------------------------

### Specify ESP-IDF Version for ESPHome

Source: https://github.com/agittins/bermuda/wiki/Troubleshooting

Use this workaround to address issues with Bluetooth advertisements not being sent by ESPHome proxies, potentially caused by ESP-IDF v5.5.2. This configuration pins the framework version to 5.5.1.

```yaml
esp32:
  framework:
    type: esp-idf
    version: 5.5.1
```

--------------------------------

### Follow-me music based on area

Source: https://context7.com/agittins/bermuda/llms.txt

This automation plays music on a media player, selecting the source based on the current area of the phone. It requires the media player to be in a 'playing' state.

```yaml
automation:
  - alias: "Follow Me Music"
    trigger:
      - platform: state
        entity_id: sensor.my_phone_area
    condition:
      - condition: state
        entity_id: media_player.spotify
        state: "playing"
    action:
      - service: media_player.select_source
        target:
          entity_id: media_player.spotify
        data:
          source: "{{ trigger.to_state.state }} Speaker"
```

--------------------------------

### Exclude Bermuda Data from Recorder

Source: https://github.com/agittins/bermuda/wiki/Logs,-Recorder-and-Database-size

Add this configuration to `configuration.yaml` to exclude specific Bermuda sensors from being logged by the recorder. This helps reduce database size and disk usage. Restart Home Assistant after applying changes.

```yaml
recorder:
  exclude:
    # to completely exclude all Bermuda data from logs, add this domain section. Not
    # recommended, but might be good if you like *big* hammers.
    # domains:
    #   - bermuda
    entity_globs:
      # to filter specific sensors
      - sensor.*_distance_to_aska*
      - sensor.*_distance_to_back*
      # ...etc
      # or filter all the distance-to sensors
      - sensor.*_distance_to_*
      # The area sensors
      - sensor.*_area
      # The distance to closest area sensor
      - sensor.*_distance
```

--------------------------------

### iBeacon Device Tracking

Source: https://context7.com/agittins/bermuda/llms.txt

How Bermuda automatically detects and tracks iBeacon devices.

```APIDOC
## iBeacon Device Tracking

Bermuda automatically detects iBeacon devices and creates metadevices that track them regardless of MAC address changes.

### iBeacon Identification

- iBeacons are identified by UUID_Major_Minor format.
```

--------------------------------

### Bermuda Service: dump_devices

Source: https://context7.com/agittins/bermuda/llms.txt

Service calls to dump internal device data for debugging. Supports dumping all devices, specific devices by address, or only configured devices with redaction.

```yaml
# Service call to dump all devices
service: bermuda.dump_devices
data: {}
```

```yaml
# Dump specific devices by MAC address or iBeacon UUID
service: bermuda.dump_devices
data:
  addresses: "EE:E8:37:9F:6B:54 C7:B8:C6:B0:27:11"
```

```yaml
# Dump only configured/tracked devices with redacted MAC addresses
service: bermuda.dump_devices
data:
  configured_devices: true
  redact: true
```

```yaml
# Example response structure for a tracked device:
# {
#   "ee:e8:37:9f:6b:54": {
#     "name": "Living Room Beacon",
#     "address": "ee:e8:37:9f:6b:54",
#     "area_name": "Living Room",
#     "area_distance": 2.3,
#     "zone": "home",
#     "last_seen": 1704067200.5,
#     "adverts": {
#       "ee:e8:37:9f:6b:54__aa:bb:cc:dd:ee:ff": {
#         "scanner_address": "aa:bb:cc:dd:ee:ff",
#         "rssi": -65,
#         "rssi_distance": 2.3,
#         "rssi_distance_raw": 2.8
#       }
#     }
#   }
# }
```

--------------------------------

### Turn off office lights when leaving an area

Source: https://context7.com/agittins/bermuda/llms.txt

This automation turns off office lights after a 2-minute delay when the phone leaves the 'Office' area, provided automations are enabled.

```yaml
automation:
  - alias: "Office Lights Off When Leaving"
    trigger:
      - platform: state
        entity_id: sensor.my_phone_area
        from: "Office"
    condition:
      - condition: state
        entity_id: input_boolean.automation_enabled
        state: "on"
    action:
      - delay: "00:02:00"  # Wait 2 min to confirm
      - condition: template
        value_template: "{{ states('sensor.my_phone_area') != 'Office' }}"
      - service: light.turn_off
        target:
          area_id: office
```

--------------------------------

### Device Tracker Entity

Source: https://context7.com/agittins/bermuda/llms.txt

Information about the device tracker entity created by Bermuda for Home/Away presence detection.

```APIDOC
## Entity Types: Device Tracker

The device_tracker entity enables Home/Away tracking and can be assigned to a Person for presence detection.

### Device Tracker Entity

- `device_tracker.<device_name>_bermuda_tracker`

### Example State and Attributes

```yaml
state: "home" or "not_home"
attributes:
  source_type: "bluetooth_le"
  scanner: "Kitchen Proxy"
  area: "Kitchen"
```

### Example Automation

```yaml
automation:
  - alias: "Welcome Home"
    trigger:
      - platform: state
        entity_id: device_tracker.phone_bermuda_tracker
        to: "home"
    action:
      - service: light.turn_on
        target:
          entity_id: light.hallway
```
```

--------------------------------

### Alert when active proxy count is low

Source: https://context7.com/agittins/bermuda/llms.txt

This automation triggers a notification if the number of active Bermuda proxies drops below 3 for more than 5 minutes, indicating a potential proxy issue.

```yaml
automation:
  - alias: "Alert Proxy Down"
    trigger:
      - platform: numeric_state
        entity_id: sensor.bermuda_active_proxy_count
        below: 3
        for: "00:05:00"
    action:
      - service: notify.mobile_app
        data:
          message: "Bluetooth proxy may be offline!"
```

--------------------------------

### Global Calibration: Reference Power and Attenuation

Source: https://context7.com/agittins/bermuda/llms.txt

Calibrate global reference power and attenuation to improve distance accuracy. Place the device 1m away for reference power and 4-5m away for attenuation, adjusting values until the estimated distance is accurate.

```yaml
# Typical starting values:
ref_power: -55    # RSSI at 1 metre
attenuation: 3    # Environment factor (2.0-4.0 typical)

# Distance calculation formula:
# distance = 10 ^ ((ref_power - rssi) / (10 * attenuation))
```

--------------------------------

### Sensor Entity Types

Source: https://context7.com/agittins/bermuda/llms.txt

Details on the various sensor entities created by Bermuda for presence and distance tracking.

```APIDOC
## Entity Types: Sensors

Bermuda creates multiple sensor entities for each tracked device. The main Area sensor shows which room the device is in, while Distance sensors show the calculated distance to proxies.

### Sensor Entities

- `sensor.<device_name>_area`              # Current area/room name (enabled by default)
- `sensor.<device_name>_distance`          # Distance to nearest proxy in meters (enabled by default)
- `sensor.<device_name>_floor`             # Current floor name (if floors configured)
- `sensor.<device_name>_nearest_scanner`   # Name of closest bluetooth proxy
- `sensor.<device_name>_nearest_rssi`      # RSSI from closest proxy (dBm)
- `sensor.<device_name>_area_last_seen`    # Last known area (persists when away)
- `sensor.<device_name>_distance_to_<proxy>`     # Distance to specific proxy (disabled by default)
- `sensor.<device_name>_unfiltered_distance_to_<proxy>`  # Raw unsmoothed distance

### Example State Attributes for Area Sensor

```yaml
state: "Living Room"
attributes:
  area_id: "living_room"
  area_name: "Living Room"
  floor_id: "ground_floor"
  floor_name: "Ground Floor"
  floor_level: 0
  current_mac: "ee:e8:37:9f:6b:54"
```
```

--------------------------------

### Per-Device Reference Power Calibration

Source: https://context7.com/agittins/bermuda/llms.txt

Fine-tune distance calculations for specific devices by setting a per-device reference power. This is useful for devices like Apple AirTags or custom beacons that may transmit at different power levels than the global default.

```yaml
# Set to 0 to use global default ref_power
# Set to specific value (e.g., -64) for this device only
```

--------------------------------

### Per-Scanner RSSI Offset Calibration

Source: https://context7.com/agittins/bermuda/llms.txt

Compensate for different scanner hardware sensitivities by configuring per-scanner RSSI offsets. Set the reference scanner's offset to 0 and adjust others to ensure consistent distance readings across all scanners.

```yaml
# Example offset configuration:
rssi_offsets:
  "aa:bb:cc:dd:ee:ff": 0      # Reference scanner (Kitchen)
  "11:22:33:44:55:66": -3     # Office proxy (weaker antenna)
  "99:88:77:66:55:44": 5      # Garage proxy (stronger signal)
```

--------------------------------

### Bermuda Sensor Entity Types

Source: https://context7.com/agittins/bermuda/llms.txt

Overview of sensor entities created by Bermuda for each tracked device, including area, distance, floor, and proximity to scanners.

```yaml
# Sensor entities created per tracked device:
sensor.<device_name>_area              # Current area/room name (enabled by default)
sensor.<device_name>_distance          # Distance to nearest proxy in meters (enabled by default)
sensor.<device_name>_floor             # Current floor name (if floors configured)
sensor.<device_name>_nearest_scanner   # Name of closest bluetooth proxy
sensor.<device_name>_nearest_rssi      # RSSI from closest proxy (dBm)
sensor.<device_name>_area_last_seen    # Last known area (persists when away)
sensor.<device_name>_distance_to_<proxy>     # Distance to specific proxy (disabled by default)
sensor.<device_name>_unfiltered_distance_to_<proxy>  # Raw unsmoothed distance
```

```yaml
# Example state attributes for Area sensor:
# state: "Living Room"
# attributes:
#   area_id: "living_room"
#   area_name: "Living Room"
#   floor_id: "ground_floor"
#   floor_name: "Ground Floor"
#   floor_level: 0
#   current_mac: "ee:e8:37:9f:6b:54"
```

--------------------------------

### Exclude entities from recorder database

Source: https://context7.com/agittins/bermuda/llms.txt

Configure the recorder to exclude frequently updating sensors like distance sensors and specific RSSI sensors to prevent database bloat. This configuration is placed in `configuration.yaml`.

```yaml
recorder:
  exclude:
    entity_globs:
      # Exclude all distance-to sensors (update frequently)
      - sensor.*_distance_to_*
      - sensor.*_unfiltered_distance_to_*
      # Exclude specific sensors
      - sensor.*_nearest_rssi
      # Keep area sensors for history (they update less often)
```

--------------------------------

### Template Sensor for Scanner Health

Source: https://context7.com/agittins/bermuda/llms.txt

Monitor the health of your scanners by creating a template sensor that displays the last seen timestamp for a specific scanner. This uses the `scanners` attribute from `sensor.bermuda_data`.

```yaml
template:
  - sensor:
      - name: "Kitchen Proxy Last Seen"
        state: >
          {% set scanners = state_attr('sensor.bermuda_data', 'scanners') %}
          {{ scanners['aa:bb:cc:dd:ee:ff']['last_seen'] | timestamp_local }}
```

--------------------------------

### Bermuda Device Tracker Entity

Source: https://context7.com/agittins/bermuda/llms.txt

The device_tracker entity created by Bermuda for Home/Away presence detection. Can be assigned to a Person for advanced presence tracking.

```yaml
# Device tracker entity:
device_tracker.<device_name>_bermuda_tracker
```

```yaml
# Example state and attributes:
# state: "home" or "not_home"
# attributes:
#   source_type: "bluetooth_le"
#   scanner: "Kitchen Proxy"
#   area: "Kitchen"
```

```yaml
# Use in automations:
automation:
  - alias: "Welcome Home"
    trigger:
      - platform: state
        entity_id: device_tracker.phone_bermuda_tracker
        to: "home"
    action:
      - service: light.turn_on
        target:
          entity_id: light.hallway
```