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
See moreSidewalkConnection.uploadDeviceMetrics
settings.Declaration
Swift
public enum UploadDeviceMetricsConstants
-
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
SidewalkMessage
s 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
forSidewalkMessage
s destined to the mobile service, and callscompletion
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 10completion
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 viacompletion
closure.To stop the coverage test properly after this method is called, you should call
cancel()
on the returnedSidewalkCancellable
, and hold theSidewalkConnection
object until thecompletion
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()