Amazon Sidewalk Mobile SDK Overview

The Amazon Sidewalk Mobile SDK includes the library, supporting documentation, and a sample app to teach you how to use Amazon Sidewalk functionalities.

Amazon Sidewalk Mobile SDK library

Amazon Sidewalk Mobile SDK is for mobile developers who want to build customized Amazon Sidewalk applications. To integrate Amazon Sidewalk Mobile SDK with your app, follow the step-by-step guide given in the link below to set up your app.

Amazon Sidewalk Mobile SDK sample app

Amazon Sidewalk Mobile SDK Sample App demonstrates how to integrate Amazon Sidewalk Mobile SDK into your app with basic API call flows. To try out the Amazon Sidewalk Mobile SDK functionalities and to run the sample app, follow the step-by-step guide given in the link below.

Topics

What is Amazon Sidewalk Mobile SDK?
Common Amazon Sidewalk User Activities and High Level API Call Flow
Amazon Sidewalk Mobile SDK API Overview

What is Amazon Sidewalk Mobile SDK?

Amazon Sidewalk Mobile SDK provides a one-stop solution for everything related to Amazon Sidewalk on mobiles. Amazon Sidewalk Mobile SDK has its own Bluetooth and network stack, and is able to communicate to both the edge device (over BLE) and the Amazon Sidewalk cloud. Currently, the Amazon Sidewalk Mobile SDK exports the underlying Alexa Mobile Accessory (AMA) BLE stack, and allows apps to scan for AMA beaconing devices and then provision these devices over AMA to use the Amazon Sidewalk network.

The Amazon Sidewalk Mobile SDK handles the interaction between the Amazon Sidewalk cloud, edge device, exchanging keys and registering the edge device, so that the edge device can connect to the Amazon Sidewalk network via Amazon Sidewalk Gateways. Authentication is provided via integration with Login with Amazon (LWA).

The Amazon Sidewalk Mobile SDK is designed to assist developers in integrating common Amazon Sidewalk user controls into developers’ own mobile apps for controls such as the endpoint registration and de-registration. Amazon Sidewalk Mobile SDK is able to communicate to both the endpoint (over BLE) and the Amazon Sidewalk cloud.

Amazon Sidewalk Mobile SDK apps are required to integrate with Login with Amazon (LWA) SDK to collect a user Auth Token for issuing Amazon Sidewalk controls. The iOS Mobile SDK also requires OpenSSL. More details can also be found in Getting Started with Amazon Sidewalk Mobile SDK Android and iOS sections.

NOTE

For customers interacting with Amazon Sidewalk devices through Amazon Sidewalk Mobile SDK, there is a prerequisite to link their Amazon account to a Ring account, where the Amazon account is the one customer logs in to LWA and provides Auth Token for Amazon Sidewalk Mobile SDK. If the Amazon account is not linked with a Ring account, the Amazon Sidewalk cloud does not return registered devices.

To link an Amazon account with a Ring account, please visit url: https://account.ring.com/account/control-center/account-linking. Follow below steps:

Create / Signin to a Ring account
Go to ‘Amazon Account Linking’
Click ‘Link’ inside Amazon Account Linking
Enter Ring account credentials and click on ‘LINK ACCOUNT’
Enter Amazon account credentials.

The Amazon Account will be successfully linked to the Ring account.

Please check your account linking before testing with Mobile SDK, and inform your customer about the action required while releasing your app integrated with Sidewalk Mobile SDK.

Common Amazon Sidewalk User Activities and High Level API Call Flow

End User Activity	Short Description	High Level API Call Flow
Endpoint registration	User registers the endpoint to the Amazon Sidewalk network through a mobile app.	Start `scan()`. Select a device from `scan()` result array. Call `registerDevice()` with the Sidewalk Manufacturing Serial Number(`SMSN`) string of the endpoint to the Amazon Sidewalk network.
Connecting directly to an endpoint	User connects directly to an endpoint to write/receive packets directly.	Start `scan()`. Select a device from `scan()` result array. Call `secureConnectDevice()` with the Sidewalk Manufacturing Serial Number(`SMSN`) string of the endpoint, which returns a `SidewalkConnection`. `subscribe()` to listen to device messages on `SidewalkConnection`. `write()` payload as required.
Endpoint deregistration	User deregisters the endpoint from the Amazon Sidewalk network through a mobile app.	Call `deregisterDevice()` with the Sidewalk Manufacturing Serial Number(`SMSN`) string of the endpoint.
Upload device metrics to the Amazon Sidewalk cloud	User connects directly to an endpoint to collect device metrics and upload them to the Amazon Sidewalk cloud. These metrics can help the Amazon Sidewalk team in diagnosing endpoint device connectivity issues, providing supplementary support alongside endpoint logs. NOTE: It’s recommended to notify customer before calling this API.	Start `scan()`. Select a device from `scan()` result array. Call `secureConnectDevice()` with the Sidewalk Manufacturing Serial Number(`SMSN`) string of the endpoint, which returns a `SidewalkConnection`. `uploadDeviceMetrics()` to collect device metrics and upload them to the Amazon Sidewalk cloud.

Amazon Sidewalk Mobile SDK API Overview

API Call	Description
Sidewalk	- main entry point for interactions
`scan()`	API scans for available Amazon Sidewalk devices within the mobile BLE range. This function call puts the smartphone into scanning mode, and the operation must be cancelled for the API to stop scanning.
`secureConnectDevice()`	Creates a secure connection with the given Sidewalk Manufacturing Serial Number(`SMSN`) string of an Amazon Sidewalk device via BLE, and exchanges encryption keys to create a secure connection. This connection allows write and subscribe for communication.
`registerDevice()`	API registers the endpoint to Amazon Sidewalk network. By providing different parameters, you can register an endpoint by given device Id, name, or SidewalkConnection.
`deregisterDevice()`	API deregisters the endpoint from Amazon Sidewalk network.
`clearAccountCache()`	Clears user related data. You should call `clearAccountCache()` explicitly when the account credential is no longer available, e.g. user logged out.
SidewalkConnection	- handling a secure connection
`subscribe()`	Subscribes to BLE payloads sent by the device.
`write()`	Writes a BLE payload to the device.
`isAvailable()`	Checks whether the connection is available to write and subscribe messages.
`startCoverageTest()`	Starts coverage test on the connected Amazon Sidewalk device to get Amazon Sidewalk coverage information near the Amazon Sidewalk device.
`uploadDeviceMetrics()`	Uploads device metrics to the Amazon Sidewalk cloud.
SidewalkAuthProviding	- authentication provider for Sidewalk
`getToken()`	API retrieves and refreshes the Auth Token via Login with Amazon for communication with Amazon Sidewalk cloud.
SidewalkLogging	- log output for Sidewalk
`log()`	Setup `Sidewalk.logger` with your implementation of `SidewalkLogging` interface and the `log()` method to get logs from Amazon Sidewalk Mobile SDK.