Thread Network SDK for Android

The Thread Network SDK provides functionality that's similar to a digital keychain, allowing your Android apps to share Thread network credentials with Google Play services. This allows your apps to set up any Thread device from any smart home ecosystem, without exposing credentials and user data directly.

With just a few API calls, you can:

  1. Request preferred Thread network credentials from Google Play services.
  2. Set up new Thread Border Router (TBR)s and add your Thread network credentials to Google Play services.
  3. If you already have in-field TBRs, you can check if your TBRs are in the preferred network and migrate them, if necessary.

There are several user and developer journeys to consider. We'll cover most of them in this guide, along with other key features and recommended usage.

Key terminology and API concepts

Before you get started, it's helpful to understand the following terms:

  • Thread Network Credentials: Binary blob of Thread TLVs that encodes Thread Network Name, Network Key and other properties that are required by a Thread device to join a given Thread network.

  • Preferred Thread Network Credentials: The auto-selected Thread network credentials that can be shared with apps of different vendors using the getPreferredCredentials API.

  • Border Agent ID: A 16-byte globally unique ID for a TBR device. This ID is created and managed by border router vendors.

  • TBR setup app: This is your Android app that sets up new TBR devices and adds the Thread network credentials to Google Play services. Your app is the authoritative owner of the added credentials and has access to them.

Many of the Thread Network APIs return a Task that completes asynchronously. You can use addOnSuccessListener and addOnFailureListener to register callbacks for receiving the result. To learn more, refer to the Task documentation.

Credentials ownership and maintenance

The app that adds the Thread network credentials becomes the owner of the credentials, and has full permissions to access to the credentials. If you try to access credentials added by other apps, you'll receive a PERMISSION_DENIED error.

As the app owner, it's recommended that you keep credentials stored in Google Play services up-to-date when the TBR network is updated. This means adding credentials when required, updating credentials when the border router's Thread network credentials change, and removing credentials when the TBR is removed or factory reset.

Border Agent discovery

Credentials must be saved with a Border Agent ID. You'll need to make sure that your TBR setup app is able to determine the Border Agent IDs of your TBRs.

TBRs must use mDNS to advertise Thread network information, including the Network Name, Extended Pan ID, and Border Agent ID. The corresponding txt values for these attributes are nn, xp, and id, respectively.

For networks with Google Thread Border Router (gTBR)s, Google Play services automatically gets Google Thread network credentials for use.

Integrate the SDK into your Android app