ZigApi architecture

(1)

Chapter 7

ZigApi architecture

ZigApi is an extensible middleware offering high-level abstractions for the ma- naging of ZigBee networks at coordinator side. It hides the applicative protocol of ZigBee and offers a per-device and per-cluster view, so that the programmer has not to know ZigBee applicative communication standards. The architectural and procedural solutions adopted for ZigApi can be used for any communication technology (other than ZigBee) dealing with smart devices. ZigApi is a software dynamic-link library, written in C#[3] and having the following characteristics.

1. Extensibility. ZigApi functionalities are extensible without changing Zi- gApi itself. An application using ZigApi can define new clusters and devices (see section 9.6).

2. Multitasking. ZigApi is multi-thread-oriented and its interface methods are thread-safe.

3. Portability. ZigApi is compiled in Common Infrastructure Language[4]

(CIL), a cross-platform pseudo-assembly language, standardized by ECMA International.

In figure 7.1, the deployment diagram of ZigApi is shown, supposing the Home Manager and the gateway running on the same machine.

41

(2)

7.1. Offered services 42

Figure 7.1: ZigApi deployment diagram

7.1 Offered services

From now on, with the term programmer we refer to the ZigApi employer, who uses it in order to develop coordinator-side ZigBee applications.

ZigApi offers the following services.

1. Architectural abstraction. ZigApi defines a Network object and Device objects. In this way, every physical object in a ZigBee scenario (network, devices, etc.) is represented by a sofware object.

2. Protocol abstraction. ZigApi hides the implementation details of the gate- way communication protocol and of the ZigBee applicative protocol.

3. Synchronization abstraction. ZigApi controls the synchronization of Zig- Bee transactions (see section 9.3) and mutual exclusion between incom- patible operations (see section 9.3).

4. Attribute managing. ZigApi implements a database service for ZigBee at- tributes. Thus, the programmer is not required to implement a similar

(3)

7.2. Architectural overview 43

functionality in his/her applications.

7.2 Architectural overview

A Network object represents a ZigBee network. The programmer can operate on it with methods which affect the whole network, like connection or discon- nection from the gateway (Connect and Disconnect ), detection of connected devices (Inquiry), broadcast operations, etc. If the application operates on more than one ZigBee network, the programmer can create more than one Network object. A GAL instance can connect to at most one Network instance and vice- versa. Thus, the programmer has to execute a GAL instance for every Network object.

A Network object maintains a collection of Device objects, each represen- ting a (physical or virtual) device connected to the network. Such collection is updated everytime the set of connected devices changes, that is everytime devices enter or leave the network. Each device is identified by a unique IEEE 802.15.4 64-bit address. The programmer can obtain a device object by means of its address, and then perform operations on it. Figure 7.2 shows the general class diagram of ZigApi.

Network maintains a MessageCoordinator object, responsible for transac- tions’ synchronization, and a ReaderWriterLockSlim, responsible for mutual exclusion on Network accesses. RxMessage and TxMessage respectively repre- sents and incoming and outcoming ZigBee applicative messages. ZclException represents an error in the ZigBee applicative protocol, while GatewayCom- municationException represents an error in the gateway communication. Zi- gApiTimeoutException represents an exceeded time-out exception in a ZigBee applicative communication. The classes MessageCoordinator, RxMessage and TxMessage are not used directly by the programmer, unless he wants to extend the middleware (see section 9.6).

The Device class follows the Composite design pattern[6]. It is an abstract class, concretized by its derived classes, each representing a different type of ZigBee device. Device class exports a set of standard methods, generally sup- ported by all devices, like attribute reading or attribute reports configuration.

(4)

7.3. Devices and clusters implemented by ZigApi 44

Figure 7.2: ZigApi general architecture

Derived classes of Device can export more specific methods.

Each ZigBee standard cluster has a related class-interface (cluster interface), in such a way that a device implementing a particular cluster is represented by a Device object implementing the related interface. Figure 7.3 shows an example of this architecture. In the example, HeatingDevice extends the Device class and exports one cluster interface for each ZigBee cluster it implements.

7.3 Devices and clusters implemented by ZigApi

ZigApi implements four kinds of devices:

1. Plug. Represents a Telecom Italia’s smart plug, with metering and on/off capabilities.

2. Refrigerator. Represents a smart refrigerator, with content knowing and thermostat capabilities.

3. HeatingDevice. Represents a smart heating device, with thermostat capa-

(5)

7.3. Devices and clusters implemented by ZigApi 45

Figure 7.3: Device class architecture

bilities.

4. Lamp. Represents an lighting device, with on/off capabilities.

Other devices can be added inside or outside the middleware (see section 9.6).

ZigApi implements five cluster interfaces for standard ZigBee clusters:

• IBasicCluster, implemented by devices exporting Basic cluster. Includes generic functionalities, supported by every smart device.

• IIdentifyCluster, implemented by devices exporting Identify cluster. In- cludes identification functionalities.

• IAlarmsCluster, implemented by devices exporting Alarms cluster. In- cludes devices’ alarms and notifications functionalities.

• IOnOffCluster, implemented by devices exporting On/off cluster. Includes on/off functionalities.

• IThermostatCluster, implemented by devices exporting Thermostat clus- ter. Includes thermostat-related functionalities.

ZigApi implements one cluster interface for non-standard ZigBee clusters:

(6)

7.4. Programming examples 46

Figure 7.4: Cluster interfaces and devices

• IBoxCluster, implemented by devices exporting Box cluster. Includes func- tionalities related to a container that knows its content (by RFID technology, for example).

Other clusters can be added inside or outside the middleware (see section 9.6).

Table in figure 7.4 shows all the clusters implemented by every device.

7.4 Programming examples

In this section, some ZigApi usage examples will be introduced. The examples are written in simplified pseudocode. Refer to chapter 8 for the actual ZigApi interface.

Pseudocode 7.1 shows how the programmer can create a network, search for reachable devices, and print to screen their addresses and types. The Net- work.Connect operation estabilishes a connection with the gateway and contex- tually searches for reachable devices. The parameter is a time-out in milliseconds for the searching operation. The search is performed by broadcasting an inquiry command, and then waiting for replies from the devices.

The Network.Disconnect operation closes the connection with the gateway.

The pseudocode 7.2 shows how the programmer can turn off all the devices that implement the On/off cluster (for example: smart plugs, lighting devices). IOnOffCluster.Off is a ZigBee standard command included in the On/off cluster. The parameter represents a time-out for the command’s reply, in milliseconds. If such time-out is 0, a reply-less command is sent, meaning

(7)

Algorithm 7.1 Connection example void main() {

Network theNetwork = new Network("127.0.0.1:9000");

theNetwork.Connect(6000);

foreach(Device dev in theNetwork.Devices) { Console.Write(dev.LongAddress);

switch(dev.Type) { case Plug:

Console.WriteLine(" is a smart plug.");

break;

case Refrigerator:

Console.WriteLine(" is a refrigerator.");

break;

case Lamp:

Console.WriteLine(" is a lamp.");

break;

case HeatingDevice:

Console.WriteLine(" is a heating device.");

break;

} }

theNetwork.Disconnect();

}

Algorithm 7.2 Turn off example ...

foreach(Device dev in theNetwork.Devices) { if(dev is IOnOffCluster) {

((IOnOffCluster)dev).Off(0);

} }

(8)

that the device is not forced to send a reply.

7.4.1 Attributes

In ZigApi, a ZigBee attribute is identified by means of a string, called Attribute name. The pseudocode 7.3 shows how the programmer can read and write attri- butes. ReadAttr, ReadAllAttr, GetAttrVal, IsKnownAttrVal and WriteAttr are standard methods provided by all Device objects. ReadAttr retrieves the value of a particular attribute from the device, while ReadAllAttr retrieves the value of all attributes. They both are methods that always generate ZigBee network traffic. They can’t be reply-less, so the time-out parameter can’t be 0. If these methods succeed, the value of the attribute is returned and stored in a ZigBee internal database. GetAttrVal returns a value of an attribute previously stored in the database. It does not generate ZigBee traffic. IsKnownAttrVal returns true whether the value of the specified attribute is present in the database.

7.4.2 Attribute reports

The pseudocode 7.4 shows how the programmer can receive attribute reports from the devices. SetAllAttrReportCallback sets a handler function that ZigApi will call every time a report of any attribute arrives from the specified device.

The handler function is called asynchronously from the programmer’s code, by a dedicated thread, so the programmer has to pay attention to threading issues.

7.4.3 Network locking

In a real network, the list of connected devices can dinamically change when a device enters or leaves the ZigBee network. These changes are asynchronous from the programmer’s code. Even the values of a device’s attributes can asynchronously change, due to attribute reports. If the programmer wants the network or the attributes of a particular device not to change within a section of the program, lock operations have to be performed. Pseudocode 7.5 shows how the programmer can protect a program section from asynchronous net- work changes. The try-finally block ensures the Network.Unfreeze operation is

(9)

Algorithm 7.3 Attribute’s read and write example.

...

Device dev = theNetwork.DeviceAt(address);

switch(dev.Type) { case Plug:

uint powerCons = (uint)dev.ReadAttr("PowerConsumption", 5000);

Console.WriteLine("Plug: PowerConsumption={0}", powerCons);

break;

case Lamp:

dev.ReadAllAttr(5000);

Console.WriteLine("Lamp: On/off={0}, ModelIdentifier={1}", (bool)dev.GetAttrVal("OnOff"),

(string)dev.GetAttrVal("ModelIdentifier"));

break;

case Refrigerator:

dev.WriteAttr("OccupiedCoolingSetpoint", (short)600,

5000); // Setting the thermostat temperature to 6C

Console.WriteLine("Refrigerator: OccupiedCoolingSetpoint={0}", (short)dev.GetAttrVal("OccupiedCoolingSetpoint"));

break;

case HeatingDevice:

if (dev.IsKnownAttrVal("LocalTemperature"))

Console.WriteLine("HeatingDevice: LocalTemperature={0}", (short)dev.GetAttrVal("LocalTemperature"));

else

Console.WriteLine("HeatingDevice: LocalTemperature=<unknown>");

break;

}

(10)

Algorithm 7.4 Reports receiving example void main() {

Network theNetwork = new Network(

"127.0.0.1:9000",

acceptAsyncReports=true);

foreach(Device dev in theNetwork.Devices)

dev.SetAllAttrReportCallback(reportCallback);

Console.WriteLine(

"Receiving attribute reports... (type ’quit’ to exit)");

do {

string inp = Console.ReadLine();

}

while(inp != "quit");

theNetwork.Disconnect();

}

void reportCallback(

Device dev, string attrName, object value, int valueKnowTime) {

Console.WriteLine("Attribute report received from {0}: {1}={2}", dev.LongAddress,

attrName,

value.ToString());

}

(11)

Algorithm 7.5 Network freeze example

Network theNetwork = new Network(acceptAsyncAnnouncements=true);

...

theNetwork.Freeze();

try {

foreach(Device dev in theNetwork.Devices) { ...

} }

finally { theNetwork.Unfreeze(); }

performed even if an exception is thrown within the try block.

Pseudocode 7.6 shows how the programmer can protect a program section from asynchronous attribute’s changes.

Algorithm 7.6 Attributes’ lock example

Device dev = theNetwork.DeviceAt(address);

dev.LockAttr();

try {

int a = (int)dev.ReadAttr(...);

int b = (int)dev.GetAttrVal(...);

int c = (int)dev.GetAttrVal(...);

dev.WriteAttr(...);

}

finally { dev.UnlockAttr(); }