org.osgi.service.zigbee

Interface ZigBeeHost

All Superinterfaces:

ZigBeeNode

public interface ZigBeeHost
extends ZigBeeNode

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.

"Consumers of this API must not implement this interface"

Field Summary

Fields

Modifier and Type	Field and Description
static short	UNLIMITED_BROADCAST_RADIUS Value constant to set an unlimited broadcast radius.

Fields inherited from interface org.osgi.service.zigbee.ZigBeeNode

COORDINATOR, EXTENDED_PAN_ID, IEEE_ADDRESS, LOGICAL_TYPE, MANUFACTURER_CODE, PAN_ID, POWER_SOURCE, RECEIVER_ON_WHEN_IDLE, ROUTER, ZED

Method Summary

Modifier and Type	Method and Description
ZCLCommandResponseStream	broadcast(int clusterID, ZCLFrame frame) Broadcasts a ZCL frame to the cluster ID of all the nodes of the ZigBee network.
ZCLCommandResponseStream	broadcast(int clusterID, ZCLFrame frame, String exportedServicePID) Broadcasts a ZCL frame to the cluster ID of all the nodes of the ZigBee network.
void	createGroupService(int 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.
short	getBroadcastRadius() Returns the current broadcast radius value.
int	getChannel() Returns the current network channel.
int	getChannelMask() Returns the currently configured channel mask.
long	getCommunicationTimeout() Returns the current value set for the communication timeout.
String	getPreconfiguredLinkKey() Returns the current preconfigured link key.
int	getSecurityLevel() Returns the network security level.
boolean	isStarted() Checks the host's start/stop state.
void	permitJoin(short duration) Indicates if a ZigBee device can join the network.
Promise<Boolean>	refreshNetwork() Forces a new network scan.
void	setBroadcastRadius(short broadcastRadius) Sets the broadcast radius value.
void	setChannelMask(int mask) Sets a new configured channel mask.
void	setCommunicationTimeout(long timeout) Sets the timeout for the communication sent through this device.
void	setExtendedPanId(BigInteger extendedPanId) Sets the extendedPanId.
void	setLogicalType(short logicalNodeType) Sets the host logical node type.
void	setPanId(int panId) Sets the panId.
void	start() Starts the host.
void	stop() Stops the host.
void	updateNetworkChannel(byte channel) Updates the network channel.

Methods inherited from interface org.osgi.service.zigbee.ZigBeeNode

getComplexDescriptor, getEndpoints, getExtendedPanId, getHostPid, getIEEEAddress, getLinksQuality, getNetworkAddress, getNodeDescriptor, getPanId, getPowerDescriptor, getRoutingTable, getUserDescription, invoke, invoke, leave, leave, setUserDescription

Field Detail

UNLIMITED_BROADCAST_RADIUS

static final short UNLIMITED_BROADCAST_RADIUS

Value constant to set an unlimited broadcast radius.

See Also:

Constant Field Values

Method Detail

start

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.

Throws:

Exception - Any exception related to the communication with the chip.

stop

void stop()
   throws Exception

Stops the host.

Throws:

Exception - Any exception related to the communication with the chip.

isStarted

boolean isStarted()

Checks the host's start/stop state.

Returns:

true if the host is started.

setPanId

void setPanId(int panId)

Sets the panId.

Parameters:

panId - The network Personal Area Network identifier (PAN ID)

Throws:

IllegalArgumentException - if set with a value out of the expected range [0x0000, 0xffff].

IllegalStateException - If the host is already started.

setExtendedPanId

void setExtendedPanId(BigInteger extendedPanId)

Sets the extendedPanId.

Parameters:

extendedPanId - The network Extended PAN identifier(EPID)

Throws:

IllegalStateException - If the host is already started.

permitJoin

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 - The time during which associations are permitted.

Throws:

Exception - Any exception related to the communication with the chip.

setLogicalType

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 - The logical node type.

Throws:

IllegalStateException - If the host is already started.

Exception - Any exception related to the communication with the chip.

getChannel

int getChannel()
        throws Exception

Returns the current network channel.

Returns:

the current network channel.

Throws:

Exception - Any exception related to the communication with the chip.

updateNetworkChannel

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 - The network channel.

Throws:

IllegalStateException - If the host is started, or the host is not a network manager.

IOException - for serial communication exception.

getChannelMask

int getChannelMask()
            throws Exception

Returns the currently configured channel mask.

Returns:

the currently configured channel mask.

Throws:

Exception - Any exception related to the communication with the chip.

setChannelMask

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 - A value representing the channel mask.

Throws:

IllegalStateException - If the host is already started.

IOException - for serial communication exception.

refreshNetwork

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:

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.

Throws:

Exception - Any exception related to the communication with the chip.

getSecurityLevel

int getSecurityLevel()
              throws Exception

Returns the network security level.

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").

Throws:

Exception - Any exception related to the communication with the chip.

getPreconfiguredLinkKey

String getPreconfiguredLinkKey()
                        throws Exception

Returns the current preconfigured link key.

Returns:

the current preconfigured link key.

Throws:

Exception - Any exception related to the communication with the chip.

createGroupService

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 - the address of the group to create.

Throws:

Exception - when a ZigBeeGroup service with the same groupAddress already exists.

broadcast

ZCLCommandResponseStream broadcast(int clusterID,
                                   ZCLFrame frame)

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.

Specified by:

broadcast in interface ZigBeeNode

Parameters:

clusterID - The cluster ID this ZCL frame must be sent to.

frame - A ZCL Frame.

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

ZCLCommandResponseStream broadcast(int clusterID,
                                   ZCLFrame frame,
                                   String exportedServicePID)

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.

Specified by:

broadcast in interface ZigBeeNode

Parameters:

clusterID - The cluster ID.

frame - A ZCL Frame.

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

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.

See Also:

Setting the broadcast radius.

getBroadcastRadius

short getBroadcastRadius()

Returns the current broadcast radius value.

Returns:

the current broadcast radius value.

setBroadcastRadius

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 - - is the number of routers that the messages are allowed to cross. Radius value is in the range from 0 to 0xff.

Throws:

IllegalArgumentException - if set with a value out of the expected range.

IllegalStateException - if set when the ZigBeeHost is "running".

setCommunicationTimeout

void setCommunicationTimeout(long timeout)

Sets the timeout for the communication sent through this device.

Parameters:

timeout - the number of milliseconds before firing a timeout exception.

getCommunicationTimeout

long getCommunicationTimeout()

Returns the current value set for the communication timeout.

Returns:

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