xAP Message Viewer

From XAP Automation
Jump to: navigation, search

The Message Viewer is a graphical utility designed to monitor your xAP network traffic. It displays the xAP device structure on your network in a tree format, along with all messages transmitted by any device. Filtering capabilities allow the viewing of key network traffic rather than a storm of xAP messages that would otherwise be seen.


Update

This page by Stuart Booth describes the development of xAP Message Viewer.

The current message viewer application for xAP is xFx Viewer.

A Little Background History

When I first started on the xAP road I knocked up a simple application called Listener. It was a very plain console-mode application that printed out any messages as they arrived. Seeing the messages whiz past in real-time is possible in a small scale xAP deployment if you're quick. However, since Listener has very few filtering options, as the number of xAP applications and xAP-enabled devices built up, the volume of xAP message traffic quickly overwhelmed this application.

Console-mode xAP message viewer

Initially it had been written as a test of xAPFramework code, but it quickly served a more useful purpose. Its time ended with the development of the graphical xAP Hub. A certain family resemblance between the Hub and the Viewer applications indicates the common code-base for the two applications.

However they differ quite substantially in functionality. A hub is simply a message forwarder to its clients. In this sense a Windows Service version is quite sufficient. Any more advanced filtering and inspection capabilities belong in the Viewer application. You can also run Viewer on any PC regardless of the current xAP Hub status of that machine, since Viewer is designed to work a Hub Client application most of the time, or a full Hub when required.

xAP Network Mapping

The key difference between Viewer and Hub is that Viewer displays all discovered xAP devices on your network in its tree view structure. This results in a very neat diagram of your xAP network. All items are categorised by their Vendor name (such as my own vendor ID: "KCSoft"), then by their Device name (such as "Viewer" or "Hub"), and finally by their Instance name (xAP Protocol Specification).

ViewerVendorDeviceInstance

Since an Instance can be described in terms of several node names this creates a variable depth view of all xAP devices.

Deeper items in a tree

Comings and Goings

xAP software applications and hardware devices are introduced into the tree structure as they are heard from. So as soon as they send a message or a heartbeat is received from the device, they'll appear in the tree.

As applications or devices are shutdown gracefully they aren't removed from the display immediately, as they would if they connected to a software hub application, another major difference between the Viewer and the Hub. In Viewer, whenever it detects an application or device that has been shutdown, or is no longer responding for some reason (it may have been shutdown without letting anybody know, leaving them to discover this when the device's heartbeats no longer arrive at some later point in time) it greys out the device branch in the tree. This helps indicate that there's a potential problem (different colours may be used in future to indicate a gracefully shutdown application vs a not-responding application) and enables the device's messages to be viewed for a while yet, as I'll discuss later.

ViewerExpiredDevice

The Effect of Hub Termination on Hub Clients

One thing to be aware of is when you run the Viewer as Hub Client. This is discussed in greater detail in the article about the xAP Hub. Viewer will run automatically as a xAP Hub if none exist when it starts. However, if, as in the image above, Viewer is a client of the primary hub, and that hub is terminated, messages from other devices will stop arriving as no hub is forwarding them. Thus the tree items will gradually grey themselves out once the Hub exits. Try it out and try later restarting the Hub. Watch as the device items are gradually restored in colour when their next heartbeat or message is received. This occurs only after the Viewer reconnects to the Hub of course so there may be a short delay until things start happening, but it occurs automatically via the xAP Protocol and is dealt with internally by xAPFramework.NET.

ViewerManyDisconnections

Removing a Device

Getting rid of some xAP node from the tree, such as one that has expired that you no longer wish to see, can be done via the node's right click menu:

ViewerTreeMenuForget

Hardware Subaddresses

This is perhaps a more obscure but wonderfully flexible area of the xAP Protocol that essentially describes different 'endpoints' within a single device or application. It is proving extremely useful as xAP is mode widely used for different applications. More details on this can be found in the xAP Protocol Specification.

The xAP Message Viewer fully supports multiple layers of hardware subaddresses. An easy example is shown below, where the two SliMP3 devices are shown as child nodes of the main SliMP3 Connector application running on my Server PC.

ViewerHardwareSubs

Message Filtering

This is a really major topic and another major benefit of using Viewer over Hub. You'll notice that there is a message rate box on the status panel of both Hub and Viewer. In complex xAP network configurations this can reach a substantial number. When this occurs the list view of messages can get very, very busy. Finding the messages in this history view can get tricky, especially as more messages are arriving all the time.

Selected Node Filtering

By clicking on any node in the tree you immediately filter the message list in the grid on the right hand side to show just those messages that match the selected tree node. In the example image above SliMP3 is selected so only the messages to be shown will be those that have already arrived from KCSoft's SliMP3 xAP device/application, in this case the SliMP3 Connector application running on my Server PC. Any messages from this device that arrive in future will also be added to the list. You can be less selective to show all messages from all KCSoft applications/devices by clicking higher up in the tree. Lastly you can be more specific in your filtering by selecting a particular device instance further down the tree, or even a particular hardware subaddress if you have any of these are particularly interesting.

The example below shows no messages but those from Mi4.biz Home Automation Watcher, including heartbeats:

ViewerSelectedNodeFilter

Session Persistent Message Type Filtering

There will almost certainly be an awful lot more xAP Heartbeats arriving than the more interesting xAP Message types. Right clicking any node in the tree allows you to alter filtering to show only Heartbeats, only Messages, or both. Here we have much the same view as shown above, but with heartbeats disabled. As a result several of the messages have been dropped from the viewn showing the really interesting content:

ViewerTreeFilterHeartbeatsOff

You can even turn both categories off so that no messages from this device are shown no matter what node in the tree is selected.

The slightly complex bit about this is that these settings are inherited further down the branch if no explicit settings are made further down. This allows you to disable heartbeats from all mi4 devices, but enable them for Watcher perhaps in two easy steps.

"Ignore All Other Devices" is a quick means of turning Messages and Heartbeats off for all other devices present now and added in future, at least during the single Viewer session. This will exclude the currently selected node and its children. You can then add back in any additional filters for other devices to narrow the view down to just the item sets you're interested in.

To clear any settings that you've made just select Reset Filters from any menu in the tree.

Future Releases

This is only the beginning of the filtering options that will be added to future releases of Viewer. Keep an eye on the xAP Automation Mailing List for announcements on this.

Animation

As a fun feature (if somewhat unnecessary!) you can animate the xAP network tree view whenever a heartbeat from a device is detected. This briefly 'pumps' that particular device node in the tree to highlight that it has sent its regular "I'm alive!" heartbeat message. This option is off by default but can be found in Tools/Options/Application Options/xAP Network Map, in the Tree Options collection of options.

ViewerAnimateHeartbeat

Configuration Options

You can control the way nodes are added to the tree structure as they are discovered. These can 'open up' the tree structure down to the new device as it first appears. These options are enabled by default and can be found in Tools/Options/Application Options/xAP Network Map, in the Tree Options collection of options.

ViewerTreeOptions

Other options are available here including some standard xAP parameters for Viewer that you may wish to customise.

Message History View

The list on the right hand side shows all messages that have arrived, that are passed by any filters on the device nodes in the tree. These can be deleted to get rid of any uninteresting ones, copied to the clipboard for use outside of the Viewer, viewed in simple editor window or even resent as full xAP messages.

Viewing a message is particular useful as it contains the actual content of any xAP message or heartbeat as it arrived. You could edit this, save it to disc and resend it later with the xAP Send Application for example.

Group selecting a set of interesting messages and having them resent is also a powerful feature for watching the interaction of several xAPpliations or devices on the network.

ViewerListResendMessage

Message History Capacity

The number of xAP messages that are retained by the Viewer in the grid display can be configured in the Tools/Options/Application Options/Messages View dialog. Once this volume is reached the oldest message is dropped.

When a device is shutdown or fails and goes silent, it will be flagged as such in the tree view. It will remain in this state until such time as no more messages from this device exist in the message history. So a larger capacity history retains nodes in the tree for longer unless the device is explicitly forgotten, as described earlier.

This application is highly recommended for all developers.

Stuart Booth