Sidewalk Class Reference

Nested Declarations


                    
                    
                    Completion

Closure to be executed when a request has completed.

Declaration

Swift

public typealias Completion<T, E> = (_ result: Result<T, E>) -> Void where E : Error

Parameters


                                result

Result object indicating either a success or failure.


                    
                    
                    ScanResponse

Closure to be executed when a scan discovers a SidewalkDevice.

Declaration

Swift

public typealias ScanResponse = (_ device: SidewalkDevice) -> Void

Parameters


                                device

A SidewalkDevice object discovered during scanning.

Static Properties

logger
A SidewalkLogging to capture Amazon Sidewalk Mobile SDK logs.
Declaration
Swift

public static var logger: SidewalkLogging? { get set }

Initialization


                    
                    
                    init(authProvider:deregisterStrategy:)

Creates an instance of Sidewalk.

Declaration

Swift

public convenience init(authProvider: SidewalkAuthProviding,
                        deregisterStrategy: DeregisterStrategy = DefaultDeregisterStrategy())

Parameters

`authProvider`	A `SidewalkAuthProviding` instance that provides the auth token on demand. Amazon Sidewalk Mobile SDK does not keep a strong hold on the instance.
`deregisterStrategy`	A `DeregisterStrategy` instance that provides configurable settings for deregistration flow.

Public Functions


                    
                    
                    scan(onDeviceFound:completion:)

Starts scanning for Amazon Sidewalk devices via Bluetooth.

Scan for devices advertising AMA characteristics conforming to the Amazon Sidewalk protocol. Only one scan can be in operation at a time. Additional calls will restart scanning and return the same SidewalkCancellable instance.

Note

This object automatically calls cancel() when deinitialized.

Declaration

Swift

public func scan(onDeviceFound: @escaping ScanResponse, completion: Completion<Void, SidewalkError>? = nil) -> SidewalkCancellable

Parameters

`onDeviceFound`	A closure that executes when an Amazon Sidewalk device is found.
`completion`	An optional closure that executes when the scan completes. Currently `scan` only completes when an error occurs, closure returns `.failure(SidewalkError)` where `SidewalkError` indicates the the failure cause.

Return Value

A SidewalkCancellable object that can be used to stop scanning explicitly.


                    
                    
                    remoteCertificateProvisioningAuthenticate(request:completion:)

Authenticate existing devices already in the field onto the Amazon Sidewalk network.

This is part of the Amazon Sidewalk remote certificate provisioning process.

Note

This object automatically calls cancel() when deinitialized.

Declaration

Swift

public func remoteCertificateProvisioningAuthenticate(request: CertificateSigningRequest,
                                                      completion: @escaping Completion<AuthenticatingResponse, SidewalkError>) -> SidewalkCancellable

Parameters

`request`	Amazon Sidewalk remote certificate provisioning attested device certificate signing request (srcp_attested_device_csr).
`completion`	A closure that executes when authentication completes. Closure returns `.success(AuthenticatingResponse)` if the authentication completes successfully; otherwise `.failure(SidewalkError)` where `SidewalkError` indicates the the failure cause.

Return Value

A SidewalkCancellable object that can be used to stop remote certificate provisioning authentication.


                    
                    
                    clearAccountCache(completion:)

Clear user related data.

You should call clearAccountCache explicitly when the account credential is no longer available, e.g. user logged out.

Declaration

Swift

public func clearAccountCache(completion: @escaping Completion<Void, SidewalkError>)

Parameters


                                completion

A closure that executes when deregistration completes. Closure returns .success if the account cache is cleared successfully; otherwise .failure(SidewalkError) where SidewalkError indicates the the failure cause.

V2 Public API


                    
                    
                    secureConnectDevice(smsn:completion:)

Securely connects to a given Amazon Sidewalk device.

Connects to the given Amazon Sidewalk device via BLE, and exchanges encryption keys to create a secure connection.

You can establish a secure connection by the given SidewalkDevice.truncatedSmsn or SidewalkDevice.fullSmsn (if provided) received from scan. Amazon Sidewalk Mobile SDK would scan peripherals with the given SMSN and connect to the device if one found.

Note

This object automatically calls cancel() when deinitialized.

Declaration

Swift

public func secureConnectDevice(smsn: String, completion: @escaping Completion<SidewalkConnection, SidewalkError>) -> SidewalkCancellable

Parameters

`smsn`	The Sidewalk Manufacturing Serial Number(`SMSN`) of the device to attempt to connect to. The `smsn` could be either 32-Byte hex string or 5-Byte hex string, for instance, “F123456789”. String with invalid length or character will cause the process to fail directly.
`completion`	A closure that executes when the scan completes. Closure returns `.success(SidewalkConnection)` if the connection is successful; otherwise `.failure(SidewalkError)` where `SidewalkError` indicates the the failure cause.

Return Value

A SidewalkCancellable object that can be used to stop connecting explicitly.


                    
                    
                    registerDevice(smsn:completion:)

Registers an Amazon Sidewalk device with the Amazon Sidewalk network. If a SidewalkConnection has been established with the device prior to registration, use register(connection:completion:) instead.

You can register a device by the given SidewalkDevice.truncatedSmsn received from scan. Amazon Sidewalk Mobile SDK would scan peripherals with the given smsn and register the device if one found.

Process returns directly if the device is already registered to your account; otherwise the Amazon Sidewalk device will disconnect after registration regardless of result. Call secureConnect() to acquire a new SidewalkConnection if connection features are still required.

Connects to the Amazon Sidewalk device over Bluetooth Low-Energy (BLE). Attempts to register it for use on the Amazon Sidewalk network. Only one registration call can be in operation at a time.

Note

This object automatically calls cancel() when deinitialized.

Declaration

Swift

public func registerDevice(smsn: String,
                           completion: Completion<RegistrationDetail, SidewalkError>? = nil) -> SidewalkCancellable

Parameters

`smsn`	The Sidewalk Manufacturing Serial Number(`SMSN`) of the device to attempt to connect to. The `smsn` is a 5-Byte hex string, for instance, “F123456789”. String with invalid length or character will cause the process to fail directly.
`completion`	An optional closure that executes when registration completes. Closure returns `.success(RegistrationDetail)` if the Amazon Sidewalk device is registered successfully; otherwise `.failure(SidewalkError)` where `SidewalkError` indicates the the failure cause.

Return Value

A SidewalkCancellable object that can be used to stop registration.


                    
                    
                    registerDevice(connection:completion:)

Registers an Amazon Sidewalk device with the Amazon Sidewalk network through the BLE secure connection.

Process returns directly if the device is already registered to your account; otherwise the Amazon Sidewalk device will disconnect after registration regardless of result. Call secureConnect() to acquire a new SidewalkConnection if connection features are still required.

Attempts to register the connected SidewalkDevice for use on the Amazon Sidewalk network. Only one registration call can be in operation at a time.

Note

This object automatically calls cancel() when deinitialized.

Declaration

Swift

public func registerDevice(connection: SidewalkConnection,
                           completion: Completion<RegistrationDetail, SidewalkError>? = nil) -> SidewalkCancellable

Parameters

`connection`	A secure BLE connection with an Amazon Sidewalk device.
`completion`	An optional closure that executes when registration completes. Closure returns `.success(RegistrationDetail)` if the Amazon Sidewalk device is registered successfully; otherwise `.failure(SidewalkError)` where `SidewalkError` indicates the the failure cause.

Return Value

A SidewalkCancellable object that can be used to stop registration.


                    
                    
                    deregisterDevice(smsn:factoryReset:completion:)

Deregisters an Amazon Sidewalk device from the Amazon Sidewalk network.

Note

This object automatically calls cancel() when deinitialized.

Declaration

Swift

public func deregisterDevice(smsn: String, factoryReset: Bool, completion: @escaping Completion<Void, SidewalkError>) -> SidewalkCancellable

Parameters

`smsn`	The Sidewalk Manufacturing Serial Number(`SMSN`) of the device to attempt to connect to. The `smsn` could be either 32-Byte hex string or 5-Byte hex string. String with invalid length or character will cause the process to fail directly.
`factoryReset`	If set to true, will attempt to scan for and factory reset the device.
`completion`	A closure that executes when deregistration completes. Closure returns `.success` if the Amazon Sidewalk device is de-registered successfully; otherwise `.failure(SidewalkError)` where `SidewalkError` indicates the the failure cause.

Return Value

A SidewalkCancellable object that can be used to stop deregistration.

V1 Public API


                    
                    
                    secureConnect(device:completion:)

Securely connects to a given Amazon Sidewalk device. NOTE: This method is being deprecated in the near future, please use secureConnectDevice(smsn:completion:) instead for simpler Amazon Sidewalk device management with consistent smsn value.

Connects to the given Amazon Sidewalk device via BLE, and exchanges encryption keys to create a secure connection.

You can establish a secure connection by a given SidewalkDevice received from scan; or provide a SidewalkDeviceDescriptor, containing device nameFilter and / or endpointIdFilter. Amazon Sidewalk Mobile SDK would scan peripherals with the given descriptor and connect to the device if one found.

Note

This object automatically calls cancel() when deinitialized.

Declaration

Swift

@available(*, deprecated, message: "Please use `secureConnectDevice(smsn:completion:﹚` instead for simpler Amazon Sidewalk device management with consistent `smsn` value.")
public func secureConnect(device: SidewalkDeviceDescriptor, completion: @escaping Completion<SidewalkConnection, SidewalkError>) -> SidewalkCancellable

Parameters

`device`	The device to attempt to connect to. Empty device descriptor is not allowed and will cause the process to fail directly. `SidewalkDeviceDescriptor` with nil value or empty string for both `endpointIDFilter` and `nameFilter` will be considered as emtpy.
`completion`	A closure that executes when the scan completes. Closure returns `.success(SidewalkConnection)` if the connection is successful; otherwise `.failure(SidewalkError)` where `SidewalkError` indicates the the failure cause.

Return Value

A SidewalkCancellable object that can be used to stop connecting explicitly.


                    
                    
                    register(device:completion:)

Registers an Amazon Sidewalk device with the Amazon Sidewalk network. If a SidewalkConnection has been established with the device prior to registration, use register(connection:completion:) instead. NOTE: This method is being deprecated in the near future, please use registerDevice(smsn:completion:) instead for simpler Amazon Sidewalk device management with consistent smsn value.

You can register a device by a given SidewalkDevice received from scan; or provide a SidewalkDeviceDescriptor, containing device nameFilter and / or endpointIdFilter. Amazon Sidewalk Mobile SDK would scan peripherals with the given descriptor and register the device if one found.

Deregister with factory reset and re-registration will be performed if the device is already registered to your account. The Amazon Sidewalk device will disconnect after registration regardless of result. Call secureConnect() to acquire a new SidewalkConnection if connection features are still required.

Connects to the Amazon Sidewalk device over Bluetooth Low-Energy (BLE). Attempts to register it for use on the Amazon Sidewalk network. Only one registration call can be in operation at a time.

Note

This object automatically calls cancel() when deinitialized.

Declaration

Swift

@available(*, deprecated, message: "Please use `registerDevice(smsn:completion:﹚` instead for simpler Amazon Sidewalk device management with consistent `smsn` value.")
public func register(device: SidewalkDeviceDescriptor,
                     completion: Completion<(WirelessDeviceID, SidewalkID), SidewalkError>? = nil) -> SidewalkCancellable

Parameters


                                device

Device to attempt registration for. Empty device descriptor is not allowed and will cause the process to fail directly. SidewalkDeviceDescriptor with nil value or empty string for both endpointIDFilter and nameFilter will be considered as emtpy.


                                completion

An optional closure that executes when registration completes. This closure provides two parameters. Closure returns .success(WirelessDeviceID, SidewalkID) if the Amazon Sidewalk device is registered successfully, where the first parameter is the WirelessDeviceID String to be used with the Sailboat service, the second parameter is the SidewalkID; otherwise .failure(SidewalkError) where SidewalkError indicates the the failure cause.

Return Value

A SidewalkCancellable object that can be used to stop registration.


                    
                    
                    register(connection:completion:)

Registers an Amazon Sidewalk device with the Amazon Sidewalk network through the BLE secure connection. NOTE: This method is being deprecated in the near future, please use registerDevice(connection:completion:) instead for simpler Amazon Sidewalk device management with consistent smsn value.

Deregister with factory reset and re-registration will be performed if the device is already registered to your account. The Amazon Sidewalk device will disconnect after registration regardless of result. Call secureConnect() to acquire a new SidewalkConnection if connection features are still required.

Attempts to register the connected SidewalkDevice for use on the Amazon Sidewalk network. Only one registration call can be in operation at a time.

Note

This object automatically calls cancel() when deinitialized.

Declaration

Swift

@available(*, deprecated, message: "Please use `registerDevice(connection:completion:﹚` instead for simpler Amazon Sidewalk device management with consistent `smsn` value.")
public func register(connection: SidewalkConnection,
                     completion: Completion<(WirelessDeviceID, SidewalkID), SidewalkError>? = nil) -> SidewalkCancellable

Parameters


                                connection

A secure BLE connection with an Amazon Sidewalk device.


                                completion

An optional closure that executes when registration completes. Closure returns .success(WirelessDeviceID, SidewalkID) if the Amazon Sidewalk device is registered successfully, where the first parameter is the WirelessDeviceID String to be used with the Sailboat service, the second parameter is the SidewalkID; otherwise .failure(SidewalkError) where SidewalkError indicates the the failure cause.

Return Value

A SidewalkCancellable object that can be used to stop registration.


                    
                    
                    deregister(sidewalkID:factoryReset:completion:)

Deregisters an Amazon Sidewalk device from the Amazon Sidewalk network. NOTE: This method is being deprecated in the near future, please use deregisterDevice(smsn:factoryReset:completion:) instead for simpler Amazon Sidewalk device management with consistent smsn value.

Note

This object automatically calls cancel() when deinitialized.

Declaration

Swift

@available(*, deprecated, message: "Please use `deregisterDevice(smsn:factoryReset:completion:﹚` instead for simpler Amazon Sidewalk device management with consistent `smsn` value.")
public func deregister(sidewalkID: SidewalkID, factoryReset: Bool, completion: @escaping Completion<Void, SidewalkError>) -> SidewalkCancellable

Parameters

`sidewalkID`	A device’s ID to deregister.
`factoryReset`	If set to true, will attempt to scan for and factory reset the device.
`completion`	A closure that executes when deregistration completes. Closure returns `.success` if the Amazon Sidewalk device is de-registered successfully; otherwise `.failure(SidewalkError)` where `SidewalkError` indicates the the failure cause.

Return Value

A SidewalkCancellable object that can be used to stop deregistration.