Top Description Fields Methods
org.osgi.service.zigbee

public Interface ZigBeeHost

extends ZigBeeNode
Imports
java.io.IOException, java.math.BigInteger, org.osgi.util.promise.Promise
This interface represents the machine that hosts the code to run a ZigBee device or client. This machine is, for example, the ZigBee chip/dongle that is controlled by the base driver (below/under the OSGi execution environment).

ZigBeeHost is more than a ZigBeeNode.

It must be registered as a OSGi service.

Even if not specified explicitly in the javadoc, any method of this interface must throw an IllegalArgumentException exception if a or one of the passed arguments has a value not admitted by the method.

Author
$Id: 22e51155c09075c38dfa8151b2691a4dd65646ca $

Field Summary

Modifier and TypeField and Description
public static final short
UNLIMITED_BROADCAST_RADIUS

Value constant to set an unlimited broadcast radius.

Inherited from org.osgi.service.zigbee.ZigBeeNode:
COORDINATOREXTENDED_PAN_IDIEEE_ADDRESSLOGICAL_TYPEMANUFACTURER_CODEPAN_IDPOWER_SOURCERECEIVER_ON_WHEN_IDLEROUTERZED

Method Summary

Modifier and TypeMethod and Description
public ZCLCommandResponseStream

Returns:

a response stream instance that collects and allows the caller to be asynchronously notified about the ZCLFrame responses sent back by the ZigBee nodes.
broadcast(int
The cluster ID this ZCL frame must be sent to.
clusterID, ZCLFrame
A ZCL Frame.
frame)

Redeclares org.osgi.service.zigbee.ZigBeeNode.broadcast.

Broadcasts a ZCL frame to the cluster ID of all the nodes of the ZigBee network.

public ZCLCommandResponseStream

Returns:

a response stream instance that collects and allows the caller to be asynchronously notified about the ZCLFrame responses sent back by the ZigBee nodes.
broadcast(int
The cluster ID.
clusterID, ZCLFrame
A ZCL Frame.
frame, String
the source endpoint of the command request. In targeted situations, the source endpoint is the valid service PID of an exported endpoint.
exportedServicePID)

Redeclares org.osgi.service.zigbee.ZigBeeNode.broadcast.

Broadcasts a ZCL frame to the cluster ID of all the nodes of the ZigBee network.

public void
createGroupService(int
the address of the group to create.
groupAddress)

Creates a ZigBeeGroup service that has not yet been discovered by the ZigBee Base Driver or that does not exist on the ZigBee network yet.

public short

Returns:

the current broadcast radius value.
getBroadcastRadius()

Returns the current broadcast radius value.

public int

Returns:

the current network channel.
getChannel()

Returns the current network channel.

public int

Returns:

the currently configured channel mask.
getChannelMask()

Returns the currently configured channel mask.

public long

Returns:

the current value set for the communication timeout expressed in milliseconds.
getCommunicationTimeout()

Returns the current value set for the communication timeout.

public String

Returns:

the current preconfigured link key.
getPreconfiguredLinkKey()

Returns the current preconfigured link key.

public int

Returns:

the network security level, that is, 0 if security is disabled, an int code if enabled (see "Table 4.38 Security Levels Available to the NWK, and APS Layers" of the ZigBee specification").
getSecurityLevel()

Returns the network security level.

public boolean

Returns:

true if the host is started.
isStarted()

Checks the host's start/stop state.

public void
permitJoin(short
The time during which associations are permitted.
duration)

Indicates if a ZigBee device can join the network.

public Promise<Boolean>

Returns:

A promise representing the completion of this asynchronous call. In case of success the promise will resolve with Boolean.TRUE otherwise the promise is failed with an exception.
refreshNetwork()

Forces a new network scan.

public void
setBroadcastRadius(short
- is the number of routers that the messages are allowed to cross. Radius value is in the range from 0 to 0xff.
broadcastRadius)

Sets the broadcast radius value.

public void
setChannelMask(int
A value representing the channel mask.
mask)

Sets a new configured channel mask.

public void
setCommunicationTimeout(long
the number of milliseconds before firing a timeout exception.
timeout)

Sets the timeout for the communication sent through this device.

public void
setExtendedPanId(BigInteger
The network Extended PAN identifier(EPID)
extendedPanId)

Sets the extendedPanId.

public void
setLogicalType(short
The logical node type.
logicalNodeType)

Sets the host logical node type.

public void
setPanId(int
The network Personal Area Network identifier (PAN ID)
panId)

Sets the panId.

public void
start()

Starts the host.

public void
stop()

Stops the host.

public void
updateNetworkChannel(byte
The network channel.
channel)

Updates the network channel.

Inherited from org.osgi.service.zigbee.ZigBeeNode:
getComplexDescriptorgetEndpointsgetExtendedPanIdgetHostPidgetIEEEAddressgetLinksQualitygetNetworkAddressgetNodeDescriptorgetPanIdgetPowerDescriptorgetRoutingTablegetUserDescriptioninvokeinvokeleaveleavesetUserDescription

Field Detail

UNLIMITED_BROADCAST_RADIUSback to summary
public static final short UNLIMITED_BROADCAST_RADIUS

Value constant to set an unlimited broadcast radius.

Method Detail

broadcastback to summary
public ZCLCommandResponseStream broadcast(int clusterID, ZCLFrame frame)

Redeclares org.osgi.service.zigbee.ZigBeeNode.broadcast.

Broadcasts a ZCL frame to the cluster ID of all the nodes of the ZigBee network. The setBroadcastRadius(short) method, may be used to limit the broadcast radius used in the subsequent broadcast calls.

Parameters
clusterID:int

The cluster ID this ZCL frame must be sent to.

frame:ZCLFrame

A ZCL Frame.

Returns:ZCLCommandResponseStream

a response stream instance that collects and allows the caller to be asynchronously notified about the ZCLFrame responses sent back by the ZigBee nodes.

Annotations
@Override
broadcastback to summary
public ZCLCommandResponseStream broadcast(int clusterID, ZCLFrame frame, String exportedServicePID)

Redeclares org.osgi.service.zigbee.ZigBeeNode.broadcast.

Broadcasts a ZCL frame to the cluster ID of all the nodes of the ZigBee network. The passed exportedServicePID allows to force the source endpoint of the message sent to be the endpoint id of the exported ZigBeeEndPoint service having the specified service.pid property.

Parameters
clusterID:int

The cluster ID.

frame:ZCLFrame

A ZCL Frame.

exportedServicePID:String

the source endpoint of the command request. In targeted situations, the source endpoint is the valid service PID of an exported endpoint.

Returns:ZCLCommandResponseStream

a response stream instance that collects and allows the caller to be asynchronously notified about the ZCLFrame responses sent back by the ZigBee nodes.

Annotations
@Override
See Also
Setting the broadcast radius.
createGroupServiceback to summary
public void createGroupService(int groupAddress) throws Exception

Creates a ZigBeeGroup service that has not yet been discovered by the ZigBee Base Driver or that does not exist on the ZigBee network yet.

Parameters
groupAddress:int

the address of the group to create.

Exceptions
Exception:
when a ZigBeeGroup service with the same groupAddress already exists.
getBroadcastRadiusback to summary
public short getBroadcastRadius()

Returns the current broadcast radius value.

Returns:short

the current broadcast radius value.

getChannelback to summary
public int getChannel() throws Exception

Returns the current network channel.

Returns:int

the current network channel.

Exceptions
Exception:
Any exception related to the communication with the chip.
getChannelMaskback to summary
public int getChannelMask() throws Exception

Returns the currently configured channel mask.

Returns:int

the currently configured channel mask.

Exceptions
Exception:
Any exception related to the communication with the chip.
getCommunicationTimeoutback to summary
public long getCommunicationTimeout()

Returns the current value set for the communication timeout.

Returns:long

the current value set for the communication timeout expressed in milliseconds.

getPreconfiguredLinkKeyback to summary
public String getPreconfiguredLinkKey() throws Exception

Returns the current preconfigured link key.

Returns:String

the current preconfigured link key.

Exceptions
Exception:
Any exception related to the communication with the chip.
getSecurityLevelback to summary
public int getSecurityLevel() throws Exception

Returns the network security level.

Returns:int

the network security level, that is, 0 if security is disabled, an int code if enabled (see "Table 4.38 Security Levels Available to the NWK, and APS Layers" of the ZigBee specification").

Exceptions
Exception:
Any exception related to the communication with the chip.
isStartedback to summary
public boolean isStarted()

Checks the host's start/stop state.

Returns:boolean

true if the host is started.

permitJoinback to summary
public void permitJoin(short duration) throws Exception

Indicates if a ZigBee device can join the network.

Broadcasts a Mgmt_Permit_req to all routers and the coordinator. If the duration argument is not equal to zero or 0xFF, the argument is a number of seconds and joining is permitted until it counts down to zero, after which time, joining is not permitted. If the duration is set to zero, joining is not permitted. If set to 0xFF, joining is permitted indefinitely or until another Mgmt_Permit_Joining_req is received by the coordinator.

As described in "Table 2.133 Fields of the Mgmt_Permit_Joining_rsp Command" of the ZigBee specification 1_053474r17ZB_TSC-ZigBee-Specification.pdf, a permitJoin request can have the following status: ZDPException#SUCCESS, ZDPException#INV_REQUESTTYPE, ZDPException#NOT_AUTHORIZED or any status code returned from the NLMEPERMITJOINING.confirm primitive.

Parameters
duration:short

The time during which associations are permitted.

Exceptions
Exception:
Any exception related to the communication with the chip.
refreshNetworkback to summary
public Promise<Boolean> refreshNetwork() throws Exception

Forces a new network scan. It checks that the ZigBeeNode services are still representing an available node on the network. It also updates the whole representation of all nodes (endpoints, clusters, descriptors, attributes).

Returns:Promise<Boolean>

A promise representing the completion of this asynchronous call. In case of success the promise will resolve with Boolean.TRUE otherwise the promise is failed with an exception.

Exceptions
Exception:
Any exception related to the communication with the chip.
setBroadcastRadiusback to summary
public void setBroadcastRadius(short broadcastRadius)

Sets the broadcast radius value. By default the ZigBeeHost must use UNLIMITED_BROADCAST_RADIUS as default value for the broadcast.

Parameters
broadcastRadius:short

- is the number of routers that the messages are allowed to cross. Radius value is in the range from 0 to 0xff.

Exceptions
IllegalArgumentException:
if set with a value out of the expected range.
IllegalStateException:
if set when the ZigBeeHost is "running".
setChannelMaskback to summary
public void setChannelMask(int mask) throws IOException

Sets a new configured channel mask.

As described in "Table 2.13 APSME-SET.confirm Parameters" of the ZigBee specification 1_053474r17ZB_TSC-ZigBee-Specification.pdf, a set request can have the following status: APSException#SUCCESS, APSException#INVALID_PARAMETER or APSException#UNSUPPORTED_ATTRIBUTE.

Parameters
mask:int

A value representing the channel mask.

Exceptions
IOException:
for serial communication exception.
IllegalStateException:
If the host is already started.
setCommunicationTimeoutback to summary
public void setCommunicationTimeout(long timeout)

Sets the timeout for the communication sent through this device.

Parameters
timeout:long

the number of milliseconds before firing a timeout exception.

setExtendedPanIdback to summary
public void setExtendedPanId(BigInteger extendedPanId)

Sets the extendedPanId.

Parameters
extendedPanId:BigInteger

The network Extended PAN identifier(EPID)

Exceptions
IllegalStateException:
If the host is already started.
setLogicalTypeback to summary
public void setLogicalType(short logicalNodeType) throws Exception

Sets the host logical node type. ZigBee defines three different types of node: ZigBeeNode#COORDINATOR, ZigBeeNode#ROUTER and ZigBeeNode#ZED.

Parameters
logicalNodeType:short

The logical node type.

Exceptions
Exception:
Any exception related to the communication with the chip.
IllegalStateException:
If the host is already started.
setPanIdback to summary
public void setPanId(int panId)

Sets the panId.

Parameters
panId:int

The network Personal Area Network identifier (PAN ID)

Exceptions
IllegalArgumentException:
if set with a value out of the expected range [0x0000, 0xffff].
IllegalStateException:
If the host is already started.
startback to summary
public void start() throws Exception

Starts the host. If the host is a ZigBeeNode#COORDINATOR, then it can be started with or without ZigBeeNode#PAN_ID and ZigBeeNode#EXTENDED_PAN_ID (that is, if no PAN_ID, and Extended PAN_ID are given, then they will be automatically generated and then added to the service properties).

If the host is a ZigBeeNode#ROUTER, or a ZigBeeNode#ZED, then the host may start without a registered ZigBeeNode#PAN_ID property; the property will be set when the host will find and join a ZigBee network.

The host status must be persistent, that is, if the host was started, then the host must starts again when the bundle restarts. In addition, the values of channel, pan id, extended pan id, and host PID must remain the same.

Exceptions
Exception:
Any exception related to the communication with the chip.
stopback to summary
public void stop() throws Exception

Stops the host.

Exceptions
Exception:
Any exception related to the communication with the chip.
updateNetworkChannelback to summary
public void updateNetworkChannel(byte channel) throws IOException

Updates the network channel. 802.15.4 and ZigBee divide the 2.4GHz band into 16 channels, numbered from 11 to 26.

As described in "Table 2.4.3.3.9 Mgmt_NWK_Update_req" of the ZigBee specification 1_053474r17ZB_TSC-ZigBee-Specification.pdf, this request is sent as broadcast by the network manager with a ScanDuration to be set with the channel parameter.

Parameters
channel:byte

The network channel.

Exceptions
IOException:
for serial communication exception.
IllegalStateException:
If the host is started, or the host is not a network manager.