LoWPAN

On these networks, Android devices can communicate directly with other peer
devices, even ultra-low power battery operated nodes that may not have WiFi or
Bluetooth connectivity (such as door locks and window sensors). These IPv6 mesh
networks are secure and resilient with no single point of failure.

The Android Things LoWPAN API enables applications to perform the following
functions:

Scan for nearby supported low-power wireless mesh networks

Join a specific low-power wireless mesh network

Form a new low-power wireless mesh network

In order for devices to participate on the same network they must all share the
same provisioning parameters, consisting of the network identity and the
network credential. If either of these parameters are different, devices
will be unable to communicate with each other.

Hardware considerations

To develop LoWPAN applications, you will need a radio module running as an
OpenThread Network Co-Processor (NCP). One recommended
kit is the nRF52840-PDK. You will
need a standard micro USB-B to USB-A cable to connect this kit to your Android
Things device.

To get OpenThread running on the development kit, follow these
instructions.

Managing the interface connection

In order for the device to be associated with a LoWPAN network, you need to get
an instance of class LowpanInterface. Class LowpanManager does this for you.
Your application can use this manager to look up LowpanInterface objects on
your Android device.

Provisioning parameters, such as the network identity information
(LowpanIdentity) and the associated credential (LowpanCredential), are
stored persistently and are automatically restored at boot-up. To forget these
parameters, you must explicitly abandon the network by calling leave().

Once the scan is finished, you should have a list of available networks.

Note: LoWPAN beacons can be associated wtih location information. In order to
use LowpanScanner, your app must declare the
ACCESS_COARSE_LOCATION
permission.

Joining an existing network

Use the join() method of LowpanInterface when you know there is at least one
other device in range on the network you are trying to join and you want the
application to fail hard if it can't find it.

First, you need a LowpanProvisioningParams object. Create one using a
LowpanIdentity object and a LowpanCredential object. Call the join()
method of class LowpanInterface with the provisioning parameters
(LowpanProvisioningParams) to create the network.

You can also obtain the LowpanIdentity object from a scan of available
networks (see Scanning for nearby networks for the callback
definitions).

For the LowpanCredential object, you will need to obtain the credential
out-of-band (for example, through wifi or the cloud) or supply your own. This is
known as out-of-band commissioning.

Creating a new network

Use form() to create a new, empty network with only the device on it. Many of
the provisioning fields can be autogenerated with reasonable, non-conflicting
defaults. When you use form(), there must not be an existing partition in
range with the same network parameters (LowpanIdentity) or else the operation
will fail.

The LowpanProvisioningParams object passed to form() may be underspecified:
fields in LowpanInterface that aren't specified will be filled in with
reasonable, non-conflicting defaults. If a LowpanCredential isn't in the
provision, a new one will be securely generated.

Call the form() method of class LowpanInterface with the provisioning
parameters (LowpanProvisioningParams) to create the network.

private void formNetwork(LowpanInterface lowpanInterface) throws LowpanException {
/* We are only specifying the network name here. By
* doing this we allow the interface to pick reasonable
* defaults for other required fields. If we specified
* our own values for those fields, they would be used
* instead.
*/
final LowpanIdentity identity = new LowpanIdentity.Builder()
.setName("MyNetwork")
.build();
/* Not specifying a LowpanCredential here tells “form()”
* that we want the interface to generate the master key
* for us.
*/
final LowpanProvisioningParams provision = new LowpanProvisioningParams.Builder()
.setLowpanIdentity(identity)
.build();
lowpanInterface.form(provision);
}

Monitoring connectivity and state changes

Attach a LowpanInterface.Callback to listen for state changes on a specific
interface. The onLowpanIdentityChanged() method reports a successful attempt
to create or join a network. If an
error occurs during this process, it is reported through the
onProvisionException() method.

You can use onStateChanged() to react to low-level events from the hardware,
such as when an interface is enabled or a fault has occurred and the
LowpanInterface needs to be reset.