SidewalkConnection

public class SidewalkConnection

Represents a BLE connection with an Amazon Sidewalk device.

This class is created when the Amazon Sidewalk Mobile SDK is able to create a secure connection with an Amazon Sidewalk device.

The connection might be terminated by Amazon Sidewalk device if no traffic for an amount of time to prevent BLE resources occupation. The time is configurable by Amazon Sidewalk device.

Before releasing SidewalkConnection object, you should make sure the ongoing operation like startCoverageTest is properly cancelled by calling cancel() on the corresponding SidewalkCancellable object and waiting for the corresponding completion closure to be invoked. Otherwise, cancel() operation may be interrupted since the connection with Amazon Sidewalk device is disconnected.

Note

This object automatically disconnects when deinitialized.

  • Constants defined and used in Amazon Sidewalk Mobile SDK for SidewalkConnection.uploadDeviceMetrics settings.

    See more

    Declaration

    Swift

    public enum UploadDeviceMetricsConstants

Public Methods

  • Availability of the Amazon Sidewalk connection.

    Return true if the connection is available to write/subscribe messages, false otherwise.

    Declaration

    Swift

    public func isAvailable() -> Bool

  • Subscribe to SidewalkMessages received from the Amazon Sidewalk connection and get notification from the completion callback on connection termination.

    Monitors the Amazon Sidewalk device over BLE, calls onMessageReceived for SidewalkMessages destined to the mobile service, and calls completion when the connection terminates to inform error on failure case.

    Note

    This object automatically calls cancel() when deinitialized.

    Declaration

    Swift

    public func subscribe(onMessageReceived: @escaping MessageResponse,
                      completion: Sidewalk.Completion<Void, SidewalkError>?) -> SidewalkCancellable

    Parameters

    onMessageReceived

    A closure that executes when a message destined for the mobile device is received.
    completion

    An optional closure that executes when the subscription terminates on D2D disconnection.

    Return Value

    A SidewalkCancellable object that can be used to cancel the subscription,

  • Writes a SidewalkMessage to an Amazon Sidewalk device.

    Writes a SidewalkMessage over the secure BLE connection.

    Note

    This object automatically calls cancel() when deinitialized.

    Declaration

    Swift

    public func write(message: SidewalkMessage, completion: @escaping Sidewalk.Completion<Void, SidewalkError>) -> SidewalkCancellable

    Parameters

    message

    The SidewalkMessage to be written. Empty message is not allowed.
    completion

    An optional closure that executes when the write completes.

    Return Value

    A SidewalkCancellable placeholder object for future extensibility to cancel the write. Note that the cancel() here currently will not affect the write functionality at all.

  • Uploads device metrics to Amazon Sidewalk cloud.

    Call this function to upload device metrics of a registered device to Amazon Sidewalk cloud. This does not include metrics from the mobile device.

    Note

    This object automatically calls cancel() when deinitialized.

    Declaration

    Swift

    public func uploadDeviceMetrics(timeout: TimeInterval = UploadDeviceMetricsConstants.defaultGetMetricTimeout,
                                completion: Sidewalk.Completion<Void, SidewalkError>?) -> SidewalkCancellable

    Parameters

    timeout

    An optional value to indicate the amount of time(second) to wait for EACH metric uplink from Amazon Sidewalk device. The total amount of processing time would be dependent with the number of metrics sent from Amazon Sidewalk device. Note that the timeout variable is exposed explicitly for the flexibility of communication time cost between mobile and Amazon Sidewalk device. Timeout value should be a positive value within the range of (0, 10] in UploadDeviceMetricsConstants. Non-positive value will be replaced with default timeout of 3. Value exceeding the maximum of 10 will be replaced with 10
    completion

    An optional closure that executes when the transaction of all metrics are received or exceeds the expected time limit. Calls [.success] if all metrics are successfully uploaded; otherwise [.failure].

    Return Value

    A SidewalkCancellable object that can be used to cancel the subscription. Note that the cancel() here only cancels the completion result but not the upload process.

  • Start coverage test on the device in the connection.

    When coverage test is started, Amazon Sidewalk device will start ping-pong tests, and send corresponding logs to mobile. During the progress, Amazon Sidewalk Mobile SDK will provide update via onProgressUpdated closure with event. When coverage test is ended, Amazon Sidewalk Mobile SDK will collect report from Amazon Sidewalk device, and send the result via completion closure.

    To stop the coverage test properly after this method is called, you should call cancel() on the returned SidewalkCancellable, and hold the SidewalkConnection object until the completion closure passed in this method is invoked.

    Note

    This object automatically calls cancel() when deinitialized.

    Declaration

    Swift

    public func startCoverageTest(option: SidewalkCoverageTestOption,
                              onProgressUpdated: ((SidewalkCoverageTestEvent) -> Void)?,
                              completion: @escaping Sidewalk.Completion<SidewalkCoverageTestReport, SidewalkError>) -> SidewalkCancellable

    Parameters

    option

    The options to be applied for the test.
    onProgressUpdated

    The closure to be invoked whenever there is an event, indicated by SidewalkCoverageTestEvent, during the progress of coverage test.
    completion

    The closure to be invoked when the coverage test is ended with success or failure. The parameter is a Result object including the report (SidewalkCoverageTestReport) of the coverage test, or the error (SidewalkError) occurred during the progress.

    Return Value

    Cancellable task. When cancelled, the ping-pong process in the test will be stopped immediately. A report will still be collected and then sent via completion.

  • Disconnects from the SidewalkDevice.

    This is also called automatically by the SDK when the SidewalkConnection class is de-initialized.

    Declaration

    Swift

    public func disconnect()