LowpanInterface

public class LowpanInterface
extends Object

java.lang.Object
   ↳ com.google.android.things.lowpan.LowpanInterface


Class for managing a specific Low-power Wireless Personal Area Network (LoWPAN) interface.

Summary

Nested classes

class LowpanInterface.Callback

Callback base class for LowpanInterface

Constants

int ROLE_DETACHED

Detached role.

int ROLE_END_DEVICE

End-device role.

int ROLE_LEADER

Leader role.

int ROLE_ROUTER

Router role.

int STATE_ATTACHED

Attached state.

int STATE_ATTACHING

Attaching state.

int STATE_DISABLED

Disabled state.

int STATE_FAULT

Fault state.

int STATE_OFFLINE

Offline state.

Public methods

LowpanScanner createScanner()

Creates a new LowpanScanner object for this interface.

void form(LowpanProvisioningParams params)

Forms a new network with the given network information optional credential.

LowpanProvisioningParams getLowpanProvisioningParams(boolean includeCredential)

Fetches the current LowpanProvisioningParams.

String getName()

Returns the name of this network interface.

int getRole()

Returns the current role of the interface.

int getState()

Returns interface state.

String[] getSupportedNetworkTypes()

Returns the types of networks supported by this interface.

boolean isEnabled()

Indicates if the interface is enabled or disabled.

boolean isProvisioned()

Indicates if this interface is currently provisioned for a network.

void join(LowpanProvisioningParams params)

Attempts to join a pre-existing nearby network with the given provisioning parameters.

void leave()

Bring down the network interface and forget all non-volatile details about the current network.

void provision(LowpanProvisioningParams params)

Provision the interface for the network described by identity and credential.

void registerCallback(Handler handler, LowpanInterface.Callback cb)

Registers a subclass of LowpanInterface.Callback to receive events.

void registerCallback(LowpanInterface.Callback cb)

Registers a subclass of LowpanInterface.Callback to receive events.

void reset()

Resets this network interface, returning all volatile state to default values.

void setEnabled(boolean enabled)

Enables or disables the interface.

void unregisterCallback(LowpanInterface.Callback cb)

Unregisters a previously registered callback class.

Inherited methods

From class java.lang.Object

Constants

ROLE_DETACHED

int ROLE_DETACHED

Detached role. The interface is not currently participating on the network, either because it cannot find a parent or the interface is not currently provisioned.

See also:

Constant Value: 0 (0x00000000)

ROLE_END_DEVICE

int ROLE_END_DEVICE

End-device role. End devices do not route traffic on behalf of other nodes.

See also:

Constant Value: 1 (0x00000001)

ROLE_LEADER

int ROLE_LEADER

Leader role.

On Thread networks, for each partition/fragment one router is designated as the "leader", which means that it is considered authorative for all network data. In most cases this role can be considered as a synonym to ROLE_ROUTER.

Not all network types support this role.

See also:

Constant Value: 3 (0x00000003)

ROLE_ROUTER

int ROLE_ROUTER

Router role. Routers help route traffic around the mesh network.

Note that this role is independent of the device being a "border router".

Not all network types support this role.

See also:

Constant Value: 2 (0x00000002)

STATE_ATTACHED

int STATE_ATTACHED

Attached state.

This state indicates that we are an active participant on a network that has at least one other peer node in range.

The Interface can enter this state from STATE_ATTACHING.

Constant Value: 3 (0x00000003)

STATE_ATTACHING

int STATE_ATTACHING

Attaching state.

The interface enters this state when it starts the process of trying to find other nodes so that it can attach to any pre-existing network fragment, or when it is in the process of calculating the optimal values for unspecified parameters when forming a new network.

The interface may stay in this state for a prolonged period of time (or may spontaneously enter this state from STATE_ATTACHED) if the underlying network technology is heirarchical (like ZigBee IP) or if the device role is that of an "end-device" (ROLE_END_DEVICE). This is because such roles cannot create their own network fragments.

Constant Value: 2 (0x00000002)

STATE_DISABLED

int STATE_DISABLED

Disabled state.

The interface will enter this state when the interface is disabled. In this state, most of the methods in LowpanInterface will fail with InterfaceDisabledException.

This state is controlled by the method setEnabled(boolean).

This state can be entered spontaneously from any other state.

Constant Value: 6 (0x00000006)

STATE_FAULT

int STATE_FAULT

Fault state.

The interface will enter this state when the driver has detected some sort of problem from which it was not immediately able to recover.

This state can be entered spontaneously from any other state. Calling reset() will cause the device to return to the STATE_OFFLINE state.

Constant Value: 4 (0x00000004)

STATE_OFFLINE

int STATE_OFFLINE

Offline state.

This is the initial state of the LoWPAN interface when the underlying driver starts. In this state the NCP is idle and not connected to any network.

This state can be explicitly entered by calling reset(), leave(), or setUp(false), with the later two only working if we were not previously in the STATE_FAULT state.

Constant Value: 0 (0x00000000)

Public methods

createScanner

LowpanScanner createScanner ()

Creates a new LowpanScanner object for this interface.

This method allocates a new unique object for each call.

Returns
LowpanScanner Newly created LowpanScanner object.

See also:

form

void form (LowpanProvisioningParams params)

Forms a new network with the given network information optional credential. Unspecified fields in the network information will be filled in with reasonable values. If the network credential is unspecified, one will be generated automatically.

Upon success, the interface will be up and attached to the newly formed network.

This method returns immediately. You can be notified when this process is complete by adding a callback and handling the following:

Parameters
params LowpanProvisioningParams: The identity and credential of the network to form. The object doesn't need to be fully specified: by leaving specific fields blank (like the channel, xpanid, credential, etc), you are indicating that you want the interface to choose reasonable non-conflicting values.

Throws
NullPointerException if params is null.
InterfaceDisabledException if the interface was disabled.
LowpanException

getLowpanProvisioningParams

LowpanProvisioningParams getLowpanProvisioningParams (boolean includeCredential)

Fetches the current LowpanProvisioningParams.

Parameters
includeCredential boolean: false if the LowpanCredential should be omitted, true if the LowpanCredential should be included. If included, the READ_LOWPAN_CREDENTIAL permission is required.

Returns
LowpanProvisioningParams The current LowpanProvisioningParams, or null if the interface is not provisioned.

Throws
SecurityException if includeCredential was set to true but the process didn't have the READ_LOWPAN_CREDENTIAL permission.

getName

String getName ()

Returns the name of this network interface.

Returns
String

getRole

int getRole ()

Returns the current role of the interface.

If the interface is disabled, always returns ROLE_DETACHED.

Returns
int

getState

int getState ()

Returns interface state.

If the interface is disabled, always returns STATE_OFFLINE.

Returns
int The current state of the interface.

getSupportedNetworkTypes

String[] getSupportedNetworkTypes ()

Returns the types of networks supported by this interface.

Returns
String[]

Throws
LowpanException

isEnabled

boolean isEnabled ()

Indicates if the interface is enabled or disabled.

Returns
boolean

isProvisioned

boolean isProvisioned ()

Indicates if this interface is currently provisioned for a network.

Returns
boolean

join

void join (LowpanProvisioningParams params)

Attempts to join a pre-existing nearby network with the given provisioning parameters.

Upon success, the interface will be up and attached to the newly joined network.

This method returns immediately. You can be notified when this process is complete by adding a callback and handling the following:

Parameters
params LowpanProvisioningParams: The identity and credential of the network to join.

Throws
InterfaceDisabledException if the interface was disabled.
IllegalArgumentException if params is missing a credential.
NullPointerException if params is null.
LowpanException

leave

void leave ()

Bring down the network interface and forget all non-volatile details about the current network.

This method returns immediately. You can be notified when this process is complete by adding a callback and handling the following:

If the interface was not previously provisioned, calling this method does nothing.

Throws
InterfaceDisabledException if the interface was disabled.
LowpanException

provision

void provision (LowpanProvisioningParams params)

Provision the interface for the network described by identity and credential. This is similar to join(LowpanProvisioningParams), except that (assuming the identity and credential are valid) it will always succeed, even if there are no peers nearby.

This method returns immediately. You can be notified when this process is complete by adding a callback and handling the following:

Parameters
params LowpanProvisioningParams: The identity and credential of the network to provision the interface for.

Throws
InterfaceDisabledException if the interface was disabled.
IllegalArgumentException if params is missing a credential.
NullPointerException if params is null.
LowpanException

registerCallback

void registerCallback (Handler handler, 
                LowpanInterface.Callback cb)

Registers a subclass of LowpanInterface.Callback to receive events.

Parameters
handler Handler: If not null, events will be dispatched via the given handler object. If null, the thread upon which events will be dispatched is unspecified.

cb LowpanInterface.Callback: Subclass of LowpanInterface.Callback which will receive events.

registerCallback

void registerCallback (LowpanInterface.Callback cb)

Registers a subclass of LowpanInterface.Callback to receive events.

The thread upon which events will be dispatched is unspecified.

Parameters
cb LowpanInterface.Callback: Subclass of LowpanInterface.Callback which will receive events.

reset

void reset ()

Resets this network interface, returning all volatile state to default values. Any information stored in non-volatile memory is preserved. If the interface was attached to a network, this method will cause the interface to detach. In that case, once the interface has finished initialization the interface will attempt to reattach to the previous network.

This method is the only way to clear STATE_FAULT.

This method returns immediately. You can be notified when this process is complete by adding a callback and handling the following:

Throws
InterfaceDisabledException if the interface was disabled.
LowpanException

See also:

setEnabled

void setEnabled (boolean enabled)

Enables or disables the interface.

Parameters
enabled boolean

Throws
LowpanException

unregisterCallback

void unregisterCallback (LowpanInterface.Callback cb)

Unregisters a previously registered callback class.

Parameters
cb LowpanInterface.Callback: Subclass of LowpanInterface.Callback which was previously registered to receive events.