Summary: Nested Classes | Constants | Methods | Inherited Methods | [Expand All]

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.

See also:

• LowpanManager
• LowpanScanner
• LowpanProvisioningParams
• LowpanIdentity
• LowpanCredential

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 Object clone() Creates and returns a copy of this object. boolean equals(Object obj) Indicates whether some other object is "equal to" this one. void finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. final Class<?> getClass() Returns the runtime class of this Object. int hashCode() Returns a hash code value for the object. final void notify() Wakes up a single thread that is waiting on this object's monitor. final void notifyAll() Wakes up all threads that are waiting on this object's monitor. String toString() Returns a string representation of the object. final void wait(long millis, int nanos) Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed. final void wait(long millis) Causes the current thread to wait until either another thread invokes the notify() method or the notifyAll() method for this object, or a specified amount of time has elapsed. final void wait() Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this 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:

• getRole()

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:

• getRole()

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:

• getRole()

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:

• getRole()

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.

See also:

• STATE_ATTACHING
• getState()

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.

See also:

• STATE_ATTACHED
• getState()

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.

See also:

• getState()
• STATE_OFFLINE

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.

See also:

• getState()
• STATE_OFFLINE

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.

See also:

• getState()
• STATE_FAULT

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:

• LowpanScanner

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:

• onProvisionException(Exception), which is called to report errors.
• onStateChanged(int), which will transition to the state STATE_ATTACHED upon success.

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

See also:

• onProvisionException(Exception)
• join(LowpanProvisioningParams)
• provision(LowpanProvisioningParams)

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.

See also:

• LowpanProvisioningParams

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

See also:

• ROLE_DETACHED
• ROLE_END_DEVICE
• ROLE_ROUTER
• ROLE_LEADER

getState

int getState ()

Returns interface state.

If the interface is disabled, always returns STATE_OFFLINE.

Returns
int	The current state of the interface.

See also:

• STATE_DISABLED
• STATE_OFFLINE
• STATE_ATTACHING
• STATE_ATTACHED
• STATE_FAULT

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

See also:

• setEnabled(boolean)
• InterfaceDisabledException

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:

• onProvisionException(Exception), which is called to report errors.
• onStateChanged(int), which will transition to the state STATE_ATTACHED.

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

See also:

• onProvisionException(Exception)
• JoinFailedAtAuthException
• JoinFailedAtScanException
• JoinFailedException
• form(LowpanProvisioningParams)
• provision(LowpanProvisioningParams)

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:

• onStateChanged(int), which will transition to the state STATE_OFFLINE.
• onLowpanIdentityChanged(LowpanIdentity), which will be called with a null argument.

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

Throws
InterfaceDisabledException	if the interface was disabled.
LowpanException

See also:

• join(LowpanProvisioningParams)
• form(LowpanProvisioningParams)
• provision(LowpanProvisioningParams)
• getLowpanProvisioningParams(boolean)

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:

• onProvisionException(Exception), which is called to report errors.
• onStateChanged(int), which will transition to the state STATE_ATTACHED.

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

See also:

• join(LowpanProvisioningParams)
• form(LowpanProvisioningParams)
• leave()
• getLowpanProvisioningParams(boolean)

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.

See also:

• registerCallback(Callback)
• unregisterCallback(Callback)

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.

See also:

• ERROR(/#registerCallback(Callback, Handler))
• unregisterCallback(Callback)

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:

• onStateChanged(int), which will indicate state changes after reset.

Throws
InterfaceDisabledException	if the interface was disabled.
LowpanException

See also:

• STATE_FAULT

setEnabled

void setEnabled (boolean enabled)

Enables or disables the interface.

Parameters
enabled	boolean

Throws
LowpanException

See also:

• isEnabled()
• InterfaceDisabledException

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.

See also:

• ERROR(/#registerCallback(Callback, Handler))
• registerCallback(Callback)

• Classes

  • LowpanBeaconInfo
  • LowpanCredential
  • LowpanEnergyScanResult
  • LowpanIdentity
  • LowpanIdentity.Builder
  • LowpanInterface
  • LowpanInterface.Callback
  • LowpanManager
  • LowpanManager.Callback
  • LowpanProvisioningParams
  • LowpanProvisioningParams.Builder
  • LowpanScanner
  • LowpanScanner.Callback

• Exceptions

  • InterfaceDisabledException
  • JoinFailedAtAuthException
  • JoinFailedAtScanException
  • JoinFailedException
  • LowpanException
  • LowpanRuntimeException
  • NetworkAlreadyExistsException
  • OperationCanceledException
  • WrongStateException