Skip to content

FR-8.3: Background scanning support #38

Description

@itsniper

Goal

Add background scanning support so ReliaBLE can continue discovering peripherals while the integrating app is backgrounded, complying with iOS background-execution rules.

Addresses PRD FR-8.3:

  • FR-8.3.1 — Implement background scanning capabilities, ensuring compliance with iOS background execution rules.
  • FR-8.3.2 — Notify the integrating app when new devices come into range even when the app is not in the foreground, using appropriate iOS background modes like bluetooth-central.

High-level summary

Foreground scanning is already complete (FR-8.1, service-filtered scanning + discovery stream). This issue extends that foundation to keep delivering discovery events while the app is in the background:

  • Document and support the bluetooth-central background mode requirement for integrating apps (Info.plist / capabilities).
  • Honor CoreBluetooth's background-scanning constraints: service-UUID filtering is required in the background, advertisement data is reduced, and discovery callbacks are coalesced/throttled by the OS.
  • Surface background-discovered peripherals through the existing discovery streams so apps don't need a separate code path.
  • Account for state restoration considerations (CBCentralManagerOptionRestoreIdentifierKey) — at minimum document the path; full state-restoration may be a follow-up.

Sketch of scope

  • Enable/verify background-compatible scan options (service-filtered scans only when backgrounded).
  • Optional ReliaBLEConfig flag for background scanning + restoration identifier.
  • Demo app: document required background mode + show background discovery (delegate to a sub-agent per Demo/CLAUDE.md).
  • Tests: validate that background-mode scan options are applied correctly through the mock harness where feasible.

Notes / constraints

  • Builds directly on the completed FR-8.1 scanning foundation; relatively low dependency risk.
  • Energy efficiency in background scanning is tracked separately (NFR-7.1 / NFR-8.1) but should be kept in mind.

Acceptance criteria

  • Scanning continues to emit discovery events while the app is backgrounded (with service-UUID filtering applied).
  • Required iOS background-mode setup is documented for integrating apps.
  • Behavior degrades gracefully / per Apple guidelines when backgrounded (filtered scans, coalesced callbacks).
  • Discovery events flow through the existing discovery stream — no separate background API surface.

References

  • PRD: FR-8.3 (FR-8.3.1, FR-8.3.2)
  • Foundation: FR-8.1 (FR-8.1: Specific Service Scanning #3, completed) — service-filtered scanning + discovery stream
  • Architecture: AGENTS.md (@BluetoothActor, mock harness); Demo work per Demo/CLAUDE.md

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions