December 2011 Newsletter

Web Services Description Language

The purpose of this article is to provide a very brief description of the Web Services Description Language (or WSDL) as well as provide some resources of where to more detailed information and tutorials on the language.

WSDL is simply an XML file.  However, this file has a specific structure that can provide useful information to a user.  Specifically, WSDL is used to describe the functionality offered by a Web service.
This language is broken up into 5 parts, 3 of which (types, messages, and port type) are abstract definitions which define the interface, and the other 2 (binding and service) which are concrete details of how aforementioned abstract interfaces map to messages on the wire.

Very briefly, the 5 parts are described below:

• Types – a container for abstract type definitions defined using XML Schema.
• Message – a definition of an abstract message that may consist of multiple parts, each part may be of a different type.
• PortType – an abstract set of operations supported by one or more endpoints; operations are defined by an exchange of messages.
• Binding – a concrete protocol and data format specification for a particular PortType.
• Service – a collection of related endpoints, where an endpoint is defined as a combination of a binding and an address (or URI).

These elements together make up a WSDL definition.

Resources

For more information on WSDL and Web Services please refer to these websites:

• Understanding WSDL
• Web Services Description Language
• Web Service
• Web Services Description Language (WSDL) 1.1

Tutorials

For some tutorials about WSDL and Web Services please refer to these websites:

• WSDL tutorial
• Web Services tutorial

Skype Prevents HyperTerminal From Using Com Port

Sometimes Hypertemrinal tells you the port is in use even when you think it is not. Skype likes grabbing your com port especially COM1. When you try to use the port you can’t, even after you quit Skype. To remedy this situation, use Process Explorer to find and kill any process using the com port because Skype is not the only offender.

Steps:

1. Download Process Explorer.
2. Unzip and Run the process explorer.
3. Select FIND.
4. Type: serial.
5. You will get a list of processes using the serial ports.
6. Kill them.

An alternative solution:

1. Go to the Control Panel > System.
2. Disable COM1.
3. Reboot and then re-enable it.

VHS Drawbot

The VHS Drawbot is a drawing robot created by one of our engineers, Steven Smethurst, which can draw on small or large walls digitally. In other words, it simply transfers or prints computer graphics onto the walls effortlessly.

So, how does it climb up the wall vertically? Easy. The robot is connected with one string which its two ends go up and are hung at the top left and right rollers, and then go down to two motors on each side to control its movement.

The prototype can be seen on youtube, we welcome any feedback, questions or comments.

VHS Drawbot

Please visit our Facebook Page to watch the video.

Modbus Transaction Identifier

When sending a Modbus TCP frame, the frame is split into 6 different sections:

1. Transaction Identifier ( 2 bytes )
2. Protocol Identifier (2 bytes)
3. Length Field (2 bytes)
4. Unit Identifier (1 byte)
5. Function Code (1 byte)
6. Data bytes (n bytes)

The very important bytes for this frame are the Unit Identifier, Function Code and Data bytes and some scanners will only use these bytes when polling for and displaying information via a Modbus TCP protocol.

However other scanners will use the transaction identifier as a means of validating response messages.

The actual use for the transaction identifier is for synchronization between messages of server and client.  So if a scanner checks the transaction identifier from the query it sent against the transaction identifier from the response it receives and the values do not match, it identifies the response message as an invalid Modbus message and will timeout.

Visual Test Shell – General Information

The Visual Test Shell (or VTS) is a free and open source software.  This application is used for testing the BACnet functionality of various devices used in building automation systems.

The application can “generate BACnet compliant service messages, detect and decode BACnet compliant service messages, and run scripts to generate, receive and respond to BACnet compliant service messages.”  (VTS3Guide.doc)

Download the application, version 3.5.5.

The VTS is a testing suite that is listed by the BACnet Testing Laboratories and BACnet.org as a useful open source tool for testing your own BACnet implementations.

For more information on the project or to find some help, visit their forums.

Installation

Go to the Visual Test Shell project website and press the Download button to begin downloading.

Check your downloads directory for the newly downloaded zip file.

Unzip the files and you will see the following file directory:

Here is a description of some of the contents of the VTS directory.

Docs – Contains all the guides and documents for using VTS
QuickStart.html – Provides some quick and easy steps to get VTS working
VTS Survival Guide.doc – Provides tips and further explanation of some items from the VTS3Guide
VTS3Guide.doc – The complete guide for using the VTS application.
VTSScripting.html – A guide to using scripts with VTS.
Scripts – Contains examples of different types of scripts that can be run while using VTS.  More information about scripts and how to make and use them, will be included in an upcoming article.
PTP.dll and VTS.exe – These are the main two items that are needed for VTS to run properly.

To start the application, simply double-click the VTS.exe icon.

Note:  The PTP.dll must be included in the same directory as the VTS.exe.  If it is not, the application will not work.

Visual Test Shell – First Time Use

When you want to use the Visual Test Shell (VTS) for the first time, browse to the directory where you installed the application.

Double-click on the VTS.exe to start the application.

You will notice that two files will be generated:

1. vts3.cfg – the default workspace, which contains all of the VTS configuration data. (Devices, Ports, Names, etc.)
2. vts3.vpk – the default log file, which contains the packet data that is captured while running VTS.

These two files can be used to share sessions with other users and can be used to save specific sessions.

After starting the application you will see this screen:

Here is a brief description of the Menus and their contents:

• File: In this menu you can Create and Open Scripts, Create, Save, and Switch workspaces, Print, Export, and Exit
• Edit: In this menu you can create and edit Devices, Ports, Names, change the Logfile, and set Preferences
• View: The view menu controls the different viewing windows of the applications.  This includes the Detail View, Hex View and EPICS View.
• Send: The send menu is where you can send specific messages to created Devices or to devices that are on the network.
• EPICS: This menu is where you can load EPICS files
• Tests: The test menu is where you can back up or test for inconsistencies
• Help: Contains information about VTS

This is just a brief description of what you can do in VTS.  Future articles will delve into these options more and provide instructions on how to accomplish various tasks.

Visual Test Shell – Configuring Devices

To Configure a Device in the Visual Test Shell (VTS), follow these instructions.

1)    Click on the “Edit” menu and Select the “Devices…” option

2)    You will now see the Devices Configuration Dialogue as shown below.

3)    Fill in the necessary fields for the tests that you want to run.  The Device Tab contains device specific fields, such as Name, Instance, and Vendor ID (see Figure 2: Device Configuration Dialogue).  The Options Tab contains various support options for the device.

4)    Right-Click the newly created device.  In the Right-Click menu, Select the “New Object” option to add a new object to the selected device.  Or Select the “New Device” option to add a new device.

5)    Fill in the object information fields.

6)    From the drop down menu, Select the Object Type.

7)    Right-Click the newly created object.  In the Right-Click menu, Select the “New Property” option to add a new property to the selected object.

8)    Fill in the property information.  There are two ways to do this.  1) Select a property from the drop down “Description” menu.  Or 2) Enter the property ID value in the “ID” text box.

9)    Right-Click the newly created property.  In the Right-Click menu, Select the “New Value” option to add a new value to the selected property.

10)    Fill in the information for the value.  Select the data type from the “Data Type” drop down menu (for example: Boolean, Real, Integer, etc.).  Enter the actual value in the “Value” text field.

11)    Repeat steps 7 through 10 to add more properties and values an object.

12)    Repeat steps 4 through 6 and 11 to add more objects to a device.

13)    Right-Click to bring up the Right-Click menu and Select the “New Device” option to create a new device (see Figure 4: Device Configuration Dialogue Right-Click Menu).  Repeat steps 3 through 12 to configure another device.

Visual Test Shell – Configuring Ports

After configuring some devices and objects, the next step is to configure the ports (or connections) to connect to these devices.  For the Visual Test Shell (VTS) to be able to communicate with a device, a Port must refer to a configured Device object. Follow these instructions to configure ports in the VTS.

1)    In the “Edit” menu, Select the “Ports…” menu option.

2)    You will see the Ports Configuration Dialogue.  Click on the “New” button to begin configuring a new port

3)    Fill in the Fields for the Port

Here is a brief description of these fields.

• Name – The name of the Port (helps with identification)
• Network – The network the port exists on.

There is also a drop down menu containing a list of configured devices.  Select one of these devices to signify a connection on this port to that specific device.

Below is a set of tabs that detail the specific type of port.  The next step will detail to different types of ports and some of their configuration fields.

4)    Select a tab to choose the type of the port.  Null contains no specific parameters.

• IP – The IP tab is for setting up a BACnet IP port connection

• Interface – This drop down menu contains a list of network cards installed on the computer.  Select one of them.
• UDP Port – The is the port that the connection is on. Default is 47808 (0xBAC0)

These two are usually enough for the configuration of a simple BACnet IP port.

• Ethernet – The Ethernet tab is for setting up a BACnet Ethernet port connection

• Adapter – This drop down menu contains a list of network cards installed on the computer. Select one of them.
• Promiscuous mode – Check this box if you want to enable this mode.
• MSTP – The MSTP tab is for setting up a BACnet MSTP port connection

• MAC Address – The unique address of the port.
• Max Master – The maximum number of master devices to iterate through when passing the token.
• Max Info Frames – The maximum number of information frames.
• Baud Rate – The baud rate for the connection to the port.
• PTP – The PTP tab is for setting up a BACnet PTP port connection

• Serial Port – The serial port connection.
• Baud Rate – The baud rate for the connection to the port.
• Parity – Set at N (None).
• Data Bits – Set at 8.
• Stop Bits – Set at 1.

5)    Once a port type has been selected and configured, Check the “Enable” check box to enable the port and Click the “OK” or “Apply” buttons to save the configuration and close the dialogue.

Once one or multiple ports have been configured the next step is to configure Names.  The next article will detail the steps and describe some of the options and fields required for configuring Names.

Configuring Names

After configuring the Devices and Ports, the next step is to configure the Names.  In the Visual Test Shell (VTS) a name is a shortcut for an address.  They are used not only in the source and destination address areas of ports, but also in the SNET and DNET portion of the BACnet network layer.

Note: A Name specifies the physical (MAC) address AND the local Port for a BACnet destination.  AS such, make sure to set up a Port for the device (see the Visual Test Shell – Configuring Ports article) BEFORE setting up a Name.

Note: VTS will create an entry for itself named TD ( or Test Device).  Remember, however, that you MUST create an entry for the device being tested, and it must be named IUT, which stands for Implementation Under Test.

Follow these steps and descriptions to configure a Name.

1)    Click on the “Edit” menu and Select the “Names…” option

2)    In the Names dialogue, Click the “New” Button to begin configuring a new Name.

3) Fill in the fields and options.  The following is a brief description of the various options for configuring a Name.

Address Type

• Null – No type chosen.  Use this when you aren’t sure what Address Type is appropriate and want to fill it in later.
• Local Broadcast – Packets are sent to all devices on the local network.
• Local Station – Sends packets to any specific device on the local network.
• Remote Broadcast – Packets are sent to all devices on the specified network.
• Remote Station – Sends packets to any specific device the specified network, usually a network other than the TD’s local network.
• Global Broadcast – Packets are sent to all devices on all reachable networks.

Name – Give the entry a name

• Note:  IUT has a special meaning in VTS because scripts will automatically SEND and EXPECT messages from whatever address is associated with the IUT name, as long as an explicit destination is not specified in the script.

Port – Choose one of the configured Ports.  If no Ports have been configured, the only option will be “any port”.

Network – If you selected Remote Broadcast or Station as the Address Type, then enter in the specific network in this field.

Address – If you selected Remote Station as the Address Type, then enter in the remote device’s address in this field.

4)    Once all the fields have been filled, Click the “Okay” button to finalize the Name configuration.  You can create and configure more Names by Clicking the “New” button, or delete unneeded Names by Clicking the “Delete” button.

Configuring names is the last part of the configuring the VTS.  Once the configuration is complete, the next step is to test the configuration.  The easiest way to test your configuration is to send packets.  The next article will describe how to send packets manually.

Visual Test Shell – Sending Packets Manually

After configuring the Devices (and Objects), Ports, and Names in the Visual Test Shell (VTS) the next step is to begin sending packets.  Packets can be sent in two ways:

1. Manually creating and sending the packets, or
2. By using a script.  This article will focus on manually sending packets.

In this article you will find instructions on how to create and send a Who-Is message.  Please note that there are many other messages that can be created and sent and that some experimentation is necessary to fully understand how to create these messages.

Who-Is

The following instructions are for creating and sending a Who-Is message.

1)    Click on the “Send” menu.

Here is a brief description of the menu options:

• New Packet – Opens the send packet dialogue
• TestPort(IP) –This is where any ports that you configured will be.  Select one to begin sending packets from that port.
• IP, BVLL, Network…. – The rest of the items in the menu are submenus that contain specific message types.  For example in the “Object Access” submenu you will find the Read Property option.  Click on one of these options to begin creating a packet of that type.

2)    Move the mouse over the “Remote Device Management” submenu and Click on the “Who-Is” message.

3)    View the Send Packet dialogue.  Note: the dialogue will contain different options depending on what was selected from the “Send” menu.  Configure  the Who-Is fields contained in the Who-Is tab

The following is a brief description of the dialogue window:

• Tabs – The tabs at the top of the window contain the configurable fields to create the packet.  The tabs will change depending on what packet is being created.  In this case, for creating the Who-Is message, the IP (IP options), BVLCI (Broadcast options), NPCI (NPDU options) , and Who-Is (Who-Is options) tabs will be displayed.
• TestPort Drop Down Menu – The drop down menu on the upper right contains all the Ports that have been configured.  Use this menu to quickly select a Port.
• File Browser – The file browser on the right side of the window contains the different message types.  Browse through them and double click on the message you want to send to begin configuring it.
• Hex Stream – The hex stream at the bottom left of the window contains the bytes that will be sent.  These will change as you change the fields in each of the tabs.
• Buttons – The buttons on the bottom right allow you to send the pack and/or to close the window.

4)    Click through the other tabs and fill in the information required there.

5)    When you are satisfied with the packet you created, you can View the byte stream that will be sent, then Click the “Send” or “Send and Close” to send the packet.  If you do not want to send the packet, simply Click the “Close” button.

6)    You can see the packet information in detail in the “Detail View” or the “Hex View” frames.  Note: You can click on various sections in the Detail View which will highlight the actual bytes in the Hex View.

Once the packet has been sent, you can keep track of the packets sent in the main view.
There is another way to send packets, and that involves using scripts.  The next article will discuss what elements are in a VTS script and how they are used to send packets.

Testing MSTP Device

In order to test a BACnet MSTP device using the Visual Test Shell (VTS) there are a few items to take into consideration.

1)    The VTS will not connect to an MSTP link using an RS-485 port on a PC.

2)    The most common way to connect VTS with MSTP is to connect the VTS on IP and use a BACnet IP-to-MSTP router.

3)    The MSTP tab in the VTS Ports dialogue uses a device called the NB-Link from American Auto-Matrix.

If you do not have a NB-Link from American Auto-Matrix you must use the IP-to-MSTP router option to test the MSTP device with VTS.