ZigBee Dongle Configuration

There ZigBee Dongle Configuration contains the parameters that can change the behavior of the library implementing the
data link protocol between PC and Dongle on the RS232, thus it can not use any OSGi configuration feature but it relies on standard SystemProperties which can be set in several why, the most common is to use the -D<property-name>=<property-value> option of the Java Virtual Machine. The available properties are:
  • it.cnr.isti.cc2480.low.milliseconds_per_packet set the number of milliseconds that must elapsed between two consecutive frame sent from the PC to the Dongle. The zero value or any negative values disable the packet speed control. By default is set to 0

ZigBee Dongle Specific Configuration

The following properties affects the behavior of zb4osgi, only if the proper driver is used

EZ430_RF2480 (CC2480) Driver

All the following properties affects only the zigbee.ez430_rf2480.driver Driver, and they can be set ONLY by means of the SystemProperties:
  • zigbee.driver.ez430_rf2480.resend.timout specifies the amount of time that the Driver can wait for receiving the SRSP related to a SREQ. If the expected SRSP doesn't arrives or arrives later the communication must be considered failed. By default is set to 1000 (1 second)
  • zigbee.driver.ez430_rf2480.resend.max specifies how many times the communication with a Driver should be retransmit SREQ request during a failure. By default is set to 3
  • zigbee.driver.ez430_rf2480.resend.exceptiononly when set to true the Driver try to retransmit the packet (i.e. usually a SREQ frame as defined by CC2480 specification) only if an exception is thrown (e.g. when set to false a timeout will fire a retransmit). By default is set to true

It is worth to note that some combination of the above parameter may freeze the dongle. In particular, the combinations zigbee.driver.ez430_rf2480.resend.exceptiononly=true and zigbee.driver.ez430_rf2480.resend.timout<1000 may lead to a freezing prone behavior. In fact, we discovered from experiment, that sending the sequence SREQ SREQ freeze the dongle.

CC2530 Driver

All the following properties affects only the zigbee.CC2530.driver Driver, and they can be set ONLY by means of the SystemProperties:
  • zigbee.driver.tsb.resend.timout specifies the amount of time that the Driver can wait for receiving the SRSP related to a SREQ. If the expected SRSP doesn't arrives or arrives later the communication must be considered failed. By default is set to 1000 (1 second)
  • zigbee.driver.tsb.resend.max specifies how many times the communication with a Driver should be retransmit SREQ request during a failure. By default is set to 3
  • zigbee.driver.tsb.resend.exceptiononly when set to true the Driver try to retransmit the packet (i.e. usually a SREQ frame) only if an exception is thrown (e.g. when set to false a timeout will fire a retransmit of the packet). By default is set to true

ZigBee Base Driver Configuration

The ZigBee Base Driver (ZBD) uses the Configuration Admin Service Specification for providing an OSGi standard way for hat modification of its behavior. In particular, it registers a ManagedService with PID = it.cnr.isti.zigbee.driver.configuration. At the moment, the ZBD behavior can be modified by modifying the properties describe in the next sections. It's worth to notice that the behavior affects not only the ZBD itself but also the Simple Driver service way to access the ZigBee Network Controller (ZNC)

ZigBee Network Controller

  • it.cnr.isti.zigbee.driver.flush if set to true for the ZNC to clean up its status (i.e.: network status, end point installed, binding table, etc. ). By default is set to false
  • it.cnr.isti.zigbee.driver.serial.port the name of the serial port where the ZNC hardware is connected to. The special value auto, if supported, enabled an auto-discovery of the port where the ZNC is connected to. By default is set to auto
  • it.cnr.isti.zigbee.driver.serial.baudrate the speed to use for communicating with the ZNC on the serial port. By default is set to 38400

ZigBee Network

  • it.cnr.isti.zigbee.pan.id when set it specifies the Pan Id of the ZigBee network that to create or to connect to. By default is set to 0x1357. The special value 0xFFFF allows the connection to any Pan Id.
  • it.cnr.isti.zigbee.pan.channel when set it specifies the Channel of the ZigBee network that to create or to connect to. By default is set to 23
  • it.cnr.isti.zigbee.driver.mode identifies the type of the device the ZNC should behave as (i.e.: Coordinator, Router, or End Device ). By defaults it set to Coordinator, other possible values are Router or EndDevice

ZigBee Communication

  • it.cnr.isti.zigbee.driver.communication.retry.count specifies how many times the communication with a ZigBee Device should be retried on failure. By default is set to 3.
  • it.cnr.isti.zigbee.driver.communication.retry.delay specifies the number of milliseconds to wait before retransmit a failed communication to a ZigBee Device. By default is set to 1000 (1 second)
  • it.cnr.isti.zigbee.driver.communication.timout specifies the number of milliseconds to wait before considering the communication with a ZigBee Device as failed. By default is set to 2500 (2.5 seconds)
  • it.cnr.isti.zigbee.driver.communication.ep.address.retry specifies the total number of tentative for registering a local device when the registration fail because the endpoint address selected is already in use. By default it is set to 0 (no retry, so only one tentative)
  • it.cnr.isti.zigbee.driver.communication.ep.address.first specifies the first end point address to consider free for registering local device. By default is set to 2

ZigBee Discovery

  • it.cnr.isti.zigbee.driver.network.browsing.period specifies the minimum amount of time, in milliseconds, that has to elapse between starting two network browsing by means of address-tree walking. By default is set to 900000 (15 minutes).
  • it.cnr.isti.zigbee.driver.device.inspection.rate specifies the minimum amount of time, in milliseconds, that has to elapse between the inspection of the device on a node (either if the node are found by means of network browsing or device announce). By default is set to 10000 (10 seconds).

Home Automation Configuration

The Home Automation Refinement Driver (HA Driver) uses the Configuration Admin Service Specification for providing an OSGi standard way for hat modification of its behavior. In particular, it registers a ManagedService with PID = it.cnr.isti.zigbee.ha.configuration. At the moment, the HA Driver behavior can be modified by modifying the properties describe in the next sections. It's worth to notice that the behavior affects not only the HA Driver itself but also all the driver extension that are installed on the OSGi framework

Refinement Behavior

  • it.isti.cnr.zigbee.ha.driver.cluster.discovery.mode set the way the HA Driver checks the Input and Output clusters list of an End Point during the refinement process either for checking Simple Description of the device and also for creating optional clusters only when available. By default is set to HomeAutomationProfileStrict which means that a input cluster implemented by the device must be present in input cluster list of the Simple description of the device. The other possible value is EitherInputAndOutput which is more relaxed and it allows the device to describe its input cluster either in the input or the output cluster list of the Simeple description
    NOTE: Up to now, this property may be set only by means of System properties.

Reporting

  • it.cnr.isti.zigbee.ha.reporting.min set the default value for the Minimum Rerporting Interval to be used when sending the Report Configuration Command. By the default is set to 60, which means report only a minute is elapsed since last notification.
  • it.cnr.isti.zigbee.ha.reporting.max set the default value for the Maximum Rerporting Interval to be used when sending the Report Configuration Command. By the default is set to 0, which means report only if the value change.
  • it.cnr.isti.zigbee.ha.reporting.change set the default value for the Reportable Change to be used when sending the Report Configuration Command. By the default is set to 0.0d, which means any change
  • it.cnr.isti.zigbee.ha.reporting.overwrite set the default behavior of the reporting to either overwrite any existing reporting configuration on the cluster or to apply the changes only if no reporting configuration is active. By default is set to true, which means that the configuration is overwritten

Appendix A: Looking at source code

You can look at the file source code for missing option or undocumented parameters. In particular, a good starting point is looking at: