Stall Status is a Silverlight-based Vista Sidebar Gadget that uses the Z-Wave wireless protocol and door sensors to notify you of the occupied/available state of the bathroom stalls.
Jerry Brunning Clarity Consulting, Inc Difficulty: Easy Time Required: 1-3 hours Cost: $50-$100 Software: Visual C# Express Edition Hardware: ControlThink Z-Wave SDK,  Hawking Technologies Z-Wave HRDS1 door sensor Download: Download

Stall Status

Every now and then someone throws out an idea for a completely off-the-wall application that just has to be built. When Jon Rauschenberger, Clarity’s CTO, came into my office with his “brilliant idea” for a monitoring system to track the “occupied/available” state of our washroom stalls, I immediately recognized it as one of those moments. I had been doing some research on the Z-Wave wireless protocol for a client project earlier that week, and I thought “Stall Status” would be a fun way to get some hands on experience using Z-Wave.

In this article I will walk you through how to write managed code that interacts with Z-Wave devices. I’ll also show how to use Silverlight 2.0’s access policies to write “connected clients”: client applications that establish a persistent TCP connection to a remote server and thereby avoid having to poll the server for status changes. Finally, I’ll walk through the steps necessary to deploy a Silverlight 2.0 application as a Windows Vista Sidebar Gadget.

What is Z-Wave?

Z-Wave is a wireless communication protocol that works over radio frequency and is specifically designed for low-power, low-bandwidth usage scenarios. Typical usage scenarios for Z-Wave devices are monitoring and control applications – such as home automation. Available devices include door sensors, switches, and motors. Z-Wave devices are interoperable - devices labeled as Z-Wave compliant should all work together.

A Z-Wave network consists of one or more devices and a centralized controller. A controller can be a standalone (often hand held) hardware unit or a software-based kit. Devices on a Z-Wave network handle the routing of messages automatically without the need to set up pre-defined routes. This means that if you have several devices in your network that need to communicate together (e.g. a door sensor and an alarm), the devices can route messages through each other. This “mesh” communication capability allows you to extend the range of your network much farther than you would be able to if the devices all required direct connections to each other.  For example, if you have three devices, A, B and C, device A can communicate with device C, even if C is outside of A's range, by routing its messages through device B.  This all works automatically.

My simple Z-Wave network for Stall Status consists of door sensors to notify me when a stall door is opened and closed, and a software based controller. I used Hawking Technologies’ HRDS1 battery powered door sensors for each stall door in the washroom. The HRDS1 is considered an “occasionally on” device – it quietly sits in sleep mode until it detects an open/close event from the door. This is the same type of device you would use, for example, when building an alarm system for monitoring windows and doors.  For the Z-Wave controller I used an excellent software-based controller and SDK from ControlThink, which you can purchase for $70. The controller consists of a USB dongle and a set of APIs for connecting to and communicating with devices. ControlThink includes a number of .Net sample applications, but be warned that the sample applications are not device specific, and the available devices usually assume you are integrating them into an existing hardware-controlled environment, so the documentation surrounding their usage tends to be sparse.

Using the ControlThink SDK is very straight forward. You simply plug in the USB dongle, reference their DLL from your .Net application, and connect to the controller with a single line of code. Once connected, you can manage your network by adding devices, removing devices, iterating the list of devices, etc.

I ended up writing three applications to support Stall Status:

1. An administrative application for adding/removing/listing the Z-Wave devices on my network.  This is called StallStatusAdmin.
2. A Windows Service to listen for open/close events from the door sensors and notify any connected client.  This is called StallStatusController.
3. A Silverlight 2.0 client application (the end-user interface) that connects to the Windows Service to receive event notifications.  This is called StallStatusSilverlight.

Setting up the Z-Wave network

The administration application is a simple Windows Forms EXE that allows me to manage the network by adding, removing and listing the devices. This is simple to do using the ControlThink SDK – in most cases involving just a couple lines of code. Each Z-Wave device has some mechanism to put the device into “programming mode” . The HRDS1 has a button on the back that when pressed, puts the device into programming mode and allows the device to accept programming codes from the controller.

Listing 1 shows how to add a device to the network. Adding a device consists of registering the device with the controller, and then creating a relationship between the controller and the device's association group to enable the device to route messages to the controller. Once a device is registered, the controller assigns a unique NodeID that we will use to differentiate the three sensors from each other.

C#

ZWaveController controller = Connect(); 
MessageBox.Show("After pressing OK, press the \"programming\" button on your device.");
ZWaveDevice device = controller.AddDevice();
            
device.Groups[1].Clear();
device.Groups[1].Add(controller.Devices.GetByNodeID(controller.NodeID));

VB.Net

Dim controller As ZWaveController = Connect()
MessageBox.Show("After pressing OK, press the ""programming"" button on your device.")
Dim device As ZWaveDevice = controller.AddDevice()

device.Groups(1).Clear()
device.Groups(1).Add(controller.Devices.GetByNodeID(controller.NodeID))

Listing 1 – Adding a device to the network.

Getting a list of the registered devices on the network is as easy a iterating through the Devices collection on the controller.

C#

string result = "";
ZWaveController controller = Connect();

if (controller.Devices.Count > 0) {
   foreach (ZWaveDevice d in controller.Devices)    {
    result += d.GetType().ToString() + " as Node #" + d.NodeID + " PollEnabled = " + d.PollEnabled + "\r\n";
   }
}
else {
   result = "No devices found on the network";                
}
MessageBox.Show(result);

VB.Net

Dim result As String = ""
Dim controller As ZWaveController = Connect()

If controller.Devices.Count > 0 Then
   For Each d As ZWaveDevice In controller.Devices
    result &= d.GetType().ToString() & " as Node #" & d.NodeID & " PollEnabled = " & d.PollEnabled & Constants.vbCrLf
   Next d
Else
   result = "No devices found on the network"
End If
MessageBox.Show(result)

Listing 2 – Listing the devices in the network.

Receiving Z-Wave Events

Once the devices are registered on the network, they will send event notifications back to the controller each time the sensor is triggered. The next steps for us are to write code to receive the events and forward them to any client applications that are connected. To do this we’ll write a Windows Service that listens for events from the sensors.

All of the work for listening for events from the Z-Wave devices is handled for us by the ControlThink SDK. We simply connect to the controller and sink the LevelChanged event. We do this in our Run method, which is called from within our service’s OnStart function.

C#

public void Run() {
   try  {
       _controller = new ZWaveController();
       try  {
          _controller.Connect();
       }
       catch (Exception ex) {
          throw new Exception("Unable to connect.\r\n" + ex.ToString());
       }

       _controller.LevelChanged += new ZWaveController.LevelChangedEventHandler(_controller_LevelChanged);

       _policyListener = new PolicyListener();
       _listener = new SocketListener();
       _listener.Port = 4530;
             
        new System.Threading.Thread(new System.Threading.ThreadStart(_listener.StartSocketServer)).Start();
        new System.Threading.Thread(new System.Threading.ThreadStart(_policyListener.StartSocketServer)).Start();
        new System.Threading.Thread(new System.Threading.ThreadStart(ClearRecent)).Start();
   }
   catch (Exception ex) {
       Logger.WriteException(ex);
   }
}

VB.Net

Public Sub Run()
   Try
       _controller = New ZWaveController()
       Try
          _controller.Connect()
       Catch ex As Exception
          Throw New Exception("Unable to connect." & Constants.vbCrLf & ex.ToString())
       End Try

       AddHandler _controller.LevelChanged, AddressOf _controller_LevelChanged

       _policyListener = New PolicyListener()
       _listener = New SocketListener()
       _listener.Port = 4530

        CType(New System.Threading.Thread(New System.Threading.ThreadStart(AddressOf _listener.StartSocketServer)), System.Threading.Thread).Start()
        CType(New System.Threading.Thread(New System.Threading.ThreadStart(AddressOf _policyListener.StartSocketServer)), System.Threading.Thread).Start()
        CType(New System.Threading.Thread(New System.Threading.ThreadStart(AddressOf ClearRecent)), System.Threading.Thread).Start()
   Catch ex As Exception
       Logger.WriteException(ex)
   End Try
End Sub

Listing 3 – Listening for Z-Wave events when our service starts up.

In addition to listening for events from the ZWave Controller, our Run method also sets up socket listeners for talking to the Silverlight client application, which we will talk about later. An important detail to note, however, is the use of threading in the Run method. Remember that this is called directly from our service’s OnStart code which we should not block - if you block OnStart, you’ll see the service stuck at “Starting...” in the Service Control Manager. Anything that will block or that is long running (such as a socket listener) needs to run on a separate thread.

When the controller detects that one of the sensors has changed its state, it throws the LevelChanged event to our service. Our service handles LevelChanged in the _controller_LevelChanged method. The signature for the LevelChanged event looks like this:

void _controller_LevelChanged(object sender, ZWaveController.LevelChangedEventArgs e)

The LevelChangeEventArgs contains the original device that raised the event. We have three door sensors connected to our network. When any of them are triggered, LevelChanged is raised and we can inspect the LevelChangedEventArgs to get the NodeID of the unique identifier of the device. That’s all there is to interacting with the Z-Wave network.

Silverlight 2.0

Now that we’ve got the server infrastructure set up it is time to build a client application so we can actually start using Stall Status. I built the client application in Silverlight as an exercise to show how to use Silverlight 2.0’s access policy to make cross domain network calls from a Silverlight client application. I also knew that it is simple to deploy a Silverlight application as a Windows Vista Gadget, and the Sidebar was to be my preferred deployment model for the application.

Figure 1 – Stall Status interface

The main UI for the application is pretty simple – three ellipses, one for each stall, colored green if the stall is available and red if the stall is occupied. Most of the challenge with building the client piece has to do with connecting to the service and listening for updates. To do this, we create a persistent TCP connection and wait for data to be sent from the service over the socket. This is much better than a polling approach for an application like this because of the way the Z-Wave door sensors work. They are in sleep mode most of the time, and are only using power when they transmit a signal due to the door opening or closing. If we polled the devices frequently, it would kill the batteries in the device. Also, most of the time there is no change to the state of the doors, so polling would really be a waste.

Silverlight contains certain security mechanisms around network connectivity, especially TCP sockets. This is due to the fact that a Silverlight application runs in the context of the user’s browser, so special controls need to be in place to limit the type of connectivity that Silverlight applications can initiate. For socket-based connections, Silverlight 2.0 requires an access policy to be in place on the target server. This access policy essentially is a challenge/response mechanism that prevents a Silverlight application from connecting to an arbitrary server, potentially masquerading as the end user.

Access Policy

An Access Policy must be in place on the server for in order to enable a Silverlight 2.0 client to connect using sockets. The Silverlight framework handles all of the validation for the presence of the access policy, so your client application does not need to do anything. However, if the proper policy is not in place on the target server, Silverlight will throw an Access Denied exception, so your client application should be prepared to handle this situation. This is all very similar to how network access in Flash applications work. In fact, Silverlight can consume Flash policy files directly, as well as Silverlight policy files. In the Stall Status application, we’re going to be using Silverlight policy.

When a Silverlight application attempts to open a socket to a target server, Silverlight will automatically look for an access policy on the server by establishing a TCP connection over port 943, and sending a policy request. The policy request is simply an XML-style string: <policy-file-request/>. It is up to the author of the service that is receiving the request to ensure that they properly respond to this request, or else Silverlight will raise an exception on the client. All of this is described in detail in the MSDN documentation on the new network security restrictions in Silverlight 2.0.

In order to respond to a request for an access policy on our server, we need to implement a network listener on port 943 that responds to Silverlight’s policy file request. Dan Wahlin wrote a multi-part blog post showing exactly how to do this, and the listener I used for Stall Status, plus much of the other socket code, is copied from his example. I recommend reading his post - it is a great primer on writing TCP socket clients in Silverlight 2.0.

Our listener class run in our windows service and simply sets up a listener on port 943. When it receives a policy file request, it returns the appropriate response, as shown below.

<?xml version="1.0" encoding ="utf-8"?>
<access-policy>
  <cross-domain-access>
    <policy>
      <allow-from>
        <domain uri="*" />
      </allow-from>
      <grant-to>
        <socket-resource port="4530" protocol="tcp" />
      </grant-to>
    </policy>
  </cross-domain-access>
 </access-policy>

This response tells Silverlight to allow incoming connections to port 4530, which is the port that our service is listening on to accept connections from our Silverlight client.

Why is this important? Well, without access policy in place, there is nothing that prevents a malicious Silverlight application from connecting to a server without permission. For example:

• Suppose you have an active session with your online bank. A malicious Silverlight application served up from Site A could attempt to connect to your bank using your existing login token (which may be stored as a cookie). With access policy in place, your bank would need to have a policy stating that it allowed Silverlight applications originating from Site A to connect to your bank.
• Suppose you connect to Site A and download a malicious Silverlight application. The application can potentially connect to your corporate intranet and because you are on a corporate domain, the Silverlight app impersonates you. With the access policy rules in place, this would be prevented.

Persistent client connections

Now that we’ve got our access policy in place, we’re ready to code up our Silverlight client to connect to our server and wait for updates. Silverlight 2.0 can only connect using sockets over the port range 4502-4534. Our Windows Service uses 4530. It creates a listener on this port and then sits and waits for connections from our Silverlight clients.

C#

_listener = new TcpListener(IPAddress.Any, Port);
_listener.Start();
while (true)
{
   _waitEvent.Reset();
   _listener.BeginAcceptTcpClient(new AsyncCallback(OnBeginAccept), null);
   _waitEvent.WaitOne();
}

VB.Net

_listener = New TcpListener(IPAddress.Any, Port)
_listener.Start()
Do
   _waitEvent.Reset()
   _listener.BeginAcceptTcpClient(New AsyncCallback(AddressOf OnBeginAccept), Nothing)
   _waitEvent.WaitOne()
Loop

Listing 4 – Our main listener for client connections

We’re using asynchronous sockets, so we’ve set up a delegate – OnBeginAccept – to accept and process our connections. The code to process the connects is listed below.

C#

_waitEvent.Set();
TcpListener listener = _listener;
TcpClient client = listener.EndAcceptTcpClient(ar);

if (client.Connected)
{
   Logger.WriteLine("Accepted a connection from " + client.Client.RemoteEndPoint.ToString());

   StreamWriter writer = new StreamWriter(client.GetStream());
   writer.AutoFlush = true;
   _clients.Add(writer);
   writer.WriteLine("Connected.");

   if (ClientConnected != null)
   {
     ClientConnected(this, null);
   }
}

VB.Net

_waitEvent.Set()
Dim listener As TcpListener = _listener
Dim client As TcpClient = listener.EndAcceptTcpClient(ar)

If client.Connected Then
   Logger.WriteLine("Accepted a connection from " & client.Client.RemoteEndPoint.ToString())

   Dim writer As New StreamWriter(client.GetStream())
   writer.AutoFlush = True
   _clients.Add(writer)
   writer.WriteLine("Connected.")

   If ClientConnected IsNot Nothing Then
     ClientConnected(Me, Nothing)
   End If
End If

Listing 5 – Accepting a new client connection

Here we are simply adding a StreamWriter for each connected client to a List. We do this so when we receive events from the door sensors, we can loop through this List and notify all of the clients. We notify them by writing a tokenized string to the StreamWriter. We also have code to remove any clients from the list if we fail to write to their stream. This way we can catch the situation where the client disconnected.

C#

for (int i=_clients.Count-1;i>=0;i--)
{
   try
   {
      _clients[i].WriteLine(eventText);
   }
   catch (Exception ex)
   {
      Logger.WriteException(ex);
      Logger.WriteLine("Removing client # " + i + " because we failed to send them data.");
      _clients.Remove(_clients[i]);
   }
}

VB.Net

For i As Integer = _clients.Count-1 To 0 Step -1
   Try
      _clients(i).WriteLine(eventText)
   Catch ex As Exception
      Logger.WriteException(ex)
      Logger.WriteLine("Removing client # " & i & " because we failed to send them data.")
      _clients.Remove(_clients(i))
   End Try
Next i

Listing 6 – Sending an update to all clients

The text we pass to each client (represented in the code above by the eventText variable) is simply the NodeID of the sensor that triggered the event and the state (open/closed) on the sensor. The Silverlight client receives this text, parses it out, and updates the color of the ellipse accordingly.

C#

private void UpdateText(string text)
{
    string[] parts = text.Split(' ');

    if (parts.Length != 2) {
        return;
    }

    int stallNumber = Convert.ToInt32(parts[0]);
    string status = parts[1].ToLower();

    StatusIndicator thisStall = null;
    switch (stallNumber) {
        case 1:
            thisStall = this.Stall1;
            break;
        case 2:
            thisStall = this.Stall2;
            break;
        default:
            thisStall = this.Stall3;
            break;
    }

    if (status.Trim() == "open") {
        thisStall.Status = StallStatus.Open;
    }
    else if (status.Trim() == "closed") {
        thisStall.Status = StallStatus.Closed;
    }
    else if (status.Trim() == "recent") {
        thisStall.Status = StallStatus.Recent;
    }
    else {
        thisStall.Status = StallStatus.Unknown;
    }
}

VB.Net

Private Sub UpdateText(ByVal text As String)
    Dim parts() As String = text.Split(" "c)

    If parts.Length <> 2 Then
        Return
    End If

    Dim stallNumber As Integer = Convert.ToInt32(parts(0))
    Dim status As String = parts(1).ToLower()

    Dim thisStall As StatusIndicator = Nothing
    Select Case stallNumber
        Case 1
            thisStall = Me.Stall1
        Case 2
            thisStall = Me.Stall2
        Case Else
            thisStall = Me.Stall3
    End Select

    If status.Trim() = "open" Then
        thisStall.Status = StallStatus.Open
    ElseIf status.Trim() = "closed" Then
        thisStall.Status = StallStatus.Closed
    ElseIf status.Trim() = "recent" Then
        thisStall.Status = StallStatus.Recent
    Else
        thisStall.Status = StallStatus.Unknown
    End If
End Sub

Listing 7 – Receiving the update on the client from the server

The only other thing the application contains is the concept of "recently occupied". Once a stall has been vacated, we track it as recently occupied. This shows up on the client application as a yellow ellipse. To do this we keep track of a timestamp whenever the door opens.  Our Service contains a dedicated thread that checks for doors opened more than 2 minutes ago. If it finds any, it changes the door's status from “Recent” to a status of “Opened”.

C#

private void ClearRecent()
{
  while (!_wait.WaitOne(10000,false))
  {
    var q = from stall in _stalls
      where stall.Timestamp.AddMinutes(2) < DateTime.Now && stall.State.Equals(DoorState.Recent)
      select stall;

    foreach (Stall stall in q)
    {
      if (stall.State.Equals(DoorState.Recent)) {
        stall.State = DoorState.Open;
        Broadcast(stall.NodeID, DoorState.Open);
      }
    }
  }
}

VB.Net

Private Sub ClearRecent()
  Do While Not _wait.WaitOne(10000,False)
    Dim q = From stall In _stalls _
            Where stall.Timestamp.AddMinutes(2) < DateTime.Now AndAlso stall.State.Equals(DoorState.Recent) _
            Select stall

    For Each stall As Stall In q
      If stall.State.Equals(DoorState.Recent) Then
        stall.State = DoorState.Open
        Broadcast(stall.NodeID, DoorState.Open)
      End If
    Next stall
  Loop
End Sub

Listing 8 – Clearing the “recently opened” flag

Vista Sidebar Gadget

Once I had the Service and Silverlight client apps written, it was time to deploy the client as a Vista Sidebar Gadget. This is actually pretty simple to do with a Silverlight application, but there are a couple things to work through for 64-bit versions of Vista.

Packaging a Silverlight application to run as a Gadget is not that different than running it locally or via a web page. You simple collect all of the files for your application, add a manifest file, zip them up, and rename the ZIP file so it has a .gadget file extension.

One easy way to create the manifest file is to start from an existing file from one of your existing gadgets. You can find your installed gadgets in the folder \Users\<user name>\AppData\Local\Microsoft\Windows Sidebar\Gadgets. Note that by default the AppData folder is hidden. Check the folders of any of your gadgets and you’ll see that they all contain an gadget.xml file. Copy one of these, open it, and make any changes that you need to. Most of the elements in the file are self explanatory, but for a full explanation, check out this article.

Once you’ve got your files and manifest packaged up, you can distribute your gadget. Users can run .gadget files directly in Vista and Vista automatically installs them into the sidebar.

Figure 2 – Stall Status deployed as a Vista Sidebar gadget

One note with Silverlight-based gadgets and the 64-bit version of Windows Vista: Since Silverlight is a 32-bit application, you cannot directly host Silverlight-based gadgets in the 64-bit version of Sidebar.exe (which is the running by default on 64-bit Vista). As a work around, you can run the 32-bit version of Sidebar.exe, which is located in the \Program Files (x86)\Windows Sidebar\ folder.

As we’ve seen in this article it is easy to use .Net to control a Z-Wave network, and there are tons of creative uses for the technology. Writing network-enabled Silverlight applications has become much more powerful in Silverlight 2.0. And deploying Silverlight-based applications as Vista Sidebar Gadgets is pretty simple.

The Coding4Fun Developer Kit that was released to CodePlex last month contains a bunch of neat libraries and components for jumpstarting development against some of the new features of Vista. Included in the kit is a managed wrapper around Bluetooth communication that is designed to run in non-mobile environments – something that has not previously been widely available. With most newer laptops shipping with Bluetooth radios, and the proliferation of Bluetooth devices and receivers, I looked forward to trying this out. To get familiar with the managed wrappers, I built a simple screen locking application that I call Bluetooth Screenlock. The Bluetooth ScreenLock application runs on your PC, connects to your phone, and when it detects that you've walked out of range, locks your workstation. Using the Bluetooth wrappers included in the Coding4Fun Developer Toolkit makes this pretty simple.

Bluetooth Profiles

The managed Bluetooth wrapper classes that are part of the Coding4Fun Developer Kit (C4F Kit) contain libraries for connecting to three different Bluetooth profiles: Serial Port, File Transfer and Object Push. A profile is a standardized interface specification that devices comply to in order to communicate with each other. For the Bluetooth ScreenLock application I used the Serial Port profile to establish a connection and then send heartbeat messages across the Bluetooth channel periodically. If any heartbeat were to fail, the program will lock the user's workstation.

Discovery and Pairing

Discovery is the process of detecting nearby Bluetooth devices and potentially asking them to enumerate their supported services. In order to discover a device and enumerate its services, one of two things must happen: The phone must be set to discovery mode, which enables any other Bluetooth device to see it, or the two devices must be paired. Note for security reasons you generally don't want to leave your phone set up as discoverable.

Pairing is the process of establishing a trust relationship between two devices. Pairing usually involves the exchange of a key pair – a pin-like series of digits that must be entered on both devices before the trust relationship is established. In order to use the Bluetooth ScreenLock application you must pair your phone to your PC. You can start this from the PC, or from your phone. In Vista you can start the pairing process by opening the Bluetooth Devices utility and clicking the Add button on the Devices tab (see Figure 1).  Note that I built and tested the application with a Motorola Q smartphone.

Figure 1 - The Bluetooth Devices utility in Vista

Once you've paired your phone to your PC, you can use the application. I decided to build the application as a Windows Forms application, but it just as easily could have been a Windows Service set to start automatically. The form is simple – just a combo box listing nearby devices and a button to enable the ScreenLock feature. It would be a pretty easy exercise to configure the application to automatically enable itself at Windows startup.

Figure 2 - The ScreenLock window

Connecting to a device

The code for the ScreenLock application uses just two of the functions in the C4F toolkit – DiscoverDeviceByName and DiscoverServicesByType. DiscoverDeviceByName is used to get an instance of a Device, which is a managed class exposed through the C4F.DevKit.Bluetooth.DeviceAndServiceDiscovery assembly.

C#

public bool DiscoverDevice(string deviceName){    bool returnValue = false;    try    {        DeviceServicesManager _manager = new DeviceServicesManager();        SelectedDevice = _manager.DiscoverDeviceByName(deviceName);        if (SelectedDevice != null)        {            returnValue = true;        }    }    catch (Exception ex)    {        throw new Exception("An unexpected error was raised during device discovery." + Environment.NewLine + ex.Message);    }    return returnValue;} 

VB.Net

Public Function DiscoverDevice(ByVal deviceName As String) As Boolean    Dim returnValue As Boolean = False    Try        Dim _manager As DeviceServicesManager = New DeviceServicesManager()        SelectedDevice = _manager.DiscoverDeviceByName(deviceName)        If Not SelectedDevice Is Nothing Then            returnValue = True        End If    Catch ex As Exception        Throw New Exception("An unexpected error was raised during device discovery." & Environment.NewLine & ex.Message)    End Try    Return returnValue End Function

Once you have an instance of a Device, you can get a handle to the serial port service by calling DiscoverServicesByType.  After that you could connect directly to the service on the device:

C#

public bool Connect(){    bool returnValue = false;    List<RemoteService> serviceList = _manager.DiscoverServicesByType(SelectedDevice, ServiceType.SerialPortProfile);    RemoteService remoteService = null;    try    {        remoteService = serviceList[0];        _stream = remoteService.Connect();        _connectedService = remoteService;        returnValue = true;    }    catch (ServiceConnectionException servEx)    {        throw new Exception("An error occurred while trying to connect to " + remoteService.Name + Environment.NewLine + "Error Details: " + servEx.Message);    }    catch    {        throw;    }    return returnValue;}

VB.Net

Public Function Connect() As Boolean    Dim returnValue As Boolean = False    Dim serviceList As List(Of RemoteService) = _manager.DiscoverServicesByType(SelectedDevice, ServiceType.SerialPortProfile)    Dim remoteService As RemoteService = Nothing    Try        remoteService = serviceList(0)        _stream = remoteService.Connect()        _connectedService = remoteService        returnValue = True    Catch servEx As ServiceConnectionException        Throw New Exception("An error occurred while trying to connect to " & remoteService.Name & Environment.NewLine & "Error Details: " & servEx.Message)    Catch        Throw    End Try    Return returnValue End Function

Bluetooth devices are recognized by their 48-bit address, but most devices use a friendly name to identify themselves. The friendly name can usually be changed by the owner of the device. The ScreenLock application allows the user to specify the friendly name to use to connect, or to search for paired devices (in the case where they don't know the device name). To search for nearby devices the app uses the DiscoverAllDevices function with returns a list of Device objects. Since we only need the device names to populate our combo box, we use a simple LINQ query to extract the names and project them into a List of type string:

C#

public List<string> DiscoverDevices(){    var q =        from device in _manager.DiscoverAllDevices()        select device.Name;    return q.ToList<string>();}

VB.Net

Public Function DiscoverDevices() as List(Of String)   Dim result As List(Of String) = New List(Of String)   For Each d As Device in _manager.DiscoverAllDevices()      result.Add(d.Name)   Next   Return result End Function

Once a device is connected to the serial port profile, the application simply uses a timer to periodically write a byte of text to the port. If the transmission fails for any reason, the application will lock the workstation by calling the LockWorkstation API call from user32.dll.

C#

public bool Ping(){    bool returnValue = true;    if (!object.Equals(_stream,null)) {        try        {            _stream.WriteByte(1);        }        catch (Exception ex)        {            returnValue = false;        }    }    return returnValue;}

VB.Net

Public Function Ping() As Boolean    Dim returnValue As Boolean = True    If (Not Object.Equals(_stream,Nothing)) Then        Try            _stream.WriteByte(1)        Catch ex As Exception            returnValue = False        End Try    End If    Return returnValue End Function 

The excellent Coding4Fun Developer Toolkit hides all of the complexity of setting up socket connections using the Bluetooth protocol and exposes a few simple but useful functions for interacting with Bluetooth devices from managed code. If you're interested in writing Bluetooth apps in managed code, I suggest you take a look at it – it includes several detailed samples. In addition to the Bluetooth wrapper, there several other cool samples, such as those showing you how to write your own Preview Handlers and interact with Windows Vista Contacts.

Back in October one of my co-workers at Clarity, Kevin Marshall, wrote an article about how he modified the foosball table in our employee lounge to allow us to track game results and individual player statistics (see article here). Statistics are the basis for bragging rights, and at a competitive software development company, we're big on bragging rights. Following in the tradition of the foosball, we next set out to make similar capabilities to track scoring and statistics for our recreational dart board. We ended up building a WPF-enabled windows form-based application to use as our virtual scoreboard, attached it to a touch screen monitor, and hooked it up to a database to track statistics. This article will show how we went about building a Cricket scoreboard application. 

Since the application makes heavy use of animations, a video works better to convey some of the features.  You can view a video of the dart board application in action here.

Windows Presentation Foundation

Windows Presentation Foundation (WPF) is Microsoft's next generation framework for building rich user experiences for both forms-based and web-based applications. At the core of WPF is the Extensible Application Markup Language (XAML – pronounced “Zamel”) which allows developers to lay out a user interface using XML in a hierarchical tree structure. If you're not familiar with WPF, you may want to stop reading this article and first read an overview of WPF on MSDN. This article assumes you have a basic understanding of the concepts of WPF. I built the application in this article using the November 2006 CTP of the Visual Studio 2005 extensions for .NET Framework 3.0. Make sure you install the .NET 3.0 runtime prior to installing the Visual Studio extensions.

Laying out the main form

In support of WPF, Microsoft has released a slew of tools that make writing WPF applications easier. Expression Studio is a suite of tools that Microsoft market's towards “creative designers”, but these tools are equally important for developers, especially with the WPF framework's designer glitches in the current release. In many cases you cannot use the designers built into Visual Studio. For example, if your forms use controls that you create, you will not be able to open your XAML file in the visual designer in Visual Studio. To get around this, you can use Expression Blend to open your Visual Studio project and view your form (Expression Blend can natively open Visual Studio project and solution files).

Figure 1: Microsoft Expression Blend XAML editor

Expression Blend is great for editing XAML and creating Storyboard (animations) but it is important to note that the tool is not a code editor.  You cannot edit the .NET code behind files or even HTML or Javascript files from within Expression Blend.  However, there is nice integration with Visual Studio .NET - opening a code file from within Expression Blend will automatically kick off an instance of Visual Studio, open your solution, and present you with the source file to edit.

Our application contains just a few screens - the main dartboard form, plus a couple forms used to manage the players in the game and view statistics. Our scoreboard application will be run in a kiosk and use a touch screen monitor as the main interface. The idea is that a player throws the dart, and then touches the appropriate section of the screen to indicate where the dart landed. The scoreboard then tracks the score and statistics based on the accumulated data.
To create the main form I started with a vector image of a dartboard and used Expression Design to export the image to XAML. The vector image consists of paths for each individual component so the resulting XAML will contain the details for each path. Below is a sample snippet from a one of the Path elements in the scoreboard's XAML. Each individual Path element makes up a second of the image.

<Path x:Name="Path" Width="93.8075" Height="113.784" Canvas.Left="120.154" Canvas.Top="641.654" Stretch="Fill" Fill="#FFFF1A00" Data="F1 M... />

Once I have the XAML representation of the board, I can rename the individual Path elements and make them “clickable” by simply adding the appropriate attributes to each Path element, and then writing the event handler in the code behind file. In this case, I added the OnLeftMouseUp attribute to each Path element which would be raised for each section whenever the player clicks on the board.

<Path x:Name="Double16" MouseLeftButtonUp="Double16Click" Width="93.8075" Height="113.784" Canvas.Left="120.154" Canvas.Top="641.654" Stretch="Fill" Fill="#FFFF1A00" Data="F1 M... />

In the example Path above – the Double16 – the resulting code behind that would handle the event looks like this:

C#

        void Double16Click(object sender, EventArgs e)
        {
            OnDartThrown(Darts.Dart16, 2);
        }

VB

        Private Sub Double16Click(ByVal sender As Object, ByVal e As MouseButtonEventArgs)
            OnDartThrown(Data.Darts.Dart16, 2)
        End Sub

The OnDartThrown method simply performs a swtich on the Dart enum and performs the appropriate animation followed by notifying the game class to record the score.

Scoring and Rules

Since we envision using this framework to support multiple dart games, we created a BaseGame class and derived a CricketGame class from BaseGame. Our scoreboard has a member variable of type BaseGame that is set to an instance of the current game type (note: we didn't implement multiple game types yet –that could be done by adding an additional screen to choose the type of game to play – so for this version all games are of type Cricket). Our BaseGame has a virtual method called UpdateGame that is called after every dart is thrown. This gives the game class a change to update any game data, player scores, statitistics, or other state as required. Since our game is Cricket, CricketGame class manages the scoring rules specific to Cricket, such as maintaining open/close state of each target number:

C#

   if (lastDartThrown != Darts.DartOutOfBounds)
   {
       score = UpdateScores(lastDartThrown, numberThrown);
       UpdateClosedStatus(lastDartThrown);
   }

   List<int> dartMarks = _players[_currentPlayerIndex].MarkDart(lastDartThrown, numberThrown);
   _dartHistory.Push(new DartHistoryItem(score, lastDartThrown, numberThrown,wasClosed, _currentPlayerIndex, _round, dartMarks));

VB

        If lastDartThrown <> Darts.DartOutOfBounds Then
            score = UpdateScores(lastDartThrown, numberThrown)
            UpdateClosedStatus(lastDartThrown)
        End If

        Dim dartMarks As List(Of Integer) = _players(_currentPlayerIndex).MarkDart(lastDartThrown, numberThrown)
        _dartHistory.Push(New DartHistoryItem(score, lastDartThrown, numberThrown, _
        wasClosed, _currentPlayerIndex, _round, dartMarks))

Setting up the animations

One of the key new capabilities WPF gives to developers is a way to add animations to their applications. For the dartboard framework, we wanted to add animations after each scoring throw. To give us a good variety, we played around with several different types of animations as part of the storyboards in our application.  For the dartboard scoreboard we built custom animations for various events that occur during the game – scoring throws, transitions between the scoreboard and the settings screens, and transitions between rounds during the game. We implemented our animations in .Net and referenced the .Net classes from within the XAML by adding a namespace declaration in the root node of our scoreboard XAML file. Referencing .Net code from within XAML (and also referencing XAML-defined elements from within .Net) is an important concept to understand when writing complex WPF applications.

<UserControl
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:uc="clr-namespace:DartScoreboard.GUI.Controls" 
    xmlns:CustomAnimations="clr-namespace:DartScoreboard.Animations" .../>

With the namespace for our custom animations declared, we can reference them via storyboards in the XAML. For example, the XAML below is a storyboard that refers to our BounceDoubleAnimation.

      <Storyboard x:Key="roundChangedAnimation" SpeedRatio="2.0">               
              <CustomAnimations:BounceDoubleAnimation
                    From="-500" To="0" Duration="0:0:5" EdgeBehavior="EaseOut" 
            Storyboard.TargetName="roundChangedBounce" 
            Storyboard.TargetProperty="(TranslateTransform.Y)"/>
      </StoryBoard>

This animation is used during the transition from one round to the next, and results in the text bouncing as it moves from the top of the screen to the bottom.

DependencyProperties

One of the steps in implementing the animation in a .Net code-behind class is to define DependencyProperties. DependencyProperties are special types of properties that can be used by WPF to perform things like data binding, animations, inheritance, and styling. It is DependencyProperties, for example, that allow the WPF runtime to render the styling of a child element based on where it is nested in the XAML tree.  For our custom animations, any properties we want to add to our classes that affect or control the animation behavior must be defined as DependencyProperties.  For example, our BounceDoubleAnimation has a property called EdgeBehavior that controls whether the animation starts on the screen and moves off the screen (EdgeOut) or starts off the screen and moves onto the screen (EdgeIn).  We define this as a DependencyProperty below.

Creating a DependencyProperty in your code required two steps: First, you need to register the property with WPF. Second, you need to define property Get and Set methods that call the special GetValue and SetValue functions used to read and write DependencyProperties. The example below shows how to register the “EdgeBehavior” DependencyProperty used by the BounceDoubleAnimation:

C#

        public static readonly DependencyProperty EdgeBehaviorProperty =
            DependencyProperty.Register("EdgeBehavior",
                typeof(EdgeBehaviorEnum),
                typeof(BounceDoubleAnimation),
                new PropertyMetadata(EdgeBehaviorEnum.EaseInOut));

VB

        Public Shared EdgeBehaviorProperty As DependencyProperty = _
            DependencyProperty.Register("EdgeBehavior", _
                GetType(EdgeBehaviorEnum), _
                GetType(BounceDoubleAnimation), _
                New PropertyMetadata(EdgeBehaviorEnum.EaseInOut))

This snippet below shows how to create the property Get and Set methods for a DependencyProperty. Notice the calls to the GetValue and SetValue methods. 

C#

        /// <summary>
        /// Specifies which side of the transition gets the "bounce" effect.
        /// </summary>
        public EdgeBehaviorEnum EdgeBehavior
        {
            get
            {
                return (EdgeBehaviorEnum)GetValue(EdgeBehaviorProperty);
            }
            set
            {
                SetValue(EdgeBehaviorProperty, value);
            }
        }

VB

        Public Property EdgeBehavior() As EdgeBehaviorEnum
            Get
                Return CType(GetValue(EdgeBehaviorProperty), EdgeBehaviorEnum)
            End Get
            Set(ByVal Value As EdgeBehaviorEnum)
                SetValue(EdgeBehaviorProperty, Value)
            End Set
        End Property

Invoking Animations from managed code

Like most things in WPF, animations can be defined declaratively in the XAML, or via managed code.  Similarly, they can be triggered from within the XAML, or dynmaically from .NET.  In this case, we've defined the animations in Storyboard elements in the XAML, but we'll call them from .NET (for example, as a result of a dart being thrown).  It is easy to get a reference to a Storyboard and invoke methods against the managed Storyboard class: 

C#

        private void AnimateDoubleBull()
        {
            Storyboard doubleBullAnimation = (Storyboard)FindResource("doubleBullAnimation");
            doubleBullAnimation.Begin(this);
        }

VB

        Private Sub AnimateDoubleBull()
            Dim doubleBullAnimation As Storyboard = CType(FindResource("doubleBullAnimation"), Storyboard)
            doubleBullAnimation.Begin(Me)
        End Sub

Putting it all together

While all the WPF related features were fun to build, the real purpose of the framework is to track statistics. For our purposes we will track the typical win/loss record, plus player efficiency, which is the ratio of darts thrown to scoring throws. Since a “scoring throw” has a different meaning depending on what game is being played, we write the code to handle scoring in the derived BaseCricket class. For example, for Cricket we define a scoring throw as any throw that hits a 15 or higher, or a bullseye. We store this per player in a simple database and then compile statistics on the most efficient players. This isn't perfect of course but it works well for what we wanted. With a little work (and some interruption to the game's flow), you could compile statistics on a per target level to answer questions like who is the best at hitting the triple 20.

With the game framework coded and looking good we next looked to find a good place to position the touch screen monitor. We wanted a place that was convenient to the thrower, but yet not in the way. At first we mounted the monitor on the wall adjacent to the thrower. This worked well but we didn't have a good place to put the PC. We eventually ended up building a kiosk to house the PC with an angled top containing the touch screen monitor.

This made the whole presentation seem a little nicer and with the addition of some color and a couple Clarity logos it could make a great conversation piece when it comes to recruiting.