PolarBleApi

public protocol PolarBleApi : PolarActivityApi, PolarBleLowLevelApi, PolarDerivedMeasurementApi, PolarDeviceToHostNotificationsApi, PolarFirmwareUpdateApi, PolarH10OfflineExerciseApi, PolarLoggingApi, PolarOfflineExerciseV2Api, PolarOfflineRecordingApi, PolarOnlineStreamingApi, PolarRestServiceApi, PolarSdkModeApi, PolarSleepApi, PolarTemperatureApi, PolarTestApi, PolarTrainingSessionApi, PolarWatchFaceApi

API.

  • remove all known devices, which are not in use

    Requires

    Requires SDK feature(s): None (core API).

    Declaration

    Swift

    func cleanup()

  • Enable or disable polar filter.

    Requires

    Requires SDK feature(s): None (core API).

    Declaration

    Swift

    func polarFilter(_ enable: Bool)

    Parameters

    enable

    false disable polar filter

  • Start connecting to a nearby device. PolarBleApiObservers polarDeviceConnected is invoked when a connection is established.

    Requires

    Requires SDK feature(s): None (core API).

    Declaration

    Swift

    func startAutoConnectToDevice(_ rssi: Int, service: CBUUID?, polarDeviceType: String?) async throws

    Parameters

    rssi

    (Received Signal Strength Indicator) value is typically between -40 to -55 dBm.
    service

    optional service to contain in device advertisement prior to connection attempt
    polarDeviceType

    like H10, OH1 etc… or nil for any polar device

    Return Value

    Completes when scan for nearby device has ended and connection attempt is started and deviceConnecting callback will be invoked.

  • Request a connection to a Polar device. Invokes PolarBleApiObservers polarDeviceConnected.

    Requires

    Requires SDK feature(s): None (core API).

    Throws

    InvalidArgument if identifier is invalid polar device id or invalid uuid

    Declaration

    Swift

    func connectToDevice(_ identifier: String) throws

    Parameters

    identifier

    Polar device id printed on the sensor/device or UUID.

  • Disconnect from the current Polar device.

    Requires

    Requires SDK feature(s): None (core API).

    Throws

    InvalidArgument if identifier is invalid polar device id or invalid uuid

    Declaration

    Swift

    func disconnectFromDevice(_ identifier: String) throws

    Parameters

    identifier

    Polar device id

  • Start searching for Polar device(s).

    Requires

    Requires SDK feature(s): None (core API).

    Declaration

    Swift

    func searchForDevice() -> AsyncThrowingStream<PolarDeviceInfo, Error>

    Return Value

    AsyncThrowingStream emitting PolarDeviceInfo for every new Polar device found.

  • Start searching for compatible device(s) with a given device name prefix.

    Requires

    Requires SDK feature(s): None (core API).

    Declaration

    Swift

    @available(*, deprecated, message: "Use searchForDevice(withNameContaining: String﹚ instead.")
func searchForDevice(withRequiredDeviceNamePrefix: String?) -> AsyncThrowingStream<PolarDeviceInfo, Error>

    Parameters

    withRequiredDeviceNamePrefix

    Returned devices are filtered based on the given device name prefix. Pass nil to return all devices. Default: "Polar"

    Return Value

    AsyncThrowingStream emitting PolarDeviceInfo for every new device found.

  • Start searching for compatible device(s) with a given device name prefix.

    Requires

    Requires SDK feature(s): None (core API).

    Declaration

    Swift

    func searchForDevice(withNameContaining: String?) -> AsyncThrowingStream<PolarDeviceInfo, Error>

    Parameters

    withNameContaining

    Returned devices are filtered based on the given device name prefix. Pass nil to return all devices. Default: "Polar"

    Return Value

    AsyncThrowingStream emitting PolarDeviceInfo for every new device found.

  • Start listening the heart rate from Polar devices when subscribed. This observable listens BLE broadcast and parses heart rate from BLE broadcast. The BLE device don’t need to be connected when using this function, the heart rate is parsed from the BLE advertisement

    Requires

    Requires SDK feature(s): None (core API).

    Declaration

    Swift

    func startListenForPolarHrBroadcasts(_ identifiers: Set<String>?) -> AsyncThrowingStream<PolarHrBroadcastData, Error>

    Parameters

    identifiers

    set of Polar device ids to filter or null for a any Polar device

    Return Value

    AnyPublisher emitting multiple values

  • Check if the feature is ready.

    Requires

    Requires SDK feature(s): None (core API).

    Declaration

    Swift

    func isFeatureReady(_ identifier: String, feature: PolarBleSdkFeature) -> Bool

    Parameters

    identifier

    the identifier of the device to check.
    feature

    the feature to check for readiness.

    Return Value

    a boolean indicating whether a specific feature is ready for use on a given device.

  • Set local time to device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_time_setup

    Throws

    see PolarErrors for possible errors invoked

    Declaration

    Swift

    func setLocalTime(_ identifier: String, time: Date, zone: TimeZone) async throws

    Parameters

    identifier

    polar device id or UUID
    time

    time to set
    zone

    time zone to set
  • getLocalTime(_:) Asynchronous

    Get current time in device. Note, the H10 is not supporting time read.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_time_setup

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    @available(*, deprecated, message: "Use getLocalTimeWithZone(﹚ instead to also get timezone")
func getLocalTime(_ identifier: String) async throws -> Date

    Parameters

    identifier

    polar device id or UUID

    Return Value

    Date representing the current device time.

  • Get current time and timezone from device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_time_setup

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func getLocalTimeWithZone(_ identifier: String) async throws -> (Date, TimeZone)

    Parameters

    identifier

    Polar device id or UUID

    Return Value

    (Date, TimeZone) representing the current device time and timezone.

  • getDiskSpace(_:) Asynchronous

    Get PolarDiskSpaceData from device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func getDiskSpace(_ identifier: String) async throws -> PolarDiskSpaceData

    Parameters

    identifier

    polar device id or UUID

    Return Value

    PolarDiskSpaceData with disk space information from the device.

  • Set [LedConfig] to enable or disable blinking LEDs (Verity Sense 2.2.1+).

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_led_animation

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func setLedConfig(_ identifier: String, ledConfig: LedConfig) async throws

    Parameters

    identifier

    polar device id or UUID
    ledConfig

    to enable or disable LEDs blinking

  • Enable or disable telemetry (trace logging / diagnostics) on the device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func setTelemetryEnabled(_ identifier: String, enabled: Bool) async throws

    Parameters

    identifier

    Polar device ID or BT address
    enabled

    true = telemetry on, false = off

  • Perform factory reset to given device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    @available(*, deprecated, message: "Use doFactoryReset(_ identifier: String﹚ instead.")
func doFactoryReset(_ identifier: String, preservePairingInformation: Bool) async throws

    Parameters

    identifier

    polar device id or UUID
    preservePairingInformation

    preserve pairing information during factory reset
  • doFactoryReset(_:) Asynchronous

    Perform factory reset to given device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func doFactoryReset(_ identifier: String) async throws

    Parameters

    identifier

    polar device id or UUID

  • Perform restart to given device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    @available(*, deprecated, message: "Use doRestart(_ identifier: String﹚ instead.")
func doRestart(_ identifier: String, preservePairingInformation: Bool) async throws

    Parameters

    identifier

    polar device id or UUID
    preservePairingInformation

    preserve pairing information during restart
  • doRestart(_:) Asynchronous

    Perform restart to given device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func doRestart(_ identifier: String) async throws

    Parameters

    identifier

    polar device id or UUID

  • Set [FtuConfig] for device

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.
    • [PolarFirstTimeUseConfig] class enforces specific ranges and valid values for each parameter:
      • Gender: “Male” or “Female”
      • Height: 90 to 240 cm
      • Weight: 15 to 300 kg
      • Max heart rate: 100 to 240 bpm
      • Resting heart rate: 20 to 120 bpm
      • VO2 max: 10 to 95
      • Training background: One of the predefined levels (10, 20, 30, 40, 50, 60)
      • Typical day: One of [TypicalDay] values
      • Sleep goal: Minutes, valid range [300-660]

    Declaration

    Swift

    func doFirstTimeUse(_ identifier: String, ftuConfig: PolarFirstTimeUseConfig) async throws

    Parameters

    identifier

    polar device id or UUID
    ftuConfig

    Configuration data for the first-time use, encapsulated in [PolarFirstTimeUseConfig].
  • isFtuDone(_:) Asynchronous

    Check if the First Time Use has been done for the given Polar device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func isFtuDone(_ identifier: String) async throws -> Bool

    Parameters

    identifier

    Polar device id or UUID

    Return Value

    true when FTU has been done, false otherwise.

  • Get the user’s physical data from the given Polar device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func getUserPhysicalConfiguration(_ identifier: String) async throws -> PolarPhysicalConfiguration?

    Parameters

    identifier

    Polar device ID or UUID

    Return Value

    PolarPhysicalConfiguration if available, or nil if not set on device.

  • setWarehouseSleep(_:) Asynchronous

    Set the device to warehouse sleep state. Factory reset will be performed in order to enable the setting.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func setWarehouseSleep(_ identifier: String) async throws

    Parameters

    identifier

    polar device id or UUID
  • setHibernateMode(_:) Asynchronous

    Set hibernate mode on a given device. Hibernate puts the device into a low-power state that retains device time, unlike warehouse sleep (storage mode). Battery should last for tens, or even hundreds of days in hibernate.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func setHibernateMode(_ identifier: String) async throws

    Parameters

    identifier

    polar device id or UUID
  • turnDeviceOff(_:) Asynchronous

    Turn of device by setting the device to sleep state.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func turnDeviceOff(_ identifier: String) async throws

    Parameters

    identifier

    polar device id or UUID

  • Get Device User Settings to a device from proto in device (UDEVSET.BPB)

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func getPolarUserDeviceSettings(identifier: String) async throws -> PolarUserDeviceSettings.PolarUserDeviceSettingsResult

    Parameters

    identifier

    polar device id or UUID

    Return Value

    PolarUserDeviceSettings.PolarUserDeviceSettingsResult containing the user device settings.

  • Set Device User Settings to a device (UDEVSET.BPB)

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func setPolarUserDeviceSettings(_ identifier: String, polarUserDeviceSettings: PolarUserDeviceSettings) async throws

    Parameters

    identifier

    Polar device id or UUID
    polarUserDeviceSettings

    Collection of user device settings, like device location on user.

  • Delete data [PolarStoredDataType] from a device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func deleteStoredDeviceData(_ identifier: String, dataType: PolarStoredDataType.StoredDataType, until: Date?) async throws

    Parameters

    identifier

    Polar device ID or BT address
    dataType

    PolarStoredDataType — a specific data type that shall be deleted
    until

    Data will be deleted from device from history until this date.

  • Delete device date folders from a device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func deleteDeviceDateFolders(_ identifier: String, fromDate: Date?, toDate: Date?) async throws

    Parameters

    identifier

    Polar device id or UUID
    fromDate

    The starting date to delete date folders from
    toDate

    The ending date of last date to delete folders from

  • Delete telemetry data files from a device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func deleteTelemetryData(_ identifier: String) async throws

    Parameters

    identifier

    Polar device id or UUID
  • waitForConnection(_:) Asynchronous

    Waits for the device to establish a connection.

    Requires

    Requires SDK feature(s): None (core API).

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func waitForConnection(_ identifier: String) async throws

  • Set user device location on a device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func setUserDeviceLocation(_ identifier: String, location: Int) async throws

    Parameters

    identifier

    Polar device id or UUID
    location

    Device location as an integer value (see PolarUserDeviceSettings.DeviceLocation)

  • Set USB connection mode on a device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func setUsbConnectionMode(_ identifier: String, enabled: Bool) async throws

    Parameters

    identifier

    Polar device id or UUID
    enabled

    Boolean flag to enable or disable USB connection mode

  • Set automatic training detection settings on a device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func setAutomaticTrainingDetectionSettings(
    _ identifier: String,
    mode: Bool,
    sensitivity: Int,
    minimumDuration: Int
) async throws

    Parameters

    identifier

    Polar device id or UUID
    mode

    Boolean flag to enable or disable automatic training detection
    sensitivity

    Sensitivity level as integer, range [0, 100]. Higher values cause training to trigger more easily
    minimumDuration

    Minimum training duration in seconds

  • Set the next Daylight Saving Time (DST) settings on the device in the current timezone. Gets the current timezone from the device and sets DST value based on that.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func setDaylightSavingTime(_ identifier: String) async throws

    Parameters

    identifier

    Polar device id or UUID

  • Request multi BLE connection mode status from device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_features_configuration_service

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func getMultiBLEConnectionMode(identifier: String) async throws -> Bool

    Parameters

    identifier

    Polar device id or UUID

    Return Value

    true if multi BLE connection mode is enabled, false otherwise.

  • Enable multi BLE connection mode on a given device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_features_configuration_service

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func setMultiBLEConnectionMode(identifier: String, enable: Bool) async throws

    Parameters

    identifier

    Polar device id or UUID
    enable

    Boolean flag to enable or disable multi BLE connection mode

  • Request Sensor Initiated Security Mode status from device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_features_configuration_service

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func getSensorInitiatedSecurityMode(identifier: String) async throws -> Bool

    Parameters

    identifier

    Polar device id or UUID

    Return Value

    true if Sensor Initiated Security Mode is enabled, false otherwise.

  • Enable Sensor Initiated Security Mode on a given device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_features_configuration_service

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func setSensorInitiatedSecurityMode(identifier: String, enable: Bool) async throws

    Parameters

    identifier

    Polar device id or UUID
    enable

    Boolean flag to enable or disable Sensor Initiated Security Mode

  • Notify device of the incoming data transfer operation(s). By using this method the device will handle data transfer operations more efficiently by setting it to faster data transfer mode. It also will cause the device to flush the latest data to files giving you the most up-to-date data.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func sendInitializationAndStartSyncNotifications(identifier: String) async throws

    Parameters

    identifier

    Polar device id or UUID

  • Notify device that data transfer operations are completed. By calling this API device will set itself back to normal data transfer mode that will use less battery.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func sendTerminateAndStopSyncNotifications(identifier: String) async throws

    Parameters

    identifier

    Polar device id or UUID

  • Enable or disable AUTOS file generation on the device. AUTOS files contain 24/7 OHR data. Status of this setting can be read with getUserDeviceSettings().

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_polar_device_control

    Throws

    See PolarErrors for possible errors invoked.

    Declaration

    Swift

    func setAutomaticOHRMeasurementEnabled(_ identifier: String, enabled: Bool) async throws

    Parameters

    identifier

    Polar device ID or BT address
    enabled

    true = AUTOS files enabled, false = disabled

  • Get last received RSSI (Received Signal Strength Indicator) value for the connected device. The value is obtained from iOS BLE in 1 second interval. The value is typically between -40 to -55 dBm when the device is nearby.

    Requires

    Requires SDK feature(s): None (core API).

    Declaration

    Swift

    func getRSSIValue(_ identifier: String) throws -> Int

    Parameters

    identifier

    Polar device ID or BT address

    Return Value

    Integer value of the last received RSSI or error if the device is not connected or identifier is invalid.

  • Check if the device did disconnect from BLE due to removed pairing. If the device did disconnect due to removed pairing, the device will not be available for connection until it is paired again. It may be required to forget the device from iOS Bluetooth settings and pair it again.

    Requires

    Requires SDK feature(s): None (core API).

    Declaration

    Swift

    func checkIfDeviceDisconnectedDueRemovedPairing(_ identifier: String) throws -> Bool

    Parameters

    identifier

    Polar device ID or BT address

    Return Value

    True if was disconnected due to removed pairing, false otherwise (BLE connection is OK).

  • Common GAP (Generic access profile) observer

    Declaration

    Swift

    var observer: PolarBleApiObserver? { get set }

  • Device info observer for DIS (Device information service) and BAS (Battery service) GATT (Generic attributes) client

    Declaration

    Swift

    var deviceInfoObserver: PolarBleApiDeviceInfoObserver? { get set }

  • Device observer for HR GATT client

    Declaration

    Swift

    @available(*, deprecated, message: "The functionality has changed. Please use the startHrStreaming API to get the heart rate data ")
var deviceHrObserver: PolarBleApiDeviceHrObserver? { get set }

  • Bluetooth power state observer

    Declaration

    Swift

    var powerStateObserver: PolarBleApiPowerStateObserver? { get set }

  • Device features ready observer

    Declaration

    Swift

    var deviceFeaturesObserver: PolarBleApiDeviceFeaturesObserver? { get set }

  • Helper to check if Ble is currently powered

    Declaration

    Swift

    var isBlePowered: Bool { get }

    Return Value

    current power state

  • Optional logger set to get traces from sdk

    Declaration

    Swift

    var logger: PolarBleApiLogger? { get set }

  • Optional disable or enable automatic reconnection, by default it is enabled.

    Note that firmware update (FWU) turns on automatic reconnection automatically, and restores the setting automatically when operation completes. One should not change this setting during FWU.

    Declaration

    Swift

    var automaticReconnection: Bool { get set }

  • Request last observed battery level value from device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_battery_info

    Declaration

    Swift

    func getBatteryLevel(identifier: String) throws -> Int

    Return Value

    Returns the level of battery charging percentage 0 - 100% Will return -1 if battery battery level is not available.

  • Request last observed charging status value from device.

    Requires

    Requires SDK feature(s): PolarBleSdkFeature.feature_battery_info

    Declaration

    Swift

    func getChargerState(identifier: String) throws -> BleBasClient.ChargeState

    Return Value

    Returns ChargeState value indicating the last observed charging status of the device. Will return -1 if battery battery charging percentage level is not available.