BTL LAB
VTS 3 General Guide and Quick Reference
Revised April 25, 2002
By Brad Spencer
BACnet Testing Laboratories
55 Temple Pl. Boston MA 02111
(617) 350-7550 ext 242
Table of Contents
Introduction
CHAPTER
i
1
CHAPTER
3
Introduction to VTS
Manual and Scripted Testing
Requirements for Test
Manual Testing
Installation
Scripted Testing
VTS Environment
Logging
CHAPTER
CHAPTER
2
4
VTS Configuration
VTS 2.x – VTS 3 Script Conversion
Ports
Quick Reference Guide
Interfaces
Object Lists
Names
Definitions
Index
V T S
3
1
Chapter
G U I D E
Introduction to VTS 3
Audience: This guide is designed for BTL LAB testers and pre testers who are
submitting devices to the BTL lab and who need information on the latest test
tool. Knowledge of BACnet services, objects and encoding is assumed – when
referenced a term explanation is given at the left of the text.
V
TS 3 is a test tool for BACnet that was developed by the Building and Fire
Research Laboratory of N.I.S.T. The program and source code are in the
public domain.
VTS is the primary test tool used by the BTL lab to test BACnet devices for
compliance to the BACnet standard (ANSI/ASHRAE Standard 135) and is used by
manufacturers to pretest their device before submitting devices to the BTL lab. VTS 3
is a simple test tool that generates BACnet
compliant service messages.
T E R M S U S E D
IUT - Implementation Under Test
For example VTS 3 or the TD can generate a
WHO-IS message which would cause the device
 WHO-IS (see the BACnet standard)
being tested (IUT) to generate an I-AM
response. With VTS this simple test can be run
 I-AM (see the BACnet standard)
manually and the result verified manually in the
 EPICS (see the 135.1) and Definitions
VTS trace or the test can be run from a script
where the sent message as well as the received message are automatically verified and
the result passed to the tester would be in the form of a pass or fail. For more
information on manual and script tests please see chapter 3.
TD - Test Device (the PC with VTS)
Requirements for Test
In order to test a device a few basic components are needed. First the latest version of
VTS 3 needs to be correctly installed. The device being tested (IUT) needs to be on the
1
V T S
3
G U I D E
same BACnet inter-network as the VTS machine (TD). For script-based testing, a
formal description of the IUT called an EPICS must be on the TD machine.
VTS 3 System Requirements
Win95 and WinNT standard system requirements.
EPICS Requirements
An EPICS is not required in order to run manual tests using VTS. If script tests will
be run the EPICS must be written in such a way that VTS 3 is able to interpret this
document correctly. A significant amount of debugging may be necessary in order for
VTS to understand this document. For information about how to create an EPICS, go
to
the
BTL
Pretest
web
site
(http://www.bacnetassociation.org/BTLPRETEST/default.htm).
VTS 3 Script Requirements:
A script that follows all the rules of VTS 3 scripting and parses correctly under VTS 3.
General scripting information can be found at:
http://bacnetassociation.org/BTLPRETEST/Related Documents/THESIS.doc
Installation
Audience: This section assumes that the hardware and software meeting the requirements is at hand…
 Install VTS 2.29, then run the VTS 3.0 application. See
Documentation on VTS installation at:
http://bacnetassociation.org/BTLPRETEST/vtsrelease/VTSstart.htm
VTS Environment
2
V T S
3
G U I D E
Audience: This section assumes that VTS has been successfully installed…
In this section, you will get VTS up and running in a manual and scripted environment.
It would be best to start with manual testing first since this is the easiest way to test.
The Test Environment:
When VTS starts you will notice a single window titled VTS. This VTS
window holds two other windows that are the work areas for VTS.
-
The first window is the database window which holds the log files and
when this window is selected the VTS window contains options
specific for using the database window.
-
The second window is the script window which is used for making on
the fly variable changes or simple script logic changes. You will notice
that when this window is selected the VTS window toolbar changes so
that selections can be made specific to the scripting window.
Loading the EPICS: This is done from the script window. Select the
script then select the ‘Load EPICS' option from the Script toolbar in the
VTS window.
3
V T S
3
2
Chapter
G U I D E
VTS 3 Configuration
Audience: This section assumes that VTS has been successfully installed and
an IUT is placed on a reachable segment.
Configuring VTS 3
The goal of this chapter is to correctly configure the VTS TD as a valid device and
specify information that VTS can use to find the IUT. The configuration is all done
through a GUI and is stored in an external file. This external file is a database with a.
.vdb extension. This file contains all information required for VTS to communicate
with an IUT. This database is a creatable and savable file that may be opened later to
load a particular setup that VTS uses to connect to a particular IUT.
This is the device object that VTS will use for itself during testing. The UI
allows for configuration of only a small subset of properties that are required for VTS
to send a message. For more information on device objects see the BACnet standard.
Device
In VTS the port configuration section is used to describe the direct interface the
VTS machine has to the data link segment. The Port must be bound to a device
Object. This binding is accomplished in the UI by first configuring the VTS device
then selecting the device in the Ports UI. The network number and the option to
enable the port must be configured in the port section before testing a device.
Ports
In VTS ‘Names’ are used to associate a referencable name to a device on the
BACnet network or to a local or remote broadcast. The names defined here can be
used in a script or selected for a manual test. The IUT's and TDs MAC address is
specified in this form.
NAMES:
USAGE:
a. Sending unicast messages to a device across a router: The remote station check
box must be selected. The IUT name is configured in this section along with
its MAC address and network number. The TD's port that would lead to the
IUT must be set. Note: The name for the IUT must always be called "IUT".
4
V T S
3
G U I D E
b. Sending broadcast messages: The broadcast address used by VTS to
communicate to a remote device through services like Who-Is is configured in
the names UI section. If a broadcast on a local Ethernet segment is needed
then give a name to the broadcast and select 'Broadcast' in the left pane.
Step 1 Create a new .vdb
How to Create a .vdb:
a. Click - File | New | VDB then give the name and location for this database file. The name should
describe something about the IUT and TD configuration.
How to Save a vdb file: Click – File | Save…
How to Open a saved .vdb: Click – File | Open | This will load a previously saved .vdb file but does not load the EPICS or script.
Step 2 Configure Device
How to create a device object: Click – Edit | Devices Select ‘New’
a.
Give a name to the device.
b.
Specify device instance number, segment size, window size, etc.
Step 3 Configure the Port
a.
Click – Edit | Ports Select ‘New’
b.
Give a name to this port.
5
V T S
3
G U I D E
c.
Specify the media that this port is attached. For example if VTS is directly attached to an
ethernet segment then select "ethernet". Note: Do not select the media of the IUT because the IUT may
be on a remote segment using a different media.
d.
Select the Device that was created in Step 2 as well as the network number of the segment
where the TD is attached.
e.
Enable the device and select ‘OK’
Step 4 Configure the Names
a.
Click – Edit | Names Select ‘New’
b.
Specify a name for unicast or broadcast message (Must have at least one name called "IUT").
c.
Specify a name for the TD (Must have at least one name called TD)
d.
Specify the address type
e.
Select the port that was configured in Step 3
6
V T S
3
G U I D E
Step 5 Run a Manual Test to verify connectivity (See manual testing)
.
7
V T S
3
3
Chapter
G U I D E
Audience: This section assumes that the VTS machine has been configured
correctly and is able to communicate with the IUT.
Manual and Scripted testing
T
his chapter explains how to use VTS manually and through scripts. A manual
VTS test is a test that is run and verified by the tester. The tester should know
what is expected from the device in order to verify the results of manual
testing. A script run test is a test or group of tests that are started by the tester
and the results are partially or fully automatically
verified by VTS.
T E R M S
U S E D
IUT - Implementation Under test
TD - Test Device
 Scripting (see the Thesis)
 Functional Group (see the BACnet standard)
 BACnet Service (see the BACnet standard)
 NPCI (see the BACnet standard)
Manual Testing
Manual testing is best used to verify a VTS configuration, run quick tests that would
take more time to configure in scripting or to find devices on the network. Manual
tests are also an important part of debugging scripts.
Step 1 Select the functional group to be tested.
a.
In the source tab select the TD.
8
V T S
b.
3
G U I D E
In the Destination tab select IUT or a broadcast message. This depends on the type of service
being sent.
Step 2 Select the BACnet Service to be tested
a.
The service selection depends on the configuration in the Ethernet tab. Match Broadcasts with
services that can broadcast and unicast with services that can send a unicast message.
Step 3 Configuring the Ethernet tab
a)
The messages source and destination are configured here. A drop down box displays the
configured names and MAC address.
Step 4 Configuring the NPCI
a)
this tab holds configuration for network layer parameters like DLEN, DNET, DADR. And
SNET, SLEN, SADR.
b)
If the IUT is on the other side of a router then these fields must be filled in appropriately.
c)
DER – Data Expecting Reply and the Priority are configured in the NPCI tab.
Step 5 Configuring the Confirmed request
a.
Segment size, invoke ID and MAX APDU are configured in this tab.
Step 6 Configuring the service
a.
Select the functional group and service and send the message…
Step 7 Send the Message
a.
If everything is configured properly the Send button will be selectable and the message may be
sent.
Scripted Testing
The best source of information on how to write scripts is from the Thesis.doc written
by Peter H. Dillinger and the GDthesis.doc written by Georg Dudas. This section in
the test guide uses these documents as a reference to give a basic description o how to
write a VTS script based on the BACnet standard.
When to use a script. Script testing is best used for repetitive tests or when long
sequences of test steps need to be performed. Every script needs to be customized to
fit a particular device and the time it takes to configure a script may exceed the time it
would take to run a manual test- in these cases manual tests should be performed.
9
V T S
3
G U I D E
Basic Encoding for Scripting VTS send and expect messages:
1
From the BACnet Standard
2
3
4
5
ReadProperty-Request ::= SEQUENCE {
; page 377 in the 2001 BACnet Standard
objectIdentifier
[0] BACnetObjectIdentifier,
propertyIdentifier
[1] BACnetPropertyIdentifier,
propertyArrayIndex [2] Unsigned OPTIONAL
--used only with array datatype - if
omitted with an array the entire array is referenced
}
6
7
8
9
10
11
12
13
14
ReadProperty-ACK ::= SEQUENCE {
; page 377 in the 2001 BACnet Standard
objectIdentifier
[0] BACnetObjectIdentifier,
propertyIdentifier
[1] BACnetPropertyIdentifier,
propertyArrayIndex [2] Unsigned OPTIONAL, --used only with array datatype
-- if omitted with an array the
entire array is referenced
propertyValue
[3] ABSTRACT-SYNTAX.&Type
}
15
From a VTS Script
16
SEND
(
17
PDU = Confirmed-Request
17
Service = ReadProperty ; is enumerated of type BACnet ConfirmedServiceChoice
19
Object = 0, OBJECT1
20
Property = 1, Object-Identifier
; Type BACnetObjectIdentifier
)
Note: The tags for objects and properties from the BACnet standard match the VTS script.
1
Full version of a single test script:
2
---SETUP SECTION-------------------------------------------------------
3
4
; ReadProperty Service Execution Tests
; RPmmddyy.vts
5
OBJECT1 = device, 3050000
; Placed an Object Identifier into a variable
6
OBJECTX = 3, device, 3050000 Placed an object and context tag into a variable
7
INDEX2 = 4
; Placed a signed, unsigned or real into a variable
8
BITS = 1,1,1,1
; Placed a Bitstring into a variable
9
PASSW = ANSI X3.4,"aaa"
; Placed a Charstring into a variable
10
TEST #1a - Read Property of Type Object Identifier ; Tells VTS that this is the beginning of a script
11
DEPENDENCIES None
12
REFERENCE (B) ReadProperty Service and (T) Reading Object Identifiers ; Skip, don’t use
13
SEND
; Skip don’t use
(
10
V T S
3
G U I D E
14
PDU = Confirmed-Request
15
Service = ReadProperty ; is enumerated of type BACnet ConfirmedServiceChoice
16
Object = 0, OBJECT1
17
Property = 1, Object-Identifier
18
19
20
EXPECT (
PDU = ComplexAck
21
Service = ReadProperty
22
Object = 0, OBJECT1
23
Property = 1, Object-Identifier
24
; Type BACnetObjectIdentifier
)
OpenTag 3
25
-- AL = {Object-Identifier} ; Variation 1 Expected value is stored in the EPICS
26
-- AL = X'3EC402001F413F' ; Varaiation 2 Expected value is stored in hex
OBJECTIDENTIFIER = OBJECT1
27
28
CloseTag
; Variation 3 (Expected value is stored in a variable)
)
Note: There are two ways to comment either using – or ; semicolon
Note: Variables can be declared for BOOLEAN, UNSIGNED, INTEGER, FLOAT VALUES, OCTET STRINGS,
CHARACTER STRINGS, BIT STRINGS, ENUMERATED, DATE, TIME.
Note: Context tags can be embedded in the variable. See line 6
Note: Every script must have a the ‘Test’ keyword at the top of the script and a Dependencies and Reference line. For an
explanation on the Dependencies and Reference lines see the Thesis.doc.
Lines 25 – 27 – These are three ways in which a value can be compared to what is expected.
Logging
All BACnet messages sent on the wire are decoded and viewable in the built in logging
window VTS 3. At the time of writing this document the logging mechanism is being
developed.
How to View the log file: Open the .vdb file and in the left pane you will see several time
stamped packets. Select the packet to see information about sent and received packets.
11
V T S
3
4
Chapter
G U I D E
Quick Reference Guide
Before scripting the following compilation of frequently used information should be in hand.
B A C N E T
S T A N D A R D
2 0 0 1
 Print Pages 373 – 408
 Print VTS Keywords below
In the BACnet Standard 2001 in the section marked Formal
Description of APDUs (Page 373) is a section for confirmed and
unconfirmed services. There are ASN.1 modules describing how to
tag each service and is required info for scripting.
In the BACnet Standard in the section marked Formal Description
of APDUs (Page 387) is a section marked Base Types. Tagging for
these complex data types are listed here.
VTS Keywords:
Service Choice VTS Keywords
ACKNOWLEDGEALARM, CONFIRMEDCOVNOTIFICATION,
CONFIRMEDEVENTNOTIFICATION, GETALARMSUMMARY,
GETENROLLMENTSUMMARY, SUBSCRIBECOV,
ATOMICREADFILE, ATOMICWRITEFILE,
ADDLISTELEMENT, REMOVELISTELEMENT,
CREATEOBJECT, DELETEOBJECT,
READPROPERTY, READPROPERTYCONDITIONAL, EADPROPERTYMULTIPLE,
WRITEPROPERTY, WRITEPROPERTYMULTIPLE,
DEVICECOMMUNICATIONCONTROL, REINITIALIZEDEVICE,
CONFIRMEDPRIVATETRANSFER, CONFIRMEDTEXTMESSAGE,
VTOPEN, VTCLOSE, VTDATA, AUTHENTICATE, REQUESTKEY,
I-AM, I-HAVE, UNCONFIRMEDCOVNOTIFICATION,
UNCONFIRMEDEVENTNOTIFICATION, UNCONFIRMEDPRIVATETRANSFER,
UNCONFIRMEDTEXTMESSAGE, TIMESYNCHRONISATION, WHO-HAS, WHO-IS
Object Choice VTS Keywords
ANALOG-INPUT, ANALOG-OUTPUT, ANALOG-VALUE, BINARY-INPUT,
BINARY-OUTPUT, BINARY-VALUE, CALENDAR, COMMAND, DEVICE,
EVENT-ENROLLMENT, FILE, GROUP, LOOP, MULTISTATE-INPUT,
MULTISTATE-OUTPUT, NOTIFICATION-CLASS, PROGRAM, SCHEDULE
Property Choice VTS Keywords
12
V T S
3
G U I D E
ACKED-STATES, ACK-REQUIRED, ACTION, ACTION-TEXT, ACTIVE-TEXT
ACTIVE-VT-SESSIONS, ALARM-VALUE, ALARM-VALUES, ALL,
ALL-WRITES-SUCCESSFUL, APDU-SEGMENT-TIMOUT, APDU-TIMOUT,
APPLICATION-SOFTWARE-VERSION, ARCHIVE, BIAS, CHANGE-OF-STATE-COUNT,
CHANGE-OF-STATE-TIME, NOTIFICATION-CLASS,
CONTROLLED-VARIABLE-REFERENCE, CONTROLLED-VARIABLE-UNITS,
CONTROLLED-VARIABLE-VALUE, COV-INCREMENT, DATELIST,
DAYLIGHT-SAVINGS-STATUS, DEADBAND, DERIVATIVE-CONSTANT,
DERIVATIVE-CONSTANT-UNITS, DESCRIPTION, DESCRIPTION-OF-HALT,
DEVICE-ADDRESS-BINDING, DEVICE-TYPE, EFFECTIVE-PERIOD,
ELAPSED-ACTIVE-TIME, ERROR-LIMIT, EVENT-ENABLED, EVENT-STATE,
EVENT-TYPE, EXCEPTION-SCHEDULE, FAULT-VALUES, FEEDBACK-VALUE,
FILE-ACCESS-METHOD, FILE-SIZE, FILE-TYPE, FIRMWARE-REVISION, HIGH-LIMIT,
INACTIVE-TEXT, IN-PROCESS, INSTANCE-OF, INTEGRAL-CONSTANT,
INTEGRAL-CONSTANT-UNITS, ISSUE-CONFIRMED-NOTIFICATIONS, LIMIT-ENABLE,
LIST-OF-GROUP-MEMBERS, LIST-OF-OBJECT-PROPERTY-REFERENCES,
LIST-OF-SESSION-KEYS, LOCAL-DATE, LOCAL-TIME, LOCATION, LOW-LIMIT,
MANIPULATED-VARIABLE-REFERENCE, MAXIMUM-OUTPUT,
MAX-APDU-LENGTH-ACCEPTED, MAX-INFO-FRAMES, MAX-MASTER,
MAX-PRES-VALUE, MINIMUM-OFF-TIME, MINIMUM-ON-TIME, MINIMUM-OUTPUT,
MIN-PRES-VALUE, MODEL-NAME, MODIFICATION-DATE, NOTIFY-TYPE,
NUMBER-OF-APDU-RETRIES, NUMBER-OF-STATES, OBJECT-IDENTIFIER,
OBJECT-LIST, OBJECT-NAME, OBJECT-PROPERTY-REFERENCE, OBJECT-TYPE,
OPTIONAL, OUT-OF-SERVICE, OUTPUT-UNITS, POLARITY, PRESENT-VALUE,
PRIORITY, PRIORITY-ARRAY, PRIORITY-FOR-WRITING, PROCESS-IDENTIFIER,
PROGRAM-CHANGE, PROGRAM-LOCATION, PROGRAM-STATE,
PROPORTIONAL-CONSTANT, PROPORTIONAL-CONSTANT-UNITS,
PROTOCOL-CONFORMANCE-CLASS, PROTOCOL-OBJECT-TYPES-SUPPORTED,
PROTOCOL-SERVICES-SUPPORTED, PROTOCOL-VERSION, READ-ONLY,
REASON-FOR-HALT, RECIPIENT, RECIPIENT-LIST, RELIABILITY,
RELINQUISH-DEFAULT, REQUIRED, RESOLUTION, SEGMENTATION-SUPPORTED,
SETPOINT, SETPOINT-REFERENCE, STATE-TEXT, STATUS-FLAGS, SYSTEM-STATUS,
TIME-DELAY, TIME-OF-ACTIVE-TIME-RESET, TIME-OF-STATE-COUNT-RESET,
TIME-SYNCHRONIZATION-RECIPIENTS, UNITS, UPDATE-INTERVAL, UTC-OFFSET,
VENDOR-IDENTIFIER, VENDOR-NAME, VT-CLASSES-SUPPORTED,
WEEKLY-SCHEDULE
VTS 2.x – VTS 3 Script Conversion
There a only a couple very minor steps needed to convert a 2.x script to a v3 script. Other
changes will be tracked in an ongoing document that will be included into this guide.
1) All time date variables must be declared by comma separation. yy,mm,dd
instead of VTS 2.29 yy:mm:dd
2) Remove IUT config section (This information is now stored in a vdb file)
3) You may remove all reference to MAC addresses and network number variables.
13
V T S
3
G U I D E
4) Remove from all send and receives the following lines.
NETWORK = NET_1
DA = Broadcast
DNET = DNET_MSTP
DADR = IUT_MAC
DER = TRUE
Definitions
EPICS defined: The most complete and detailed description of and EPICS is in the
ASHRAE 135.1 testing standard.. The EPICS is just a document, a formal description
of an IUT that follows a specific set of rules. This EPICS document is imported into
VTS 3 and used by VTS and the tester to:
1.
Allows VTS Automatic scripted testing
2.
Allows VTS and Tester to easily check object property consistency.
Which means -- …
3.
Gives the tester an easy to read picture of the devices capabilities.
VTS 3 Checks the EPICS for correct syntax and informs the tester when a problem is
found..
14
15