sdk/fidl/fuchsia.bluetooth.le/periodic.fidl

// Copyright 2025 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.bluetooth.le;

using fuchsia.bluetooth as bt;
using zx;

@available(added=28)
const MAX_SUBEVENTS uint8 = 128;

/// 64-bit unique value used by the system to identify a PeriodicAdvertisingSync.
@available(added=28)
type PeriodicAdvertisingSyncId = struct {
    value uint64;
};

@available(added=28)
type PeriodicAdvertisingReport = table {
    /// The signal strength of the advertising report.
    1: rssi int8;
    /// The advertising data payload sent with this report.
    2: data ScanData;
    /// The event counter of the event that the advertising packet was received
    /// in. This can be used to reply to the report.
    3: event_counter uint16;
    /// The subevent number of the report. Only present if the packet was received in a subevent.
    4: subevent uint8;
    /// The timestamp when the report was received by the host.
    5: timestamp zx.Time;
};

/// A BIGInfo report that was received with a periodic advertisement.
@available(added=28)
type BroadcastIsochronousGroupInfoReport = table {
    1: info BroadcastIsochronousGroupInfo;
    /// The timestamp when the report was received by the host.
    2: timestamp zx.Time;
};

@available(added=28)
type PeriodicAdvertisingSyncConfiguration = table {
    /// Filter out duplicate advertising reports.
    /// Optional.
    /// Default: true
    1: filter_duplicates bool;
};

@available(added=28)
type SyncReport = flexible union {
    1: periodic_advertising_report PeriodicAdvertisingReport;
    2: broadcast_isochronous_group_info_report BroadcastIsochronousGroupInfoReport;
};

@available(added=28)
type PeriodicAdvertisingSyncError = flexible enum : uint32 {
    INITIAL_SYNCHRONIZATION_FAILED = 0;
    SYNCHRONIZATION_LOST = 1;
    NOT_SUPPORTED_LOCAL = 2;
    NOT_SUPPORTED_REMOTE = 3;
};

/// Closed by the server when the sync fails to be established or is lost.
@available(added=28)
open protocol PeriodicAdvertisingSync {
    /// Sent once when the sync is established.
    flexible -> OnEstablished(table {
        /// Used in Connection.TransferPeriodicAdvertisingSync.
        1: id PeriodicAdvertisingSyncId;
        /// The number of subevents this periodic advertisement has.
        2: subevents_count uint8;
        3: peer_id bt.PeerId;
        /// Present for Sync transfers only. Application specific data received
        /// with the transfer.
        4: service_data uint16;
        5: advertising_sid uint8;
        6: phy PhysicalLayer;
        /// Kept in interval units as profiles use this field unchanged.
        /// Range: 0x0006 to 0xFFFF
        /// Time: N × 1.25 ms
        7: periodic_advertising_interval uint16;
    });

    /// Sent either when synchronization fails to be established or when synchronization is lost (after `OnEstablished`).
    /// The protocol will close after sending this event.
    flexible -> OnError(struct {
        error PeriodicAdvertisingSyncError;
    });

    /// Returns the next advertising report(s). Hangs until the next advertisement is received.
    /// Only one call may be pending at a time.
    flexible WatchAdvertisingReport() -> (table {
        1: reports vector<SyncReport>:MAX;
    });

    /// Synchronize to subevents of this periodic advertisement.
    /// * error FAILED: The synchronization failed.
    flexible SyncToSubevents(table {
        /// A list of subevent numbers to sync to.
        1: subevents vector<uint8>:MAX_SUBEVENTS;
    }) -> () error zx.Status;

    /// The server will end the synchronization and then close the protocol.
    /// Synchronization will not be cancelled if other clients are synchronized to the same Periodic
    /// Advertisement.
    /// Synchronization can also be cancelled by closing the protocol on the client end.
    flexible Cancel();
};