Tridium, Inc. 3951 Wester re Parkway • Sui te 350 Richmond, Virginia 23233 USA http://www.tridium.com Phone 804.747.4771 • Fax 804.747.5204 Technical Publications Ni ag ar a S tan d ar d Programming Reference Niagara Release 2.3.5 Revised: April 20, 2004
This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
This document may not, in whole or in part, be copied, photocopied, reproduced, translated, or reduced to any electronic
medium or machine-readable form without prior written consent from Tridium, Inc., 3951 Westerre Parkway, Suite 350,
Richmond, Virginia 23233.
The confidential information contained in this document is provided solely for use by Tridium employees, licensees, andsystem owners; and is not to be released to, or reproduced for, anyone else; neither is it to be used for reproduction of this
Control System or any of its components.
All r ights to revise designs described herein are reserved. While every effort has been made to assure the accuracy of this
document, Tridium shall not be held responsible for damages, including consequential damages, arising from the application
of the information given herein. The information in this document is subject to change without notice.
The release described in this document may be protected by one of more U.S. patents, foreign patents , or pending
applications.
Trademark Notices: BACnet and ASHRAE are registered trademarks of American Society of Heating, Refrigerating and
Air-Condit ioning Engineers. Microsoft and Windows are registered trademarks, and Windows NT, Windows 2000,
Windows XP Professional, and Internet Explorer are trademarks of Microsoft Corporation. Java and other Java-based
names are trademarks of Sun Microsystems Inc. and refer to Sun's family of Java-branded technologies. Communicator and
Navigator are registered trademarks of Netscape Communications Corporation. Echelon, LON, LonMark, LonTalk, andLonWorks are registered trademarks of Echelon Corporation. Tridium, Niagara, the Niagara Framework, Vykon,
WorkPlace Pro, Web Supervisor, JACE-4, JACE-5, JACE-NP, and JACE-NX are trademarks of Tridium Inc.
All other product names and services mentioned in this publication that are known to be trademarks, registered trademarks,
or service marks have been appropriately capitalized and are the property of their respective owners.
Document SummaryThis document contains ten chapters and an appendix, summarized below.
Chapter 1, “Station and Objects,” —Provides an overview of how objects define a
Niagara station. Reference information is provided on the Station object. Also
included are some approximate limits and guidelines for station resources.
Chapter 2, “Data Species and Links,” —Provides an explanation of the data types
(data species) that object properties use. Information about links between input and
output properties is also included.
Chapter 3, “Commands and Views,” —Provides general explanations of commands
available in Niagara objects, plus available object views.
Chapter 4, “Services,” —Provides reference information on each of the standard
Niagara service objects, including property descriptions and available views.
Chapter 5, “Control Objects,” —Provides reference information on each of the
standard Niagara control objects, including property descriptions.
Chapter 6, “Apps Objects,” —Provides reference information on each of the standard
Niagara apps (application) objects, including property descriptions.
Chapter 7, “Container Objects,” —Provides reference information on each of the
standard Niagara container-type objects, including property descriptions.
Chapter 8, “Gx Objects,” —Provides reference information on each of the standard
Niagara Gx (graphical interface) objects, including property descriptions.
Chapter 9, “Notification Objects,” —Provides reference information on each of the
standard Niagara notification objects, including property descriptions.
Chapter 10, “Ndio Objects,” —Provides reference information on each of the Ndio
(Niagara direct input/output) objects, including property descriptions. These objectsare used if engineering a JACE with onboard I/O or with an I/O expansion module.
Appendix A, “Object Property Quick Reference,” —Includes a quick reference table
for each Niagara object type, listing all properties. Each property row shows the
property sheet tab, data species used, and attributes (read/write, user level).
Reference information on all data species (variable types and enumerations) is also
included.
An Index provides alphabetical reference to important topics in this manual.
Niagara Standard Programming Reference Revised: April 20, 2004
Preface About This Document
Commonly Used Terms
xi i
Commonly Used TermsThroughout this document, references are made to acronyms and terms encountered
with most any Niagara station. This section provides definitions for these terms and
is intended to ensure their consistent use.
active Generic term for one of two binary (boolean) states, typically synonymous with
“On,” “Run,” or “True.” The complimentary term is inactive.
Admin Tool The Niagara Framework software tool used for local and remote station
administration, including starting and stopping stations, station database
management, upgrades, and license file installation. Also provides network, user, and
time configuration for the selected host, and a Standard Output window used for
station troubleshooting. The Admin Tool can be run from inside the JDE, or as
standalone application. Not to be confused with the AdminTool object .
alarm An “off-normal” condition for an object when it meets alarm criteria, such as alarmlow (analog) or alarm state (binary or multistate). Alarms occur in event-type objects.
Alarm (as a term) also applies to alarm-type exception messages, which can be
generated upon detection of an alarm condition.
alert A “warning”-type exception message generated when an object reaches some
predefined limit, for example, hours of runtime or COV , COS count limit.
analog Data represented by a continuously-variable value, typically a floating-point (float).
Control object types AnalogInput, AnalogOutput, and AnalogOverride (among
others) use analog data.
apps objects Application objects. A class of Niagara objects that include global control objects
(Calendar and Schedule), various data logging (log) types, and the Program object.
BACnet® Building Automation Controls network. An ASHRAE®-developed “open”
communications protocol designed for the HVAC controls industry, where data is
modeled using a common set of “objects” and a standard set of “services.” Many
Niagara object types are closely modeled after BACnet objects. By default, all JACE
controllers are equipped for integration into a BACnet device network.
binary Data represented by only two discrete states (boolean), either active or inactive.
Control object types BinaryInput, BinaryOutput, and BinaryOverride (among others)
use binary data.
child object In general Niagara terms, any object contained inside another object’s Workspace.
A child object can be a primitive object or a container object (with its own children).
Niagara Standard Programming Reference Revised: April 20, 2004xiii
commands A station-user can give a command to a selected object to perform some predefined
action. Commands are either control-related (On, Off, setpoint adjust, etc.) or
administrative (clear log buffer, backup station database, etc.), depending on the
object type. The user requires command (security) privileges for that object.
container object If all lowercase (container), it refers to any Niagara container-type object, includingBundle, Composite, Container, GxPage, PollAlways, and PollOnDemand types. All
typically contain child objects. If capitalized (Container), refers to that specific type.
control objects A class of Niagara objects that provides a common object model for defining data and
control sequences, including alarm monitoring. Combinations of control objects and
shadow objects (plus apps objects) are typically referred to as control logic.
COV, COS Change-of-value, change-of-state.
data species Niagara data types, of which there are many. Data species include primitive data
types, data enumerations, and structured data types (variable types). Each property ofa Niagara object is implemented with a specific data species.
dependencies Requirements, particularly for child-parent relationships between object types. For
example, service objects have a parent dependency of (only) the ServiceContainer.
GxPage (container) objects have child dependencies of (only) Gx objects.
enumerations An enumeration is a numbered list of integers, where each number corresponds to a
specific state, condition, or other meaning (within that number group). An example
enumeration is 0 through 6 for the days of the week (Sunday through Saturday).
events Generally, an event is an exception to a normal condition or normal operation. A
number of control object types are event-type objects, meaning that they are capable
of generating an alarm (and in some cases, an alert).
inactive Generic term for one of two binary (boolean) states, typically synonymous with
“Off,” “Stop,” or “False.” The complimentary term is active.
input An object property designed for linking to the output of another object. Data received
on an input is typically used in the object’s algorithm (purpose).
JAR file Java ARchive file. A file format used to package all components required by a Java
application. Class files, images, sounds, etc., can be bundled into a single file. In
addition, JAR supports run-time data compression, which decreases download times. Niagara software modules install as JAR files.
Because component files remain packaged inside JAR files, a “virtual” file system is
seen in the Local Library —the tridium JAR and tridiumx folder cannot be found
directly in Windows Explorer, for example. In the case of the tridium JAR,
components reside mostly in the “\nre\modules\coreRuntime<release>.jar” file. To
simplify, however, this document refers to the tridium JAR file and tridiumx folder.
Niagara Standard Programming Reference Revised: April 20, 2004
Preface About This Document
Commonly Used Terms
xiv
JDE Java Desktop Environment. The Niagara Framework PC application used to engineer
station databases, using objects described in this document. The JDE can also be used
to monitor stations. Formerly referred to as WorkPlace Pro (WPP).
links Data connections between objects, where each link connects the output of one object
to the input of another object. Links are the basis for data sharing, integration, andcontrol sequences. Links are engineered in the JDE using the Link Editor. Depending
on its category and type, each link appears in the JDE as a line or a pair of link boxes.
Local Library Folders and files that can be accessed through the Tree View of the JDE workstation.
All are local (on the workstation), and are located under the niagara\<release>
directory. Access includes actual directories, such as “stations,” plus “virtual”
resources, such as the tridium JAR file and tridiumx subfolder. Files and directories
can be created, deleted, copied, and moved as needed. Also see Remote Library.
LonWorks® The collective hardware and software technology originally developed by the
Echelon corporation. LonWorks provides an off-the-shelf, peer-to-peer, networking
platform for designing interoperable control networks. By default, JACE controllers
support a LonWorks network, using a LonWorks FTT-10 connection point.
multistate Similar to binary data (two discrete states), but with three or more discrete states. For
example, a two-speed fan has three multistate values: Off, On, Fast. Control object
types MultistateInput, MultistateOutput, and MultistateOverride use multistate data.
object In the context of Niagara, object can refer to a node at the lowest level of station
database hierarchy, such as a control object or apps object. In other words, a primitive
object. However, because the term node is also widely-used to mean a networked
device (particularly for LonWorks), this document consistently uses the term object
instead of node. This usage applies to the top-level Station object, and all childobjects that make up a station database.
object types Niagara objects are of particular known types. For readability purposes, leading and
internal caps are used when referring to object types—for example, AnalogInput,
GxPage, FunctionGenerator, and so on.
output An object property designed for linking to the input of another object. Data produced
at an output typically reflects the results of the object’s algorithm (purpose).
Ndio Niagara direct input/output. Niagara software module used by a station for a JACE
model with onboard I/O (JACE-4). Contains special control objects known as NdioObjects, used to interface with the hardware I/O points.
node Within the context of Niagara, nodes are synonymous with objects, where node
sometimes means a container-type object. Node is the common base class for all
Niagara objects. Node constructs are similar to JavaBean characteristics—each has
properties, a set of methods exposed to other objects, and events that can be fired.
Please note that this document consistently uses the term object instead of node.
Niagara Standard Programming Reference Revised: April 20, 2004xv
parent In general Niagara terms, a child object’s particular container (object). Refers to the
hierarchy of objects in a station database. For example, the Station object is the parent
of the ServiceContainer object. A primitive object is never a parent.
primitive In the context of objects, a primitive object is any object that is not a container—for
example, a control object, apps object, Gx object, or a notification object. Note that primitive does not mean “crude” however, as many primitive objects are quite
sophisticated (Loop or Schedule object, for example).
In the context of data species, a primitive is the most fundamental type of data.
Primitive data types are either boolean, float, integer, or string.
properties A property is a component of an object, representing some piece of data. Most objects
have both internal properties (configuration, status, visual, and security types) as
well as linkable properties (input properties and output properties).
resource count A measure of storage for objects in a station, where each object consumes some
number of resources. Roughly equivalent to RAM, resource counts relate directly to
“Java handles and objects” used by the station’s JVM (Java virtual machine). Each
object description in this document lists the object’s Resource Count Range.
Remote Library Folders and files on a remote JACE host that can be accessed through the Tree View
of the JDE. Access includes actual directories, such as “stations,” plus “virtual”
resources, such as the tridium JAR and tridiumx subfolder. Files and directories can
be created, deleted, copied, and moved as needed.
service A special class of Niagara object that publishes itself to other objects in the station,
providing specialized routines and functions. Every station has some number of core
services plus additional (optional) services.
sns Serialized Node Set (SNS). A compact file format for storing a station database (or a
portion, in the case of a container object copied to the Local Library).
Standard Output An Admin Tool option providing a special window to view and save a running
station’s activity. Standard Output displays JVM station requests and responses in
real time, including station startup messages. It is typically used for troubleshooting.
Standard Output also works with “debug” modes of various Niagara services.
station The JVM that hosts the running of objects, plus a station database containing all
object configuration. Provides the environment to configure, manage, and run a
single database of objects and the services required to support a control application.
swid System-wide identifier, or SWID (To improve readability, common usage is swid).
Each object (whether container, service, control object, etc.) in the station has a name.
Since all objects are part of a Station’s tree, names can be concatenated together to
create a unique system-wide identifier (swid), much like a path in a file system.
Syntax for a swid follows standard URL naming conventions, for example:
ht t p: / / <host nameOr I P>/ db/ <st at i onName>/ <cont ai nerName>/ <obj ect Name>
Niagara Standard Programming Reference Revised: April 20, 2004
Preface About This Document
Commonly Used Terms
xvi
Tree View The left portion of the JDE window, showing the hierarchical structure of the station
database. Tree View in the JDE operates much like Windows Explorer, where you
expand container (parent) objects to see subordinate child objects. Tree View
timestamp Time (and date) stamp, typically generated within an object’s historical records. For
example, timestamps are included in samples of log objects (logs) and various status properties related to system or object actions, such as “timeOfStateCountReset.”
trigger An event-based data-sharing method, where a trigger-type output can be “fired,”
either by a user-command or a predetermined event. Receipt of a trigger pulse at a
linked trigger-type input results in that object performing some predetermined
function. This is a different model than used for most data sharing, as it is not
value-based . Most control and apps objects have at least one trigger property.
URL Uniform Resource Locator. The global address of a document or other resource.
Within the context of Niagara, a URL is similar to a swid . A swid defines a particular
object or resource in a station database, whereas a URL can include a swid or a
resource located elsewhere.
views Objects have views, each of which provide access to characteristics of the object. All
objects have a Properties view and Links view, for example. Container objects have
a Workspace view and WorkplaceEditor view. These are standard views. Some
objects also have special views. For example, a Calendar object provides a Calendar
view, to graphically review and edit holiday dates.
Web Superviso r The Niagara station (at a job) that runs on a PC, configured as the Supervisor station
(archive destination) for any networked JACE controllers. Typically this PC is also
running full suite of Niagara applications, including the JDE and the Alarm Console.
WebUiService Web User Interface Service. The Niagara service required by a station to provide a
full set of views to its objects when using a Web browser connection. The
WebUIService is a suite of servlets that use HTML and Java applets to provide a
browser user interface (BUI) to station data.
Workspace The runtime view for any container object, as it appears in the right side of the JDE
window. Also called monitor mode, it is where values update in real time and user
commands to child objects can be given.
WorkspaceEditor The edit view for any container object, as it appears in the right side of the JDE
window. Also called edit mode, it is where objects can be added, deleted, modified,linked and unlinked.
networking, including configuration details for any Niagara host, firewall
considerations, modem (dialup) setup, reference data, and troubleshooting tips.
• Niagara Web Solutions Guide —Provides information about engineering a Niagara station optimized for web browser access. Discusses GxPages, HTML
templates and framesets, and other features provided by the WebUIService.
• Niagara BACnet Integration Reference —Provides details on engineering a
station with the BACnetService, including BACnet client operation (shadow
objects) and BACnet server operation (exposing standard Niagara objects).
• Niagara Modbus Integration Reference —Provides details on engineering a
station with any of the Modbus integration services, namely ModbusAsync,
ModbusTCP, and ModbusSlave. Includes reference data on all shadow objects.
• Niagara System and Power Monitoring, Engineering Notes—Provides details
on “sysmon” configuration for the JACE-NP and JACE-NX platforms,
including special shadow objects found in the tridiumx/systemMonitor JAR.
Document UpdatesUpdates to this document are listed below.
Date Update, Notes
11/15/2001 Initial document revision for Release 2.2.
05/09/2002 Revised document for Release 2.3.
05/14/2002 Minor update, still Release 2.3.
09/30/2002 Various corrections, still Release 2.3.06/13/2003 Initial document revision for Release 2.3.4.
For details about changes in Release 2.3.4 from the previous release, please referto the Release Notes document for Niagara r2.3.4.
03/24/2004 Initial document revision for Release 2.3.5. Object coverage expanded to include“CpStringNode,” page 5-68, “VasRecipient,” page 9-18, as well better details onengineering units (“About Units,” page 5-6). Various other small changes.
For details about changes in Release 2.3.5 from the previous release, please referto the Release Notes document for Niagara r2.3.5.
Niagara Standard Programming Reference Revised: April 20, 2004
Preface About This Document
Document Updates
xviii
04/14/2004 Revision. Minor change in Note about entering characters plus (“+”) or semicolon(“;”) in edit dialog of CpStringNode object when using a browser connection.Pagination remains unaffected.
04/20/2004 Revision. Minor change in Appendix A, “Object Property Quick Reference,” adding
enum type “DatabaseTypeEnum” and updating DatabaseService properties list.
Niagara Standard Programming Reference Revised: April 20, 20041–3
Niagara ObjectsObjects are the building blocks of a Niagara station database. Each object type is a
defined data structure with a predictable behavior. Objects represent every level of
the database, starting with the “root” Station node (object).
Each object is a collection of properties. Depending on its type, each object also has
some number of available commands or special views. Objects can be linked to other
objects, where links provide sharing of data and control.
In the JDE, each object has a right-click Property Sheet and Links Sheet to access
properties and links (Go > Properties and Go > Links). Detailed information about
object properties, commands and views, and links is provided in subsequent chapters
about specific object types.
The following topics apply to a general understanding of Niagara objects:
• Object Model (Integration Platform)
• Data Modeling• Object Hierarchies
• Object Name and SWID
• Object Dependencies
Object Model (Integration Platform)
A Niagara station uses a common object model to provide an integration platform for
exchange of information with foreign devices, including a common user interface.
The different libraries of Niagara objects include “standard” objects, described in this
document, plus other integration objects, such as LonWorks and BACnet objects.
Integration objects expose foreign devices (and contained information) using thesame familiar patterns used by standard objects. In general, most integration objects
“shadow” devices and/or values in devices that are physically networked with a
JACE controller. For this reason, integration objects are often called shadow objects.
Note Niagara integration (shadow) objects are beyond the scope of this reference manual.
Integration is performed by JACE controllers. Each JACE provides a number of
standard communications ports. These include a LonWorks port (FTT-10 LonTalk
transceiver), a 10/100 Mbps ethernet port, and at least one RS-232 serial port and
RS-485 port. Typically, one or more of these communications ports are used to
network the JACE with some number of other foreign (non-Tridium) devices.
By combining integration objects with standard objects, you can quickly build
applications that draw from multiple vendor devices (and protocols). Furthermore,
because of the common object model, integrated devices are represented in the
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Niagara Objects
1–4
Although not covered in this document, most Niagara integrations include these
types of objects:
• Service object—provides the necessary communications-subsystem support
for the integration, plus protocol support. Typically, this object has
configurable settings for device status monitoring and debug.
• Network-level object—provides a container for all foreign device-types
objects specific to an integrated network.
• Device-level objects—each provides a shadow object representing a particular
device. Depending on the integration, this object may be a container object that
contains data-level objects, or instead may contain a number of properties
(inputs and outputs) for device data.
• Data-level objects—each provides access to a specific I/O point or software
value in the foreign device.
Data Modeling
The Niagara object model structures data between three distinct levels:
• Primitive —A data primitive is either a boolean (binary) value, integer value,
floating-point value, or a string. Primitives are the building blocks for all data
structures. Combinations of primitives are used to define variable types (data
species).
• Object —The data structure that represent the granularity of data most often
used in Niagara. Objects can be configured, linked, copied, and stored in
custom libraries for future reuse. In any running station, objects are executed
by “engine services” that perform control and interface functions.
• Station —The combination of a database, Web server, and object engines that
processes all objects. A job (site) may consist of one station (JACE controller),or may contain multiple stations (JACE controllers) and a Web Supervisor.
Using this model, data flow is bidirectional—primitives are gathered and represented
in objects (status monitoring), and control is provided for changing primitives in
devices.
Object Hierarchies
Depending on its type, an object can have “child” objects, that is, be a “parent” that
contains other objects. The obvious example is the Station object, the parent of all
other objects in the station. All other objects are children of the Station object. Bydefinition, all container-type objects are intended to be parent objects.
Many levels of hierarchies are possible in a station database, where parent objects can
contain other parent objects, and so on. In this tree-like hierarchy, objects at the
lowest level in any branch are objects that are only child objects ( primitive objects).
An example of primitive objects are the standard “control” objects, which represent
a piece of data or a data function. Other primitive objects include all apps objects, Gx
Niagara Standard Programming Reference Revised: April 20, 20041–7
Object DependenciesIn general, objects of different types can be placed in most levels of a station
database. However, there are cases in which some types of objects have
dependencies. For example, any service object must be located within the
ServiceContainer object, of which there can be only one instance per station. Inaddition, the ServiceContainer object must be in the root level of the station.
Using the New Station wizard in the JDE, these particular object dependencies are
automated such that the ServiceContainer object and the selected service objects are
correctly created and ready to modify, as needed.
Parent (container) objects may have dependencies as well. For example, a GxPage
object (a type of container object) may contain only Gx objects, and no other object
types. However, Gx objects can be children in other container-type objects as well.
The JDE enforces object dependencies when you are engineering a station. In each
object description included in this document, “Parent Dependencies” are listed.
“Child Dependencies” (for container objects that have them) are also provided.
Object CategoriesStandard Niagara objects are organized in categories, reflected by category names
when using the JDE. When adding a new object in the WorkspaceEditor (Figure 1-1),
you select objects from within these categories.
Figure 1-1 “New” menu in WorkspaceEditor groups object types by categories.
The different object categories are:
• Foundation —Only one type, the Station object. Each station has only one.
• Control Objects —Several standard types, used to handle values and status
received by communications subsystems (provided by some services) and
provide a common control logic model for system integration. Different types
of control objects provide various control algorithms, and can be individually
configured and linked together to provide complex control sequences.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Object Categories
1–8
Note Niagara control objects have many characteristics of BACnet objects.
Several Niagara object types can be exposed directly as BACnet
objects, and the station itself exposed as a BACnet device.
• Apps Objects —Several standard types, used to provide scheduling control,data logging, and other global control functions. One type, the Program object,
allows you to create a custom application for use with control objects.
• Gx Objects —Several standard types, each can be used as a component of a
graphical view built to show real-time values and status (user interface).
• Container Objects —Several standard types, used to hierarchically organize
and provide specific functionality to contained objects (children).
• Notification Objects —Several standard types, each provides unique functions
to a station’s NotificationService (a particular type of service object).
• Services —Several standard types, explained ahead. Service objects publish
their functionality for other station objects to use.
Object Libraries
Most standard Niagara objects are distributed in the tridium JAR file, including the
Station object, all control, apps, container, and Gx objects, and most service and
notification objects. These objects are covered in detail in this manual.
In addition to these standard object types, various integration and lib(rary) objects are
distributed within the tridiumx folder. The tridiumx folder includes many JAR files,
primarily for foreign device integrations. This includes both “standard” integrations
(BACnet, LonWorks, and various vendor-specific LON types) as well as optional
integration types. This latter group includes a few Modbus (open-protocol)integrations, and various proprietary integrations, such as Johnson Controls N2
network, Invensys GCM and DMS, and several others. Each JAR file contains
various objects to support the integration (ranging from a service object to data
objects). These integration objects are covered in separate documents, and are
outside the scope of this manual.
Aside from the JAR files for these device integrations, the tridiumx folder also
contains a lib JAR file. The lib JAR contains two especially important folders:
• programs —Holds various pre-engineered Program objects for standard use in
data and unit conversions, HVAC routines, and other purposes. The purpose of
each Program object is explained in “comments” of its TRIPL program code.
In addition, a lib /docs/libdocs.html document provides an overview for eachavailable Program object.
• applications —A collection of various pre-engineered applications, each with
one or more graphics (GxPages) linked to standard Niagara control objects.
For more details, see the lib /docs/applicationInstructions.html document.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Station
1–9
StationQuick reference for all properties: Table A-72
The Station object is the parent (root)
container for all other objects in a Niagara
station. Every station has one Station object.
A Station object has various properties, but
no inputs or outputs. Object views include
those typical to any container, such as the
Workspace, WorkspaceEditor, Properties,
Links, and Report views.
In addition to these views, each Station object
has these “Go” views in the JDE:
• AddressBook
• UserAdmin
• ActiveUsers• Alarms
The AddressBook and UserAdmin views are
especially important for job configuration.
A Station object provides various runtime
commands. These commands perform station
database backups or restart/reboot the station
or station host.
Resource Count Range: 89 to 200, plus the sum of all other objects.
Trigger Properties None.
CommandsUsers with Command, Admin privileges have the following available command:
• BackupXML —Causes the selected station to locally backup its running
database to XML format (backup “there”). Applicable for JACE-NP and Web
Supervisor stations only (and not JACE-4/5s, which store only in SNS format).
• BackupSNS —Causes the station to locally backup its running database to
SNS format (backup “there”). Applies to any selected Niagara station,
including a JACE-4/5.
• BackupSubordinatesXML —Applies if the selected station is configured as
supervisor (typically, Web Supervisor). Backs up the running station databasein each subordinate-designated station, to the appropriate stations subfolder, in
XML format (a global-backup “here”). All station types are supported.
• BackupSubordinatesSNS —Applies if the selected station is configured as
supervisor (typically, Web Supervisor). Backs up the running database in each
subordinate-designated station, to the appropriate stations subfolder, in XML
format (a global-backup “here”). All station types are supported.
Inputs
Object Shape
Outputs
(none) (none)
Input / Output Property Reference for Station Object(only input and output types, see Table 1-1 for all properties)
Type Label Property Name Data Species
input — — —
output — — —
Station Icon Meanings (Tree View)
Icon Description Typical Meaning
Station icon isblack.
Station is open and online.
Station icon is gray. The station is a subordinate of another opened station(or) a station that was open when the JDE was last exited.Double-click (or expand) to open it online.
Gray cylinder. Station is open off line.
Gray cylinder withred shading.
Station is open offline, and changes have been made butnot saved.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Station
1–11
S t a t u s ,
c o n
t .
osArch Read Only: Operating system architecture.Is “x86” for JACE-NP or Web Supervisor, or“ppc” for JACE-4/5.
x86or
ppc
SeeDescrip.
osName Read Only: Operating system name. Is“Windows NT” for JACE-NP, NX, or WebSupervisor, and “VxWorks” for JACE-4/5.
Windows NTor
VxWorks
SeeDescrip.
osVersion Read Only: Operating system version.JACE-NP (NT) is 4.0JACE-NX (XP) is 4.0 or 5.1.Web Supervisor (NT, 2000, or XP) is 4.0,5.0, or 5.1, respectively.If JACE-4/5, will be latest VxWorks version.
See Descrip. SeeDescrip.
and Note.
At time of 2.3.5release, VxWorksversion is 5.4.2.
javaVendor Read Only: Vendor of JVM used. Currently,is” Sun Microsystems” for r2.3.5 JACE-NX,JACE-NP, or WebSup. If a JACE-4/5, either“Insignia Solutions Inc.” or “Wind RiverSystems Inc.”
See Descrip. SeeDescrip.
Prior to r2.3.5,Win32 platformsused Microsoft’sJVM.
javaVersion Read Only: Version of JVM used by station.At 2.3.5 release time, version is 1.4.1 (SunHostspot) or 1.1 (Wind River Systems).
See Descrip. SeeDescrip.
release Read Only: Niagara Release level in use.For example, 2.301.507.v1
valid releaselevel
SeeDescrip.
C o n
f i g
httpPort Read-Write: Number of logical port used forTCP/UDP connections in HTTPD access.Applies to normal station communications.
The JDE and browsers, by default, assumethe “well known” port of 80. If you assign adifferent port, you need to append thisnumber (with colon) after the hostname or
IP address when opening the station in theJDE, or when accessing in a browser.
For example: http://192.168.1.25:85for a browser connection on port 85.
80(recommended)
or otherunused port
80 If using a port otherthan 80, you also need a line in thestation.properties file, for example:
httpPort=85
Otherwise, you will
not be able to doDbAdmin functions.
An httpPort changebecomes activeafter station restart.
httpsPort Read-Write: (Future Use) Number of logicalport for TCP/UDP connections in HTTPSaccess. Applies if enableSSL is True.
Port 443 is the “well known” standard.
443
or otherunused port
443 SSL will besupported in afuture Niagararelease.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Station
1–12
C o n
f i g ,
c o n
t .
pstoreFlushTime Read-Write: Applies to JACE-NP and WebSupervisor stations only. Specifies theinterval, in milliseconds, between automatic
saves of persistently-stored properties.Updates the Config.db file in the properstations subdirectory, at this frequency.
1000 toMAX_VALUE
5000(ms)
Does not apply to aJACE-4/5.
Only properties
modified since thelast flush are saved.
snsBackupTime Read-Write: Specif ies the interval, inminutes, between automatic backups of thestation database to sns (serialized nodeset)format. All persistently-stored properties aresaved.
Each backup updates the Config.sns file inthe proper stations subdirectory. Theprevious Config.sns is renamed toConfig.sns.old.
For a JACE-4/5 or Web Supervisor station,
if the Config.db database cannot be loaded,the Config.sns is automatically used(sometimes called “Auto Restore”).
integer, 1 to n
for snsbackups
0 or negativeto disable auto
sns backup
180(minutes)
Applies to Niagarastation on any hostplatform.
interstationSendTime Read-Write: Specifies the interval, inmilliseconds, between sending change ofvalue updates to external subscriptions(external links, i.e., links between stations).
integer,500 to n
5000(ms)
More propertiesthat affect externallinks are adjusted insystem.properties.
membershipGroups Read-Write: (Future use) niagaraR2 niagaraR2 These propertiesare related to afuture release ofNiagara software.
Their applicationwill be explained ata later date.
announcementTTL Read-Write: (Future use) — 3
enableAnnouncement Read-Write: (Future use) Leave at False(default) to avoid unnecessary messaging.
alarmText Read-Write: The (final) top-level alarmTextavailable for any alarmable child objects.
For child objects to use this, their alarmTextproperties must have only the defaulthyphen (-). See “Alarm and Alert Text” onpage 7-5 for more information.
(for each)
255 charactersmaximum.
Any text string,including
spaces andmixed casecharacters.
- The alarmTextvalue is not used in“change-of-state”events of Station objects. Instead,the messageText inalarm records forthese events usesthe enumerateddescriptor , such as“stationDown” or“stationUp.” See“Station AlarmTypes” onpage 1-23.
alertText Read-Write: The (final) top-level alertTextavailable for any alert-capable child objects.
For child objects to use this, their alertTextproperties must have only the defaulthyphen (-). See “Alarm and Alert Text” onpage 7-5 for more information.
-
Table 1-1 Station object propert ies. (continued)
Tab Property Name Description Valid Values Default Notes
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Station
1–13
A l a r m
S e
t u p , c o n
t .
notificationClass Read-Write: The notification class used forchange-of-state events for the station (forexample, coming “Up” after going “Down”).
This class is also used in notifications ofstation events occurring for remote stations,meaning those “monitored” by this station(AddressBook view).
If a JACE-NP on JACE-NX and environmentmonitoring is enabled (1-27), associatedalarms are sent to this notification class.
0 to8388607
0 A NotificationClass object with thissame notification
class number isrequired in thestation’sNotificationService container.
V i s u a
lposition Read-Write: Has no practical application for
the Station object. — -2147483648
x 0
alarmPageUrl Read-Write: (Future Use) Specifies the URLto display on alarm.
— — Not currentlyimplemented.
E n g
i n e e r i n g
nextHandle Read Only: Shows the handle (number) thatwill be automatically assigned to the next
object added to the station database. Eachobject has a unique handle.
The 0 handle is reserved for the Stationobject. Handles are seen in StandardOutput following a “dump” command.
<integer>greater than 0
— The integer value ofnextHandle
approximates thenumber of objects inthe station.
S e c u r i t y
securityGroups Read-Write: Shows the security groups towhich the Station object is assigned.
In the JDE, these security settings affectaccess to the Station object, and not all childobjects (unlike with other container objects).
A JDE user without any rights to the Stationobject can still expand the station in TreeView and see other container objects
(assuming that rights exist tosecurityGroups assigned to those objects).
Any mix ofthese types:
• General
• HVAC
• Security
• Life Safety
• Group 4
• Group 5• Group 6
• Group 7
General A JDE user withonly operator-levelproperty readaccess to theStation object canstill use UserAdminto change theirlogon password,JDE Home, andBrowser Home.
strongPasswords Read-Write: Specifies whether station userseach require a “strong” password (True).
The rules for entering a strong password (inthe UserAdmin view of the station):
• Must be a minimum of 8 characters, withno spaces permitted.
• At least 1 character must be uppercase.
• At least 1 character must be lowercase.
• At least 1 character must be a specialcharacter, meaning either a numeral 0 to
9, or one of the following: ! @ # $ %Some examples of strong passwords:
J%ohn9Tv 1toGoHome GroovyBaby!
False, True False If strongPasswordsis enabled after users are alreadycreated, existing(non-strong)passwords willcontinue to workOK.
However, nochanges for a user(UserAdmin view)
can be made until astrong password isassigned to them.
Table 1-1 Station object propert ies. (continued)
Tab Property Name Description Valid Values Default Notes
• Host Address —IP address (recommended) or hostname for the remote
station’s host. If that station is using a “non-default” http port (other than 80),it must be included (with a colon delimiter). For example: 192.168.1.211:85
If using dialup access, leave this field blank unless the remote station is using
a “non-default” http port (other than 80). Then, include a “:<port>”, e.g: :85
Dialup: This section is typically left blank, unless a dial-up modem connection is
required to connect to the station.
Notes • Dialup connection to a station requires configuration of its host’s RAS (remote
access service). For more information, refer to the Niagara Networking &
Connectivity Guide, Chapter 4, “Connecting with Direct Dial.”
• External links between stations are not supported by dialup connections.
However, dialup connections support archiving of logs, receiving alarms, and
dialup access using the JDE.
• Phone # —Phone number to dial into the remote host machine.
• Host User Name —Logon user name for the host machine.
• Host Password —Password for the user name above, to access the host
Poll Archive Group: Applicable only if this station has the PollArchiveService.
Provided is a drop-down list of poll archive groups—each remote station can beassigned to any (including disabled). See “PollArchiveService” on page 4-40.
(Station relationship): Drop-down list with description of the remote station’s
relationship to this station. Selections include:
• Peer —Typical between JACE controllers, where data is exchanged between
stations. Less typical (but possible) is a peer also used as the archive
destination, providing that it has the DatabaseService.
• Subordinate —When in the AddressBook of a Web Supervisor station, this is
typical for each JACE station entry.
• Supervisor —When in the AddressBook of any JACE controller station, this is
typical for the Web Supervisor station entry.
Monitor: Whether or not the remote station is to be monitored (pinged), and what
“non-response” time (in minutes) is tolerated before a “stationDown” alarm occurs.
For the AddressBook of a Web Supervisor station, this is typical for each JACE
station entry. Optionally, JACE stations can also monitor each other as well.
Alarms generated by monitoring other stations can be reviewed in the Station object’s
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Station
1–17
UserAdmin The UserAdmin view is especially important for any Niagara station. It is used to
add, modify, and delete user accounts for accessing the station. A station can have up
to 256 users. Each station user has specific security privileges (rights), plus other user
preferences, such as home page defaults and hot links.
Figure 1-4 UserAdmin view lists currently defined user accounts for the station.
The following subtopics apply to adding and changing station users:
• The Administrator
• Edit Tabs (General, Hot Links, Security)
The Administrator
The New Station wizard creates a single Administrator user, with default user name
of “admin” (and whatever password was entered). Consider this account the “super
user” for the station, as it has fixed (full) security and administrative privileges.
Moreover, the administrator user can never be deleted , although the password can be
changed and other user preferences adjusted.
Note A JDE user logged on as the default administrator can effectively “replace” the
administrator account, using the menu bar command UserAdmin > Change AdminUser. This allows changing the “User Name” of this special account, but also clears
the password, and prior user preferences (“home” settings, logoff period, hot links).
Edit Tabs
When adding or modifying a station user in the JDE, three tabs are available:
• General Tab
• Hot Links
• Security Tab
Note Starting in r2.3.4, browser access to station user administration is available. The
Niagara host (Web Supervisor or JACE) requires the t r i di umx/ webuser JAR
installed, and the station must have the WebUserAdminService in its services
folder. Most functionality found on the General and Security tab is available,
including the ability to add new station users and/or change security rights.
The URL to access the Web User Administration feature is: http://<host>/user
For more information, refer to the Niagara Browser Access Guide.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Station
1–20
Security Tab—The most critical edit tab for any user. A user’s security rights
(Security Mask) apply whether the user is logged onto the station using the JDE or
using a Web browser.
Figure 1-8 Example Security tab of a user selected in UserAdmin view.
Note For any user except the administrator (or a user assigned as a “Security
administrator”) all fields in the Security tab are read-only (cannot be modified).
Entry field sections are:
Account enabled: Checked, by default, for any user. If cleared, the user will not be
able to logon to the station (using either the JDE or a Web browser).
Security administrator: Cleared, by default, for any user except the defaultadministrator. If checked, the user will have full security administrator privileges.
Note Without regard to any other security rights, a user with security administrator
privileges can change their own security settings, as well as those for any
other user . In addition, a security administrator can add and delete users.
For these reasons, be careful about assigning security administrator rights.
Security Mask: Applies to the eight separate security groups that can be assigned to
any Niagara object. Each object must belong to at least one security group. A newly
created object defaults to the “General” group. See “About Security” on page 1-21.
For each security group, three main categories of security access apply:
• Admin —Gives the user Read (R), or Read and Write (W) permissions for all
properties of the object, including admin-level properties. In an object’s
property sheet, most (Config, Alarm Setup, Visual tabs) are admin-level.
Admin-level write is also needed for edits of Calendar and Schedule objects.
Note that selecting R or W for “Admin”-level automatically includes the same
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Station
1–21
• Operator —Gives the user Read (R) or Read and Write (W) permissions for
any operator-level properties of the object. In an object’s property sheet, these
are typically only properties on the Status tab.
• Command —Gives the user access to various commands or actions, depending
on selections, as follows:
– Std —Standard level commands. Applies to right-click, priority-level 8(Manual) commands for object types AO, BO, MSO.
Also applies to various right-click commands for other object types,
including AnalogOverride, BinaryOverride, Command, DateTimeTrigger,
Loop, MultistateOverride, and PeriodicTrigger.
– Alarm —Alarm acknowledgment. Gives the user alarm acknowledgment
permissions for alarmable objects.
– Emer —Emergency level commands. Applies to right-click, priority-level
1 (Manual Life Safety) commands for object types AO, BO, MSO.
Note that if a user is given rights for emergency-level commands,
standard-level (Std) commands are automatically included too.– Admin —Administrator commands. Applies to system-administration
type commands of various objects. Example commands include “clear,”
“archive,”, and “clearLast Archive” (log objects), “cleanupSpecials”
(Schedule object), various backup commands, “restart,” and “reboot”
(Station object).
Note that if a user is given rights for Admin-level commands, rights are
automatically given for the other three types (Std, Alarm, Emer) as well.
About Securi ty
The eight security groups are independent of each other and their meaning is a local
matter. This means that there is no prioritizing or “weighting” of any security group.Any object can be assigned to any combination of the eight security groups through
its securityGroups property. Each object must belong to at least one group. In this
way, many different security permissions can be defined simultaneously.
A user's access rights to an object are determined by combining his or her rights for
each group that is checked in the object's securityGroups property. If the object is
assigned to any securityGroup providing access to that user, the user has those rights.
Also (when working in the JDE), if a user has rights to a container type object, some
rights are automatically applied to its child objects.
• If a user has Operator read rights to a container, child objects are visible in its
Workspace.• If a user has Admin write rights to a container, all the edit (WorkspaceEditor)
right-click menu features are available for child objects, except Go menu items.
Child objects can be linked, cut, copied, duplicated, deleted and renamed.
In sections ahead on different object types, descriptions for object commands note the
security rights needed. The security access-level required for each property of
standard objects is included in the “Attribute Notation” of all properties listed in each
object as they appear in the “Property Quick References” section on page A-3.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Station
1–22
ActiveUsers A Station object’s ActiveUsers view lists all currently connected JDE users.
Figure 1-9 ActiveUsers view lists all JDE users that have the station open.
Each row shows the station’s user name, full name, host machine name (IP address)
on which the JDE is running, and the station logon time.
User Messages
In the station’s ActiveUsers view, you can send messages to other JDE users, using
one of the ActiveUsers pull-down options from the menu bar, or these toolbar icons:
Either selection produces a dialog box in which you can enter text for the message.
When you type your message and click OK:
• Send Message—The message appears as a pop-up at the selected user’s JDE.
• Broadcast Message—The message appears as a pop-up on the JDE of all users.
In either case, the message popup remains “on top” of the JDE until acknowledged by a remote user. Figure 1-10 shows an example broadcast message being sent (left)
and received (right).
Figure 1-10 ActiveUsers view lists all connected JDE users.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Station
1–23
Alarms The Alarms view of a Station object lists only station alarms that have occurred since
the last station startup. Each includes a timestamp, event type, and alarm message.
Figure 1-11 A Station object’s Alarms view lists only station alarms.
Figure 1-11 shows an Alarms view for a station that is monitoring another station. It
contains three alarms: its own startup alarm, and separate “stationDown” and
“stationUp” alarms for a remote station (being monitored by this station).
Note Unless the station is configured to monitor other stations (AddressBook setup), oftenonly a single alarm exists—a “stationBoot Down ...Up” alarm with a timestamp of
when the station was last started.
There are relatively few types of station alarms—all are “change-of-state” event
types. The following types exist:
Station Alarm Types
(StationAlarmEnum)
For any station alarm, the enumeration’s description appears in the “message” field
of the alarm record.
Note If a JACE-NP configured for sysmon (internal environment monitoring), additional
types of station alarms are possible. These alarms can apply to the JACE-NP’s CPU
temperature, various voltage levels, or CPU fan speed. For more information, see
may be included in a later revision of that document, but is currently not available.
Due to the flexibility of the Niagara Framework, it is risky to set arbitrary limits on
the makeup of a station database. However, limits in Table 1-2 establish some rough
guidelines, according to host platform (PC, JACE-NP, JACE-5 models, JACE-4).
These limits apply to the four areas of resource boundaries, namely:
• RAM memory—The station operates from RAM, consumed (roughly)
according to the number of objects in the station. A more accurate yardstick is
resource count , available (whole or in part) from a running station. See
“Checking Object Count” and “Checking Resource Count.”
• CPU Utilization—The ability of the host processor to execute the necessary program threads that allow the station to perform work.
Of the three resource factors, this is the most important for the newer JACE
controller models (JACE-401 and JACE-51x). It is also important for
JACE-50x models (in addition to resource count). See “Checking JACE-4/5
CPU Utilization.”
Table 1-2 Rough limits for station resource allocations, by Niagara platform.
Niagara Platform Resource Count CPU utilization Disk/Flash Space External Links
PC (Web Supervisor)500MHz PIII, 256MB RAM
1GHz P4, 512MB RAM
1,000,0001
2,000,0001
1. PC (Web Supervisor) maximum resource count limits are predicated upon (typical) DatabaseService resource loads.
Not applicable. 2GB minimum. 25,000
50,000JACE-NP (earlier, 64MB) 400,0002
2. Tridium Systems Engineers (who provide technical support to the field) think these numbers are more realistic than ones previouslypublished, which were: 600,000 for earlier (64MB) JACE-NP and 1,000,000 for current (128MB) JACE-NP.
Not applicable. Not applicable. ?
JACE-NP (current, 128MB) 600,0002 Not applicable. Not applicable. ?
JACE-401 600,0003
3. Chances are that various engines (control, ui) and poll threads will need to be slowed down to reach this600,000 resource count for aJACE-401 or JACE-51x. Refer to the Engineering Notes document, Niagara Capacities, for more detailed information.
20% (or greater) CPUIdle is required by all
embedded JACEs.
A JACE-501 or 502 isalso constrained by
resource count.
CPU utilization is thekey constraint for any
Jeode VM-basedJACE (40x, 51x).
n KB free /tffs Some free fi lespace (n KB) is
required toallow database
backups.
See “CheckingJACE-4/5 Flash
Space” onpage 1-26.
?
JACE-501,JACE-502
300,000
n KB free /tffs4
4. JACE-501 and JACE-502 models without WebUI are the most prone to flash memory limitations (database space limitations).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Station Limits and Guidelines
1–25
• Disk storage—Typically not an issue for a Web Supervisor or JACE-NP, this
relates mostly to flash memory availability for a JACE-4/5. See “Checking
JACE-4/5 Flash Space.”
• External links —Typically extensive in a Web Supervisor station, where
graphics (Gx objects in GxPages) or log objects are linked to control logic.
Limits shown in Table 1-2 are extremely high (25,000 or more)—a dedicatedEthernet LAN would likely be needed to ensure network availability.
Checking Station Resources
The following station resource checks are available:
• Checking Object Count
• Checking Resource Count
• Checking JACE-4/5 CPU Utilization
• Checking JACE-4/5 Flash Space
• Checking External Links
Checking Object Count—The total number of objects in a running station are
reported by the Prism servlet:
http://<stationHost>/prism
The object count is in the line “nodeCount=n.”
Checking Resource Count—Check the resource count for a running station by
opening it in the JDE, selecting the station (or a portion of) in the Tree View, and
selecting Search > Resource Count from the menu bar (or use the ALT-R shortcut).
The Prism servlet also provides resource count statistics, using the URL:
http://<stationHost>/prism/resources
– The “ Total Obj ect s n” line provides the station’s total resource count.
– The “Chi l dr en” section provides individual resource counts and
percentages of total resource counts.
Checking JACE-4/5 CPU Util ization—Check the CPU utilization of a station
running in a JACE-4/5 by opening the “spy” utility with a browser connection to the
JACE-4/5 host , using the URL:
http:<JACE-4/5 IP address>:3011/system/spy
(enter the host username and password, for example, “tridium” and “niagara”)
The spy utility provides a “snapshot” of different tasks (threads) run by the CPU,
including a “total %” column that gives some relative indication of CPU utilization. Near the bottom of this window, the line “IDLE” should read 20%, as a minimum.
Notes • Failure conditions (less than 20% IDLE) typically result in:
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Station Limits and Guidelines
1–26
• During station boot and immediately thereafter, the “tJmain” task may appear
to consume an excessive amount of CPU time. This is normal. It is the main
JVM thread, and loads all of the classes and the station database.
Checking JACE-4/5 Flash Space—Use the Admin Tool’s Summary tab to
check free file space on a JACE-4/5. This panel lists that total number of bytes lefton the primary /tffs drive and (according to JACE model) an /sm drive.
A total of 128KB is reserved on each flash disk. The number reported via the
AdminTool is actually total space minus the 128 KB reserve.
Free file space requirements depend on the JACE-4/5 model and the size of the
station database (stored by the JACE in two files, config.sns and config.sns.old):
• Models with the /sm drive must have enough free space on the /sm drive.
• Models without the /sm drive must have enough free space on the /tffs drive.
In either case, the required free space, when added to the 128KB reserve, must exceed
the station’s config.sns file size.For example, if config.sns is 144KB, the minimum required free space is >16KB.
where 144KB - 128KB(reserve) = 16KB
Notes • A config.sns file typically grows during runtime, due to logging activity.
• Typical failure symptoms of having insufficient flash memory space are:
– Failure to install a new module / upgrade (not applicable to a JACE-511 or
JACE-512).
– Database backup failure (particularly if a JACE-501 or JACE-502 without
WebUI).
• The database backup failure should be rare. The 128 KB reserve should handle
all but the largest databases.
• The newer JACE-511 and JACE-512 models have increased storage for
Niagara modules, as shown on the /tffs drive. However, you should not install
any “extraneous” (unused) modules. Extra installed modules consume RAM
otherwise used by the station, and slow station startup.
Checking External Links—Use a browser connection to a station to quickly see
the state of its external links, which are listed in a subscriptions table and a
publications table. This feature is part of the prism servlet, common to any station.The URL is: http://<stationHost> /prism/externalLinks
• The subscriptions table is posted first , with a total number of subscriptions
listed in brackets [n].
• The publications table is posted next (the total number does not appear).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Monitoring JACE-NX, JACE-NP Environment Variables
1–27
Monitoring JACE-NX, JACE-NP Environment Variables
A station in a JACE-NX or JACE-NP has the ability to monitor the JACE’s internal
main-board temperature and other environment variables (various voltages, CPU fan
speed), and generate Niagara alarms upon reaching critical limits. Alarms generated
by the sysmon feature are automatically sent to the Station object’s notification class(property sheet Alarm Setup tab, notificationClass).
The full name of this feature is the “Win32SysMonDriver.” However, it is typically
referred to simply as “sysmon.” Use of this feature is optional. Sysmon setup in a
JACE-NX or NP is configured in the JACE’s drivers.properties file.
In r2.3.4 and later, additional sysmon support was added. A “systemMonitor” JAR
can be installed in the JACE-NX or JACE-NP, which provides an available
“SysMon X ” object that you can place in the station’s database. Linkable outputs
provide currently monitored environment variables, including alarm indications.
Refer to For up-to-date configuration details for sysmon and power monitoring, please referto the Engineering Notes document: Niagara System and Power Monitoring.
That document also contains details on the optional SysMon X and PowerMon2
objects found in the tridiumx/systemMonitor JAR file.
JACE-NX-UPS,UPS Monitoring
A “power monitoring” feature is also available for the JACE-NX-UPS, the
JACE-NX model with integral UPS (uninterruptable power supply). Monitored
items include UPS battery level, operating load, and various other variables.
As in sysmon, alarms generated by power monitoring are automatically sent to the
Station object’s notification class. Also like sysmon, power monitoring is configured
in the JACE-NX-UPS’s drivers.properties file. In r2.3.4 and later, the
systemMonitor JAR also provides a “PowerMon2” object that you can place in the
station’s database. This object has linkable outputs that provide currently monitored
UPS variables for the JACE-NX-UPS, including alarm indications.
Niagara Properties FilesWith Niagara r2.3.5, even more features have been added that you can adjust by
editing various “properties” files. These are simple ASCII text files that reside on the
Niagara host, and they invariably affect station operation.
Use the Admin Tool to access these files. For example, drivers.properties can beedited on a particular host by opening a connection to it in the Admin Tool, selecting
the host, and on the Installation tab selecting Edit drivers.properties.
The following topics apply to Niagara properties files:
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Host > Edit File
1–28
Host > Edit File
Since Niagara build 2.301.330, the Admin Tool has also provided an “extensible”
method of adding/editing many remote properties files, using a “Host > Edit File”
menu command (Figure 1-12). A pull-down menu lists possible properties files that
you can edit (including create new, if not existing) using a text editor in the JDE.
Figure 1-12 Host > Edit File command in Admin Tool.
Figure 1-12 shows five possible properties files: System Properties, Gx Properties,
BACnet Properties, Status Color Properties, and Time Zones— the “default” r2.3.5
installation for the JDE.
This menu is “driven” by the file adminfiles.txt, in your JDE (PC’s) directory:D:\niagara\<release>\nre\lib (or equivalent). A “standard” r2.3.5 file is this:
Menu choices “System Properties” and “Gx Properties” always appear (even if you
remove adminfiles.txt), but the other three (BACnet Properties, Status Color
Properties, and Time Zones) are being sourced from this text file.
#
# adminfiles.txt
#
# This is a list of files that can be edited using the AdminTool.
# The entries in the list appear as menu items under the
# Host->Edit File menu of the AdminTool.
#
# The format of the lines is:
# [Menu Item Text;]file path
#
# The menu item text is optional. If excluded the menu item
# text is the name of the file.
#
BACnet Properties;/rel/nre/lib/bacnet.properties
Status Color Properties;/rel/nre/lib/statusColors.properties
Ti me Zones; / r el / nre/ l i b/ t i mezones. t xt
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Niagara Properties Files
1–30
Archiving Properties Files
With the sole exception of station.properties, all Niagara properties files are actually
“host” files (do not reside under a station directory). Whenever you upgrade Niagara
in a JACE, all existing properties files are left undisturbed . This allows for proper
station operation when the host reboots, reading the host’s license.properties file,drivers.properties entries, and so forth. However, be aware that you may need to
make changes (or add) properties files after upgrading Niagara or adding a module.
Archiving JACE properties files
If a need arises to replace a JACE, you must re-create properties files in the new
(replacement) JACE, as only station.properties is restored when you install a station.
Therefore, it is recommended that you save all previously-edited properties files.
Note This does not apply to license.properties, the digitally-signed file specific to a
particular host (JACE). That file must be obtained directly from Tridium.
Procedure 1-1 Archiving JACE properties fi les (drivers.properties, etc.)
Step 1 Open the JACE host in the Admin Tool.
Step 2 Using the recommended access method for that properties file (Table 1-3), open that
properties file in the editor.
Step 3 Click in the edit window and press CTRL-A (to select all).
All lines in the properties file should be highlighted.
Press CTRL-C (to copy to the Windows clipboard).
Step 4 Open Notepad (or similar text editor) to start a New file.
Step 5 Click in the Notepad editor and press CTRL-V (to paste from clipboard).
Step 6 Use the Save As feature of Notepad to save the copied properties file to your local
Niagara PC. Use the navigation controls and New Folder control, if needed.
It is recommended that you use a filename with a JACE-specific-prefix, for example:
JACE-NP_Floor4_drivers.properties
Step 7 Repeat steps 2 through 6 for each properties file you need to preserve.
Now, if you need to re-create properties files on a replacement JACE, you will have
copies that you can cut and paste from, as needed.
Web SupervisorConsiderations
By design, each new Niagara build installation on a PC is directed to a new build
<release> folder. Therefore, Niagara properties files are automatically archived.
Following a new Niagara installation, you typically copy any properties file that you
previously edited (from the previous niagara\<release>\nre\lib folder), along
with the existing license.properties file and adminfiles.txt. This may be
especially important for files such as drivers.properties or bacnet.properties.
Niagara Standard Programming Reference Revised: April 20, 20041–31
However, first you may wish to save copies of all the new “default” properties files
before overwriting them. This allows you to compare between the old and new
versions, and possibly add new entries if needed.
List of Niagara Properties Files
Various Niagara properties files are listed alphabetically in Table 1-3. Each entry
includes the recommended method of access and a brief description. This list does
not include Niagara properties files that are exclusively “auto-generated.”
Table 1-3 Niagara properties fi les, listed alphabetically.
File Name Access Method Description / Notes
bacnet.properties Admin Tool, command
Host > Edit File
(default in r2.3.4 and laterAdmin Tool)
Applies only if the Niagara host is running a station with the BACnetservice. In the initial r2.3.5 release of BACnet, very few parameters areaccessed through the host’s bacnet.properties file. However, as laterr2.3.5 build updates become available, this may change.
For more information about bacnet.properties, refer to the NiagaraBACnet Integration Reference, r2.3.4 or later.
Starting in r2.3.4, DDNS (dynamic domain name service) support wasextended to include LAN/WAN support, in addition to the previous RAS(dialout with captive ISP). This configuration file holds the DDNSparameters.
More information may be found in the Niagara Networking &
Connectivity Guide, 2.3.x (as an updated version becomes available).
It is used to configure/specify various low-level communicationsdrivers used by the Niagara host and the JDE. You may need to editthis file on various Niagara hosts, with some examples listed:
JDE engineering PC: If configured for BACnet/Ethernet, must be
edited with Ethernet adapter name (see Niagara 2.3.x BACnet docs).Same applies if a BACnet Supervisor.
JACE-NX or NP: To configure sysmon, power monitoring limits. Referto Engineering Notes doc, Niagara Sysmon and Power Monitoring.
JACE-4/5: To configure power monitoring limits, BACnet MS/TP driverfor VxWorks.
Some integration drivers for JACEs may also require editing ofdrivers.properties (details in specific Niagara Integration documents).
Note: If your PC-based Niagara host (Web Supervisor/JDEengineering PC/BACnet Supervisor) requires edits todrivers.properties, after upgrading to a new Niagara build, you shouldcopy and paste the old (edited) drivers.properties into the newniagara\<release>\nre\lib folder, replacing the “default” one installed
by Niagara. This also applies to your license file (license.properties),plus any other properties file that you have especially edited.
This does not apply to any JACE you have upgraded, as the oldproperties files are retained.
Note: Changes to drivers.properties do not become effective for astation running on the host until the station is restarted.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Niagara Properties Files
1–32
gx.properties Admin Tool, command
Host > Edit File
Applies if the Niagara host is running a station with the WebUiService.Currently, this file allows you to specify a small delay between servingGx objects to a client browser, useful to avoid issues with animated .gif
files. For more details, refer to “gx.properties File,” page 8-15.license.properties Read Only!
Admin Tool,Installation tab,View License
Lists the features licensed for the Niagara host, plus other informationabout the host.
You should never edit this file. If you do, you will render yourNiagara host unusable!
mime.properties Admin Tool, command
Host > Edit File
(can add entry, see notes)
Typically, you do not need to edit this file on any Niagara host. It is usedby the web server to notify client browsers about the mapping of fileextensions to MIME file types, so that client browsers can useappropriate applications.
If you decide to add it to adminfiles.txt, use this entry:
Mime Properties;/rel/nre/lib/mime.properties
ndio.properties Read Only!
Menu access not recommended. Found in therel/nre/lib folder of a JACE-4,with other properties files.
Starting in r2.3.4, it applies only to JACE-4 hosts—either models withonboard I/O or that accept I/O expansion modules. It is used by theJACE and its ndio module to map indexes of Ndio objects correctly.
You should never edit this file. If you do, you will render I/O onthe JACE-4 or JACE-IO-XX as inoperable!
niagarad.properties Admin Tool, command
Host > Edit File
(can add entry, see notes)
Typically, you do not need to edit this file. Includes optional parameterto specify the TCP “Admin Port” for the host (default port is 3011). Thisis the port used for most operations from the Admin Tool.
adminPort=nnnn (where nnnn is TCP port number).
Another parameter is for the initial buffer-size, in charcters, of aStandard Output window (opened for a station running on that host):
bufferSize=5000
Another parameter can specify the name of the NT Administratorgroup, typically for non-US installations (localization). For French, e.g.:
adminGroup=administrateurs
If you decide to add this to adminfiles.txt, use this entry:
Found in the nre/lib folder ofany r2.3.5 Win32 host.
Applies only to Win32 hosts, to specify which JVM is used.Automatically set upon r2.3.5 installation, where the default (andsupported) setting is:
vm=hotspot
port.properties Admin Tool,Network Settings tab,Edit Port Properties
Applies only to JACE-4 hosts, to specify how serial port assignmentsCOM1 and COM2 are mapped to physical ports RS-232, RS-485, andinternal modem. Refer to the Niagara Networking & Connectivity
Guide, or to the Installation Instructions document for that JACE-4.
ras.properties Admin Tool,
Network Settings tab,Edit Modem Properties
Sometimes referred to as “modem.properties.” Applies only to JACE-4
or JACE-5 hosts. Used to both configure modems and enable thedirect-dial function on the JACE-4/5. Refer to the Niagara Networking
& Connectivity Guide for more details.
In r2.3.5, support was added for CHAP (Challenge AuthenticationProtocol), used to authenticate a user of dialup (PPP) connection.Previously, PAP (Password Authentication Protocol) was the onlyconfiguration option. Certain limitations apply to this feature.
For more details, please refer to issue #3182 CHAP support in ther2.3.5 Release Notes document (section Core, dialup).
Niagara Standard Programming Reference Revised: April 20, 20041–33
station.properties Admin Tool, command
Station > Edit > Properti es
(station must be selected)
Unlike other properties files, which configure the host, this file isspecific to a selected station, and is stored under that station directory.Included is whether the station “auto starts” (after a host reboot),
and/or “auto restarts.” (Note that “Auto start” is configured using acheckbox dialog, with Admin Tool command Station > Configure.)
If the station is configured to use an HTTP port other than the defaultport 80, (Station object, config property: httpPort), a line is needed thatspecifies this same port (to support DB Admin functions), for example:
httpPort=85
Note: Changes do not become effective until the station is restarted.
statusColors.properties Admin Tool, command
Host > Edit File
(default in r2.3.4 and laterAdmin Tool)
Starting in r2.3.4, this file allows global customizing of the status colorsused by any station running on that host. Status colors are reflected inobject and object output colors in the JDE, linked Gx objects inGxPages (JDE and browser) and in the status servlet (browser).
Both status background (bg) and foreground (fg) colors are adjustable.
• Default status bg colors, by status/color are: alarm/red, fault/orange,down/yellow, overridden/magenta, outOfService/cyan.
• Default status fg colors, by status/color are: alarm/white, <any otherstatus>/black.
In this file, you specify status colors by their hexadecimal RGB values.For example, to change override status to show as pink (fg) on darkgray (bg) from the defaults black (000000) on magenta (ff00ff):
See the comments in the statusColors.properties file for more details.
system.properties
(continues next)
Admin Tool, command
Host > Edit File
In earlier releases, this file was primarily used to enable or disable FTPand Telnet in embedded (JACE-4/5) hosts; this usage still applies.
For example:ftpEnable=falsetelnetEnable=false
In Niagara r2.3.3 (2.3), various “timeout” properties were added, andthe file had wider host applications (all JACEs, Web Supervisor). Also,a “garbage collection” daemon property became available for use witha host running a station with the DatabaseService and Cloudscape.
In Niagara r2.3.4, more properties were added, including several thataffect publications (sending) of external links (interstation links) andcontrol the number of processing threads to the station’s web server.
Note: Starting in r2.3.4, changes to the following properties becomeimmediately effective, without a system reboot:connectionTimeout
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 1 Station and Objects
Niagara Properties Files
1–34
system.properties(continued)
Admin Tool, command
Host > Edit File
In Niagara r2.3.5, more properties were added, including one fordisabling DirectX on Windows platform (to prevent Sun JVM conflict),a method to disable UTF-8 encoding by the MailService, and
properties to aid operation of master/slave interstation links betweenhosts running different Niagara releases.
Log archive tracing was also added, as was a configurable “steadystate delay” to permit a station, upon startup, to allow all objectsadequate execution time before enabling web server operation.
Note: Starting in r2.3.5, the system.properties entry:gc.daemon=n
is no longer necessary, as the Sun Hotspot JVM has no relatedmemory leak (DatabaseService with Cloudscape appdb). Be sure todisable this entry if present, otherwise, station performance may slow.
See the comments lines (#) in the r2.3.4 and later system.propertiesfile for explanations of the various properties. Please note thatadditional coverage of when (and why) you would change properties inthis file are planned in a future Engineering Notes document.
Note: Changes to the following properties added in r2.3.5 becomeimmediately effective, without a system reboot:archive.trace
mail.useUTF
masterSlave.checkRelease
masterSlave.releaseSpoofing.enabled
Also starting in r2.3.5, any running station provides a debug servletavailable from a browser using the URL:
http://<host>/debug
Included is “System Properties” link, with this URL (also in r2.3.4):
http://<host>/prism/systemPropertiesto review currently effective system.properties values.
time.properties Menu access not recommended.
For r2.3.5 host only, in nre/libfolder if Win32, or /sys folderif JACE-4/5 host.
Reflects the currently selected Java time zone for the Niagara host, bytime zone ID. The host’s time zone database is customizable, and isstored locally in a file named timezones.txt.
timezones.txt Admin Tool, command
Host > Edit File
> Time Zones
(default for r2.3.5 and laterAdmin Tool)
New in r2.3.5, not exactly a “.properties” file, but the host’s source timezone database, stored in its nre/lib folder as a plain text file. Usefulmainly for localization scenarios. Applies to all Niagara platforms.
Allows editing of individual time zones, where each line represents onetime zone. Each time zone begins with a time zone “ID”, which is visiblewhen selecting the host’s time zone in the Admin Tool (System Time
tab). Time zone ID is also seen in all timestamp data in the station, e.g.log records, alarms and alerts, and time-based object properties.
Other parameters in each time zone line determine the UTC offset inmilliseconds, and various start/end changeover points for DaylightSavings Time (if DST is used at all). All parameters in each time zoneare delimited using the pipe (|) symbol.
For more details, including “translated” values for each available timezone in the standard r2.3.5 timezones database, please refer to thelocalization document “Java Time Zones for Niagara r2.3.5.”
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 2 Data Species and Links
Data Species
2–2
Data Primitives
A primitive is the most basic of data types. A property implemented as a primitive
has a value expressed as one of the following:
• boolean —Either false or true.
• float (floating-point)—IEEE floating-point standard 754, 32-bit single
precision. Very small and large numbers are possible.
• int (integer)—a signed 32-bit integer, within the following ranges:
minimum: -2,147,483,648 to maximum: 2,147,483,647
Note In object property sheet fields, the integer minimum and maximum
limits above are represented as MIN_VALUE and MAX_VALUE.
• String —an ASCII text string (no theoretical character limit).
For example, the property description (a property of most object types) uses a dataspecies of type String. This is a read-write property that you can use to describe the
object. For most object types, the default value of this property is empty.
Data Enumerations
Some data species use enumerations. An enumeration is simply a numbered list with
a choice of values. There are about 40 documented enumerations used among data
species. Refer to the “Enumerations” section on page A-53 for a complete listing.
For example, WeekdayEnum is an enumeration for days of the week, with the
following definition:• Sun (0)
• Mon (1)
• Tue (2)
• Wed (3)
• Thu (4)
• Fri (5)
• Sat (6)
As with primitives, some properties are implemented with just one enumeration. For
example, the property eventState, a status property in many control objects, uses a
data species of EventStateEnum. This enumeration is defined as follows:
Niagara Standard Programming Reference Revised: April 20, 20042–3
Variable Types
Like data primitives, enumerations can be used as “pieces” in other data species,
called structured types. Structured data species are defined by some combination of
data primitives, enumerations, and sometimes other (nested) structured data types.
Structured data species are classified as variable types, along with the four primitivedata types. There are about 32 documented variable types. Refer to the “Variable
Types” section on page A-49 for a complete listing.
For example, the DateTimeTrigger object has an engineering property, lastTrigger,
that uses the variable type DateType. This data species is structured with the
following data fields in its definition,
where: rw means read-write capable, and r means read-only:
• year rw int
• month rw MonthEnum
• day rw int
• weekday rw WeekEnum
• nextDay r DateType
• prevDay r DateType
Note that data fields year and day are primitives (int), while fields month and
weekday are enumerations. Data fields nextDay and prevDay both use the definition
of the variable type DateType.
Status andPriority Types
Among the variable types are two important classes used for many input and output
(linkable) properties, particularly among control objects. These two classes of
variable types are:
• Status Types —Each is a primitive value and a “status flags” enumeration.
• Priority Types —Each is a primitive value and a control-priority enumeration.
Status Types
Status-variable types are used in object input and output properties named
“statusInput” (sIn) and “statusOutput” (sOut), and include these variable types:
• booleanStatusType
• floatStatusType
• integerStatusType
Each has two components, the primitive data value and a status flags component. The
status flags component provides a general indication of “health” of the received
property value (if a statusInput), or of the object itself (if a statusOutput).
Note Status flags for a statusOutput (sOut) property are reflected by the object’s
statusFlags property (visible on the objects property sheet, Status tab).
Niagara Standard Programming Reference Revised: April 20, 20042–5
Property AttributesApart from the data species a property uses, it also has a number of attributes. These
attributes determine the following about the property’s usage:
• Read/Write access—read-only (status) or read-write.• Station storage options—Property’s value is either:
– stored to disk (flash), that is: persistent
– operating only in RAM, that is: transient
– typically stored to disk (flash), but may be subject to change in a shadowed
foreign device. A fetch command may be necessary to update the station
with the latest value. This is called on_demand_transient.
• Input/Output/Internal—whether the property is available as a linkable input or
output (or not). If available, whether it appears by default on the object shape.
• User (Security) Access—whether the property is accessible to a station user
with Operator-level property access, or only Admin-level property access.
For example, a property may be either readable or both readable and writable. It may
be persistently stored. It may be a linkable input or output, or an internal value only.
It may be accessible (on the JDE property sheet) at both the Operator and Admin
levels, or only the Admin level.
Refer to Appendix A, “Object Property Quick Reference,” for listings of each
property’s attributes, as well as an explanation of “Attribute Notation.”
Links
Most Niagara objects have one or more properties that you can link to another objectto establish data relationships. Examples include control objects, apps objects, Gx
objects, and integration (shadow) objects.
Note Some objects are not typically linked, for example, Container objects.
A linkable property is typically either an output or an input, and a link connects an
output to an input.
The following link-related topics are explained ahead:
Niagara Standard Programming Reference Revised: April 20, 20042–7
Links View In addition, for any object, a right-click Links view is available when using the JDE
(Go > Links), as shown in Figure 2-2.
Figure 2-2 Links view of a selected object lists all links to and from the object.
The Links view lists all existing links for the selected object, including each link’s:
• Type
• Property
• Other swid
• Other Property
• Service (typically applies only if a LonWorks-related link)
Note The Links view for any object is also available from a Web browser connection, providing that the station has the WebUIService. The URL requires the station swid
of the object, ending with string “$Links”.
For example:
ht t p: / / 192. 168. 1. 2/ db/ demoR2/ Si m/ Logi c/ Ai r Handl er/ cool i ngCoi l $Li nks
Link Categories
A link connects two Niagara objects. From a connection standpoint, any link can be
categorized as one of the following:
• Local Link
• Internal Link
• External Link
A typical Niagara station is engineered with many local and internal links. Unless it
is a standalone JACE station (no Web Supervisor), there are typically external links
Niagara Standard Programming Reference Revised: April 20, 20042–11
Link Colors In the JDE menu bar option View > Options > Link Colors, you can assign each link
type a color. Link colors apply to all link categories, meaning local link (lines) and
link boxes (internal and external links). Usually, link colors are left at defaults.
It is helpful to learn link colors, so you can quickly distinguish link types when
viewing containers in the WorkspaceEditor.
Note Link colors is a JDE “tool” setting, not associated with any particular station.
Figure 2-6 Link colors are editable from the JDE menu bar View > Optio ns menu.
Link Rules
In most cases, in order for two properties to be linked, they must use the same
data species. In a link, one object’s output supplies the value (or trigger) used by
the other object with the receiving input. The Link Editor in the JDE enforces this
rule when you select a property on one side of the window to link.
Note An exception to the need for matching data species occurs when linking Gx objects,which have only inputs. For example, the “binding” input of a GxText object can be
linked to any internal (configuration property) of another object, in addition to most
output properties. When linked to an internal property, a GxText object displays text
showing the value of that property.
Unlike “normal” links, Gx object links are considered user-interface (“ui”) links, not
part of “control logic.” Instead, they provide the building blocks of a user interface.
The “Background” color for each link type is themain color used.
The default Background color for each link typeis as follows:
Niagara Standard Programming Reference Revised: April 20, 2004
CHAPTER
3–1
3
Commands and Views
Niagara objects have various commands, depending on the object type and signon
level of the station user. In addition, objects have “standard” views to access their
properties and links. Some object types also have special views for other purposes.
The following general topics are explained in these sections:
• Commands
• Views
CommandsCommands for objects in a running Niagara station vary by object type. Commands
can provide control functions, such as with a BinaryOutput object or administrative
(admin) functions, such as with a Station object.
The following topics apply to commands:
• Control Commands
• Admin Commands
• All Available Commands
Control Commands
Control commands apply mainly to “commandable” control objects. Commands are
available only if the user has “Std” (standard) or “Emer” (emergency) level command
rights for a security group assigned to that object.
For example, if a JDE user is signed on with sufficient command privileges, aBinaryOutput (BO) object provides the user with right-click commands to set it
active, inactive, or in auto (Figure 3-1, left). If the object is linked to a Gx object in
a GxPage, the same command menu is available from a browser, by right-clicking on
a linked Gx object (Figure 3-1, right).
Note Command access through a Gx object is validated using the Gx object’s
securityGroups property. Refer to “Providing Command Access,” page 8-6.
Niagara Standard Programming Reference Revised: April 20, 20043–7
• Links —Lists all links made to (and from) the selected object, as shown in
Figure 2-2. Not the default view for any object type.
• Report —Provides a form in which you choose items about the selected object
to be “printed” in a text report. Also not the default view for any object type.
Selectable items include properties, links, and child objects. Text from a
generated report appears below the report form, and can be exported (saved) toa file or directed to a printer.
Note If a station has the WebUiService, read-only versions of properties and links views
are available for any object from a Web browser connection. The URL requires the
station swid of the object, ending with string “$Properties” or “$Links”.
For example:
ht t p: / / 192. 168. 1. 2/ db/ demoR2/ Si m/ Logi c/ VAVs/ VAV1/ Damper$Pr opert i es
StandardContainer Views
For all container-type objects (except for the ServiceContainer), the followingadditional JDE “Go” views are also available:
• Workspace —Also called “monitor mode,” this is the runtime view showing
the container’s child objects, with values updating in real time. This is the
default view for most container-type objects.
• WorkspaceEditor —The “edit mode” for the container, where child objects
can be added, linked, cut, duplicated, and so on. Available only if the user has
Admin write privileges for the container object.
Note Using a Web browser connection, only GxPage objects offer a Workspace view
(default view). The station must have the WebUiService for this feature.WorkspaceEditor views are never browser-accessible (the JDE is always required).
Special Views
Some object types have special views. Sometimes called facets, these views provide
a graphical representation of the object’s configuration or status. For example, when
using the JDE, the following objects have default views:
• Schedule objects have a ScheduleEditor view. This view allows the user to
review and adjust schedule event times for the selected object using the mouse.
• Log objects (AnalogLog, BinaryLog, IntegerLog and MultistateLog) providea LogChart view to show the object’s log data visually graphed, complete with
controls for zooming, time scaling, and various other adjustments.
• Calendar objects have a Calendar view for reviewing and entering calendar
dates.
If the station has WebUiServices, the equivalent graphical views for the objects
above (Schedule, Calendar, log-types) are provided to a user accessing the station
Niagara Standard Programming Reference Revised: April 20, 20044–3
• A station for a JACE controller may (or may not) include the WebUiService
and/or DatabaseService, depending on its model type (the DatabaseService is
not supported by a JACE-4/5 controller). More importantly, a JACE controller
station will have one or more Protocol Services.
ProtocolServices
JACE controller stations require additional services for protocol support ofnetworked devices. An example is the BACnetService, which is licensed for any
JACE controller. In addition to this service, other open protocol services may be
required, such as the ModbusAsyncService or LonWorksService. Vendor-specific
protocol services are also available for many legacy control systems.
Note Device-support protocol services (commonly called “drivers”), are not covered in
this document. For more information on these services, please refer to the
appropriate Niagara integration document.
General Notes on Services Niagara services have common characteristics that are explained in this section. The
following topics apply to all services:
• About Licensing
• Adding or Removing Services
• Common Service Object Properties
About Licensing
Niagara services must be licensed in the host running the Niagara station. Licensing
is done using a license.properties text file, which resides in the nre/lib folder under
the Niagara release directory of the host machine (Web Supervisor PC, JACE-NX,
JACE-NP, or JACE-4/5 controller).
Caution Each license.properties file is a “digitally-signed” file, and is specific to its particular
host machine. Changes to this file, if any, must be performed through Tridium. Any
other attempt to alter or copy this file will render the Niagara software unusable.
In the license.properties file, the “features” line is where licensed services appear.
Your can use the Admin Tool to open a connection to any Niagara host and view itslicensed features, as shown in Figure 4-1.
Note Licensed features are separated from each other by a semicolon (;).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
General Notes on Services
4–4
Figure 4-1 Niagara services are licensed by inclusion in the “features” line of the host’s license.properties file.
All services explained in this document are licensed by the “coreRuntime” entry in
the features line of license.properties, with the following exceptions:
• WebUiService —Requires a feature line entry of: webUi
• DatabaseService —Requires a feature line entry of: database
• PolledArchiveService —Requires a feature line entry of: multisite
Note The Admin Tool provides an “Install New License” command from its main menu.You should use this whenever installing an updated license.properties file that you
have received from Tridium.
Adding or Removing Services
Add a service to a running station by opening the station in the JDE and then using
the Tree View to copy the service needed from the Local Library (or Remote
Library). Paste the copied service in the ServiceContainer in the root of the station.
Notes • A newly-added service will not be active until you restart the station.
Often, you may wish to define service properties before you perform a station
restart. This way, the service will initialize and operate in the intended manner.
• The host must be licensed for the service. See “About Licensing,” page 4-3.
• Services are “one-only” in a station. Do not add a service that already exists.
• The BackupService is intended only for stations running the DatabaseService
(Web Supervisor or possibly a JACE-NP). It has no use in a JACE-4/5 station.
This license.properties is for a JACE-NP, which in addition to coreservices (coreRuntime) and device-related services, is licensed forthe WebUIService and DatabaseService (webUi, database).
Niagara Standard Programming Reference Revised: April 20, 20044–5
You can remove a service, if needed, by simply opening the station in the JDE and
using the Tree View to select and “cut” it. However, you should be careful about
deleting services, particularly if the station has been operating with it.
Common Service Object PropertiesService objects each have a small group of properties standard to most Niagara
objects. They are explained in Table 4-1, which lists common properties organized in
the property sheet tab in which you can find them. In the case where some property
variation exists for a particular type of object, that difference is noted in the property
table for that object type.
Table 4-1 Common propert ies for al l service objects.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType Read Only: The service object type. Bydefault, a newly added service uses this
string in its name (unless renamed).The full string for the object type is shown,for example, BackupService or LogService.
See description reflectsobject type
statusFlags Read Only: Current state of the object’sstatus flags. A “normal” state (no flags set)is where the status flags value is “ok”.
The only status flag that can be set is:
• down—The station is down or offline.
either:
ok (no flags)
or
down
ok Unlike some other objecttypes, service objects donot have alarm states.
description Read-Write: Permits a user-defined textdescriptor for describing the service. Anyprintable characters, including spaces andmixed case characters, are allowed.
See description —
V i s u a
l
position Read-Write: For other object types, this isthe x-y coordinates (in pixels) for theobject’s position on the JDE Workspace.
However, the position property does notapply to service objects.
— -2147483648
x
0
Because the parent(ServiceContainer)object has noWorkspace, the positionproperty for any servicehas no real application.
S e c u r i t y
securityGroups Read-Write: Shows the security groups towhich the object is assigned. A user musthave the appropriate privileges in at leastone security group to view and modifyproperties and issue commands.
Refer to the “Security Tab” section onpage 1-20 (Station object UserAdmin topic)
for more details on how securityGroupssettings apply.
Any mix ofthese types:
•General
•HVAC
•Security
•Life Safety
•Group 4
•Group 5
•Group 6
•Group 7
General Also refer to the “AboutSecurity” section onpage 1-21.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
AuditLogService
4–7
Properties
AuditLogService NotesEach log record created by the AuditLogService has the following fields:
• tstamp —Timestamp of the recorded change, for example,
“10:05:20 4-Sep-2001 EDT.”
• userName —Station user that affected the change, for example, “admin.”
• source —Swid of the changed object, for example,
“/demoR2/Services/Notification.”
• auditAction —Description of the database change (with new value), for
example, “Property changed: "debug" = "true".”
Table 4-2 AuditLogService proper ties.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType,
statusFlags,description
See Table 4-1 on page 4-5 for information on
these properties common to all service objects.
— — description default
Logs records ofuser modifications.
lastArchiveTimestamp Read Only: Shows a date/timestamp for whenthe last archive occurred. Shows “null” if therehave been no archives or if theclearLastArchive command was given.
validtimestamp
or null
null
C o n
f i g
bufferSize Read-Write: Defines the number of loggedchanges that can reside locally (in RAM).
An allocation of “resource counts” (RAM) is setaside based upon the entered number.
1 to 1000 100
stopWhenFull Read-Write: If set to True, logging stops whenthe number of logged changes equals theconfigured bufferSize. If set to False (the
default), the log buffer rotates—this means thatthe oldest recorded change is overwritten aseach new change continues to be recorded.
False, True False
archiveSetup Read-Write: Defines the events that cause theobject’s log data to be archived. Flags can beset in any combination.
• nearFull —Archive occurs at 80% of the logbuffer size.
• daily —Archive occurs daily, at the timeconfigured in the LogService.
• polled —Applies only if another (remote)Niagara station is configured with the PolledArchive (multisite) service.
selection ofany or all:
nearFull,daily,polled
daily
V i s u a
l
position Read-Write: See “position,” page 4-5. — -2147483648x 0
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For more details,see “securityGroups,” page 4-5
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
BackupService
4–9
BackupService NotesThe BackupService is strongly recommended for archiving Web Supervisor stations,
as opposed to performing a direct backup of the running station using another method(tape backup, copy to CD, etc.). It zips everything under the running station’s station
directory, including the entire “app” (application database) folder.
Note By default, the BackupService is added when using the New Station wizard and the
“Is this station going to be a server?” option is selected.
Backup zip files are placed in a <niagaraRelease>\backups\<stationName> directory,
as shown in Figure 4-2.
C o n
f i g
backupEnabled Read-Write: Toggles the ability to perform adaily backup as On (True) or Off (False).
False, True True If False, a manual“forceBackup”command still
works.scheduledBackupTime Read-Write: Specifies the time of day, in
24-hour format, for the BackupService tocreate the backup.zip file for this station.
00:00to
23:59
00:00
(midnight)
V i s u a
lposition Read-Write: See “position,” page 4-5. — -2147483648
x 0
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For moredetails, see “securityGroups,” page 4-5
General,
7 others
General
Table 4-3 BackupService propert ies. (continued)
Tab Property Name Description Valid Values Default Notes
Figure 4-2 The “ backups” directory is created under the Niagara <release> directory.
Two backups are stored: thelast (backup.zip) andprevious (backupOld.zip).
Typically at a job, thebackup.zip file is copied toremovable media on a dailybasis.
If a failure scenario requiresa restore, the most recentbackup.zip file can beunzipped back to theNiagara host.
Note: To restore, unzip the
backup.zip to the root of theNiagara release directory,with the “Use Folder Names”option selected.
Read Only: Shows the number of objects ineach execution frequency group, includingthe continuous-types (fastest, faster, normal,slower) and others (onTrigger, minutely).
(each)
integer,0 to
— minutely typesinclude all Calendarand Scheduleobjects.
Read Only: The accumulated number ofexecution cycles for each frequency grouplisted. The “minutelyCycles” value equals thenumber of minutes of operation that thestatistics are based upon.
(each)
integer,1 to
— Statistics globallyupdate every 10seconds.
totalOverruns Read Only: The total number of overrunscounted, across all four of thecontinuous-type frequency groups.
Equal to the sum of the next four overrunproperties (fastest, faster, normal, slower).
Read Only: The overruns counted for eachindividual execution frequency group.
An overrun is counted when the actual cycletime for a group exceeds its target executiontime, as defined by executionFrequenciesproperty settings (on the Config tab).
integer,0 to
—
fastestAverageExecuteTime,
fasterAverageExecuteTime,
normalAverageExecuteTime,
slowerAverageExecuteTime,
minutelyAverageExecute
Time
Read Only: For each repeating-typeexecution group, shows the averageexecution time (in milliseconds) for onecomplete object cycle.
floating pointvalue
— If profileNodes isenabled (for a shortperiod only), eachobject accumulatesits individual average executiontime. The sum ofthese times, perfrequency group,equals the values inthese properties.
lateStarts Read Only: The number of object executioncycles that started later than “anticipated,”(after the next cycle should have begun).
LateStarts occur as a result of other
asynchronous events that require processortime. Examples are performing a databasebackup, or the periodic “garbage collection”performed by the JVM.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
ControlEngineService
4–12
ControlEngineService NotesThe ControlEngineService executes all executable objects in the station except for
Gx objects (executed by the UIEngineService). Within the Java virtual machineexecution of a station, processor time is typically dedicated with the running of these
two services, plus whatever ongoing device integration (polling) services exist.
Notes on the ControlEngineService are in the following subsections:
• Object Execution
• Scheduling Execution
Object Execution When an object is executed by the ControlEngineService, usually there are three
phases of processing:
1. Read inputs1 —Values are “pulled” from outputs linked to inputs.
2. Calculation —The object’s algorithm, using its configuration properties.
3. Write outputs1 —Values are updated at outputs.
All three phases occur within the object’s execution time.
C o n
f i g
executionFrequencies Read-Write: Target execution cycle times foreach frequency group.
Default values for each group are:
• fastest: 500 ms
• faster: 1 seconds
• normal: 2 seconds
• slower: 5 seconds
Rules for values:fastest <= faster <= normal <= slower
100msto
999 seconds
(See Rules)
100ms stepsup to 2
seconds,thereafter 1
second steps
Seedescrip.
Cycle times set tooshort are reflectedby numerous
overruns. For anygroup, if the numberof overruns stays“lock step” with thenumber of cycles,the cycle time is setmuch too short.
profileNodes Read-Write: If True, causes all objectsexecuted by the ControlEngineService tolocally maintain their own execution statisticsin properties minExecuteTime,maxExecuteTime, and avgExecuteTime(found on the Engineering tab of each
object’s property sheet).
False, True False Do not leave at Truefor extendedperiods (usesstation resources).
displayDots Read-Write: If True, causes a period (dot)written to Standard Output after eachcompletion of the object execution cycle.
False, True False
V i s u a
lposition Read-Write: See “position,” page 4-5. — -2147483648
x 0
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For moredetails, see “securityGroups,” page 4-5
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
ControlEngineService
4–13
Note The third phase (write outputs) is skipped whenever the difference between the
object’s calculated value and its last written value is less than the object’s configured
“covIncrement” value (assuming the object is so configured).
Station-wide, you can use this efficiency by assigning objects with a “covIncrement” property to a non-default (not 0.0) value. This results in fewer property changes
propagated to objects linked “downstream,” thereby reducing total system load.
For example, AnalogInput objects assigned a covIncrement of “0.1” (if suitable)
typically improve station efficiency. Other object types with covIncrement include
the AnalogOutput, Loop, Math, and the various Ndio UI objects.
An object’s behavior is usually determined by its object type and the settings of its
configuration properties. In the case of a Program object, behavior is defined by its
TRIPL program.
SchedulingExecution
The control engine thread of the station periodically walks a list of objects and
executes them in a sequential fashion. The scheduling of execution is determined by
the executionParameters property of individual objects, which has two parts:
• freq —Frequency. Most types of objects provide the following selections:
– never
– slower
– normal (the default)
– faster
– fastest
– minutely– on_trigger
For more information, see “Execution Frequency.”
• order —The following selections are available for all objects:
– input
– processor
– output
For more information, see “Execution Order.”
Execution Frequency
By default, most objects are executed in a continuously repeating fashion, and are
assigned by default to the “normal” execution frequency group. You can assign them
to one of the other three frequency groups for continuously executing objects, namely
“slower,” “faster,” and “fastest.” Target cycle times for the four execution frequency
groups are on the Config tab of the ControlEngineService property sheet.
Calendar and Schedule object types are special cases that execute only once a minute,
(at the “top” of the minute). If desired, you can assign other executable objects to
execute only at the top of the minute, by assigning the freq parameter to “minutely.”
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
DatabaseService
4–15
DatabaseServiceQuick reference for all properties: Table A-24
abbrev: (none); DatabaseService
The DatabaseService provides an RDBMS
(relational database management system) forarchiving log object data, plus events such as
alarms and alerts. Referred to as an
application database (or appdb) it is separate
from the station’s configuration database.
The default appdb is an embedded,
Java-based, SQL-type by Cloudscape.
The DatabaseService is required for a Web
Supervisor. It is optional for a JACE-NP or
NX, and is not supported on a JACE-4/5.
The service provides Web browser access to
the application database, including an indexto all archives, plus an SQL query form.
Output from SQL queries can be directed to
different MIME type outputs, including text
in plain, HTML, XML, tab-separated, and
comma-separated formats.
A DatabaseBrowser view is also provided in
the JDE, as the object’s default view. This
provides access to summary, data, and SQL
query commands from within the JDE.
Parent Dependencies: ServiceContainer
Only one DatabaseService per station.
Resource Count Range: 55 to 63
Trigger Properties None.
CommandsIf a Cloudscape appdb, users with “Command, Admin” privileges have the following
available commands (these commands do not apply if MSDE or MS SQL appdb):
• Open —Opens a connection from the station to the application database.
Typically, this connection always remains open during station operation, so
that the station can populate the database and support the alarming subsystem. Note a connection is automatically opened upon any station restart.
• Close —Closes the connection from the station to the application database.
Note Do not close the database connection unless you have a specific reason.
While closed, station data that would otherwise be archived will be lost, and
the Niagara alarming subsystem will not function.
Note: Starting with Niagara 2.301.321.v1, additional (and optional)support for Microsoft MSDE or MS SQL databases was introduced, asan alternative to the standard Cloudscape SQL database.Configuration properties relating to these options are not explainedhere, but are covered in another document, MSDE or SQL Server 2000
Database Installation and Configuration Instructions.
Inputs
Object Shape
Outputs
(none) (none)
Input / Outpu t Property Reference for DatabaseService Object(only input and output types, see Table 4-5 for all properties)
urlPrefix Read Only: String used within URLs forbrowser access to the application database.
For example:http:/<host>/<urlPrefix>/index.html
appdb appdb
databaseType Read-Write: Specifies the SQL databasetype for the appdb, with following choices:
• Cloudscape
• MSDE
• MS_SQL_Server
• Oracle (currently not supported)
Note: If Cloudscape, see “Memory UsageNotes,” page 4-26.
(see descrip). Cloud-scape
Cloudscape is thestandard SQLdatabase type.MSDE orMS_SQL_Serverare speciallylicensed options.
orderByTimestampDescending
Read-Write: Specifies how data records inan archive are ordered in table views, either:
• Most recent data first (at top of table),orderByTimestampDescending= True
• Oldest data first (at top of table)orderByTimestampDescending= False
False, True True
V i s u a
l position Read-Write: See “position,” page 4-5. — -214748364
8
x 0
S e c u r i t y
securityGroups Read-Write: Shows the security groups towhich the object is assigned. For more
details, see “securityGroups,” page 4-5.
Note: In r2.3.4 and later, any browser userrunning a query (“Using the SQL QueryForm,” page 4-21) must have Admin Writeprivileges to issue any SQL commandbesides “Select”. Previously, any stationuser could issue any SQL command.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
DatabaseService
4–19
Archive DataFormat
Within any table, archived data appears in table rows; each record is a separate row.
Typically, each record begins with a unique timestamp (first column), followed by
one or more other fields (columns) with values and status.
Note Starting in r2.3.4, the default order for archive records are “most recent data first.” Ifneeded, you can reverse this display order (from top-to-bottom) such that oldest data
is first (top). To do this, set the config property orderByTimestampDescending to
False —this duplicates the previous sort method used in older Niagara releases.
For archives of log types AnalogLog, BinaryLog, IntegerLog, and MultistateLog,
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
DatabaseService
4–22
Browser Access—From a Web browser, use the following procedure:
Procedure 4-2 Running an SQL query from a Web browser
Step 1 Access the SQL query form using the URL:
http://<stationName or IP address> /appdb/queryFormfor example, ht t p: / / 192. 168. 1. 195/ appdb/ queryFor m
Step 2 Type the query, using the SQL command, schema.table, and supporting SQL syntax.
A typical query uses this standard format:
select * from <table name> where <column name>='<string>'
example: select * from archive.demo_services_errorlog where severity='ERROR'
Step 3 Select the MIME type output (see “Query Output Types”).
Step 4 Click Execute.
Query results appear in the same browser window.
Note When using a browser connection, you can save query results by using the browser’s
File > Save As feature. Typically, this allows you to save a query as either an HTML
table or a text (.txt) file, or if you selected text/xml MIME output, in XML format.
Query Output Types
You can select any of the following MIME (Multipurpose Internet Mail Extensions)
types of output when running an SQL query. Each is listed below:
• text/html —Data is pre-formatted within an HTML table, using standardHTML tags. Included are column headers for each record field.
• text/plain —Data is formatted in plain text, one record per row, with each field
separated by a comma (,). Header (field name) information is not included.
• text/xml —Data is formatted using XML tags that reflect field (column)
headers, for example <TSTAMP> and </TSTAMP>. The XML output is
viewable in newer browsers. Header (field name) information is not included.
• text/tab-separated-values —Data is formatted in plain text, one record per
row, with each field separated by a tab. Header (field name) information is not
included.
• text/comma-separated-values —Data is formatted in plain text, one record
per row, with each field separated by a comma (,). Header (field name)information is not included. (Output is identical to the “text/plain” selection.)
• application/x-tridium-datax —Data is encapsulated in a binary file for use in
another application. This output selection is directed to a saved file only (not
viewable in the DatabaseBrowser or a Web browser window).
Lists all fields (*) for records of theBinaryLog object OAOLog created by atransition to On (true).
command select
selection value
operator =
select * fromarchive.demoR2_sim_logicscreens_energymgmt_schlogwhere ((extract(month from tstamp))=(extract(month fromcurrent_date)-1) and (extract(day fromtstamp))>=(extract(day from current_date)) or(extract(month from tstamp))=(extract(month fromcurrent_date)) and (extract(day fromtstamp))<=(extract(day from current_date))) and(extract(year from tstamp))=(extract(year fromcurrent_date))
An advanced level query using acombination of functions and operators(thanks to author Gerard Huff).
Lists all fields (*) for all records in theselected archive (in this case,BinaryLog object SCHLog) for a “rollingmonth’s” worth of data.
In other words, lists all archivedrecords from today’s date in last month until today’s date.
command select
selection tstamp
operators =, AND, OR
Also uses functions:
extract
Note: This query works forall months except forretrieving December datain January.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
DatabaseService
4–24
Timesaver To avoid typing a table name in a query, open a browser connection to the
database index ( ht t p: / / <host >/ appdb/ i ndex) and copy the table name to the
clipboard. Do this by dragging backwards (right-to-left) over the table’s
hyperlink, until it is completely highlighted. Then press CNTRL-C to copy. It can
now be pasted (CNTRL-V) inside your SQL query, as needed.
DatabaseBrowservs. Web Browser
For the most part, everything in the application database that can be accessed using
the JDE DatabaseBrowser can also be accessed using a Web browser connection
(including, as previously noted, with an improved width of view).
However, the following features are available only in the JDE’s DatabaseBrowser:
• List Filters
• Summary Information
List Filters: You can list tables filtered on schema type (ALERT, ARCHIVE,
EVENT) and/or table string (Figure 4-4). By default, both the schemaFilter and
tableFilter are “wild cards” (*).
For example, with schemaFilter left at “*” and tableFilter changed to *ahu*, when
you press ENTER the list of tables updates to include only archives with “AHU”
(note this is not case sensitive). On the other hand, in the browser-accessible list, all
tables are alphabetically listed using the URL ht t p: / / <st at i on>/ appdb/ i ndex.
delete from archive.demoR2_services_auditlog wheretstamp<'2001-01-01 00:00:00'
Deletes all audit log records withtimestamps for years prior to 2001.
Note: Be careful when using the deletecommand. There is no undo.
command delete
selection tstamp
operator <
delete from alert.unackedalerts wheretstamp>'1980-01-01 00:00:00'
Deletes all unacknowledged alerts(currently pending acknowledgment).
Note: This would be used only to “freeup” the alarm console before jobturnover. However, it does not write anacknowledgment timestamp to alertscollected in the alert history.
command delete
selection tstamp
operator >
drop tablearchive.demoR2_sim_logicscreens_energymgmt_oaolog
Deletes the entire table (archive) forthe named table, in this case, for the
AnalogLog object OAOLog.
Note: Be careful when using the droptable command. There is no undo.
command drop table
selection (none)
operator (none)
Table 4-7 SQL query examples with descriptions. (continued)
Query Entry Example What It Does Command, Selections,
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
ErrorLogService
4–28
Properties
ErrorLogService NotesEach log record created by the ErrorLogService has the following fields:
• tstamp —Timestamp of the recorded error or event, for example,
“10:05:20 4-Sep-2001 EDT.”
• severity —Can be one of the following:– MESSAGE (informational) Examples include a message identifying
station startup or a new service added.
– WARNING (low) An example is from a “Cannot send packet” message.
– ERROR (high) Examples include “Cannot send mail” or “Cannot load
Ethernet Packet Driver.”
Table 4-8 ErrorLogService proper ties.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType,
statusFlags,description
See Table 4-1 on page 4-5 for information on
these properties common to all service objects.
— — description default
Logs configurationand softwareerrors.
lastArchiveTimestamp Read Only: Shows a date/timestamp for whenthe last archive occurred. Shows “null” if therehave been no archives or if theclearLastArchive command was given.
validtimestamp
or null
null
C o n
f i g
bufferSize Read-Write: Defines the number of loggedchanges that can reside locally (in RAM).
An allocation of “resource counts” (RAM) is setaside based upon the entered number.
1 to 1000 25
stopWhenFull Read-Write: If set to True, logging stops whenthe number of logged changes equals the
configured bufferSize. If set to False (thedefault), the log buffer rotates—this means thatthe oldest recorded change is overwritten aseach new change continues to be recorded.
False, True False
archiveSetup Read-Write: Defines the events that cause theobject’s log data to be archived. Flags can beset in any combination.
• nearFull —Archive occurs at 80% of the logbuffer size.
• daily —Archive occurs daily, at the timeconfigured in the LogService.
• polled —Applies only if another (remote)Niagara station is configured with the Polled
Archive (multisite) service.
selection ofany or all:
nearFull,daily,polled
daily
V i s u a
lposition Read-Write: See “position,” page 4-5. — -2147483648
x 0
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For more details,see “securityGroups,” page 4-5
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
ErrorLogService
4–29
• source —Swid of the object involved in the error or event (most typically a
service object). For example: “/demoR2/Services/MailService.”
• message —Description of the error or event, for example, “Cannot send mail”,
“Cannot send packet”, or “Station started successfully. (HTTP port=80).”
• stackTrace —Populated only if a WARNING or ERROR severity, this often
provides a “reason” for the error, and identifies (in some detail) the failed Java process. For example:
j avax. mai l . SendFai l edExcept i on: No r eci pi ent addr esses at j avax/ mai l / Transport . send0 ( Transpor t . j ava: 96) at j avax/ mai l / Transport . send ( Tr ansport . j ava: 71) att r i di um/ ser vi ces/ Mai l Ser vi ce. sendI mpl ( Mai l Ser vi ce. j ava: 230) att ri di um/ ser vi ces/ Mai l Ser vi ce
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
LogService
4–31
PropertiesTable 4-9 LogService proper ties.
Tab Property Name Description Valid Values Default Notes
S t a
t u s objectType,
statusFlags,description
SeeTable 4-1 on page 4-5 for information on
these properties common to all service objects.
— — description default
Provides logsupport.
C o n
f i g
logUrlPrefix Read Only: String used within URLs for browseraccess to log buffered data.For example:http:/<host>/log/index
log log
archiveUrlPrefix Read Only: String used within URLs for browseraccess to archived log data.For example:http:/<host>/archive/index
archive archive Applies only if thestation has theDatabaseService.
archiveMode Read-Write: Determines whether logs arearchived, and if so, where.
• A Web Supervisor station should always be
set to archive_local.• JACE controllers are typically set to
archive_remote (unless a JACE-NP with theDatabaseService).
archive_disabled
archive_local
archive_remote
Note: Changerequires astation restart.
archive_disabled
If archive_disabled,the LogService doesnot archive, nor is
“polled archiving”(from a pollingstation with thePollArchiveService)performed.
archiveAddress Read-Write: Specifies the station with theDatabaseService where logs are archived.Uses the station’s AddressBook setup.The property has two parts:
• Supervisor checkbox—Check i f archivingremotely to a station already defined as theSupervisor in the AddressBook.
• station drop-down list—Lists stationsavailable when archiving remotely. These
stations are defined as peers or subordinatesin the AddressBook. A “none” selection isalso included.
Supervisor,
none
archiveTime Read-Write: Specifies the archive time for alllogs configured to archive daily.
Uses a 24-hour format (Hr:Min) from 00:00(midnight) to 23:59 (11:59 PM).
00:00to
23:59
02:00
lastDailyArchive Read Only: Shows a date/timestamp for the lastdaily archive.
valid timestampor null (none)
null
minRetryTime Read-Write: Specifies the minimum time, inminutes, for the “retry window” following a failedarchive. A retry is made within this window.
1 to n 5(minutes)
Archives may faildue to connectionproblems to thearchive host. The
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
MailService
4–36
MailService NotesThe MailService is used by MailRecipient objects linked to NotificationClass objects
(both reside in the NotificationService container).
The following notes apply to the MailService:
• Outbox Notes
• Authentication Notes
• Localization Notes
C
o n
f i g ,
c o n
t .
smtpHost Read-Write: Specifies the SMTP host to use tosend e-mail notifications.
Starting in r2.301.429.v1 and later, you can also
specify a TCP port different than 25 (default):<hostname>:<port> for example:
ourMailSrv:40
Note:A station restart is required afterentering (changing) the SMTP host name.
valid hostnameof SMTP server(and optionally)
TCP port if not 25
- The SMTP host isread upon stationstartup.
If station is runningin a JACE-NX,review/adjust itssecurity policy asneeded if changingdefault port or usingDNS.
fromAddress Read-Write: Specifies the “from” address usedin sent e-mail notifications. An e-mail accounton the SMTP server is typically required usingthis same address.
Often, an e-mail account using the station’sname is created and used.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
MailService
4–37
Outbox Notes The outbox of the MailService collects failed e-mail notifications (ones that were not
successfully sent). The service periodically attempts to resend the failed notifications
in the outbox, based upon a time specified in the outboxRetryTime property.
The outbox exists as a file residing under the station folder, using this file path:
niagara\<release>\stations\<stationName>\mail\outbox.mbxThe outbox.mbx file is automatically created (or appended to) by the MailService,
upon demand. An outbox.mbx file of 0 bytes indicates there are no failed (pending)
e-mail notifications—any other file size indicates pending e-mails exist. The contents
of the outbox.mbx is all failed e-mails, in plain text format.
The MailService command “deleteOutbox” deletes the outbox.mbx file. If necessary,
the service automatically creates a new outbox.mbx file.
Note (Setup) If the SMTP host is incorrectly identified in the smtpHost property,
notifications routed via MailRecipients are stored in the outbox (outbox.mbx file).
These e-mails will be successfully sent after the smtpHost property is correctlymodified, and the station is restarted . If you do not want them sent, issue the
“deleteOutbox” command to the MailService before restarting the station.
AuthenticationNotes
If the target SMTP mail server is configured to require authentication for send
requests, you must configure the service’s config properties username and password
with the appropriate entries. Contact the mail server’s system administrator for this
information.
In addition, the Niagara host’s system.properties file must have the following line
present:
mail.smtp.auth=true
For information on accessing Niagara properties files, refer to “Host > Edit File,”
page 1-28.
LocalizationNotes
In r2.3.5 and later, the MailService uses UTF-8 encoding (by default) to support the
sending of localized alarm messages. If necessary, this feature can be disabled so that
straight ASCII encoding is used instead. This might be necessary if e-mail clients
cannot handle UTF-8 encoding properly.
Do this by adding a line in the Niagara host’s system.properties file as follows:
mail.useUTF=false
If this line is missing or has a value of “true,” the default UTF-8 encoding is used.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
NotificationService
4–39
NotificationService NotesBy default, the NotificationService in a newly-created station contains a single child
NotificationClass object, with a notification class number of zero (0). Typically,
additional child objects are added and linked in the NotificationService workspace.
Note You can place NotificationClass objects and recipient objects in containers under the
NotificationService, and not just directly in the NotificationService.
For more details on the various notification child objects (classes and recipients), please refer to Chapter 9, “Notification Objects.”
C o n
f i g
alarmArchiveAddress Read-Write: Specifies the station with theDatabaseService (and alarm console)where alarms and alerts are archived. Uses
the station’s AddressBook setup.The property has two parts:
• Supervisor checkbox—Check if archivingremotely to a station already defined asthe Supervisor in the AddressBook.
• station drop-down list—Lists stationsavailable when archiving remotely. Thesestations are defined as peers orsubordinates in the AddressBook. A“none” selection is also included.
See descrip. Supervisor,
none
archiveMode Read-Write: Specifies how notification andassociated archiving occurs. The default“disable” selection prevents notificationfrom occuring.
The “archive_local” selection is valid only ifthe station is running the DatabaseService(typically, this is the Web Supervisor).
archive_disable
archive_local
archive_remote
archive_local_no _SQL
archive_disable
A station in a typicalJACE controllerrequires thearchive_remoteselection. The“local_no_SQL” isfor a standaloneJACE-4/5 only.
E n g
i n e e r i n g debug Read-Write: When set to True, provides
detailed information in the station’sStandard Output relating to routing andacknowledgment of alarms and events.
False, True False
V i s u a
lposition Read-Write: See “position,” page 4-5. — -2147483648
x 0
S e
c u r i t y securityGroups Read-Write: Shows the security groups to
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType,statusFlags,description
See Table 4-1 on page 4-5 for information onthese properties common to all service objects.
— — description default
Service to supportmulti-site logcollection.
lowPriorityQueueSize
Read Only: Number of queued group archivesinitiated by regular frequency.
0 to n 0 Typically, each is 0or a low number. See“Priority Queues,” page 4-43.
highPriorityQueueSize
Read Only: Number of queued group archivesinitiated by “pollGroupn” commands.
0 to n 0
C o n
f i g
group0enabled,frequency
through
group7enabled,frequency
Read-Write: (Separately configurable for eachpoll archive group.) Specifies whether that pollarchive group is enabled for poll archiving, andif so, what regular, repeating frequency ofarchive should occur (in hourly increments).
• If False, poll archiving does not occur.
• If True but frequency is 0, poll archivingoccurs only upon a pollGroupTrigger pulse ora pollGroup command.
False, True
0 to n hours (integer)
False,
0
lowPriorityQueueCapacity
Read-Write: Specifies group archive queuemaximum size, for low priority (frequencyinitiated) group archives.
10 to 60 50 Values much overdefaults (50) shouldnot be necessary.
See “PriorityQueues,” page 4-43.
highPriorityQueueCapacity
Read-Write: Specifies group archive queuemaximum size, for high priority (commandinitiated) group archives.
10 to 60 50
V i s u a
lposition Read-Write: See “position,” page 4-5. — 10 x 10
Tab Property Name Description Valid Values Default Notes
Figure 4-5 Polled archive (Master Web Supervisor) configuration.
The PollArchiveServiceuses a “pull” approach.
The Master Web Supervisorhas the PollArchiveService,and is the “poller.”
All the JACE controllersand/or Web Supervisorsshown are entered in theMaster Web Supervisor’saddressBook, and areassigned to a particular pollarchive group (each may beassigned to the same group
or a unique group, asneeded).
Web Supervisors orJACE-NPs or NXs with theDatabaseService eachhave their own SQLapplication database(appdb). When thesestations are polled, newdata from its log archives is“pulled” to the Master WebSupervisor.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
PollArchiveService
4–43
Configuration Configuration for the PollArchiveService is done in the AddressBook of the Station
object for the Master Web Supervisor. Each target station must be identified and
assigned to a particular poll archive group (0 to 7). This is done using the Poll
Archive Group setting, which by default is “archive_disabled.” Each group 0 to 7
maps to a groupn configuration in the PollArchiveService's property sheet.
Once you have mapped a Station to archive groups in the AddressBook, you are
ready to configure the PollArchiveService itself. There are three mechanisms to poll
a group. First is a manual command on the PollArchiveService itself. Secondly you
may enable the group, and setup a poll frequency in hours (zero is a disable). The
time begins when the station is started. For instance, a group with a frequency of 2
would poll for the first time 2 hours after the station was started, then 2 hours later,
and so on. The third mechanism to enable the polling of a group is to use a trigger
input. This allows polling based on Calendars, Schedules, DateTimeTriggers, or
custom Program objects.
Additional configuration requires the station running the PollArchiveService to have
the DatabaseService, and the local LogService set to archive_local.
Operation The actual poll process is as follows. Once a group is polled, the service looks in the
AddressBook to find all the stations configured in that group. For each station it
attempts to open a connection and get the list of logs to archive and the timestamp of
their latest record. It compares this list against it own local SQL database, to see what
records are missing. If any records are missing, then a request is made back to the
station to upload all the missing records.
When the PollArchiveService requests the list of logs to archive there are three
possible outcomes, dependent on the source station’s LogService archiveMode
property. If this property is set to archive_disable, then no logs are archived during
the poll process. If this property is set to archive_remote, then the list is generated
from the in-memory object database using only logs with the polled flag set in theirarchiveSetup. If the archiveMode is set to archive_local (polling of a server), then the
list is generated from all the tables located in the archive schema of the application
database (the standard location for LogService archival).
Priority Queues
In r2.3.4 and later, “low and “high” priority queues were added, including associated
properties (status and config), plus “clear” commands. The queues provide orderly
execution of pending archives of poll groups—note that in some cases, the poll
archive for a single group may take up to an hour to complete.
• Low priority queue—For all regularly scheduled poll group archives, meaning
each initiated at intervals defined for that groupn’s frequency, in hours.
• High priority queue—For poll group archives initiated by a pollGroupn
command (see “Commands,” page 4-41) given to the PollArchiveService.
In most cases, default queue sizes (50) are recommended. In the case where you
notice status property lowPriorityQueueSize climbing much above zero (0), this may
indicate communications problems to target stations, or groups that are configured
with too low a frequency value (in hours). In the latter case, adjust the groupn’s
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
TimeSyncService
4–45
TimeSyncService NotesThe TimeSyncService is typically used to keep all Niagara stations for a job
synchronized to the same exact time. At the time of this reference, a URL listing ITS
(Internet Time Service) servers used by NIST (USA National Institute of Standards
and Technology) is as follows:
ht t p: / / www. boul der . ni st . gov/ t i mef r eq/ ser vi ce/ t i me- ser ver s. ht ml
Other public ITS servers are available on a world-wide basis.
C o n
f i g
serverEnabled Read-Write: Must be True for serveroperation. If False, client (time protocol)requests to the station are not answered.
False, True True
serverPort Read-Write: Specifies the application portused by the server operation.
valid portnumber
37 Port 37 is the “wellknown” Time port.
clientEnabled Read-Write: Must be True for cl ientoperation. If False, polling of time serversstops, station time is not adjusted, and statusproperties serverReportn show “Disabled.”
False, True True
clientPollFrequency Read-Write: Specifies, in minutes, thefrequency of the polling of the namedtimeProtocolServers.
1 to n 15
clientResetTolerance Read-Write: Specifies, in seconds, themaximum ± time difference among multipleservers before their times are averaged,(else an ERROR, then avg. discarded), and
then the minimum ± time difference requiredbetween this “filtered” average and station’stime before station’s time is resynchronized.
1 to n 30 With mulitple timeservers, a “filtered”average value isevaluated against
the station’s time.This “filter” is newstarting in r2.3.4.
timeProtocolServer1,
timeProtocolServer2,
timeProtocolServer3
Note: If not using theSupervisor choice,you should specify
all three (different) valid time servers tobest enable “filtering.”
Read-Write: Each property specifies a TimeServer to use for synchronization (as client).
If the station’s AddressBook is configurednaming another station as the Supervisor,the Supervisor checkbox is a valid option.
When entering server names, IP addressesare typically better than qualified hostnames.For example, 132.163.4.101 instead oftime-a.timefreq.bldrdoc.gov (NIST, Boulder,Colorado).
(each)
Supervisor(if configured) or
IP address or valid fullyqualified
hostname
— If the Supervisorcheckbox reads“not configured,” itis not a validselection.
E n g
i n e e r i n g
debug Read-Write: When set to True, providesdetailed information in the station’s StandardOutput relating to the connection to (andcommunication messages with) thedesignated Time Protocol server(s).
Includes roundtrip and oneway times, serverand station times, and delta time (in ms).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
UiEngineService
4–46
UiEngineServiceQuick reference for all properties: Table A-76
abbrev: (none); UiEngineService
The UiEngineService executes all user
interface objects (Gx objects) in the station. Itis mandatory for any Niagara station.
The UiEngineService is similar to the
ControlEngineService, but has a more limited
role. A cycleTime configuration property
allows setting the target execution time. The
default cycleTime (500) ms is often adjusted
upwards with no adverse effect.
Parent Dependencies: ServiceContainer
Only one UiEngineService per station.
Resource Count Range: 40 to 47
Trigger Properties None.
CommandsUsers with “Command, Std” privileges have the following available command:
• resetStatistics —Clears (zeroes) accumulated statistics found on the Status tab
of the property sheet. This includes execution cycle counts, overruns, average
execution times. Also cleared are the accumulated lateStarts.
Properties
Inputs
Object Shape
Outputs
(none) (none)
Input / Output Property Reference for UiEngineService Object(only input and output types, see Table 4-14 for all properties)
Type Label Property Name Data Species
input — — —
output — — —
(none)
Table 4-14 UiEngineService properties.
Tab Property Name Description Valid Values Default Notes
S
t a t u s
objectType,statusFlags,description
See Table 4-1 on page 4-5 for information onthese properties common to all serviceobjects.
— — description default:
Execution enginefor user interfaceobjects.
averageExecuteTime Read Only: Shows the average executiontime, in milliseconds, for a complete cycle(totalExecuteTime/executionCycles).
float value(ms)
—
totalExecuteTime Read Only: Shows the total execution time,in milliseconds, since the last station startup.
integer (ms)
—
executionCycles Read Only: The accumulated number of
execution cycles since last station startup.
integer —
overruns Read Only: The total number of overrunscounted. An overrun occurs when the actualcycle time exceeds its target time, as definedby the cycleTime property (on Config tab).
integer —
objectCount Read Only: The total number of objectsexecuted by the UiEngineService. Thisincludes all Gx objects in the station (not justthose in GxPage containers).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
WebUiService
4–48
WebUiServiceQuick reference for all properties: Table A-78
abbrev: (none); WebUiService
The WebUiService (Web User Interface) is
used to provide a set of views to certain Niagara objects using standard Web
browsers. An optional Niagara service, it is
included in the following products:
• Web Supervisor
• JACE-NP-2
• JACE-50x-UI
• JACE-51x-UI
• JACE-401-UI
The WebUiService includes a suite of
servlets that use HTML and Java applets to provide a Web browser interface. Some
servlets reference HTML files (templates),
which are used to frame applets. You can
customize and save HTML templates, if
needed. Configuration properties of the
WebUiService allow you to globally
reference various template files.
Parent Dependencies ServiceContainer. Only one WebUiService per station.
Resource Count Range: 25 to 33
Trigger Properties None.
Commands None.
Properties
Inputs
Object Shape
Outputs
(none) (none)
Input / Output Property Reference for WebUiService Object(only input and output types, see Table 4-15 for all properties)
Type Label Property Name Data Species
input — — —
output — — —
(none)
Table 4-15 WebUiService properties.
Tab Property Name Description Valid Values Default Notes
S t a t u s objectType,
statusFlags,description
See Table 4-1 on page 4-5 for informationon these properties common to all serviceobjects.
— — description default:
Web browser
interface support.
C o n
f i g
defaultTemplateUrl Read-Write: References a swid file path toone of the 4 “global” HTML templates.
This default template is used as the“backup” template. It frames a WebUi appletin case one of the other 3 “global” templateproperties (GxPage, Calendar, Schedule) isblank, and a local template is not specified.
Default (new station) value:/tridium/services/defaultTemplate.html
A valid swidreferencing anHTML file thatcontains theappropriateserver tags.
See descrip. The default (newstation) value pointsto an HTML filecontained in thetridium JAR file.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 4 Services
WebUiService
4–49
WebUiService Notes
The WebUiService includes the following servlets:
• Gx —Browser access to Niagara graphics (GxPages).
• Chart —Browser access to Log charting (LogChart and LogSelector views).
• Schedule: Browser access to Schedule and Calendar object views.
• Alarm: Browser access for viewing and acknowledging alarms.
• Status: Browser access to a text table “snapshot” of current values and
statuses. A “Status Query” form (with wildcard capability) supports searches.
• Text —Supports a custom external HTTP application, responding with text
output to specific swid “object.property” requests.
Refer to For detailed information on using the WebUiService, please refer to the Niagara Web
Solutions Guide.
gxPageTemplateUrl Read-Write: References a URL filepath toan HTML template used to globally displayGxPages (graphics). It is used whenever a
local override template (property availablefor each GxPage) is not referenced.
Default (new station) value:(none—blank)
A valid swidreferencing anHTML file with
the appropriateserver tags.
See descrip. If left blank, thedefaultTemplateUrlnamed HTML file is
used instead.
calendarTemplateUrl Read-Write: References a URL filepath toan HTML template used to globally displayCalendar editor views. It is used whenever alocal override template (property availablefor each Calendar object) is not referenced.
Default (new station) value:(none—blank)
A valid swidreferencing anHTML file withthe appropriate
server tags.
See descrip. If left blank, thedefaultTemplateUrlnamed HTML file isused instead.
scheduleTemplateUrl Read-Write: References a URL filepath toan HTML template used to globally display
Schedule editor views. It is used whenevera local override template (a property foreach Schedule object) is not referenced.
Default (new station) value:(none—blank)
A valid swidreferencing an
HTML file withthe appropriateserver tags.
See descrip. If left blank, thedefaultTemplateUrl
named HTML file isused instead.
V i s u a
lposition Read-Write: See “position,” page 4-5. — -2147483648
x 0
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For moredetails, see “securityGroups,” page 4-5
General,
7 others
General
Table 4-15 WebUiService properties. (continued)
Tab Property Name Description Valid Values Default Notes
Niagara Standard Programming Reference Revised: April 20, 20045–5
Common Control Object ThingsControl objects have properties common to all Niagara object types, such as the
status properties “objectType” and “description”. Other common properties are for
object execution and security (user access). A JDE “dump” command also exists.
Rather than explaining for each object type, these common properties are covered in
this section. Also, many object type have a “units” property, for display purposes.
A listing of all possible units selections is given in “About Units,” page 5-6.
Several object types are alarm-capable, and so have additional properties related to
alarming. See the following the “Event-Type Objects” section on page 5-11.
Trigger Properties
Most control objects have at least one “trigger-type” property. While viewing
property sheets in the JDE, you do not see trigger-type properties listed. This is
because unlike other types of properties, there is no associated value, state, or string(only the possibility of a transient “pulse,” likely to go unnoticed anyway).
In this chapter, the description for each control object type includes a “Trigger
Properties” section that lists and describes the object’s available trigger properties.
executeTrigger—Except for the Command object, every control object has a
linkable input property, executeTrigger. This input is rarely used . The intention of
this input is to have the object execute (once) each time a trigger pulse is received.
In this case, you would set the object’s configuration property execution Parameters,
“freq” field from the default setting of “normal” to “on_trigger”. Otherwise, the
object would continue to execute during each ongoing cycle of the control engine
(ControlEngineService), and it would ignore any received trigger pulses.
This is mentioned only because the executeTrigger input is shown for each object
type in the “All Inputs / Outputs” figure. However, be aware that for most control
objects, this input has limited or no application.
Debug Command
If you have “Command, Admin” privileges, this menu bar command is available in
the JDE for any control object (you must have the object’s property sheet displayed):
Commands > dump —Sends data about the object to the Standard Output window,
including the objects swid, handle, name, parent, properties and values, and links.
Note Typically, the dump command is used only during development. The JDE right-click
command Go > Report is a more flexible utility that provides similar information.
Various control object types have other available commands, both right-click types
(which are available when accessing the station using a browser), and JDE accessible
commands. Each object’s available commands are listed in subsequent descriptions.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
Common Control Object Things
5–8
Common Control Object Properties
Table 5-3 lists common properties organized in the property sheet tab in which you
can find them. In the case where some property variation exists for a particular type
of object, that difference is noted in the property table for that object type.
Table 5-3 Common propert ies for al l control objects.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType Read Only: The control object type. Bydefault, a newly added object uses thisstring in its name (until renamed).
The full string for the object type is shown,for example, AnalogInput or Comparison.
See description reflectsobject type
For most object types, astandard abbreviation forthat type appears insidethe object’s shape (nearthe top).
This abbreviation isnoted in the individualdescriptions for eachcontrol object.
statusFlags Read Only: Current state of the object’s
status flags, which reflect the general“health” of the object. Depending onconditions, status flags can be set incombinations. A dominant flag sets theobject’s color to something other than gray(the same color appears at its outputs).
A “normal” state (no flags set) is where thestatus flags value is “ok”, and the object’scolor is gray. Outputs appear normally.
Briefly, status flag values mean:
• inAlarm—An alarm state currently exists.The object’s shape and outputs are red.Another property, alarmState, is True.
• fault—A fault state occurs when anotherproperty, reliability, has any value except “no_fault_detected.” The object’s shapeand outputs are orange.
• overridden—The object’s propertiespresentValue and reliability are no longertracking changes.
• outOfService—The object’s propertyoutOfService has been set to True.The object’s shape and outputs are cyan.
• unackedAlarm—An alarm has occurredthat is still pending acknowledgment.If the inAlarm flag is still set, the objectoutputs are red and also flashing.
• down—The station (or integration device)is down or offline. The object ‘s shape andoutputs are yellow.
where values
appear inbraces :
inAlarmfault
overriddenoutOfService
unackedAlarmdown
ok Not al l object types can
alarm, meaning thatsome objects havestatus flags that arenever set.
The total set of 6 statusflags is a superset of theBACnetStatusFlag type,adding these 2 flags tothe 4 BACnet types:
• unackedAlarm
• down
description Read-Write: Permits a user-defined textdescriptor for describing the object. Anyprintable characters, including spaces andmixed case characters, are allowed.
See description — Not available for aCommand object.
Niagara Standard Programming Reference Revised: April 20, 20045–9
C
o n
f i g
executionParameters
Read-Write: Defines the frequency andorder for the object as it is executed by thestation’s ControlEngineService.
• freq (frequency)—Specifies how often theobject is executed. Typically, the defaultfrequency (normal) is acceptable.
• order —Specifies the order of execution ineach cycle. On each cycle of the controlengine, objects specified as inputs areprocessed first, then processors next, andlastly the outputs. By default, the defaultorder setting reflects the object’s type. Forexample, input-type objects (AI, BI, MSI)will have an order value of “input,”processing type objects (Loop, Logic,etc.) will have an order value of“processor,” and so forth.
freq:
never slower
normalfaster fastest
minutelyon_trigger
order:
inputprocessor
output
freq:normal
order:
<seedescrip>
This property is notavailable (nor applies to)a Command object.
Usually, default valuesare recommended.
Frequency selectionsare exclusive. Forexample, if on_trigger isselected, the object willexecute only if the inputexecuteTrigger is linkedand a trigger pulse isreceived on that input.
For related details, seeControlEngineService and its Config property“executionFrequencies”.
foreignAddress Read-Write: BACnet usage only. Exposesthe Niagara object as a BACnet object.
Note: Currently, this property has apractical application for these object types:AnalogInput (AI), AnalogOutput (AO),Binary Input (BI), BinaryOutput (BO),MultistateInput (MSI), MultistateOutput(MSO), Calendar, Schedule, and all NdioObjects.
For these object types, a valid value is anyinteger from 0 to 4194302 (the maximumBACnet Instance Number for any object).
SeeDescription
If assigned, thisproperty valuemust be unique in the station,
within the
object’s type
(AI, AO, BI, BO,MSI, MSO,Calendar,
Schedule, etc.)
-1
(not used)
Not shown for aCommand object.
Before using, theBACnet service must beinstalled and configuredin the station.
In the case of Ndioobjects, the station mustalso have theBACxNdioService. Ndioobjects count as eitherAI, AO, BI, or BOobjects—refer to
Table 10-2on page 10-8.membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
V i s u a
l
position Read-Write: The x-y coordinates for theobject’s position on the JDE Workspace.
Coordinate values are in pixels, and arerelative to the upper-left corner of theWorkspace and the upper-left corner of theobject shape (including its input area).
An object with a position of “0,0” is in the topleft corner of the Workspace.
Some positivex, y value less than the parent
(container)object’s “size”property value.
Near themousepointer
when theobject is
firstcreated.
Typically, you don’tmanually enter positionvalues, but use themouse to drag the objectas needed on the JDEWorkspace.
However, if needed, youcan enter values directlyto “tweak” an object’sposition.
Table 5-3 Common properties for all control objects. (continued)
Tab Property Name Description Valid Values Default Notes
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
Common Control Object Things
5–10
E n g
i n e e r i n g
minExecuteTime Read-Write: Can show the object’sminimum execution time, in mil liseconds.
Shows MAX_VALUE if “profileNodes” in the
ControlEngineService was not previouslyset (since the last station start).
integer, 0 to n Seedescrip.
Providing that theControlEngineServicewas set to
“profileNodes”, theseproperties show theobject’s executionstatistics. Typically, youdo not leave theControlEngineServiceconfigured this wayexcept for brief periodsto collect these values.
This properties are notavailable (nor apply to) aCommand object.
maxExecuteTime Read Only: Can show the object’smaximum execution time, in milliseconds.
Shows MIN_VALUE if “profileNodes” in theControlEngineService was not previouslyset (since the last station start).
integer, 0 to n Seedescrip.
averageExecuteTime
Read Only: Can show the object’s averageexecution time, in seconds.
Shows 0.0 if “profileNodes” in theControlEngineService was not previouslyset (since the last station start).
valid float Seedescrip.
userData Read-Write: Stores a user entered string.Can be used by servlets and the API forconfiguration information.
Any desiredtext string forservlet/API
usage.
<blank>
S e c u r i t y
securityGroups Read-Write: Shows the security groups towhich the object is assigned. A user musthave the appropriate privileges in at leastone security group to view and modifyproperties and issue commands.
Refer to the “Security Tab” section onpage 1-20 (Station object UserAdmin topic)for more details on how securityGroupssettings apply.
Any mix ofthese types:
•General
•HVAC
•Security
•Life Safety
•Group 4
•Group 5
•Group 6
•Group 7
General Also refer to the “AboutSecurity” section onpage 1-21.
Table 5-3 Common properties for all control objects. (continued)
Tab Property Name Description Valid Values Default Notes
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
Common Control Object Things
5–12
StatusProperties
Each event-type object includes standard Niagara object status properties such as
objectType and description, plus a collection of BACnet-derived properties, listed in
Table 5-4.
Table 5-4 Status properties for standard event-type objects (AI, AO, BI, BO, Loop, MSI, MSO).
Tab Property Name Description Valid Values Default Notes
S t a t u s
eventState Read Only: Shows the object’s currentalarm state, which is one shown at right.
normalfault
offnormalhigh_limitlow_limit
normal offnormal applies to BI,BO, MSI, and MSOobjects. The high_limitand low_limit statesapply to AI, AO andLoop objects.
reliability Read-Write: Required for BACnet usage.Indicates whether the presentValue oroperation of the object is “reliable,” and ifnot, why. Selections include:
outOfService Read-Write: Allows setting the object as outof service (when set to True).
This allows logic testing of error conditions.While set to outOfService, you can thenselect a value for the reliability property. Forexample, you can set outOfService to Trueand reliability to ”unreliable_other,” whichwill force a fault condition.
False,True
False For input-type objects(AI, BI, MSI), you canset outOfService toTrue and then write topresentValue. Thisvalue appears at theoutput while the objectis outOfService.
ackedTransitions Read Only: Flags, that when cleared,indicate that an unacknowledged eventtransition has occurred. Separate for eventtypes: to-offnomal, to-fault, to-normal.
set or cleared set Relates to the setup ofthe associatedNotificationClass object. See also the
notificationClass property description.
toOffnormal,
toFault,
toNormal
Read Only: For event transitions of type:to-offnormal (alarm), to-fault, to-normal.Each property has three fields:
• eventTime—Date and timestamp for thelast alarm event.
• ackTime—Date and timestamp for the lastacknowledgment.
• count—Total event count since the lastacknowledgment. Resets to 0 uponreceipt of acknowledgment.
valid date andtimestamp foreventTime,
ackTime, or “null”if the event hasnot occurred.
0 to <n>for any count
“null” fordate and
timestamp
0 for count
If an event-type is not set in the associatedNotificationClassobject to requireacknowledgment, theackTime value remains“null” and the countvalue never resets to 0.
presentValue Read Only or Read Write: Required for
BACnet. In normal usage, reflects theobject’s output.
For input-type objects (AI, BI, MSI), thisproperty is writable. When such an object isset to outOfService, an enteredpresentValue appears at the statusOutput.
Setting outOfService back to False clearsany previously entered presentValue.
Niagara Standard Programming Reference Revised: April 20, 20045–13
Alarm SetupProperties
Only event-type control objects have Alarm Setup properties. Many of these
properties define how an alarm condition is determined, using settings such as alarm
limits and deadbands. These properties can vary by object type, and so are covered
individually in the description for each object type.
In addition to those properties, each event-type object has the following common
alarm setup properties, which work in a consistent manner among object types.
Table 5-5 Alarm Setup properties for standard event-type objects (AI, AO, BI, BO, Loop, MSI, MSO).
Tab Property Name Description Valid Values Default Notes
A l a r m
S e
t u p
timeDelay Read-Write: Minimum time period inHr:Min:Sec, that an alarm (off-normal)condition must exist before the objectalarms (statusFlag “inAlarm” becomes setand the object and its outputs turn red).
The delay timer begins when an alarmcondition, as configured, occurs. If the alarmcondition clears before the delay timer
expires, the object does not alarm and thedelay timer is reset.
any practicalvalue in
Hr:Min:Sec
Typically, this issome number
of seconds andor minutes
00:00:00(no delay)
This timeDelay periodalso applies to anobject returning“to-normal” from analarm state.
However, thetimeDelay period doesnot apply to transitions
to (or from) fault conditions.
notificationClass Read-Write: The assigned notification classnumber, used in routing alarms.
A NotificationClass object using the same
number must exist under the
NotificationService (container) object.
Configuration of this NotificationClassobject determines what type of events(to-offnormal, to-fault, to-normal) require
acknowledgment (ack). If an event type,such as “to-normal”, does not require anack, then it is always set (checked) in this
object’s status property, ackedTransitions.Such an event transition will never clear thatfield in ackedTransitions, meaning it will notset the statusFlag “unackedAlarm”.
An alarm requiring acknowledgment resultsin a flashing red statusOutput (see Note).
0 to 8388607 0 NotificationClassobjects reside in orunder theNotificationServicescontainer (under thestation’s services).
If the object’seventEnable flag is setfor “to-offnormal,”
AND the associatedNotificationClassobject is configured torequire an ack forto-offnormal, theobject’s statusOutputflashes red during anunacknowledgedalarm.
eventEnable Read-Write: Flags that define the types ofevent (alarm) transitions for this object thatare sent to the alarm console.
Selection ”to-offnormal” applies to anyalarm state, e.g. “high-limit” or ”low-limit” foran AI, AO, or Loop object, or “offnormal” fora BI, BO, MSI, or MSO object.
selection of anyor all:
to-offnormalto-fault
to-normal
(noneselected)
notifyType Read-Write: Required for BACnetcompliance. In a Niagara system, it makesno difference which type is selected. (Eitherselection functions the same in the Niagaraalarming subsystem.)
However, if exposing the object as BACnet,and notifyType is set to event (not alarm), anactive unacknowledged alarm is not reported by the station’s BACnet service,GetAlarmSummary.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
Common Control Object Things
5–14
Alarm Setup Propert ies Notes
Most alarm setup properties have direct BACnet heritage. However, two of these
properties are unique to Niagara objects, namely:
• inhibitTime —This works in conjunction with the object’s statusInhibit input
(a booleanStatusType property), and applies only when this input is linked.
Note that the alarm inhibit mechanism operates independently from
“delayTime,” which is a BACnet-type property.
• eventTriggerEnable —This works in conjunction with the object’s
eventTrigger output (a triggerType property). Unlike eventEnable, which
relates to alarm notification, the eventTriggerEnable flags determine which
types of event transitions cause the object’s eventTrigger output to fire.
A l a r m
S e
t u p , c o n
t .
inhibitTime Read-Write: Duration (Hr:Min:Sec) of thealarm inhibit timer, which applies only if theobject’s inputs statusInhibit is linked.
The purpose is to prevent nuisance alarmson equipment startup and shutdown.
Note: For further details specific to anobject type, see the inhibitTime propertydescription for that object.
any practicalvalue in
Hr:Min:Sec
00:00:00(no inhibit)
A minimum value of 1second (00:00:01) isrecommended
whenever thestatusInhibit is linked.
eventTriggerEnable Read-Write: Flags that specify the types ofevent (alarm) transitions, as they occur, thatfire the object’s eventTrigger output.
Selection ”to-offnormal” applies to anyalarm state, e.g. “high-limit” or ”low-limit” foran AI, AO, or Loop object, or “offnormal” fora BI, BO, MSI, or MSO object.
selection of anyor all:
to-offnormalto-fault
to-normal
(noneselected)
These flags operateindependently of theeventEnable flags.
alarmText Read-Write: Text descriptor included in ato-offnormal or to-fault alarm for this object,as sent to the alarm console. Appears in themessageText field of the alarm record.
This text is not included in a return to-normalevent sent to the alarm console.
If left at the default hyphen (-), the object’scontainer object (Container, Bundle,Composite, PollAlways, PollOnDemand)“alarmText” property value is used.
Note: If alarms or alerts will be routed fromthe object to a Web Supervisor running the
Vykon Alarm Service, and a special alarmsound and/or URL is needed at VAS clients(associated with the object), you mustappend “extra” information at the end of thealarmText and/or alertText property. Fordetails, see the Vykon Alarm Service
Installation and Configuration Instructions.
255 charactersmaximum.
Any text string,including
spaces andmixed casecharacters.
-(hyphen)
For BI, BO, MI, andMSO objects, anotherproperty, “alertText”,applies to runtime andCOS alerts sent to thealarm console.
If alarmText is default(-) for both the objectand its container, thethe next highercontainer’s alarmTextis used (and so on).If all parent container
objects have thedefault (-) alarmText,the Station object’salarmText is used.
Table 5-5 Alarm Setup properties for standard event-type objects (AI, AO, BI, BO, Loop, MSI, MSO).
Tab Property Name Description Valid Values Default Notes
See Table 5-4 on page 5-12 for informationon these properties common to allevent-type control objects.
— — presentValue can bewritten to directlywhenever the object
is set tooutOfService.
C o n
f i g
executeParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 5-9.
normal,input
foreignAddress Read-Write: BACnet usage only. Set to apositive integer for this object to appear as aBACnet AnalogInput object to other BACnetdevices. See “foreignAddress,” page 5-9,for more information.
0 to 4194302
or -1(not exposed)
-1 If set, must be aunique numberamong all otherAnalogInput objectsin station.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
units Read-Write: Selection of engineering unitsfor display purposes. Choose from a logicalgrouping, then a specific unit.
For selections see “About Units,” page 5-6.
Select any(BACnet-typeunit choices)
Other,no_units
Units can bedisplayed by alinked GxTextobject.
covIncrement Read-Write: The minimum requiredchange-of-value at the statusInput (sincethe last output change) before outputs andpresentValue update. Affects these outputs:
• statusOutput
• covTrigger (fires at change of value)
valid float 0.0
(nominimum)
Execution efficiency (of downstreamobjects) is typicallyincreased byentering a smallvalue here, say 0.1
defaultInput Read-Write: The input value used by the AIobject if its statusInput link is broken orassumes a status that includes “fault.”
See Table 5-5 on page 5-13 for informationon these properties common to allevent-type control objects.
— — * See specific detailson inhibitTime, thenext property.
inhibitTime Read-Write: Duration (Hr:Min:Sec) of thealarm inhibit timer, which applies only if theobject’s input statusInhibit is linked. Thepurpose is to prevent nuisance alarms onequipment startup and shutdown.
The inhibitTime is triggered by a transition
from false-to-true at the statusInhibit input.• When statusInhibit becomes true, alarm
processing is delayed for the inhibit time.
• Whenever statusInhibit becomes false,alarm processing remains inhibited. Thealarm status of the object cannot change.This applies whether the object’sstatusFlags show a “normal” ok state or“inAlarm” and/or “unackedAlarm” states.
any practicalvalue in
Hr:Min:Sec
00:00:00(no inhibit)
A minimum of 1second (00:00:01) isrecommendedwhenever thestatusInhibit is linked.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
AnalogInput
5–19
AI Alarm Notification
Alarming notification determines which type of event transitions (alarms) are sent to
the Niagara alarming subsystem (Alarm Console). Events sent to the alarming
subsystem require user acknowledgment.
Note Alarm notification is a “step beyond” alarm detection. If you want only alarm
detection (and visual indication) for an object, leave the eventEnable flags cleared.
Using the various recipient options for the target notificationClass object, event
notifications can also be routed to printers, e-mail addresses, and APIs. If the AI
object is exposed as a BACnet object, BACnetRecipients can also be designated.
In the AI object, properties on the Alarm Setup tab relating to notification are:
• notificationClass —Must match an existing notificationClass object in the
station’s notificationServices container. The default class is zero (0).
• eventEnable —Flags that determine which event transition types are sent tothe alarming subsystem (to-offnormal, to-fault, to-normal). The default is all
flags cleared, meaning that object alarms are not sent for notification. You must
set flags as needed to receive alarm in the alarm console, route alarms, etc.
• notifyType —Either event (the default) or alarm. Operation within the Niagara
alarming subsystem is the same for either selection.
However, in a BACnet integration, in a response to a requesting BACnet
client’s “GetAlarmSummary” request, the station reports “BACnet-exposed
objects” currently in alarm only if their notifyType properties are set to alarm.
• alarmText —Text descriptor sent as an alarm record field whenever a
“to-offnormal” or “to-fault” event transition occurs (not a “to-normal”).
AI Alarm Inhibit
In addition to BACnet-type alarm properties, Niagara provides an alarm inhibit
feature based upon a boolean input to the object. Use of this feature is optional.
However, whenever the statusInhibit input is linked , the object’s inhibitTime
property should hold a defined value (not the default of 00:00:00 in Hr:Min:Sec).
Otherwise, the AI object will not be capable of alarming.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
AnalogInput
5–20
Figure 5-2 Alarm inhibit feature requires linking to the statusInhibit input.
The inhibit feature is intended to prevent unintended alarms, such as in after-hours
situations where a piece of equipment is turned off. For example, a return air
humidity sensor for an air handler may require alarm-limit monitoring during unit
operation (and only when the unit is running), as shown in Figure 5-2.
In this particular example, an alarm-status change can occur only after the air handler
has been running at least 15 minutes, as defined in the object’s inhibitTime. The
inhibit timer is reset whenever a state change at the statusInhibit input is received.
AI Alarm Delay
Alarm delay is a BACnet-type property, separate from the alarm inhibit mechanism.
It means that the object’s statusInput must meet the “alarm-change criteria” for a
continuous period equal to or greater than defined in the timeDelay property, before
an alarm status change occurs.
The alarm delay applies to both types of status transitions:• “to-offnormal”, meaning normal (ok) to alarm (high_limit, low_limit)
• “to-normal”, meaning alarm (high_limit, low_limit) to normal (ok)
In the case of a “to-normal” transition, the alarm-change criteria includes any defined
deadband value.
The general intention is to prevent nuisance alarms caused by momentary spikes or
dips in a received value. Typically, when both an alarm delay and alarm inhibit is
used, the timeDelay is shorter than the inhibitTime.
Fault Conditions The min and maxPresentValue properties can be used to set fault limits on the value
received at the object’s statusInput. When below or above these limits, the AI object
and its statusOutput have a status of “fault” (show as orange).
Default values for these properties are “MIN_VALUE” and “MAX_VALUE”;
effectively this means that no fault values are defined.
Whenever a logic false(inactive) is at thestatusInhibit (sInh) input,the AI object cannotchange status to (or from)
an alarm condition.
Upon a false-to-true (active) transition,the object’s inhibitTime periodbecomes effective. Until this periodexpires, the object remains inhibited from any alarm status change.
After the inhibitTime period expires,the object is capable of changingalarm status to (or from) alarm.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
AnalogInput
5–21
Note In some integrations, related shadow objects have a statusOutput that supplies fault
status information, however, you can define fault limits in a linked AI object as well.
If defined, min and maxPresentValue properties should extend past any configured
alarm limits (minPresentValue < lowLimit and maxPresentValue > highLimit). Notethat the alarm delay feature does not apply to transitions to (or from) a fault status.
Examples Figure 5-30 shows several examples of using AnalogInput objects.
Figure 5-3 AnalogInput examples.
The two AI objects at rightare used to format thereceived decimal value toone place, and assign units(temperature, in this case).
This AI object passes aduct pressure value, asconverted by a Math object(DIV) from Pascals toinches water column.
Here, the AI object isnecessary only foralarming capability andexposure as a BACnetobject (as the Math objectalso has units and decimal
values for display).
The eventTrigger output ofthis AI object is linked to thedoArchiveTrigger input atmultiple log-type objects.
If an alarm (or other statusevent) occurs, the logobjects archive theiraccumulated data to thestation’s designatedarchive supervisor.
By default, a linked GxTextobject shows the“abbreviated” units of theAI object.
This AI object providesalarming capability andthe ability to be exposedas a BACnet object.
This AI object is also configuredfor alarm inhibit. See See “AIAlarm Inhibit” on page 5-19.
See Table 5-4 on page 5-12 for informationon these properties common to allevent-type control objects.
— — presentValue isalways read-only.
P r i o r i t i e s
priorityArray(input: pIn )
Read Only: Shows values present on eachof the 16 priority level slots for thepriorityArray (pIn) input.
<valid float> orauto,
levels 1 to 16
auto
1 to 16
relinquishDefault Read-Write: Defines the output value whenall 16 priority level slots have an “auto”.
valid float 0.0
C o n
f i g
executeParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 5-9.
normal,output
foreignAddress Read-Write: BACnet usage only. Set to apositive integer for this object to appear as aBACnet AnalogOutput object to other
BACnet devices. See “foreignAddress,” page 5-9, for more information.
0 to 4194302
or -1(not exposed)
-1 Must be a uniquenumber among allAnalogOutput objects
in station.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
units Read-Write: Selection of engineering unitsfor display purposes. Choose from a logicalgrouping, then a specific unit.
For selections see “About Units,” page 5-6.
Select any(BACnet-typeunit choices)
Other,no_units
covIncrement Read-Write: The minimum requiredchange-of-value at the priorityArray input (since the last output change) before theoutputs and presentValue update. Affectsthese outputs:
• prioritizedOutput
• statusOutput
• covTrigger (fires at change of value)
valid float 0.0
(nominimum)
Execution efficiency (of downstreamobjects) is typicallyincreased by enteringa small value here,say 0.1
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
AnalogOutput
5–24
A l a r m
S e
t u p ,
c o n t .
inhibitTime Read-Write: Duration (Hr:Min:Sec) of thealarm inhibit timer, which applies only if theobject’s input statusInhibit is linked. The
purpose is to prevent nuisance alarms onequipment startup and shutdown.
Note: Alarming is based solely on the valueat the priorityArray input (unlike a BO orMSO object, the statusInput is ignored).
The inhibit timer is triggered by a transitionat the statusInhibit input.
• When statusInhibit becomes true, alarmprocessing is delayed for the inhibit time.
• When statusInhibit becomes false, alarmprocessing remains inhibited. While alarmprocessing is inhibited or delayed, the
alarm status of the object cannot change.This applies whether the object’sstatusFlags show a “normal” ok state or“inAlarm” and/or “unackedAlarm” states.
any practicalvalue in
Hr:Min:Sec
00:00:00(no inhibit)
A minimum of 1second (00:00:01) isrecommended
whenever thestatusInhibit is linked.
minPresentValue Read-Write: Valid processing low range.Below this value, the object and itsstatusOutput have a fault status (orange).
The minimum value that can be set for theobject using its right-click command menu.
Less than maxsetting (below)
See Notes Defaults are MIN andMAX_VALUE.
A non-default value isrequired for both ofthese properties inorder to provide aslider adjustmentfrom the JDE.
maxPresentValue Read-Write: Valid processing high range.Above this value, the object and itsstatusOutput have a fault status (orange).
The maximum value that can be set for the
object using its right-click command menu.
Greater thanmin setting
(above).
See Notes
highLimit Read-Write: Value above which the object isconsidered in high-limit alarm.
valid float 0.0
lowLimit Read-Write: Value below which the object isconsidered in low-limit alarm.
valid float 0.0
deadband Read-Write: Differential value applied tooff-normal limits before return-to-normal.
valid float 0.0
limitEnable Read-Write: Flags that enable low-limit andhigh-limit alarms.
valid float 0.0
V i s u a
l
position Read-Write: See “position,” page 5-9. — —
decimalFormat Read-Write: Sets decimal position from 0 to6 places, and optionally force (+) sign for
positive values.
0 to 6,
(+) sign,
no (+) sign
2,
no (+) sign
commandTags Read-Write: Defines the command labelsthat show on the right-click command menufor the object. Default tags are:
• Set (manualSet level)
• Auto (manualAuto level)
• Emergency Set (emergencySet level)
• Emergency Auto (emergencyAuto level)
Any desiredtext string,including
spaces andnumerals.
Seedescrip.
If a tag is blank (nocharacters), thecommand is notavailable on thecommand menu.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
AnalogOutput
5–25
AnalogOutput NotesThe AO object is typically used to provide a user-adjustable setpoint. In some cases,
an AO object is used to directly control a physical analog output of a remote device,
represented by a shadow object. In this case, the statusOutput of the AO object is
typically linked to an input of a device object, or to an input of an AO “point” object.
CommandRelatedProperties
Although the object provides alarming capabilities identical to the AI object (based
upon the value at the priorityArray input) AO objects are not typically configured for
alarm indication and notification.
However, two properties on the Alarm Setup tab of the property sheet are routinely
configured from defaults, namely:
• minPresentValue —Determines the minimum valid value that can be
commanded, using the right-click Set command.
• maxPresentValue —Determines the maximum valid value that can be
commanded, using the right-click Set command.
These limits also define “fault” status conditions for the AO object. Such conditions
can occur if the priorityArray input is linked, and the received value falls outside of
these limits. During a fault condition, the AO object and its statusOutput are colored
orange.
E n g
i n e e r i n g
minExecuteTime,maxExecuteTime,averageExecuteTime,
userData
Properties common to all control objects.For more information, see Table 5-3 onpage 5-8.
— —
statusInhibit(input: sInh)
Read Only: Shows the current boolean stateand status of the statusInhibit input.
false, true :status flags
false : ok
statusInput(input: sIn )
Read Only: Shows the current value andstatus received on the statusInput.
Note: This input value is not used in the AOobject’s alarm processing (no real use).
<float value>status flags
00.0 ok If statusInput is notlinked, reflects valueat priorityArray.
statusOutput(output: sOut)
Read Only: Shows the current value andstatus of the statusOutput.
<float value>status flags
00.0 ok
prioritizedOutput(output: pOut)
Read Only: Shows the current value andstatus of the statusOutput.
<float value> @<pri. level>
0.00 @ 16
statusFeedbackOutput
(output: sFbOut) Read Only: Shows the current value andstatus at the statusFeedbackOutput. <float value>status flags 00.0 ok Reflects statusInputvalue (if linked),otherwise shows thestatusOutput value.
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For moredetails, see “securityGroups,” page 5-10
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
AnalogOutput
5–26
Note that both minPresentValue and maxPresentValue must be configured from the
defaults in order for the “slider bar” to appear in the JDE when commanding the
object, either directly or from a linked Gx object (Figure 5-4).
Figure 5-4 Command limits are determined by min and maxPresentValue (Alarm Setup tab).
This AO object has thedefault values for min andmaxPresentValue.
When using the JDE or a webbrowser to issue a right-clickcommand to the object(either directly, or through alinked Gx object), any valuecan be entered.
This AO object hasconfigured values for min andmaxPresentValue.
When using the JDE to issuea right-click command to theobject (either directly orthrough a linked Gx object), aslider bar appears that can bedragged to change the value.The commanded value canonly be between theconfigured limits.
No slider is available whenissuing an AO command froma Web browser (through alinked Gx object).
However, the popup controlremains displayed if thecommanded value is beyondmin or maxPresentValue.
In addition, the lower leftcorner of the browser windowshows an “Invalid Input” whilethe cursor is over the OKbutton.
Use the Alarm Setuptab to access min andmaxPresentValue.
Default “MIN” and “MAX” values
allow a Set command to any value.
Slider bar appears because both min andmaxPresentValue are configured.
Use the Alarm Setuptab to access min andmaxPresentValue.
The lower left corner of the browser shows“Invalid Input” with the cursor over OK.
Popup control for right-click commandwhen using a Web browser.
Whenever the entered value is out ofrange, the popup command control
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
AnalogOverride
5–28
AnalogOverrideQuick reference for all properties: Table A-5
abbrev: AOvrd
An AnalogOverride (AOvrd) object provides
a prioritized analog output signal that iscontrolled from a right-click command menu.
Commands include starting a timed-override
for a specified duration, canceling an
override, and changing the override value.
The priority level of an override is
configurable to any level (from 1 to 16).
Parent Dependencies: None (any
container).
Resource Count Range: 41 to 57
Trigger Properties The AOvrd object has the standard input property, executeTrigger , (typically not
used) plus an additional trigger-type input :
• overrideTrigger —Any received trigger pulse starts an override at the object’s
presently configured overrideValue, overrideTime, and priorityForWriting.
If needed, this input can be linked to an object with a trigger-type output, for
example, a Command object. This would allow a user to start an override, but not to
change the override value, cancel the override, or change its duration. An overridewould be started each time a trigger pulse is received at this input.
CommandsFor any user with “Command, Std” privileges, an AOvrd object has a right-click
command menu that provides these commands:
• override —To start an override and specify the duration, in minutes.
• cancel —To cancel any current override.
• setOverrideValue —To set the prioritizedOutput value used in an override.
Properties
Inputs
Default Object Shape
Outputs
(none) statusInOverride
prioritizedOutput
Inputs
All Inputs / Outputs
Outputs
executeTrigger
overrideTrigger
inOverride
statusInOverride
prioritizedOutput
Input / Output Property Reference for AnalogOverride Object(only input and output types, see Table 5-8 for all properties)
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
AnalogOverride
5–29
AnalogOverride NotesThere are two basic ways to use an AnalogOverride object:
• Available directly to users—see “Directly Available”.
• Available through a Command object—see “Used with a Command object”.
C o n
f i g
executeParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 5-9.
normal,input
foreignAddress Read-Write: Does not apply to this object. -1 -1
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
priorityForWriting Read-Write: Defines the priority level usedat the prioritizedOutput during an override.
When the override expires or is canceled,this level is auto’ed.
Any prioritylevel,
from 1 to 16
ManualOperator
(8)
overrideTime (min) Read-Write: Defines the duration of anoverride, in minutes.
When an override is commanded, this timeis initialized and begins counting down. Ifnot canceled or re-initiated, the override willlast this duration.
This property is most important when using
the input “overrideTrigger.”
Any positiveinteger from 1
up to 32-bitlimit.
60 If using the object’sright-click commandmenu, this overridetime is displayed (andcan be adjusted)each time an overrideis issued.
overrideValue Read-Write: Defines the value that appearsat the prioritizedOutput during an override.This value will be issued at the priority leveldefined in the priorityForWriting property.
When the override expires or is canceled,the output value expires (level is auto’ed).
This property is most important when usingthe input “overrideTrigger.”
Any floatingpoint value.
0.0 If using the object’sright-click commandmenu, this overridevalue can beadjusted(setOverrideValue).
V i s u a
lposition Read-Write: See “position,” page 5-9. — —
decimalFormat Read-Write: Sets decimal posit ion from 0 to6 places, and optionally force (+) sign forpositive values.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
BinaryInput
5–34
C o n
f i g
executeParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 5-9.
normal,input
foreignAddress Read-Write: BACnet usage only. Set to a
positive integer for this object to appear as aBACnet BinaryInput object to other BACnetdevices. See “foreignAddress,” page 5-9, formore information.
0 to 4194302
or -1(not exposed)
-1 Must be a unique
number among allBinaryInputobjects in station.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
polarity Read-Write: Determines if the sameboolean state at the statusInput is reflectedat the statusOutput (normal), or if the outputremains opposite from the input (reverse).
normal, reverse normal
defaultInput Read-Write: The input value used by the BIobject if its statusInput link is broken orassumes a status that includes “fault.”
on these properties common to allevent-type control objects.
— — * See specific
details oninhibitTime, thenext property.
inhibitTime Read-Write: Duration (Hr:Min:Sec) of thealarm inhibit timer, which applies only if theobject’s input statusInhibit is linked.The purpose is to prevent nuisance alarmson equipment startup and shutdown.
The inhibitTime is triggered by a transition atthe statusInhibit input.
• When statusInhibit becomes true, alarmprocessing is delayed for the inhibit time.
• When statusInhibit becomes false, alarmprocessing is delayed for three times theinhibit time.
any practicalvalue in
Hr:Min:Sec
00:00:00(no inhibit)
A minimum valueof 1 second(00:00:01) isrecommendedwhenever thestatusInhibit inputis linked.
Alarm processingcompares thestatusInput valueto the definedalarmValue.
changeOfStateAlertLimit Read-Write: Number of COS occurrencesthat generate a changeOfStateCount alert.
Positive integer 0
activeTimeAlertLimit Read-Write: Amount of runtime (elapsedactive time), in Hr:Min:Sec, that generates aruntime alert.
Value up to99999:59:59(Hr:Min:Sec)
00:00:00
alertNotificationClass Read-Write: The assigned notification classnumber, used in routing alerts.
A NotificationClass object using the same
number should exist in theNotificationService object’s container.
0 to 8388607 0
periodicAlerts Read-Write: Determines if both COS countalerts and runtime alerts are periodicallygenerated each time the respective limit isreached.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
BinaryInput
5–37
BI Alarm Detection
Several properties on the Alarm Setup tab determine whether an alarm condition is
detected by the BI object. In order of relative importance, these properties include:
• alarmValue —State at which the BI is considered “offnormal” (inAlarm),
providing that the alarmValueEnabled property is set to True. The object shapeand its statusOutput are red during this state.
• alarmValueEnabled —Determines if the BI is capable of an alarm condition.
The default is False (no alarming capability).
• timeDelay —Optional time period that must be met before any alarm state
change occurs with the object. See “BI Alarm Delay” on page 5-38.
BI Alarm Notification
Alarming notification determines which type of alarm transitions are sent to the
Niagara alarming subsystem (Alarm Console). Events sent to the alarming subsystem
require user acknowledgment. Using the various recipient options for the target
notificationClass object, event notifications can also be routed to printers, e-mailaddresses, and APIs. If the BI object is exposed as a BACnet object,
BACnetRecipients can also be designated.
Note Alarm notification is a “step beyond” alarm detection. If you want only alarm
detection (and visual indication) for an object, leave the eventEnable flags cleared.
In the BI object, properties on the Alarm Setup tab relating to alarm notification are:
• notificationClass —Must match an existing notificationClass object in the
station’s notificationServices container. The default class is zero (0).
• eventEnable —Flags that determine which event transition types are sent tothe alarming subsystem (to-offnormal, to-fault, to-normal). The default is all
flags cleared, meaning that object alarms are not sent for notification. You must
set flags as needed to receive alarm in the alarm console, route alarms, and so
on.
• notifyType —Either event (the default) or alarm. Operation within the Niagara
alarming subsystem is the same for either selection.
However, in a BACnet integration, in a response to a requesting BACnet
client’s “GetAlarmSummary” request, the station reports “BACnet-exposed
objects” currently in alarm only if their notifyType properties are set to alarm.
• alarmText —Text descriptor sent as an alarm record field whenever a
“to-offnormal” or “to-fault” event transition occurs (not a “to-normal”).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
BinaryInput
5–38
BI Alarm Inhibi t
In addition to BACnet-type alarm properties, Niagara provides an alarm inhibit
feature based upon a boolean input to the object. Use of this feature is optional.
Note Whenever the statusInhibit input is linked , the object’s inhibitTime property shouldhold a defined value (not the default of 00:00:00 in Hr:Min:Sec).
Otherwise, the BI object will not be capable of alarming.
Figure 5-11 Alarm inhibit feature requires linking to the statusInhibit input.
The inhibit feature is intended to prevent unintended alarms, such as in after-hours
situations where a piece of equipment is turned off. For example, a dirty-filter switch
for an air handler may require alarm monitoring during unit operation (and only when
the unit is running), as shown in Figure 5-11.
In this particular example, an alarm-status change can occur only after the air handlerhas been running at least 30 seconds, as defined in the object’s inhibitTime. The
inhibit timer is reset whenever a state change at the statusInhibit input is received.
BI Alarm Delay
Alarm delay is a BACnet-type property, separate from the alarm inhibit mechanism.
It means that the object’s statusInput must meet the “alarm-change criteria” for a
continuous period equal to or greater than defined in the timeDelay property, before
an alarm status change occurs.
The alarm delay applies to both types of status transitions:
• “to-offnormal”, meaning normal (ok) to in_alarm.
• “to-normal”, meaning in_alarm to normal (ok).
The general intention of timeDelay is to prevent nuisance alarms caused by
momentary change in the received boolean value. Typically, when both an alarm
delay and alarm inhibit is used, the timeDelay is less (shorter) than the inhibitTime.
Whenever a logic false(inactive) is at the statusInhibit (sInh) input, the BI objectcannot change status to (orfrom) an alarm condition.
Upon a false-to-true (active) transition,the object’s inhibitTime periodbecomes effective. Until this periodexpires, the object remains inhibited from any alarm status change.
After the inhibitTime period expires,the object is capable of changingalarm status to (or from) alarm.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
BinaryInput
5–39
BI AlertNotifications
In addition to (or instead of) alarming on a particular binary state, a BI object is also
capable of generating “alerts,” based upon configurable limits for runtime (elapsed
activeTime) and/or number of COS transitions (change of states). Alerts are sent to
the Niagara alarming subsystem (Alarm Console), and require acknowledgment.
Like alarms, alerts are associated with a specified notificationClass and can be routed
to various recipients.
BI object alert subtopics include:
• Alarm Setup Properties for Both Alert Types
• Change-of-State (COS) Alerts
• Runtime (Active Time) Alerts
Alarm Setup Propert ies for Both Alert Types
Alarm Setup properties that apply to both types of BI alerts (runtime and COS) are:
• alertNotificationClass —Must match a notificationClass object in the
notificationServices container. The default is 0, the same default for alarms.
• periodicAlerts —Determines whether runtime and COS alerts should repeat
upon each accrued interval of runtime or COS count. For example, if enabled
(True), and the COS count limit is defined at 150, a COS alert will be issued at
COS counts of 150, 300, 450, and so on. The default value is False.
• alertText —Any user-friendly text string wanted. Appears as a field in the alert
record for any runtime or COS alert, as a means of further description.
Change-of-State (COS) Alerts
Each state change at the BI’s statusInput increments the object’s COS counter by 1.
Assuming the object’s COS counter begins at 0, if the input changes from
inactive-to-active-to-inactive-to-active-to-inactive, the COS count will be 4. Thetotal number of active transitions (in this case, 2) is about half the current COS count.
The COS count is available as the Status property changeOfStateCount. It is also
available as the statusChangeOfStateCount output (using integerStatus data species).
The COS count is resettable (to 0) for any JDE user with Admin-level command
rights. Also, the COS count can be reset using a Command object linked to the
object’s resetChangeOfStateCountTrigger input, if needed.
Properties on the Alarm Setup tab that apply to COS alerts include:
• changeOfStateAlertLimit —Integer value that defines the COS count that
should result in an alert notification. If periodicAlerts is set to True, an alert is
generated at each multiple of this value.
Runtime (Active Time) Alerts
Each BI object automatically accumulates runtime, that is, elapsed active time. This
time is available formatted in Hr:Min:Sec as the Status property elapsedActiveTime.
Runtime is also available as an output, as an integer value in seconds (using an
See Table 5-4 on page 5-12 for informationon these properties common to allevent-type control objects.
<cmd state> orauto,
levels 1 to 16
auto
1 to 16
presentValue isalways read-only.
changeOfStateTime Read Only: Shows a date/timestamp for thelast COS (change of state).
valid timestampor null (none)
null
changeOfStateCount Read Only: Shows the total number ofchanges of state that have occurred sincethe last COS count reset (clear).
integer value 0
timeOfStateCountReset Read Only: Shows a date/timestamp forwhen the COS count was last cleared.
valid timestampor null (none)
null
elapsedActiveTime Read Only: Shows accumulated runtime(elapsed active time) in Hr:Min:Sec.
Time period upto 9999:99:99
00:00:00
timeOfActiveReset Read Only: Shows a date/timestamp forwhen the accumulated runtime (elapsedactive time) was last cleared.
valid timestampor null (none)
null
P r i o r i t i e s
priorityArray(input: pIn )
Read Only: Shows commands present oneach of the 16 priority level slots for thepriorityArray (pIn) input.
Active, Inactive,or auto,
levels 1 to 16
auto
1 to 16
relinquishDefault Read-Write: Defines the output state whenall 16 priority level slots have an “auto”.
Active, Inactive Inactive
inInterstartDelay Read Only: Indicates if an interstart delay iscurrently active (True) or not (False).
False, True False
C o n
f i g
executeParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 5-9.
normal,output
foreignAddress Read-Write: BACnet usage only. Set to apositive integer for this object to appear asa BACnet BinaryOutput object to otherBACnet devices. See “foreignAddress,” page 5-9, for more information.
0 to 4194302
or -1(not exposed)
-1 Must be a uniquenumber among allBinaryOutputobjects in station.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
polarity Read-Write: Determines if the same
boolean state at the statusInput is reflectedat the statusOutput (normal), or if the outputremains opposite from the input (reverse).
normal, reverse normal
minimumOnTime Read-Write: Upon a command frominactive to active, results in an activecommand stored at the Minimum On Offpriority level (6) for this time (Hr:Min:Sec).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
BinaryOutput
5–44
C o n
f i g ,
c o n
t .
minimumOffTime Read-Write: Upon a command from activeto inactive, results in an inactive commandstored at the Minimum On Off priority level
(6) for this duration (Hr:Min:Sec).
Any practicaltime needed.
00:00:00
restartDisable Read-Write: Determines whether the outputis automatically restarted following a stationrestart (reboot) or power failure. If set toTrue, an inactive at manual level (8) isissued following such an occurrence.
False, True False
interstartDelayTime Read-Write: Defines the time period theoutput is held inactive following an activecommand. Used to prevent multiplesimultaneous starts. Applies to commandsat all priority levels except Emergency (1).
See Table 5-5 on page 5-13 for informationon these properties common to allevent-type control objects.
— — * See specificdetails oninhibitTime, thenext property.
inhibitTime Read-Write: Duration (Hr:Min:Sec) of thealarm inhibit timer, which applies only if theobject’s input statusInhibit is linked.The purpose is to prevent nuisance alarmson equipment startup and shutdown.
The inhibitTime is triggered by a transitionat the statusInhibit input.
• When statusInhibit goes false-to-true,alarm processing is delayed for the inhibit
time.• When statusInhibit goes true-to-false,
alarm processing is delayed for three
times the inhibit time.
any practicalvalue in
Hr:Min:Sec
00:00:00(no inhibit)
A minimum value of1 second(00:00:01) isrecommendedwhenever thestatusInhibit input islinked.
Alarm processingcompares the
statusInput(feedback) value tothe priorityArray(command) value.
changeOfStateAlertLimit Read-Write: Number of COS occurrencesthat generate a changeOfStateCount alert.
Positive integer 0
activeTimeAlertLimit Read-Write: Amount of runtime (elapsedactive time), in Hr:Min:Sec, that generates aruntime alert.
Any value up to9999:59:99
(Hr:Min:Sec)
00:00:00
alertNotificationClass Read-Write: The assigned notification classnumber, used in routing alerts.
A NotificationClass object using the same
number should exist in theNotificationService object’s container.
0 to 8388607 0
periodicAlerts Read-Write: Determines if both COS countalerts and runtime alerts are periodicallygenerated each time the respective limit isreached.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
BinaryOutput
5–46
BinaryOutput NotesThe BO object is typically used for control of two-state device or mode of operation.
In some cases, a BO object is used to directly control a physical binary output of a
remote device, represented by a shadow object.
The following sections provide various notes on BO objects:• Priority Levels
• Routinely Configured BO Properties
• Control Related Properties
• BO Command Tags
• BO Alarming Functions
• Examples
Priority Levels The priorityArray input of a BO object can be linked to the “prioritizedOutput” of
multiple objects. Compatible object types include the BinaryOverride, Comparison,
Logic, Schedule, as well as other BO objects. Default priority levels for these objectsis typically level 8 (manual), however, it is 16 (schedule) for the Schedule object.
In addition to these types, Program objects (that have a boolean prioritized output)
can be linked, including many in the standard tridiumx library (lib). For example,
under the “hvac” folder of the tridiumx “lib” JAR are several applicable Program
objects. Included are an EDL (electric demand limiting) “ShedControl” object, and a
“OptimizedStartStop” object. By default, prioritizedOutputs of these objects work at
levels 9 (demand limiting) and 12,13 (stop, start optimization), respectively.
Typically for these objects, the priority level of its prioritizedOutput can be modified
from the default level, using the Config property priorityForWriting.
How Levels Are EvaluatedThe 16 different priority levels are evaluated upon each object execution cycle. The
highest priority is 1 (manual life safety); the lowest is 16 (schedule). Levels function
as priority “slots,” where commands “pushed” by the execution of linked object(s)
are stored, and then evaluated upon each execution cycle. The highest level with an
“active” or “inactive” (not “auto”) controls the BO object. In the case where all 16
levels are “auto,” the BO assumes the configured “relinquishDefault” state.
The “read slot” technique differs from the normal “pull input data” technique of an
object when it executes. This helps to explain what happens when the priorityArray
is linked to multiple controlling outputs, and the same priority level is used. In this
case, the duplicated level operates at the last received state (active or inactive), with
the strong probability of “control contention” (think chattering).
Notes • When linking multiple objects to the priorityArray input, it is recommended to
source from only one object per specific priority level (to prevent contention).
• A Schedule object has a fixed execution frequency of once each minute. If
linked to a BO, it updates a priority level (slot) only at the top of each minute.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
BinaryOutput
5–47
RoutinelyConfigured BOProperties
The three most typically configured properties for a BO object are:
• relinquishDefault (Priorities tab)—Defines the BO object’s output state when
all 16 of the priority-level slots at the priorityArray input have an “auto.”
The default value is inactive.
• activeInactiveText (Visual tab)—Defines the display descriptors used for theobject’s boolean states (active and inactive). Assigned descriptors appear in
linked GxText objects and in the accumulated data of a linked BinaryLog.
• commandTags (Visual tab)—Defines how user commands appear on the
object’s right-click command menu. See “BO Command Tags” on page 5-48.
If alarming functions and/or alerts are needed, additional Alarm Setup properties are
configured from default values.
Control RelatedProperties
The BO object includes several Config properties that directly determine the control
operation of its main outputs (prioritizedOutput and statusOutput).
• polarity —The default is normal. If set to reverse, this flips control such thatan inactive at the control (priorityArray) input (or from a right-click command)
produces an active at the object’s outputs, and vice-versa. Note that the
statusInput input, if used (for alarming), is then “out-of-phase” with control.
• minimumOnTime —Defines the time period in which an active command at
the “Minimum On Off” priority level (6) will exist, as a result of any command
transition from inactive to active. This can prevent equipment short-cycling.
• minimumOffTime —Defines the time period in which an inactive command
at the “Minimum On Off” priority level (6) will exist, as a result of any
command transition from active to inactive. This can prevent equipment
short-cycling.
• restartDisable —Determines how outputs are set following a station restart,host reboot, or power failure. Settings False and True are as follows:
– False (the default), restores outputs automatically to the previous state
(active or inactive).
– If set to True, outputs are set to inactive at the “Manual” level (8).
• interstartDelayTime —Defines a delay period, in seconds, before an active
command becomes effective. Does not apply with a command to inactive.
Applies to all priority levels except Emergency Manual (1). The default value
of zero (0) means no delay time.
You can use this property to prevent multiple simultaneous starts to
BO-controlled loads, which might otherwise cause energy (demand) spikes.
Note There is no “central” interstart delay timer in a Niagara station. This means you
should specify different interstartDelayTimes for each BO (or group of BOs)
included in an interstart delay sequence. For example, assign the first BO a delay
time of 0, second BO a delay time of 3, third BO a delay time of 6, and so forth.
Different times cause “to-active” states to be staggered when multiple BOs receive
a simultaneous active, for instance, from a linked Schedule (or a station restart).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
BinaryOutput
5–48
BO CommandTags
It is typical for BO objects to be configured with custom command “labels,” using
the commandTags property, located on the Visual tab of the object’s property sheet.
Editing commandTags allows more meaningful right-click menu labels on the
right-click menu than the default values, for example, “Start AHU-1” vs. “Active.”
In addition, you can clear any tags to make those commands unavailable
(Figure 5-13). This is often done for emergency-level commands, for example.
BO AlarmingFunctions Alarm detection for a BO object requires a separate link to a statusFeedback input,which receives the “actual” boolean value of the controlled device. This state is
compared against the current “controlled/commanded” state, and can result in an
alarm (if the two states are different). See Figure 5-14.
The following subtopics apply to BO alarming:
• BO Alarm Inhibit
• BO Alarm Delay
• BO Alarm Notification
Figure 5-13 The commandTags property (Visual tab) determines how (and which) commands are listed.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
BinaryOutput
5–50
BO Alarm Inhibit
In addition to BACnet-type alarm properties, Niagara provides an alarm inhibit
feature based upon a boolean input to the object. Use of this feature is optional.
Note Whenever the statusInhibit input is linked , the object’s inhibitTime property shouldhold a defined value (not the default of 00:00:00 in Hr:Min:Sec).
BO Alarm Delay
Alarm delay is a BACnet-type property, separate from the alarm inhibit mechanism.
It means that the object’s statusInput must meet the “alarm-change criteria” for a
continuous period equal to or greater than defined in the timeDelay property, beforean alarm status change occurs.
The alarm delay applies to both types of status transitions:
• “to-offnormal”, meaning normal (ok) to in_alarm.
• “to-normal”, meaning in_alarm to normal (ok).
The general intention of timeDelay is to prevent nuisance alarms caused by
momentary change in the received boolean value. Typically, when both an alarm
delay and alarm inhibit is used, the timeDelay is less (shorter) than the inhibitTime.
BO Alarm Notification
Alarming notification determines which type of alarm transitions (events) are sent to
the Niagara alarming subsystem (Alarm Console). Events sent to the alarming
subsystem require user acknowledgment. Using the various recipient options for the
target notificationClass object, event notifications can also be routed to printers,
e-mail addresses, and APIs. If the BO object is exposed as a BACnet object,
BACnetRecipients can also be designated.
Figure 5-16 BinaryOutput statusInhibit input and inhibitTime property.
The statusInhibit input istypically linked to the samesource that is controllingthe BO (linked to thepriorityArray input).
When the BO iscommanded to active, anyalarm status change isinhibited for the specified
inhibitTime, in seconds.
When commanded toinactive, any alarm statuschange is inhibited for 3
times the inhibitTime, inseconds. This extendedperiod can be considered“wind-down” time.
statusInhibit (sInh) link
priorityArray input linkfor control command
Feedback signal linkedto statusInput (sIn)
Example:inhibitTime = 30 (seconds)
When under schedule control,and going from active toinactive (On to Off), the alarminhibit delay will be 90 seconds.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
BinaryOutput
5–51
Note Alarm notification is a “step beyond” alarm detection. If you want only alarm
detection (and visual indication) for an object, leave the eventEnable flags cleared.
In the BO object, properties on the Alarm Setup tab relating to alarm notification are:
• notificationClass —Must match an existing notificationClass object in the
station’s notificationServices container. The default class is zero (0).
• eventEnable —Flags that determine which event transition types are sent to
the alarming subsystem (to-offnormal, to-fault, to-normal). The default is all
flags cleared, meaning that object alarms are not sent for notification. You must
set flags as needed to receive alarm in the alarm console, route alarms, and so
on.
• notifyType —Either event (the default) or alarm. Operation within the Niagara
alarming subsystem is the same for either selection.
However, in a BACnet integration, in a response to a requesting BACnet
client’s “GetAlarmSummary” request, the station reports “BACnet-exposedobjects” currently in alarm only if their notifyType properties are set to alarm.
• alarmText —Text descriptor sent as an alarm record field whenever a
“to-offnormal” or “to-fault” event transition occurs (not a “to-normal”).
Examples Figure 5-17 shows several examples of BinaryOutput objects in use.
Figure 5-17 BinaryOutput object examples.
The BO objects at rightprovide commandableaccess to occupancymodes for an air handlerand VAV boxes.
Upstream, a Logic object(AND function) providesoverride-OFF control frompump safeties.
This BO object has itsruntime output (sElpT)linked to a Program objectwritten to perform alead/lag rotation. An outputof the Program objectclears the BO’s runtime
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType,
statusFlags,description
See Table 5-3 on page 5-8 for information
on these properties common to all controlobjects.
— —
inOverride(output: inOverr )
Read-Only: Indicates if an override iscurrently in effect (True) or not (False).Available as a linkable output.
False, True False boolean data species.
C o n
f i g
executeParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 5-9.
normal,input
foreignAddress Read-Write: Does not apply to this object. -1 -1 Leave at default.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
priorityForWriting Read-Write: Defines the priority level usedat the prioritizedOutput during an override.
When the override expires or is canceled,this level is auto’ed.
Any prioritylevel,
from 1 to 16
ManualOperator
(8)
overrideTime (min) Read-Write: Defines the duration of anoverride, in minutes.
When an override is commanded, this timeis initialized and begins counting down. Ifnot canceled or re-initiated, the override willlast this duration.
This property is most important when usingthe input “overrideTrigger.”
Any positiveinteger from 1
up to 32-bitlimit.
60 If using the object’sright-click commandmenu, this propertyvalue is displayed(and can be adjusted)each time an overrideis issued.
overrideValue Read-Write: Stores the last given overridestate (True for active, False for inactive).The override was issued at the level definedin the priorityForWriting property.
When the override expires or is canceled,the output state expires (level is auto’ed).
Note: Any pulse received at theoverrideTrigger input causes an override atthis state: True (active) or False (inactive).
True, False False If using the object’sright-click commandmenu, this overridevalue (state) isselectable. Theselected state isstored in this property.
V i s u a
l
position Read-Write: See “position,” page 5-9. — — —
activeInactiveTextactive,inactive
Read-Write: Defines the override commandarguments that appear on the object’sright-click command menu. For instance:“override On” or “override Off.”
Default values are:
• Active (active), shows as “override Active”
• Inactive (inactive) shows as “overrideInactive”
Any desiredtext string todescribe the
override state.
Seedescrip.
Blank properties (nocharacters) result incommands that saysimply “override”. Youshould use textdescriptors that makesense to the system
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
Command
5–57
Command NotesThe Command object provides a right-click command menu containing up to four
command selections, each of which fires one of four trigger outputs. Each trigger
command has an editable label.
Examples Figure 5-30 shows an example of a Command objects in use. Other Command object
examples appear in Figure 5-8 and Figure 5-19.
Notes • Trigger-type links are unique in that “many-to-one” links are permitted as well
as the more typical “one-to-many.” This means, for example, that you can link
a Command object to an object’s trigger input that is already linked, say, to aDateTimeTrigger object and/or a PeriodicTrigger object.
• Although the Services container has no Workspace view, the AuditLogService
and ErrorLogService are represented by objects with 2 trigger inputs, namely,
“doArchive” and “doClear”. The LogService also has 2 trigger inputs, namely,
“doArchiveAllTrigger” and “doClearLastArchive.” You can use Tree View to
link Command object outputs (or trigger-type outputs of other objects) to
provide user-accessible commands to these services, as needed.
Figure 5-21 Command object examples.
This Command object islinked to a BO object andprovides a menu to clearthe BO’s COS count andruntime (elapsed activetime). Typically, such anobject would be assignedonly to select securityGroups.
Command descriptions areconfigured on the object’sproperty sheet, (Visualtab).
Any property left blankdoes not appear on theobject’s command menu.
Right-click command menu.Each command results in atrigger pulse from theCommand object.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
Comparison
5–60
Examples Figure 5-22 shows two Comparison objects used to evaluate a space temperature
value against cooling and heating setpoints. Outputs of the Comparison objects feed
a Logic object, which produces a “Setpoint OK” true or false boolean state.
Figure 5-22 Comparison objects used to compare space temperature against setpoints.
LonWorks Conversion
Figure 5-23 shows Comparison objects linked to a SnvtHvacStatusDemux object that
demuxes different fields in SNVT_hvac_status to various outputs. Five of the outputs
are FloatStatusTypes, and read either “0.0” (for Off) or “100.0” (for On). When
linked to Comparison objects, outputs are converted to boolean values that are better
suited for display and logging (as well as a control logic use downstream).
Note In this case, Comparison objects are better suited than equivalent Program objects, because each uses less resource counts (approximately 56 versus 80 or more).
Figure 5-23 Comparison objects used to convert data types.
Comparison objects
Boolean outputs to aLogic object
For this application, theseComparison objects can beleft at default Config settings.By linking to the sInA input,any input value over 0.0 (thedefault sInB value) results inan “Active” state.
The only properties editedfrom default settings were theVisual “activeInactiveText”properties. In this case, theactive text is simply “On” andthe inactive text is “Off.”
Trigger Properties None, apart from the standard input property, executeTrigger (typically not used).
CommandsBy default, a newly-created CpAnalogNode object has no right-click command menu
until you enter text in the commandText property (Visual tab).
For a user with “Command, Std” privileges, this command appears on the right-click
menu. Only values between the maxValue and minValue (inclusive) are accepted.
Properties
Inputs
Default Object Shape
Outputs
cmdLink (none)
InputsAll Inputs / Outputs
Outputs
executeTrigger
cmdLinkvalue
Property Quick Reference for CpAnalogNode Object(only input and output types, see Table 5-14 for all properties)
Type Label Property Name Data Species
input exe executeTrigger TriggerType
cmdLnk cmdLink float
output value value float
Note: This object is nearly identical to the AnalogCmd object, whichis included in the lonworks JAR (conversion folder). However, theCpAnalogNode object is a core (tridium) object, and so can be used inany Niagara station, without regard to module dependecies.
Table 5-14 CpAnalogNode object properties.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType,
statusFlags,description,
See Table 5-3 on page 5-8 for information
on these common object properties.
— —
cmdLink(input: cmdLink)
Read-Only: Current (float) value of thelinked (target) property, as on the input.
valid float 0.0
value(output: value)
Read-Only: Current (float) value of thelinked (target) property, as on the output.
Link a Gx object to the value output toprovide command access from a GxPage.
valid float 0.0 At all times equal tothe cmdLink value.
The top CpAnalogNode’s“cmdLink” input is linked tothe “highLimit” property of theAI object.
The second CpAnalogNode’s“cmdLink” input is linked tothe “lowLimit” property of theAI object.
Links shown here between Cp objects and the AI object appearunusual, as there is no “output.” Conceptually, the cmdLink inputfunctions as an output, however, it is only for user commands fromthe Cp object (no direct linkage to other control logic).
objectName: HiAlarmLimitRAT
maxValue: 85.0minValue: 75.0commandText: Change RA temp High Alarm limitdecimalFormat, precision: 1
Right-click command shows thecommandText string.
Selecting the command
produces an entry box.
In this example, two GxTextobjects are used to show thehigh alarm and low alarm limits.
Trigger Properties None, apart from the standard input property, executeTrigger (typically not used).
Commands By default, a newly-created CpBinaryNode object has no right-click command menu
until you enter text in the commandText property (Visual tab).
For a user with “Command, Std” privileges, this command appears on the right-click
menu. A selection-box in the menu popup allows toggling the current property value.
Properties
Inputs
Default Object Shape
Outputs
cmdLink (none)
Inputs
All Inputs / OutputsOutputs
executeTrigger
cmdLinkvalue
Property Quick Reference for CpBinaryNode Object(only input and output types, see Table 5-15 for all properties)
Type Label Property Name Data Species
input exe executeTrigger TriggerType
cmdLnk cmdLink boolean
output value value boolean
Note: This object is nearly identical to the N2BinaryCmd object,previously included in a johnson2 JAR. However, the CpBinaryNodeobject is a core (tridium) object, and so can be used in any Niagarastation, without regard to module dependecies.
Table 5-15 CpBinaryNode object properties.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType,statusFlags,
description,
See Table 5-3 on page 5-8 for informationon these common object properties.
— —
cmdLink(input: cmdLink)
Read-Only: Current (boolean) value of thelinked (target) property, as on the input.
Inactive,Active
Inactive
value(output: value)
Read-Only: Current (boolean) value of thelinked (target) property, as on the output.
Link a Gx object to the value output toprovide command access from a GxPage.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
CpBinaryNode
5–65
CpBinaryNode NotesThe CpBinaryNode is used to provide read/write-access to an internal property
(Config, Alarm Setup, etc.) of any Niagara object. The linked (target) property must
be read-write and use a boolean data species.
Example Figure 5-26 shows a CpBinaryNode object used to toggle periodicAlerts for a BO.
Figure 5-26 CpBinaryNode object used to expose periodicAlerts for a BinaryOutput object.
See the “CpAnalogNode Example,” page 5-63, for another Cp object application.
C o n
f i g executionParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 5-9.
normal,processor
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
V i s u a
l
position Read-Write: See “position,” page 5-9. — —
commandText Read-Write: Defines how (and if) thecommand appears on the object’s right-clickcommand menu.
By default, this property is blank—you mustenter text to provide a user command.
Any desiredtext string forthe commandto change alinked prop.
(none)
activeInactiveText Read-Write: Defines how the linkedproperty’s value displays (value output).
Note: A browser user sees only “false” and“true” in the command selection box (pop-upfrom the object’s right-click command menu,see Figure 5-26 below).
Any desireddescriptors forthe two states.
Active,Inactive
State descriptors candisplay at a linkedGxText object.
E n g
i n e e r i n g minExecuteTime,
maxExecuteTime,averageExecuteTime,userData
See Table 5-3 on page 5-8 for informationon these common object properties.
— —
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For moredetails, see “securityGroups,” page 5-10
Trigger Properties None, apart from the standard input property, executeTrigger (typically not used).
CommandsBy default, a newly-created CpIntegerNode object has no right-click command menu
until you enter text in the commandText property (Visual tab).
For a user with “Command, Std” privileges, this command appears on the right-click
menu. Only values between the maxValue and minValue (inclusive) are accepted.
Properties
Inputs
Default Object Shape
Outputs
cmdLink (none)
Inputs
All Inputs / Outputs
Outputs
executeTrigger
cmdLinkvalue
Property Quick Reference for CpIntegerNode Object(only input and output types, see Table 5-16 for all properties)
Type Label Property Name Data Species
input exe executeTrigger TriggerType
cmdLnk cmdLink int
output value value int
Note: This object is nearly identical to the N2IntegerCmd object,previously included in a johnsonn2 JAR. However, the CpIntegerNodeobject is a core (tridium) object, and so can be used in any Niagarastation, without regard to module dependecies.
Table 5-16 CpIntegerNode object properties.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType,statusFlags,description,
See Table 5-3 on page 5-8 for informationon these common object properties.
— —
cmdLink(input: cmdLink)
Read-Only: Current (integer) value of thelinked (target) property, as on the input.
valid integer 0
value(output: value)
Read-Only: Current (integer) value of thelinked (target) property, as on the output.
Link a Gx object to the value output toprovide command access from a GxPage.
valid integer 0 At all times equal tothe cmdLink value.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
FunctionGenerator
5–73
C o n
f i g ,
c o n
t .
minValue Read-Write: Minimum value that can appearat the object outputs.
valid float -10.0 If mode=sinusoidal,internally calculatedvalues are “clipped”
between these two.
maxValue Read-Write: Maximum value that can
appear at the object outputs.
valid float 10.0
increment Read-Write: Depending on mode, this valuefunctions as follows:
• Ramp mode: Step value for each outputchange, either added (when ramping up)or subtracted (when ramping down).
• Sinusoid: The output throttling range usedabove and below the offset value.
valid float 1.0 In sinusoid mode, foran output that variesfrom 0 to 100, use anincrement value of50 and an offsetvalue of 50.
See examples.
mode Read-Write: Defines operation as either:
• Ramp—Linear “sawtooth” output.
• Sinusoid—Sine wave output.
ramp, sinusoid sinusoid
offset Read-Write: Applies to sinusoid mode only
(ignored in ramp mode).Defines the midpoint of the internallycalculated sine wave.
valid float 0.0 The increment
property value isapplied above andbelow this midpoint.
degreesPerCycle Read-Write: Applies to sinusoid mode only(ignored in ramp mode).
Defines the number of degrees (°) of thesine wave’s period covered in eachexecution cycle (output change).Affects the time base of the output, where:
360°/<value> = number of output changes
For example, if degreesPerCycle is 3, thereare 120 output changes for a complete cycle(period) of the sine wave. If the object
executes once every 2 seconds, the sinewave period is 120 x 2 sec. = 240 sec (4minutes). In this case, if degreesPerCycle isset to 9, the period changes to 80 seconds.
integer value,typically from 1
to 12
1 A value of 1 makesthe smoothest (andslowest) sine wave.
A value of 0 freezesthe output atmidpoint.
See also the the“Sinusoid Mode”section onpage 5-74.
priorityForWriting Read-Write: Defines the priority level usedat the prioritizedOutput.
1 to 16 16(Schedule)
units Read-Write: Selection of engineering unitsfor display purposes. Choose from a logicalgrouping, then a specific unit.
For selections see “About Units,” page 5-6.
Select any(BACnet-typeunit choices)
Other,no_units
V i s u a
lposition Read-Write: See “position,” page 5-9. — —
decimalFormat Read-Write: Sets decimal posit ion from 0 to6 places, and optionally force (+) sign forpositive values.
0 to 6,
(+) sign’no (+) sign
2,
no (+) sign
E n g
i n e e r i n g minExecuteTime,
maxExecuteTime,averageExecuteTime,userData
These properties are common to all controlobjects. For more information, see Table 5-3on page 5-8.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
FunctionGenerator
5–74
FunctionGenerator NotesThe FunctionGenerator has two operation modes:
• Sinusoid Mode
• Ramp Mode
Both modes are explained below, with examples shown in Figure 5-30.
Sinusoid Mode When the mode property is set to sinusoid, the object’s sine wave output varies by its
midpoint, magnitude, and number of output changes (granularity). These things are
determined by the values of the following configuration properties:
• increment —Defines the magnitude above (and below) the midpoint. For
example, if you want a total output swing of 8.5, set increment to 4.25.
• offset —Defines the midpoint output value.
• degreesPerCycle —An integer that affects the “granularity” and rate of the
sine wave output. The smallest value (1) produces the smoothest output and
slowest output rate. Values 12 and under are typical. An example calculation:
Note that the object’s execution frequency (seconds per execution cycle) affects the
sine wave period. Also, the minValue and maxValue properties can be configured to
“clip” part of the output. See the third example in Figure 5-30.
Ramp Mode When the mode property is set to ramp, the object’s sawtooth output is determined by the setting of the increment property, and the min and maxValue property settings.
The properties offset and degreesPerCycle are ignored .
• increment —Defines the output step change. This value is added to the output
when ramping up and subtracted from the output when ramping down.
• minValue and maxValue —Defines the smallest and largest values for the
continuous ramp output.
In addition, the object’s execution frequency directly affects the output rate.
E n g
i n e e r i n g ,
c o n
t . prioritizedOutput(output pOut)
Read Only: The current calculated floatvalue, at the priority level specified inpriorityForWriting.
<f. value> @<pri. level>
<f. value>@ 16
statusOutput(input sIn )
Read Only: The current calculated floatvalue and status.
<f. value>status flags
<value>ok
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For moredetails, see “securityGroups,” page 5-10
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
Logic
5–80
Logic ObjectTruth Tables
Truth tables in Table 5-22 show Logic output results from different combinations at
the sInA and sInB inputs, organized by the selected logic function.
Note Outputs results shown below assume the default property values are assigned for
trueCommand (true) and falseCommand (false). Note that these properties areconfigurable to either false, true, or auto. If set to non-defaults, only the
prioritizedOutput follows those defined states, at the defined priorityForWriting
level. The statusOutput always follows the output states (sOut, pOut) shown below.
Notes • There is no operational difference between the A_XOR_B and A_NOT_B
function. Often, the A_NOT_B function is used with a single input link (for
logic inversion) and the A_XOR_B function is used with both inputs linked for
an exclusive OR operation.• Certain arrangements of logic objects provide other logic functions, such as
NAND, NOR, and EQUIV (equivalent) functions. See Figure 5-32.
Table 5-22 Truth tables for Logic object functions.
The output of a Logicobject configured asA_AND_B (with defaultConfig properties) isinverted to produce aNAND gate.
NAND Gate Operation
The NOR function is doneby using two objects.
The output of a Logicobject configured asA_OR_B (with defaultConfig properties) isinverted to produce a NORgate.
NOR Gate Operation
The EQUIV function is alsodone by using two objects.
The output of a Logic
object configured asA_XOR_B (with defaultConfig properties) isinverted to produce anEQUIV gate.
EQUIV Gate Operation
When more than 2 inputsare needed in a booleanoperation, multiple Logicobjects can be cascaded.
For example, an 8-inputAND gate is made usingseven Logic objects, asshown at right. Any of theLogic objects can beconfigured separately,depending on the booleanoperation needed.
This cluster could beencapsulated inside aComposite object, so as toexpose only the first 8inputs and final output.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
Loop
5–82
LoopQuick reference for all properties: Table A-44
abbrev: (none); LOOP
Loop objects provide closed-loop PID
control (proportional, integral, derivative) atthe station level. Independent gain constants
allow the loop to be configured as P-only, PI,
or PID.
The typical Loop application is to provide
setpoint control to a variable output device
when the process variable, setpoint input, or
control variable reside in different physical
locations.
The Niagara Loop object has many
characteristics of the BACnet Loop object,
including the ability for alarming on setpointdeviation.
Parent Dependencies: None (any
container).
Resource Count Range: 75 to 137
Trigger Properties The Loop object has the standard input property, executeTrigger , (typically not used)
plus an additional trigger-type input :
• resetIntegral —Any received trigger pulse clears the current integral
component of the loop’s output calculation. If needed, this input can be linked
to another object to provide a quick purge of the integral effect. Examples
include the changeOfStateTrigger output of a related BinaryOutput object (say
for a supply fan), or a perhaps a Command object. Typically, the later would
provide more of a “debug” utility, and should not be necessary if the Loop
object’s configuration properties are correctly defined.
Also, note that whenever the Loop’s input “statusInhibit” is linked, an integralreset occurs automatically each time a false-to-true transition is received.
In addition, the Loop object also provides two trigger-type outputs:
• eventTrigger —Fires upon each event transition (to-offnormal, to-fault,
to-normal) that has been specified in the property “eventTriggerEnable.”
• covTrigger —Fires upon each change of value at the statusOutput.
As needed, these outputs can be linked to any input using TriggerType data species.
Inputs
Default Object Shape
Outputs
controlledVariable
setpoint
prioritizedOutput
statusOutput
Inputs
All Inputs / Outputs
Outputs
executeTrigger
statusInhibit
controlledVariable
setpoint
action
resetIntegral
eventTrigger
presentValue
prioritizedOutput
statusOutput
covTrigger
Property Quick Reference for Loop Object(only input and output types, see Table 5-23 for all properties)
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
Loop
5–84
C o n
f i g ,
c o n
t .
defaultAction Read-Write: Selection of loop action aseither direct or reverse acting, where:
• direct—Loop output increases as the
value of the controlled variable becomesless than the setpoint value.In a temperature loop, this is typicallyconsidered to be a heating application.
• reverse—Loop output increases as thevalue of the controlled variable becomesgreater than the setpoint value. In atemperature loop, this is typicallyconsidered to be a cooling application.
Note: In some applications usingstatusInhibit and a reverse action loop,different configurations may be desired. Seethe the “Status Inhibit Operation” section on
page 5-88 for more information.
direct, reverse directNote: Loop action isdefined in a manneropposite to most
other controlsystems.
The “action” input, iflinked, can be usedto override thisdefault action (thisrequires a customProgram object).
outputUnits Read-Write: For display purposes, definesthe engineering units of the loop output.Choose from a logical grouping, then aspecific unit.
For selections see “About Units,” page 5-6.
Select any(BACnet-typeunit choices)
Other,no_units
Used in display ofpresentValue,statusOutput,prioritizedOutput,many propertydescriptors on theproperty sheet.
controlledVariableUnits Read-Write: For display purposes, definesthe engineering units of the controlledvariable (received at input sInCtrl). Choosefrom a logical grouping, then a specific unit.
Select any(BACnet-typeunit choices)
Other,no_units
Used in display ofsome propertydescriptors on theproperty sheet.
proportionalConstant Read-Write: Defines the value of the
proportional gain parameter used by theloop algorithm. Used to set the overall gainfor the loop.
A starting point for this value is found by:output range / throttling range.
valid float 1.0 Expressed in terms
of outputUnits overcontrolledVariableUnits.
Must be a positivevalue.
integralConstant Read-Write: Defines the integral gainparameter, in repeats per minute, used bythe loop algorithm. Also called reset rate.Acts on the magnitude of the setpoint error.
valid float,positive only
0.0(no
integral)
maxIntegralGain Read-Write: Defines the largest amount ofintegral gain allowed, typically requiredwhen using PI or PID control.
Note: For PI or PID control, this is
recommended to be set to the same valueas maximumOutput.
valid float,positive only
0.0(no
integral)
Integral effect isignored unless youenter a value here. Ifset less than themaximumOutputvalue, control offsetmay occur.
derivativeConstant Read-Write: Defines the derivative gainparameter, in seconds, used by the loopalgorithm. Acts on the rate of change of thesetpoint error.
valid float 0.0(no
derivative)
Table 5-23 Loop object properties. (continued)
Tab Property Name Description Valid Values Default Notes
See Table 5-5 on page 5-13 for informationon these properties common to allevent-type control objects.
— — * See specificdetails oninhibitTime, the nextproperty.
inhibitTime Read-Write: Duration (Hr:Min:Sec) of thealarm inhibit timer, which applies only if theobject’s input statusInhibit is linked.The purpose is to prevent nuisance alarmson equipment startup and shutdown, andalso to selectively stop Loop output
processing.
The inhibitTime is triggered by a transitionfrom false-to-true at the statusInhibit input.
• When statusInhibit becomes true, alarmprocessing is delayed for the duration ofthe inhibit time. The loop output beginsrecalculating, with the output starting at avalue based solely on the proportional
constant (the integral term is cleared).• Whenever statusInhibit becomes false,
the loop output freezes at its last value,
and alarm processing remains inhibited.
Note: In some applications usingstatusInhibit and a reverse action loop,different configurations may be desired. Seethe the “Status Inhibit Operation” section onpage 5-88 for more information.
any practicalvalue inHr:Min:Sec
00:00:00(no inhibit) A minimum of 1second (00:00:01) isrecommendedwhenever thestatusInhibit islinked.
Alarm processingcompares thecontrolledVariableinput value to thesetpoint value (plusor minus theerrorLimit).
Table 5-23 Loop object properties. (continued)
Tab Property Name Description Valid Values Default Notes
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
Loop
5–88
Status InhibitOperation
The statusInhibit input, when linked , directly affects two separate functions of a
Loop object:
• Output processing —The Loop output “freezes” at the last calculated value
when this input receives a “false” (inactive).
Upon a transition to “true,” the Loop output begins processing, however, theintegral term is initially cleared . This means the loop output starts with a value
based purely on proportional gain (using the current PV and setpoint values).
Typically, this means that the loop output makes a jump towards zero (0) for
both direct and reverse acting loops. If the loop’s value is already at its
minOutput value, obviously it will not move any lower.
Note In the case of reverse acting loops, and depending on the action of the
controlled device to the PV, it may be desired for the loop's output to
move toward its maxOutput output value when the loop's statusInhibit
changes from false-to-true. This can be done by using a Math object
setup to do a Reset function connected to the output of the loop. In thiscase, the Loop would be set to be direct acting and the Reset object
would be setup to reset the loop output, for example, from 0-100 to
100-0. This configuration provides the reverse action desired, and
allows the output of the Reset object to be near the maxOutput when the
loop starts to control.
• Alarm processing —The Loop object stops all alarm processing whenever this
input receives a “false” (inactive). The alarm status of the object cannot
change. This applies whether the object’s statusFlags show a normal (“ok”)
state or “inAlarm” and/or “unackedAlarm” states.
Upon a statusInhibit input transition to “true,” the configured inhibit timer
(property inhibitTime) begins counting down towards zero, at which point theinhibit timer expires. After this inhibit time period, if the object is in an alarm
condition (as defined by its Alarm Setup properties), it will alarm.
Proportional OnlyControl
P-only control is just reset action, where loop output is directly proportional to the
magnitude of the setpoint error (ES) and the size of the proportional gain (K P).
• Output Calculation
• P-only Configuration Guidelines
Output Calculation: P-only loop output is linear, and is calculated as follows:
Output = (K P x ES) + bias (if action = direct)or
Output = – [(K P x ES) + bias] (if action = reverse
where:
ES = [setpt - PV]
A characteristic of P-only control is setpoint offset, which occurs unless the process
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
Loop
5–90
Output Calculation: PI loop output is calculated as follows:
Output = K P x (ES + K I ) + bias (if action = direct)
or
Output = – [(K P x (ES + K I ) + bias] (if action = reverse)
where:
ES = [setpt - PV]
The integralConstant property specifies the integral gain (K I) in “repeats per minute,”
sometimes called a “reset rate.”
Repeats Per Minute—To understand repeats per minute, consider the scenario
where a loop is controlling at setpoint. If a certain setpoint error occurs, say from a
sudden setpoint change, the loop output immediately changes by a level
corresponding to its proportional constant (acting on the P-term). During this
hypothetical example, assume the controlled process does not react from any loop
output change, but stays at the original value (setpoint error stays constant).
The loop’s integral term immediately begins increasing the output (or decreasing the
output, depending on the direction of setpoint error) at specific rate determined by
the integral term. Over the period of one minute, the amount of output change that
would occur is defined by the integralConstant (repeats per minute). A “repeat”
equals the amount of output change initially generated by the P-term. For example,
if this loop was configured with an integralConstant value of 2.0, and the original
output change was +7%, over a period of one minute the integral term would linearly
ramp up the output value an additional +14%, or “2 repeats.” See Figure 5-33.
In a real-world PI loop, of course, the process variable does respond to an output
change, and this continuously-linear ramping of the output would not occur. Instead,
the process variable would start moving towards setpoint and the setpoint error would
change (changing the proportional and integral terms, thus the loop output).
Figure 5-33 Example of Loop integral gain (repeats per minute).
Compare the output of twoLoop objects, both with thesame proportional gain. Thetopmost Loop object has anintegralConstant of 2.0, whilethis property in the otherLoop has a value of 0.0 (nointegral).
The initial setpoint shiftcauses the equivalent outputchange from both objects.The output of the Loop_PIobject continues to ramp up,however, as the process
variable does not respond.After one minute, “two resets”have occurred.
Both Loop outputs change fromP-term (first setpoint change).
P-Only Loop outputstays fixed.
PI loop outputincreased abouttwice the originalamount (tworesets) in the oneminute since thesetpoint change.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
Loop
5–91
Integral Overshoot
The integral term of a PI loop can cause an “overshoot” of setpoint, meaning that the
increased loop output may result in a new setpoint error in the opposite direction. In
some cases, it is possible for this overshoot to continuously repeat (oscillation),
which is typically undesired. However, a small amount of overshoot for an initial
correction is not uncommon.
To minimize overshoot, the PI loop’s integralConstant is typically kept small, and
sized appropriately for the assigned proportionalConstant.
PI Configuration Guidelines
If using PI control, follow these guidelines:
Output limi ts—Define the maxValue and minValue properties for the loop output,
noting that the maximum value must be greater than the minimum.
Proportional Gain—Calculate and enter a proportionalConstant (K P) property
value starting with this formula:
where throttling range is the corresponding result in the process variable.
For example, for a temperature loop where a 0-to-100% loop output results in a 20°
swing in the process variable, a starting point K P is:
When tuning a PI loop, you typically reduce the proportionalConstant value, becausethe integral effect on the output will correct setpoint error over time.
Bias—Assign a value of 0.0 (no output bias). A fixed bias is not desired , because the
integral term of the loop effectively creates an “adjustable bias,” as needed.
Integral Gain—Set the integral gain (property integralConstant) to a nominal value,
typically less than one (1.0). A value of 0.5 is a good starting point for many loops.
Note Make sure to change the maxIntegralGain property from its default (0.0) to a larger
value—in most cases, maxIntegralGain should equal the maxOutput value. If
maxIntegralGain is left at default, the output will not reflect any integral gain.
Derivative Gain—Disable derivative by setting the derivativeConstant property at
0.0 (the default).
Act ion—Define the defaultAction property as either direct or reverse as needed
(noting that the Niagara loop definition is typically opposite to most control systems).
Also, note that by editing the proportionalConstant property value to a negative
value, this effectively “toggles” the action definition.
This Loop object monitorsan AHU’s discharge airtemperature, receives asetpoint from an AO object,and outputs a 0 to 100%output that is used to
position a cooling valve.
Discharge Air AHU) PI Loop Loop Object Configuration:
defaultAction: directoutputUnits: percentcontrolledVariableUnits: degreesFahrenheitproportionalConstant: 1.75integralConstant: 0.50 / min.
(other properties as listed in first example)
This Loop object monitorsthe (minimum) zone headpressure of multiple chilledwater supply lines, andreceives a constantsetpoint of 18 PSI from aMath object. The Loopoutputs a 20 to 100% signalused to control a variablefrequency drive (VFD) forthe chilled water supplypump. A Command object
is used (for tuningpurposes) to clear theloop’s integral term.
Chilled Water Supply Pump VFD Loop Object Configuration:
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
Math
5–97
Math NotesMath objects are commonly used to process float values in the station. The function
property determines the specific math operation (minimum, maximum, averaging, so
forth) performed by the object.
Not a Number(NaN)
The absence of a float value (null value) is represented in the Niagara station as
“NaN,” for “Not a Number.” Typically, you only see NaN from outputs of a device
(shadow) object, and only while that device is down. Note that NaN is different from
zero (0.0), because an object processes zero as a valid value.
By default, a newly created Math object produces a NaN output, at least until
statusInputA is linked. This is because the “default” settings for the config properties
defaultA, B, C, and D, are NaN (and not 0.0 or any other real value). In some cases,
you might want to change these property values to a real float value, as an appropriate
fallback for that input. This default value will be used whenever its corresponding
input receives an NaN or a status “fault” (supplying object is in fault, and colored
orange).
Note that in certain scenarios, the default NaN might be the best choice. For example,
if you are averaging four values received on statusInputsA through D, and a device
that is responsible for one of the values goes down, the default NaN value would give
the most accurate output (for the remaining three input values) because the Math
algorithm ignores the NaN. This same logic applies when configured for the math
functions minimum and maximum.
When configured for other functions, however, you would typically want fallback
values rather than ignored inputs—multiplication and summation, for example. Also,
note that any of the math functions that use only one or two inputs (the majority) do
not ignore NaN. Instead, the Math object produces an NaN output . Depending on
your downstream control logic, this could produce unwanted results.
Usage Notes The following sections explain some Math object topics:
• Simplest Usage
• Reset Function
• Cascading Math Objects
Simplest Usage
A Math object can be used to simply hold a constant value, for example a setpoint,
without even linking any of its inputs. In this case, you enter the constant value as its
“defaultA” property, and simply leave the object’s function at the default of
“summation”. The Math object’s outputs can be linked to float inputs of other objectsthat require this constant value. This is the simplest use of a Math object.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
Math
5–98
Reset Function
Another common use for a Math object is to perform a linear reset on the value
received at its first (statusInputA) input. The reset schedule is defined by the
following four configuration properties:
• outputHighLimit—may (or may not) be greater than the outputLowLimit• outputLowLimit—may (or may not) be less than the outputHighLimit
• inputHighLimit—must be greater than the inputLowLimit
• inputLowLimit—must be less than the inputHighLimit
A classic example is to reset a hot water (boiler) setpoint based upon the present
outside air temperature. In this case, as the outside air temperature (received on the
input) goes down, the desired boiler setpoint will go up—in other words, a reverse
reset. Engineer this by making the outputHighLimit less than the outputLowLimit.
For example, a Math object configured for a boiler setpoint (reverse) reset may have
the following values for these properties:
• outputHighLimit: 130°
• outputLowLimit: 200°
• inputHighLimit: 60°
• inputLowLimit: 0°
When the outside air temperature is 0° (or below), the boiler setpoint calculated by
the Math object will be 200°. Likewise, the boiler setpoint will be 130° when the
outside air temperature is 60° or higher. When outside air temperature is anywhere
between 0° and 60°, the setpoint output is linearly reset.
Valve Compensation—A reset-configured Math object is often used between a
Loop object and an AO object to help compensate for certain valve characteristics.For example, a valve positioned between 15% and 65% may result in from 3% to
98% flow. Although the Loop object is capable of performing a similar reset function
internally, in this case having its outputHigh and outputLow set to 65.0 and 15.0,
respectively, (versus 100.0 and 0.0), this might not be desired. For example, the
0-to-100% loop output value might be needed for display purposes, or be needed in
some other control logic. In this case, a reset-configured Math object could be used
to reset the Loop output, compensating for valve characteristics as needed.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
MultistateInput
5–102
S t a t u
s ,
c o n
t .elapsedActiveTime Read Only: Shows the accumulated runtime
(elapsed active time) formatted inHr:Min:Sec.
Time period upto 9999:99:99(Hr:Min:Sec)
00:00:00 COS andruntime-relateddata is not visible
from a BACnetexposure.timeOfActiveReset Read Only: Shows a date/timestamp forwhen the accumulated runtime (elapsedactive time) was last cleared.
valid timestampor null (none)
null
C o n
f i g
executeParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 5-9.
normal,processor
foreignAddress Read-Write: BACnet usage only. Set to apositive integer for this object to appear as aBACnet Multi-state Input object to otherBACnet devices.
See “foreignAddress,” page 5-9, and also“stateText Considerations,” page 5-104.
0 to 4194302
or -1(not exposed)
-1 Must be a uniquenumber among allMultistateInputobjects in station.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
defaultInput Read-Write: The input value used by theMSI object if its statusInput link is broken orassumes a status that includes “fault.”
Any one statedefined on theVisual tab.
Off Does not apply ifan input value isone of thefaultValues.
See Table 5-5 on page 5-13 for informationon these properties common to allevent-type control objects.
— — * See specificdetails oninhibitTime, thenext property.
inhibitTime Read-Write: Duration (Hr:Min:Sec) of thealarm inhibit timer, which applies only if theobject’s input statusInhibit is linked.
The purpose is to prevent nuisance alarmson equipment startup and shutdown.
The inhibitTime is triggered by a transitionfrom false-to-true at the statusInhibit input.
• When statusInhibit becomes true, alarmprocessing is delayed for the inhibit time.
• Whenever statusInhibit becomes false,alarm processing remains inhibited. Thealarm status of the object cannot change.This applies whether the object’sstatusFlags show a “normal” ok state or“inAlarm” and/or “unackedAlarm” states.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
MultistateInput
5–107
MSI Alarm Notification
Alarming notification determines which type of alarm transitions are sent to the
Niagara alarming subsystem (Alarm Console). Events sent to the alarming subsystem
require user acknowledgment. Using the various recipient options for the target
notificationClass object, event notifications can also be routed to printers, e-mail
addresses, and APIs.
Note Alarm notification is a “step beyond” alarm detection. If you want only alarm
detection (and visual indication) for an object, leave the eventEnable flags cleared.
In the MSI object, properties on the Alarm Setup tab relating to alarm notification
are:
• notificationClass —Must match an existing notificationClass object in the
station’s notificationServices container. The default class is zero (0).
• eventEnable —Flags that determine which event transition types are sent to
the alarming subsystem (to-offnormal, to-fault, to-normal). The default is allflags cleared, meaning that object alarms are not sent for notification. You must
set flags as needed to receive alarm in the alarm console, route alarms, and so
on.
• notifyType —Either event (the default) or alarm. Operation within the Niagara
alarming subsystem is the same for either selection.
However, in a BACnet integration, in a response to a requesting BACnet
client’s “GetAlarmSummary” request, the station reports “BACnet-exposed
objects” currently in alarm only if their notifyType properties are set to alarm.
• alarmText —Text descriptor sent as an alarm record field whenever a
“to-offnormal” or “to-fault” event transition occurs (not a “to-normal”).
MSI Alarm Inhibit
In addition to BACnet-type alarm properties, Niagara provides an alarm inhibit
feature based upon a boolean input to the object. Use of this feature is optional.
Note Whenever the statusInhibit input is linked , the object’s inhibitTime property should
hold a defined value (not the default of 00:00:00 in Hr:Min:Sec).
Otherwise, the MSI object will not be capable of alarming.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
MultistateInput
5–108
Figure 5-38 Alarm inhibit feature requires linking to the statusInhibit input.
The inhibit feature is intended to prevent unintended alarms, such as in after-hours
situations where a piece of equipment is turned off.
MSI Alarm Delay
Alarm delay is a BACnet-type property, separate from the alarm inhibit mechanism.
It means that the object’s statusInput must meet the “alarm-change criteria” for a
continuous period equal to or greater than defined in the timeDelay property, before
an alarm status change occurs.
The alarm delay applies to both types of status transitions:
• “to-offnormal”, meaning normal (ok) to in_alarm.
• “to-normal”, meaning in_alarm to normal (ok).
Note Alarm delay is not applied on any transition to (or from) a fault state.Fault states are defined in the object’s faultValues property.
The general intention of timeDelay is to prevent nuisance alarms caused by
momentary change in the received boolean value. Typically, when both an alarm
delay and alarm inhibit is used, the timeDelay is less (shorter) than the inhibitTime.
MSI AlertNotifications
In addition to (or instead of) alarming on particular discrete state(s), a MSI object is
also capable of generating “alerts,” based upon configurable limits for runtime
(elapsed activeTime) and/or number of COS transitions (change of states). Alerts are
sent to the Niagara alarming subsystem (Alarm Console), and require
acknowledgment. Like alarms, alerts are associated with a specified
notificationClass and can be routed to various recipients.
Whenever a logic false(inactive) is at the statusInhibit (sInh) input, the MSI objectcannot change status to (orfrom) an alarm condition.
Upon a false-to-true (active) transition,the object’s inhibitTime periodbecomes effective. Until this periodexpires, the object remains inhibited from any alarm status change.
After the inhibitTime period expires,the object is capable of changingalarm status to (or from) alarm.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
MultistateInput
5–110
• activeTimeAlertLimit —Amount of runtime, in Hr:Min:Sec, that should
result in an alert notification. If periodicAlerts is set to True, an alert is
generated at each multiple of this value.
Examples Figure 5-39 shows two examples of MSI objects in use.
Figure 5-39 MultistateInput usage examples.
This MSI object receivesan integer value from aDMS shadow objectconfigured to poll for theCOND (condition) elementof an AI point.
The MSI object equates theinteger values to thecorresponding conditionstates.
In addition, different statescan be defined asalarmValues andfaultValues. This can beuseful when the output ofthe MSI object is linked to aGx object such as a GxTextor GxInteger. This permitsalarm indication by color(and optionally, if desired,by flashing).
In this example, an MSIobject is linked to aProgram object written to
link to Lon Devices with anNVO implemented withSNVT_lev_disc.
The Program object has aninput (sIn) usingLonLevDiscEnum (dataspecies) and an output ofIntegerStatusType.
In this case, the output ofthe MSI is using thedefaultInput (off), as thestatusInput is receiving the255 integer valuerepresenting a null value.
MSI object
On the Alarm Setup tab ofthe MSI object’s propertysheet, different states canbe defined as alarmValuesand faultValues.
The stateText property of the MSIis configured to match the CONDelement enumerations possiblefor DMS analog points.
DMS strings were used here, butany descriptors could be entered.
stateText values mustbe contiguous and no
higher than 7.
The defaultInput value is on theMSI object’s Config tab.
stateText is definedto represent theSNVT_lev_discstate enumerations.
See Table 5-4 on page 5-12 for informationon these properties common to allevent-type control objects.
— — presentValue isalways read-only.
changeOfStateTime Read Only: Shows a date/timestamp for thelast COS (change of state).
valid timestampor null (none)
null Trigger-type inputscan be used toclear COS andruntime values.
COS and runtimeproperties have noBACnet visibility ifthe object isexposed asBACnet (these arenot included instandard BACnetmultistate objectdefinitions).
changeOfStateCount Read Only: Shows the total number ofchanges of state that have occurred sincethe last COS count reset (clear).
integer value 0
timeOfStateCountReset Read Only: Shows a date/timestamp forwhen the COS count was last cleared.
valid timestampor null (none)
null
elapsedActiveTime Read Only: Shows accumulated runtime(elapsed active time) in Hr:Min:Sec.
Time period upto 9999:99:99
00:00:00
timeOfActiveReset Read Only: Shows a date/timestamp forwhen the accumulated runtime (elapsedactive time) was last cleared.
valid timestampor null (none)
null
P r i o
r i t i e s
priorityArray(input: pIn )
Read Only: Shows defined states presenton each of the 16 priority level slots for thepriorityArray (pIn) input.
<state n> orauto,
levels 1 to 16
auto
1 to 16
relinquishDefault Read-Write: Defines the output state whenall 16 priority level slots have an “auto”. <state n> Off
inInterstartDelay Read Only: Indicates if an interstart delay iscurrently active (True) or not (False).
False, True False
C o n
f i g
executeParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 5-9.
normal,output
foreignAddress Read-Write: BACnet usage only. Set to apositive integer for this object to appear asa BACnet Multi-state Output object to otherBACnet devices.
See “foreignAddress,” page 5-9, and also“stateText Considerations,” page 5-116.
0 to 4194302
or -1(not exposed)
-1 Must be a uniquenumber among allMultistateOutputobjects in station.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
restartDisable Read-Write: Determines whether the outputis automatically set to the previous statefollowing a station restart (reboot) or powerfailure. If set to True, an “Off” state atmanual level (8) is issued following such anoccurrence.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
MultistateOutput
5–114
C o n
f i g ,
c o n
t .
minimumOnTime Read-Write: Upon a command from the“Off” state to any other state, results in thestate command to be stored at the Minimum
On Off priority level (6) for this time(Hr:Min:Sec).
Any practicaltime needed.
00:00:00
minimumOffTime Read-Write: Upon a command from anyother state to the “Off state,” results in theOff command to be stored at the MinimumOn Off priority level (6) for this duration(Hr:Min:Sec).
Any practicaltime needed.
00:00:00
perStateMinimumOnTime
Read-Write: Specifies whether theminimum On time is applied between allstates (True) or only from the Off state (firststateText entry) to any other state (False).
False, True False
interstartDelayTime Read-Write: Defines the time period(Hr:Min:Sec) that the output is held in the“Off” state following a command to anyother state. Used to prevent multiplesimultaneous starts. Applies to commandsat all priority levels except Emergency (1).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
MultistateOutput
5–116
MultistateOutput Notes
The MSO object is typically used for control of a multistate device or mode ofoperation. In some cases, a MSO object is used to directly control a physical output
of a remote device, represented by a shadow object.
RoutinelyConfigured MSOProperties
The three most typically configured properties for a MSO object are:
• relinquishDefault (Priorities tab)—Defines the MSO object’s output state
when all 16 of the priority-level slots at the priorityArray input have an “auto.”
The default value is Off (first stateText entry).
• stateText (Visual tab)—Defines the object’s possible discrete (integer) states
and the associated text descriptors that appear at the object’s outputs. Eight (8)
or more states can be defined. Descriptors are seen as options in right-click
“Set” and “Emergency Set” command menus, also in linked GxText objectsand in the accumulated data of a linked MultistateLog.
See the next section “stateText Considerations” for additional details.
• commandTags (Visual tab)—Defines how user commands appear on the
object’s right-click command menu. See “MSO Command Tags” on
page 5-118.
If alarming functions and/or alerts are needed, additional Alarm Setup properties are
configured from default values.
stateText Considerations
When exposing a Niagara MSO object as a BACnet object, be aware that you must
first edit its stateText property to be consistent with the BACnet definition.
Specifically, a zero (0) value is not allowed, plus all values must be contiguous.
The stateText property is on the Visual tab (Figure 5-40).
E n g
i n e e r i n g , c
o n
t .
prioritizedOutput
(output pOut)
Read Only: Current discrete state andpriority level of the prioritizedOutput.
<dis. state> :@ <pri. level>
Off : @ def
statusFeedbackOutput
(output sFbOut)
Read Only: Current discrete state andstatus of the feedback supplied on thestatusInput. If statusInput is not linked, thisoutput always mirrors statusOutput.
<dis. state> :status flags
Off : ok
booleanStatusFeedbackOutput
(output bsFbOut)
Read Only: Current command state as aboolean, either false if command is “Off” ortrue if any other command. Status followsstatusFeedbackOutput.
false, true :status flags
false : ok
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For moredetails, see “securityGroups,” page 5-10
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
MultistateOutput
5–117
Figure 5-40 If exposing as BACnet, the MSO object must have stateText with contiguous values, and with no zero (0).
StateText Guidelines—If you follow these guidelines when assigning stateTextvalues, you can then expose an MSO object as BACnet.
1. Assign numerical states starting at 1 (not 0, as with a standard Niagara MSO).
For a two-speed object, for example, this means 1 = Off, 2 = On, and 3 = Fast,
vs. the numerical 0, 1, and 2 assignments used in stateText defaults.
2. Assign state numbers contiguously (without skipping a number). This
contiguous restriction is from BACnet.
Note If you already assigned a foreignAddress value to expose the MSO object, but did so
before stateText complied with these guidelines, you will need to reassign the
foreignAddress value (first to -1 and then back to the desired value).
Niagara stateText Default Feature—A Niagara MSO object provides a
“default” state and an associated text descriptor, which is used whenever a received
input value does not equal one of the assigned numerical states. Typically, this
indicates an error condition. In the stateText property, the default state cannot be
deleted. However, the text descriptor can be edited from “Error,” if needed.
Note There is no “default” state equivalent for a BACnet Multistate Output object.
Control RelatedPropertiesThe MSO object includes several Config properties that directly determine thecontrol operation of its main outputs (prioritizedOutput and statusOutput).
• restartDisable —Determines how outputs are set following a station restart,
host reboot, or power failure. Settings False and True are as follows:
– False (the default), restores outputs automatically to the previous state.
– If set to True, outputs are set to Off at the “Manual” level (8).
This MSO object has had itsstateText property edited toremove the 0 value.
Other values were modifiedand added as needed, usingthe “StateText Guidelines” (below).
Default stateText valuesfor a Niagara MSI andMSO object include thenon-compliant “0” value.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 5 Control Objects
MultistateOutput
5–120
MSO Alarm Inhibi t
In addition to BACnet-type alarm properties, Niagara provides an alarm inhibit
feature based upon a boolean input to the object. Use of this feature is optional.
Note Whenever the statusInhibit input is linked , the object’s inhibitTime property shouldhold a defined value (not the default of 00:00:00 in Hr:Min:Sec).
MSO Alarm Delay
Alarm delay is a BACnet-type property, separate from the alarm inhibit mechanism.
It means that the object’s statusInput must meet the “alarm-change criteria” for a
continuous period equal to or greater than defined in the timeDelay property, before
an alarm status change occurs.
The alarm delay applies to both types of status transitions:
• “to-offnormal”, meaning normal (ok) to in_alarm.
• “to-normal”, meaning in_alarm to normal (ok).
The general intention of timeDelay is to prevent nuisance alarms caused by
momentary change in the received integer (state) value. Typically, when both an
alarm delay and alarm inhibit is used, timeDelay is less (shorter) than inhibitTime.
MSO Alarm Notification
Alarming notification determines which type of alarm transitions (events) are sent to
the Niagara alarming subsystem (Alarm Console). Events sent to the alarming
subsystem require user acknowledgment. Using the various recipient options for the
target notificationClass object, event notifications can also be routed to printers,
e-mail addresses, and APIs. If the MSO object is exposed as a BACnet object,
BACnetRecipients can also be designated.
Note Alarm notification is a “step beyond” alarm detection. If you want only alarm
detection (and visual indication) for an object, leave the eventEnable flags cleared.
Figure 5-44 MultistateOutput statusInhibit input and inhibitTime property.
The statusInhibit input istypically linked to the samesource that is controllingthe MSO.
When the MSO iscommanded from Off toany other state, any alarmstatus change is inhibitedfor the specified
inhibitTime, in seconds.
When commanded to Off,any alarm status change isinhibited for 3 times theinhibitTime, in seconds.
priorityArray input linkfor control command
Feedback signal linkedto statusInput (sIn)
Example:inhibitTime = 30 (seconds)
When commanded to Off fromany other state, the alarm inhibitdelay will be 90 seconds.
statusInhibit (sInh) link (BooleanStatusType data species)
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
About Apps Objects
6–2
About Apps ObjectsApps objects provide a variety of system functions that are linkable to a station’s
control logic, including:
• Global schedule operation of binary-controlled loads, including holiday andspecial-event definitions.
• Data-logging of various values and status originating from object outputs.
• Custom control routines, using a “design-your-own” (Program) object.
• Special Niagara station utilities.
All of these things can be needed when engineering a building automation system.
Apps objects are executed in the station by the “control engine” (managed by the
ControlEngineService ), along with all “control” objects. Most Niagara stations are
engineered to use some control and apps objects, in addition to other child-only
(primitive) objects. These other objects include shadow objects and Gx objects.
BACnet Heritage
Selected Niagara apps objects are implemented like the equivalent BACnet objects
(used to model data in BACnet devices). Because a Niagara station is inherently
capable of being integrated as a BACnet device, this feature allows it to expose these
objects directly as BACnet objects, namely:
• Calendar objects
• Schedule objects
In a BACnet integration, the BACnet service makes the Niagara station a BACnetserver to provide client access to these objects (to other networked BACnet devices).
At the same time, the BACnet service allows the station to have client access to
BACnet objects in remote BACnet devices, through the use of special BACnet
shadow objects. Currently, however, Calendar and Schedule objects can only be
exported (no shadow objects for foreign BACnet Calendar and Schedule objects).
Refer to For detailed information on Niagara and BACnet, refer to the Niagara BACnet
Niagara Standard Programming Reference Revised: April 20, 20046–5
Common Apps Object Properties
Table 6-1 lists common properties organized in the property sheet tab in which you
can find them. In the case where some property variation exists for a particular type
of object, that difference is noted in the property table for that object type.
Table 6-1 Common propert ies for al l apps objects.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType Read Only: The apps object type. Bydefault, a newly added object uses thisstring in its name (until renamed).
The full string for the object type is shown,for example, AnalogLog or Calendar.
See description reflectsobject type
For most object types, astandard abbreviation forthat type appears insidethe object’s shape (nearthe top).
This abbreviation isnoted in the individualdescriptions for eachapps object.
statusFlags Read Only: Current state of the object’s
status flags. A “normal” state (no flags set)is where the status flags value is “ok”, andthe object’s color is gray.
The only status flag that can be set is:
• down—The station is down or offline.The object ‘s shape and outputs areyellow.
either:
ok (no flags)
or
down
ok Unlike many control
objects, apps objects donot have alarm states,nor do they “assume”alarm or fault conditionsfrom linked inputs.
description Read-Write: Permits a user-defined textdescriptor for describing the object. Anyprintable characters, including spaces andmixed case characters, are allowed.
See description — Not available for anAdminTool object.
For a log object, ifdescription is entered, itappears in the object’sLogChart title.
Also used to list the log inthe station’s log indexand in the Log Selector .
C o n
f i g
executionParameters
Read-Write: Defines the frequency andorder for the object as it is executed by thestation’s control engine.
• freq (frequency)—Specifies how often theobject is executed. For most apps objects,the default frequency (normal) isacceptable. For Calendar and Schedule
objects, frequency is fixed at minutely.
• order—Specifies the order of execution ineach cycle. On each cycle of the control
engine, objects specified as inputs areprocessed first, then processors next, andlastly the outputs.
By default, all apps objects default to theprocessor order.
freq:never slower normalfaster fastest
minutelyon_trigger
order:input
processor output
freq:normal
order:<see
descrip>
This property is notavailable (nor applies to)an AdminTool object.
Usually, default valuesare recommended.
Frequency selectionsare exclusive.
For example, ifon_trigger is selected,the object will execute
only if the inputexecuteTrigger is linkedand a trigger pulse isreceived on that input.
For related details, seeControlEngineServiceConfig property“executionFrequency”.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
Common Apps Object Things
6–6
C o n
f i g ,
c o n
t .
foreignAddress Read-Write: BACnet usage only. Exposesthe Niagara object as a BACnet object.
Note: Currently, this property has apractical application only for apps objecttypes Calendar and Schedule (as well ascontrol objects AI, AO, BI, BO, MSI, MSO).
For these object types, a valid value is from0 to 4194302 (BACnet maximum), or -1if not exposed to BACnet.
SeeDescription
If assigned, this
number mustbeunique in the
station within
an object type
(Calendar,Schedule, etc.)
-1
(not used)
Not shown for anAdminTool object.
Before using, the
BACnet service must beinstalled and configuredin the station.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
V i s
u a
l
position Read-Write: The x-y coordinates for theobject’s position on the JDE Workspace.
Coordinate values are in pixels, and arerelative to the upper-left corner of theWorkspace and the upper-left corner of theobject shape (including its input area).
An object with a position of “0,0” is in the topleft corner of the Workspace.
Some positivex, y value less than the parent
(container)object’s “size”
property value.
Near themousepointer
when theobject is
firstcreated.
Typically, you don’tmanually enter positionvalues, but use themouse to drag the objectas needed on the JDE
Workspace.
However, if needed, youcan enter values directlyto “tweak” an object’sposition.
E n g
i n e e r
i n g
minExecuteTime Read-Write: Can show the object’sminimum execution time, in mil liseconds.
Shows MAX_VALUE if “profileNodes” in theControlEngineService was not previouslyset (since the last station start).
integer, 0 to n Seedescrip.
Providing that theControlEngineServicewas set to“profileNodes”, theseproperties show theobject’s executionstatistics. Typically, youdo not leave theControlEngineServiceconfigured this wayexcept for brief periodsto collect these values.
This properties are notavailable (nor apply to)an AdminTool object.
maxExecuteTime Read Only: Can show the object’smaximum execution time, in milliseconds.
Shows MIN_VALUE if “profileNodes” in theControlEngineService was not previouslyset (since the last station start).
integer, 0 to n Seedescrip.
averageExecuteTime
Read Only: Can show the object’s averageexecution time, in seconds.
Shows 0.0 if “profileNodes” in theControlEngineService was not previouslyset (since the last station start).
valid float Seedescrip.
userData Read-Write: Stores a user entered string.Can be used by servlets and the API forconfiguration information.
Any desiredtext string for
servlet/API use.
<blank>
S e c u r i t y
securityGroups Read-Write: Shows the security groups towhich the object is assigned. A user musthave the appropriate privileges in at leastone security group to view and modifyproperties and issue commands.
Refer to the “Security Tab” section onpage 1-20 (Station object UserAdmin topic)for more details on how securityGroupssettings apply.
Any mix ofthese types:
•General•HVAC
•Security
•Life Safety
•Group 4
•Group 5
•Group 6
•Group 7
General Also refer to the “AboutSecurity” section onpage 1-21.
Table 6-1 Common properties for all apps objects. (continued)
Tab Property Name Description Valid Values Default Notes
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
Common Apps Object Things
6–8
Timestamp notes
When viewing logs, the timestamps (date, time, and time zone) always reflect the
serving Niagara host’s time—that is, the station with the log objects. For example, a
BinaryLog object in a station in New York (EST, or Eastern Standard Time zone)
showing On/Off times of 8:00AM/5:00PM would have a LogTable similar to:
The time zone is actually stored as an integer “offset” from UTC (Universal Time,
Coordinated)—specific to the Niagara host that contains the log. Note that UTC “0”
(no offset) is equivalent to GMT (Greenwich Mean Time). This integer is visible
when saving log data in a pure text format, such as “text/comma-separated-values.”
For example, if saving the BinaryLog data above as “text/tab-separated-values,” theinteger offset (for time zone) is “-5” (EST is five (5) hours behind GMT).
2002- 03- 15T08: 00: 00. 78-5 t r ue On ok2002- 03- 15T17: 00: 12. 78-5 f al se Of f ok2002- 03- 16T08: 00: 10. 79-5 t r ue On ok2002- 03- 16T17: 00: 12. 78-5 f al se Of f ok
In the United States, these UTC offsets appear as:
• -5 for EST (Eastern Standard Time)
• -6 for CST (Central Standard Time)
• -7 for MST (Mountain Standard Time)
• -8 for PST (Pacific Standard Time)
Archive Timestamps—Archives, meaning logs that have archived to a Web
Supervisor station (see “Archive (SQL) Storage”) have a timestamp reflecting the
archive host’s time zone. In many cases the Web Supervisor (archive host) and remote
stations are in the same time zone. However, be aware that if a remote station is in a
different time zone from the Web Supervisor, that archive data from it appears with a
timestamp relative to the Web Supervisor.
For example, if the BinaryLog object (above) in New York archived remotely to a
Web Supervisor running in Los Angeles (PST, or Pacific Standard Time zone), the
archive data would be relative to PST, and look like:
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
Common Apps Object Things
6–10
Log Storage A log object collects and stores logs locally, in its own log buffer . The buffer
designates an area of RAM allocated by the station for logs. It is important to note
that the station treats buffered logs as critical data, and periodically stores them as
persistent data—in fact, as part of the station’s runtime database. Whenever a Niagara
station is backed up, this includes the contents of all log objects’ buffers.
Note The LogChart view (available for any AnalogLog, BinaryLog, IntegerLog and
MultistateLog), and the LogTable view (available for any log object) shows log data
from logs stored in the object’s log buffer . All logs in the buffer are included.
Archive (SQL) Storage—In addition to its log buffer, each log object can archive
its logs to an application database, meaning the SQL relational database running on
the supervisor station. The station’s LogService performs this archive routine.
Each log object has an “archiveSetup” config property that specifies archive times,
such as “nearFull” and “daily” (plus a trigger input to cause an archive). When a log
object archives its logs, its log data is “pushed” to the SQL database on the supervisorstation. Log samples in the object’s log buffer remain unaffected. Refer also tothe
“DatabaseService” section on page 4-15 and the “LogService” section on page 4-30.
Note If a job has one or more stations configured with the PollArchiveService (Niagara
module “multisite”), log data in remote stations can be “pulled” to its SQL database.
To use this feature, log objects require the “polled” flag to be set in their
archiveSetup property (along with any other archive flags). For more details on this
service, refer to the “PollArchiveService” section on page 4-40.
Buffer Size and Resource Count
The size of any log object’s buffer is configurable (property bufferSize). The default
buffer size is 60, with an allowable range from 1 to 11,5201.
Caution A log object consumes a station “resource count” in direct proportion to its
configured bufferSize. This applies whether or not any log samples (logs) exist.
A log object with the default bufferSize (60) consumes a resource count of
approximately 120 to 150 (this allows 60 to 90 for the object’s overhead).
The same object assigned a bufferSize of 1000 consumes a resource count of 1060
to 1090 (note the “one-to-one” increase in bufferSize to resource count).
If bufferSize is set to the 11,520 maximum, the object consumes a whopping 11,600
resource count! Obviously, this is not desirable, especially in a JACE-4/5 stationdatabase that may be limited to a total resource count of 300,000.
Resource count is less of an issue when engineering a station database for a JACE-NP
or a Web Supervisor. However, other considerations apply to locating log objects,
especially in multi-station jobs. See the next section, “Location of Log Objects.”
1. Niagara release 2.2 bufferSize limit is 11,520. In release 2.1, the limit is 1500.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
Common Apps Object Things
6–14
Log Selector
The log selector is a special feature of the WebUIService. A browser user can use the
log selector to graph multiple log objects and/or archives in the same LogChart. The
user can also use the log selector to select a single log object or archive, and direct its
output to the browser as a text table in a selectable format of either HTML, CSV
(comma-separated-variable), or XML.
The URL to launch the station’s log selector is:
ht t p: / / <host >/ char t / l og
This produces the log selector dialog, as shown in Figure 6-6.
Figure 6-6 Log selector dialog is a special feature of the WebUIService.
A link to the Log Selector is included among the list of “Browser View” links in the
station’s Niagara Help Index. For more details on special browser views that apply
to log objects, refer to Chapter 4, “Services.”
TipIf you want to provide a link to the log selector from the LogChart view forany log object, you can copy the defaultChartTemplate.html file from the
tridium JAR, and then edit it (adding a line for the log selector, Figure 6-7).
Then save the template file in a folder under the station’s database. Reference
this template file in each log object’s property, chartTemplateUrl, as needed.
Selection buttons forlisting logs by objectname only, or by swid.
Also, options to selectarchives only, orarchives and logs byswid (applies if stationhas DatabaseService).
You can “title” a log selectorselection. This title appears inthe LogChart results.
This is also this file name used(in a charts folder under thestation folder) if the if the “Saveto Server” button is used.
Selection list ofavailable log objectsand/or SQL archives.
Niagara Standard Programming Reference Revised: April 20, 20046–15
Figure 6-7 Log selector link can be added to a modified chart template HTML file.
Common LogObjectProperties
Log objects have a group of “Common Log Properties”, similar to many used for theBACnet Trend Log object. These status and config properties are explained in this
section. In the case where a property variation exists for a particular object type, that
difference is noted in the property table for that specific object.
Trigger Properties
All log objects have identical trigger-type properties, both inputs and outputs. These
properties are explained here and also listed and described in the “Trigger Properties”
section in each object’s description.
As needed, these trigger-type inputs and outputs can be linked to other objects that
have properties using TriggerType data species.
Trigger Inputs—Aside from the common “executeTrigger” input (rarely used),
each log object has two additional trigger inputs:
• doArchiveTrigger —A received pulse causes the log data currently held in the
object’s log buffer to be archived (sent to the LogService archive destination).
• doClear —A received pulse causes all log data currently held in the object’s
log buffer to be cleared.
Trigger Outputs—Each log object also has two trigger outputs:
• recordedTrigger —Fires upon each recorded log sample.
• archivedTrigger —Fires each time the object’s log buffer is archived.
Log ObjectCommands
For any log object, a JDE or Web browser user with Admin-level privileges has the
following right-click commands available:
• clear —Clears all log data currently held in the object’s log buffer.
• archive —Archives all log data currently held in the object’s log buffer.
In this example, a single line was added to thedefaultChartTemplate.html file (before the server line):
<a href=”/chart/log”> Run Chart Selector </a>
After editing and saving the HTML template file, you willneed to reference its URL from any log object that needsto use it. (chartTemplateUrl property, on the Visual tab.)
The browser user nowhas a Log Selector linkwhen viewing the logobject’s LogChart.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
Common Apps Object Things
6–16
• clearLastArchive —Resets the status property lastArchiveTimestamp from a
valid timestamp value to a “null” value. A subsequent archive will add all log
records to its archive (duplicate and out-of-sequence records are possible).
Note, however, that no archived data is removed from the SQL database.
Not typically needed (or wanted), except in cases where a running station
database was saved and loaded in a new host, or perhaps where host time waserroneously set ahead, archives made, and then time was corrected.
Common LogProperties
Each log object includes a number of status and config properties common to all log
objects, described in Table 6-2. Essentially, these properties function the same for
any type of log object. Differences, if any, are noted in each log object section.
The AnalogLog and IntegerLog object have additional Config properties, which are
described in the properties table for those object types.
Table 6-2 Status and Config properties common to all log objects (AnalogLog, BinaryLog, and others).
Tab Property Name Description Valid Values Default Notes
S t a t u s
description Read-Write: Permits a user-defined textdescriptor for describing the log. Anyprintable characters, including spaces andmixed case characters, are allowed.
If description is entered, it appears in theobject’s LogChart title.
See description — Also used to list thelog in the station’s logindexhttp://<sta>/log/indexand in the LogSelector .
lastArchiveTimestamp Read Only: Shows a date/timestamp forwhen the last archive occurred. Shows “null”if there have been no archives or if theclearLastArchive command was given.
— null As with buffered logdata, is saved in thestations configdatabase.
C o n
f i g
executionParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 6-5.
normal,processor
foreignAddress Read-Write: Does not apply to a log object. -1 -1
bufferSize Read-Write: Defines the number of logsamples for the object that can reside locally(in RAM
The necessary allocation of “resourcecounts” (RAM) is set aside based upon theentered number.
1 to 11520 60
stopWhenFull Read-Write: If set to True, logging stopswhen the number of unarchived log samplesequals the configured bufferSize.
If set to False (the default), the log bufferalways rotates—this means that the oldestsample is overwritten as each new logcontinues to be recorded.
False, True False If archiveSetup is setto nearFull, astopWhenFull of Trueis overridden (loggingcontinues). IfarchiveSetup is set todaily but
stopWhenFull isTrue, loggingcontinues after thedaily archive, at leastuntil the log buffer isfull.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
AdminTool
6–18
AdminToolQuick reference for all properties: Table A-1
abbrev: (none); AdminTool
The AdminTool object is a special “utility”
apps object, available in the Local Library(tridium JAR file: tridium/apps/AdminTool).
This object provides an admin-level
command to “Search and Replace” property
values for objects in the station database.
Config properties define the property name to
search, new value to write, plus other
parameters for filtering and recursion. This
operation automates what would otherwise
be a manual process of opening and
modifying multiple objects’ property sheets.
Parent Dependencies: None (anycontainer).
Resource Count Range: 31 to 53
Trigger Properties None.
CommandsA JDE user with “Command, Admin” rights has this available right-click command:
• searchAndReplace —Executes the object’s search and replace function, as
defined in its Config properties.
Caution There is no undo for any station database changes made with the AdminTool object.
It is recommended that you export the station database frequently.
Also, no range-checking is performed before changing property values (unlike
when using the property sheet of an object). You are responsible for entering
appropriate new values when using the AdminTool object.
Properties
Inputs
Default Object Shape
Outputs
(none) (none)
Inputs
All Inputs / Outputs
Outputs
(none) (none)
Input / Output Property Reference for AdminTool Object(only input and output types, see Table 6-3 for all properties)
Type Label Property Name Data Species
input — — —
output — — —
Table 6-3 AdminTool ob ject proper ties.
Tab Property Name Description Valid Values Default Notes
S
t a t u s objectType,
statusFlagsSee Table 6-1 on page 6-5 for information onthese properties common to all apps objects.
— —
C o n
f i g
rootNode Read-Write: The swid of the starting point(upper hierarchy) of the station database inwhich the AdminTool function operates.
This can range from the station’s root(/db/stationName) to any container or primitiveobject in the station’s database. If therecurseChildren property is True, theAdminTool function applies to any and allobjects under the rootNode swid.
valid swid forthe station
— In Tree View, aright-click “copy” onany object under thestation captures itsswid. Use CTRL-Vto paste the swidinto the rootNodefield of the propertysheet.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
AdminTool
6–19
C o n
f i g ,
c o n
t .
propertyName Read-Write: The target property name, exactlyas shown on the object(s) property sheet(s).The property should be a read-write type.
Not all properties can be modified.
valid propertyname
-
elementName Read-Write: Not required for most propertiesthat specify a single value of type float, integer,boolean, or string. Example properties of theabove types, in order:
However, elementName is required for “flag”properties shown as check boxes, propertieswith time in Hr:Min:Sec, and several otherproperties that have separate fields.
See descrip. - See Table 6-4 onpage 6-20 for exactelementNameproperty valuesrequired for selectedproperty types.
newValue Read-Write: The new value assigned to allmatching properties in (and under) the
specified rootNode.• Enter float, integer, or string values directly.
• For boolean-type properties represented as:
– False or True
– Inactive or Active (or the equivalent text)
Enter “false” or “true” (without quotations).
• If a check box property, also use false (toclear) and true (to set) the specified flag.
See descrip. - No range-checkingis performed
(illegal values arepossible)!
For selectedproperty types,exact newValueproperty values arerequired. SeeTable 6-4 onpage 6-20.
recurseChildren Read-Write: Defines if the search-and-replacefunction is extended to all children (andsubchildren, etc.) of the specified rootNode.
False, True False If set to False, onlythe rootNode objectis affected.
objectTypeFilter Read-Write: Defines a match filter, meaning
only objects of this matching type are affected.The asterisk (*) is used as a “wildcard.”
Partial strings of object types are supported, forexample, AnalogO* will apply to object typesAnalogOutput and AnalogOverride.
valid Niagara
object types
* See the examples
shown in Figure 6-8 and Figure 6-9,
nodeNameFilter Read-Write: Defines a match filter, meaningonly objects with matching name are affected.The asterisk (*) is used as a “wildcard.”
Partial strings of object names are supported,for example, AHU_1* will apply to objectsnamed AHU_1_SA and AHU_1_RA.
valid objectnames in the
station’sdatabase
* See the exampleshown inFigure 6-10, and the“Wildcard Notes”section onpage 6-25.
C o n f i
g ,
c o n
t . propertyValueFilter Read-Write: Defines a match filter, meaningonly objects with this exact value are affected.
The asterisk (*), when used alone, acts as a“wildcard.” (A value AND asterisk do not work.)
existing valueof the target
property
* See the exampleshown in Figure 6-8.
V i s u a
lposition Read-Write: See “position,” page 6-6. — —
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For more details,see “securityGroups,” page 6-6
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
AdminTool
6–20
AdminTool NotesThe AdminTool object can save time when engineering a Niagara station, especially
when the same property change needs to be made to multiple existing objects.
Consider it a “power user” tool. However, be aware that there is no undo for any
station database changes that you make with it. For this reason, it is recommended
that you first use the AdminTool object in a “test” setting, for example, with the Niagara demo database. This will allow you to see how the object works.
Notes • The AdminTool object “search-and-replace” function is performed only by a
running station—in other words, the station is doing the work. This object you
use in the JDE merely provides an interface to this routine.
• Ideally, when engineering a station, property values of objects should be set
carefully before the objects are replicated throughout the station’s database.
However, the AdminTool object can be useful if this was not done.
• Some properties cannot be modified via the AdminTool object. These include
ones with complex datatypes (arrays of strings, etc.).
• Properties with multiple elements can only be modified “one element at a
time.” For example, limitEnable for an AI or AO object requires different
AdminTool configurations to set both flags (“low-limit” and “high-limit”).
• In the JDE, you can run the object’s searchAndReplace command directly from
its open property sheet—access it from the Commands menu.
• Results to Standard Output are limited, but you can observe some information
by opening a Standard Output window before issuing the searchAndReplace
command. Typically, successful operations have lines with “Checking:
<objectName> [number] <objectType>,” and end with “Script complete!”
Element NameReference
For most simple float, integer, boolean, or string value properties, the elementName
property can be left blank. Table 6-4 provides information needed when modifying
some properties that do require the elementName field.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
AdminTool
6–24
Stopping FunctionGenerators
In this example, shown in Figure 6-9, the AdminTool object is configured to stop all
FunctionGenerator objects under a container “/db/NetSup2000/TestAHU_Type_1.”
The required elementName entry (frequency) and the different newValue
enumerations for the property executionParameters can be found in the Table 6-4.
Figure 6-9 AdminTool object showing element usage and object type filter.
Changing LimitEnable for AIs
The example shown in Figure 6-10 has an AdminTool object configured to set the
“high-limit” flag for all AI objects in the station with a name containing “RATemp.”When working in property sheets, the high-limit flag is set or cleared using a check
box for the limitEnable property.
Figure 6-10 AdminTool object setting a “check box” type property, using filters.
Because it has multiple elements,this property requires an exact string entered in elementName.
Func* is more than sufficient toaffect only FunctionGenerators.
Later, this can be set back to normal and the object’s command rerun(to restart the FunctionGenerators).
Because it has multiple elements,
this property requires an exact string entered in elementName.
Setting recurseChildren to True isnecessary to modify all child objects.
Filter properties are “match” filters, and can be used incombination (as done here).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
AdminTool
6–25
The required elementName entry (highLimitEnabled) for the property limitEnable
can be found in the Table 6-4. The objectTypeFilter property is set to “AnalogIn” so
that only AnalogInput objects are affected.
The newValue is set to “true” (to set the flag). To clear the flag, newValue would be
set to “false”. In this case, the propertyValueFilter was set to “false” just to prevent
changing something that already existed.
AuditLog Notes
All property value changes made using the AdminTool object are recorded by the
station’s AuditLogService, complete with a timestamp and the new property value.
Note, however, that the userName field will report “unknown” for these changes.
Wildcard Notes
The following two search filter properties for object type and object name work with
wildcard (*) characters that are either leading, trailing, or at both ends.
• objectTypeFilter —To match the Niagara object type.• nodeNameFilter —To match the name of the object(s).
The default value for each property is the single wildcard character: *
which matches all types or names.
A leading wildcard example is an objectTypeFilter of: *Input. This would apply to
object types AnalogInput, BinaryInput, and MultistateInput.
A trailing wildcard example is a nodeNameFilter of: Ch1*. This would apply to any
object with a name beginning with “Ch1,” such as Ch1sPump, Ch1rTemp,
Ch1sTemp and so on.
Wildcards at both ends of the value also can be used. An example is a
nodeNameFilter of: *1s*. This would apply to any object that contains the characterstring “1s” in its name, for example, Ch1sTemp, Ch1sPump, AHU1sFan, and so on.
Note The propertyValueFilter property value can also contain a single wildcard (*),
the default. However, a wildcard does not work with any entered value.
See Table 6-2 on page 6-16 for moreinformation on these properties common to
all log objects.
— — The collectionMode default is interval.
outputFunction Read-Write: Determines the method used tocalculate the statusOutput value usingrecorded logs, where the output is either:
• current—The last recorded log sample.
• minimum—The minimum recorded log.
• maximum—The maximum recorded log.
• average—The average of recorded logs.
• sum—The sum of all recorded logs.
current,minimum,maximum,average,
sum
current When chainingAnalogLog objects,the average selectionis often used.
changeTolerance Read-Write: Used only if collectionMode isset to change_of_value. Defines theminimum ± change required at thestatusInput (since the last recorded logsample) before a new sample is recorded.
Any positivevalue
0.00000000001 (1.0E-11)
toMAX_VALUE
0.01
deltaLogging Read-Write: Defines if log samples arerecorded as the actual statusInput value, asin the default (False), or the difference (delta) between samples (if True).
If set to True, a log sample will have anegative sign when decreasing, or be
unsigned when increasing.
Note: Delta logging is also reflected at thestatusOutput.
False, True False Typically, when usingdeltaLoggingcollectionModeshould be set tointerval. Otherwise,log samples will show
only thechangeTolerancevalue (positive ornegative).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
AnalogLog
6–28
AnalogLog NotesThe AnalogLog object is used to trend any analog value in the station. It is typically
the most widely-used type of log object. These notes apply to the AnalogLog:
• statusOutput Notes
• Delta Logging Notes
• Visual Properties Notes
C o n
f i g ,
c o n
t .
units Read-Write: Selection of engineering unitsfor display purposes. Choose from a logicalgrouping, then a specific unit.
For selections see “About Units,” page 5-6.Units appear on the LogChart showing theobject’s log data. Units can also appear ona GxText object linked to the statusOutput.
Select any(BACnet-typeunit choices)
Other,no_units
Units are not used inthe object’s LogTableview, nor with any
access to archivedlog data.
V i s u a
l
position Read-Write: See “position,” page 6-6. — —
chartType Read-Write: Defines the chart (graph) styleused to present log data in the LogChart.
The object’s LogChart is seen by a JDEuser and (if WebUIService is licensed) by aWeb browser user.
plot,area,bar,
candle,bar_3d,
candle_3d
plot For an example ofeach chart type, seeFigure 6-14.
chartColor Read-Write: Defines the color used in theLogChart to represent recorded log data.
Any desiredcolor
Red
(255,0,0)
chartTemplateUrl Read-Write: Specifies the swid to an HTMLtemplate used to frame the LogChart whenviewing it in a Web browser.
If left blank, the “default” HTML template isused (defaultChartTemplate.html).
Valid swid to anappropriate
HTMLtemplate.
— See the Tip onpage 6-14 for anexample of using thisproperty.
decimalFormat Read-Write: Sets decimal position from 0 to6 places, optionally forces (+) sign forpositive values. Decimal format is used inthe y-axis scale values on the object’sLogChart, also in displayed values in theJDE LogTable view.
0 to 6,
(+) sign,no (+) sign
2,
no (+) sign
Decimal format is not
used in browseraccess to the object’sLogTable view, norwith any access toarchived log data.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
AnalogLog
6–29
statusOutputNotes
The AnalogLog object has a statusOutput and a outputFunctionconfig property. Use
of this output is optional. However, it can be useful when gathering analog data.
• The statusOutput value is based on recorded logs— with the outputFunction
set to current (the default), the output value is the last recorded log.
• By setting outputFunction to either average, minimum, maximum, or sum, theoutput value reflects the math operation on the object’s recorded logs.
The typical use of statusOutput is for “chaining” AnalogLog objects (Figure 6-11).
Figure 6-11 AnalogLog objects can be chained together using the statusOutput.
Note A benefit of chaining AnalogLog objects is that fewer links are required to the source
object. When engineering a Web Supervisor station, most log objects are externally
linked to objects in JACEs.
Delta LoggingNotes The AnalogLog object has delta logging option, which records the difference (delta)values between recorded logs. This feature can be useful in “performance trending.”
Figure 6-12 shows delta logging used (along with the logEnable input) to track the
effect on return air temperature following an AHU system start.
Figure 6-12 AnalogLog object configured for deltaLogging (with logEnable linked).
1. OATMinuteLog
bufferSize = 60collectionMode = interval
interval (min.) =1outputFunction = average
2. OATHourLog
bufferSize = 48collectionMode = interval
interval (min.) = 60outputFunction = average
3. OATDayLog
bufferSize = 35collectionMode = interval
interval (min.) =1440
1. OATMinuteLog, holds the last hour’s (60 minutes) outside temperatures.
2. OATHourLog, holds average hourly outside temperatures for the last 48 hours.
3. OATDayLog, holds average daily temperatures for the last 35 days.
Sourceobject
When linked, an active isrequired on logEnableduring logging.
tstamp value status
17:30:00 23-Jul-2001 EDT 0.02 ok
8:00:00 24-Jul-2001 EDT 7.20 ok
8:01:00 24-Jul-2001 EDT -0.61 ok
8:02:00 24-Jul-2001 EDT -0.73 ok
Values are the differencesbetween current samplevalue and previous value.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
AnalogLog
6–30
Figure 6-13 shows a similar example, but with the addition of a DateTimeTrigger
object that periodically clears the AnalogLog object’s buffer, which is set to
stopWhenFull. In this case, only the first hour’s operation is wanted, so the bufferSize
is set to 60, with an interval of 1.
Figure 6-13 AnalogLog object configured for deltaLogging, logEnable, doClearTrigger.
In this example, the DateTimeTrigger object is configured to fire daily at 3:00 AM,clearing all logs from the buffer. This occurs after the daily archive of the station’s
log data (as defined in the LogService object), which in this case is at 12:01 AM.
Visual PropertiesNotes
The Visual tab of the log object’s property sheet provides several properties that
affect the graphical presentation of log data. These properties are:
• chartType —Determines the charting style used to show log data in the
LogChart view, as seen in the JDE or from a Web browser. For an AnalogLog
object, the default is plot , a standard x-y line-plot. For a comparison of all chart
styles, see Figure 6-14.
• chartColor —Determines the color used to display the object’s log values. The
default color is red.• chartTemplateUrl —(optional) Specifies the path to an HTML template used
to frame the chart applet (when accessing the LogChart using a Web browser).
Any named template overrides the “defaultChartTemplate.html” template.
Notes • These 3 chart properties apply only if the station is running the WebUIService.
• Any template referenced by the chartTemplateUrl property must be available
to the station, otherwise the object’s LogChart will not appear.
Another Visual tab property is decimalPrecision, which determines the decimal
format used to display the y-axis (value) scale in the LogChart view. It also specifies
the decimal format used for values in the JDE LogTable view (Figure 6-1).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
Calendar
6–36
• Calendar —Shows the current calendar month with defined dates indicated by
shading. Arrow controls allow you to scroll through months and/or years.
Button controls allow new dates to be defined and existing dates deleted.
• CalendarSummary —Shows the entire calendar year (all 12 months), with
defined dates indicated by shading. Controls allow you to scroll through years.
A click on any date opens that calendar month view (above), in which you cancreate and delete calendar dates.
• EntryList —Shows a tabular listing of all defined calendar dates, showing the
type (date, date range, week and day) and the exact dates defined.
Notes • The Calendar view is the default view for a Calendar object in the JDE
(double-click on object in Tree View). It is also the default view from a Web
browser, providing that the station has the WebUIService.
The browser Calendar view differs slightly by providing a right-click menu to
create or delete calendar dates, as opposed to the dedicated button controls in
the JDE. See Figure 6-19.• Admin-level-write privileges are required for any user to create, delete, and
modify calendar dates.
PropertiesTable 6-7 Calendar ob ject proper ties.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType,statusFlags,description
See Table 6-1 on page 6-5 for informationon these properties common to all appsobjects.
— —
presentValue Read Only: Required for BACnet. Reflectsthe object’s statusOutput state.
Inactive,Active
Inactive Displays in theobject’s configured:
activeInactiveText
C o n
f i g
executionParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 6-5.
fixed_minutely,
processor
foreignAddress Read-Write: BACnet usage only. Set to apositive integer for this object to appear as aBACnet Calendar object to other BACnetdevices. See “foreignAddress,” page 6-6,for more information.
0 to 4194302
or -1(not exposed)
-1 If set, must be aunique numberamong all otherCalendar objects instation.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
activeInactiveText Read-Write: Defines how states display atthe statusOutput, presentValue, andstatusInput, and also how they appear onthe object’s property sheet.
Any desireddescriptors forthe two states.
Active,Inactive
State descriptors candisplay at a linkedGxText object.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
Calendar
6–37
Calendar NotesA Calendar object is typically linked to one or more Schedule objects. The link is
from its statusOutput to the holidayOverride input of the Schedule object, as shown
in Figure 6-17.
The following Calendar topics are explained ahead:
• Calendar Object Processing and Priorities
• Output Configuration
• Master / Slave Operation
• Calendar View Notes
V i s u a
l
position Read-Write: See “position,” page 6-6. — —
templateUrl Read-Write: Specifies the swid to an HTMLtemplate used to frame the object’s
calendar dates in the calendar applet (whenviewing it in a Web browser).
If left blank, the station’s calendar templateis used (WebUIService’s Config property,calendarTemplateUrl). If that property isblank, the stations “defaultTemplateUrl” isused—also a WebUIService property.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
IntegerLog
6–42
PropertiesTable 6-8 In tegerLog ob ject proper ties.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType,
statusFlags,description
See Table 6-1 on page 6-5 for information
on these properties common to all appsobjects.
— — If description is
entered, it appears inLogChart title, alsoto list the log in thestation’s log index:http://<sta>/log/index
lastArchiveTimestamp Read Only: Shows a date/timestamp forwhen the last archive occurred. Shows “null”if there have been no archives or if theclearLastArchive command was given.
— null
C o n
f i g
executionParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 6-5.
normal,processor
foreignAddress Read-Write: Does not apply to this object. -1 -1
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
See Table 6-2 on page 6-16 for moreinformation on these properties common toall log objects.
— — The collectionModedefault ischange_of_value .In some cases,interval may be bettersuited.
deltaLogging Read-Write: Defines if log samples arerecorded as the actual statusInput value, asin the default (False), or the difference (delta) between samples (if True).
If set to True, a log sample will have anegative sign when decreasing, or beunsigned when increasing.
False, True False
units Read-Write: Selection of engineering unitsfor display purposes. Choose from a logicalgrouping, then a specific unit.
For selections see “About Units,” page 5-6..
Select any(BACnet-typeunit choices)
Other,no_units
Units appear on theLogChart showingthe object’s log data.
V i s u a
l
position Read-Write: See “position,” page 6-6. — —
chartType Read-Write: Defines the chart (graph) styleused to present log data in the LogChart.
The object’s LogChart is seen by a JDEuser and (if WebUIServices are licensed) bya Web browser user.
plot,area,bar,
candle,bar_3d,
candle_3d
plot
chartColor Read-Write: Defines the color used in theLogChart to represent recorded log data.
Any desiredcolor
Red(255,0,0)
chartTemplateUrl Read-Write: Specifies the swid to an HTMLtemplate used to frame the LogChart whenviewing it in a Web browser.
If left blank, the “default” HTML template isused (defaultChartTemplate.html).
Valid swid to anappropriate
HTMLtemplate.
— See the Tip onpage 6-14 for anexample of using thisproperty.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
IntegerLog
6–43
IntegerLog NotesThe IntegerLog object can be used to trend any integer value in the station.
As far as the required data species for linking to the object’s statusInput, the
IntegerLog object is interchangeable with the MultistateLog object—both require a
property link to an output using the IntegerStatusType data species.
However, these two log objects should be applied differently, depending on the input
source. Specifically:
• The IntegerLog object is used to log analog values that happen to be integers,
for example, “counts” or seconds. Examples include the changeOfStateCount
and statusElapsedActiveTime properties of BI and BO objects. Recorded logs
will display values numerically. In the object’s LogChart, the object’s assigned
units descriptor will display along the numbers labeling the y-axis.
• The MultistateLog object is used to log discrete values (states), which haveassociated integer values. Examples include the statusOutput of MSI and MSO
objects. Recorded logs will display values using the assigned stateText
descriptors (not the integer values). In the object’s LogChart, the assigned
stateText descriptors also display along the chart’s y-axis.
Similarity to AnalogLog
Basically, the IntegerLog object operates like the AnalogLog object, offering the
same choices for units, deltaLogging, and chartTypes. The basic difference is the
absence of a statusOutput, outputFunction, and decimalFormat properties.
For more information on topics common to both log objects, see the following:
• the “Delta Logging Notes” section on page 6-29.
• the “Visual Properties Notes” section on page 6-30.
Note The default collectionMode for an IntegerLog is change_of_value (unlike the default
of interval for an AnalogLog). Depending on your application, you may wish to
change this to interval, particularly if this is a rapidly changing value.
E n g
i n e e r i
n g
minExecuteTime,maxExecuteTime,averageExecuteTime,
userData
Properties common to all apps objects. Formore information, see Table 6-1 onpage 6-5.
— —
logEnable(input: enable)
Read Only: Shows the current boolean stateand status of the logEnable input.
false, true :status flags
false : ok Shows false iflogEnable is notlinked.
statusInput(input: sIn )
Read Only: Shows the current value andstatus received on the statusInput.
<int value>status flags
0 ok
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For moredetails, see “securityGroups,” page 6-6
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
MultistateLog
6–45
PropertiesTable 6-9 Mult istateLog object propert ies.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType,
statusFlags,description
See Table 6-1 on page 6-5 for information
on these properties common to all appsobjects.
— — If description is
entered, it appears inLogChart title, alsoto list the log in thestation’s log index:http://<sta>/log/index
lastArchiveTimestamp Read Only: Shows a date/timestamp forwhen the last archive occurred. Shows “null”if there have been no archives or if theclearLastArchive command was given.
— null
C o n
f i g
executionParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 6-5.
normal,processor
foreignAddress Read-Write: Does not apply to this object. -1 -1
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
See Table 6-2 on page 6-16 for moreinformation on these properties common toall log objects.
— — The collectionMode default ischange_of_value .Typically, this is left atdefault.
V i s u a
l
position Read-Write: See “position,” page 6-6. — —
chartType Read-Write: Defines the chart (graph) styleused to present log data in the LogChart.
The object’s LogChart is seen by a JDEuser and (if WebUIServices are licensed) by
a Web browser user.
area area
chartColor Read-Write: Defines the color used in theLogChart to represent recorded log data.
Any desiredcolor
Red
(255,0,0)
chartTemplateUrl Read-Write: Specifies the swid to an HTMLtemplate used to frame the LogChart whenviewing it in a Web browser.
If left blank, the “default” HTML template isused (defaultChartTemplate.html).
Valid swid to anappropriate
HTMLtemplate.
— See the Tip onpage 6-14 for anexample of using thisproperty.
stateText Read-Write: Defines all possible discretestates by value-name pairs.
Each state has two fields:
• value—Unique integer from 0 to 7.
• tag—Text to describe the associateddiscrete state. State descriptors are usedat the statusOutput, presentValue, alarmand fault values, and in both the LogChartand LogTable views.
Up to 8 statespermitted,
numericallyfrom 0 to 7.
0 = Off 1 = On
2 = Fastdefault =
Error
State descriptors candisplay at a linkedGxText object.
For log accuracy,verify that stateTextconfigurationmatches stateText inthe source MSI orMSO object.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
MultistateLog
6–46
MultistateLog NotesThe MultistateLog object is used to trend the statusOutput of either a MultistateInput
(MSI) or MultistateOutput (MSO) object, or a BACnet MSI or MSO shadow object.
Similarity toBinaryLog Object
Basically, the MultistateLog operates like the BinaryLog object, offering similar
options for display text (stateText , equivalent to activeInactiveText ). Also, the
MultistateLog is typically used to track the times of state changes, therefore, the
collectionMode property should be left at the default: change_of_value.
Note For accuracy in logging, verify that the stateText property in the MultistateLog is
configured to match the stateText property in the source MSI or MSO object.
Another similarity is the fixed chartType of “area.” The LogChart view of a
MultistateLog object is also similar to the BinaryLog’s, but typically has more than just 2 levels. An “Error” level is automatically added at the top (Figure 6-20).
Figure 6-20 Example MultistateLog LogChart view.
E n g
i n e e r i
n g
minExecuteTime,maxExecuteTime,averageExecuteTime,
userData
Properties common to all apps objects. Formore information, see Table 6-1 onpage 6-5.
— —
logEnable(input: enable)
Read Only: Shows the current boolean stateand status of the logEnable input.
false, true :status flags
false : ok Shows false iflogEnable is notlinked.
statusInput(input: sIn )
Read Only: Shows the current value andstatus received on the statusInput.
<float value>status flags
00.0 ok
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For moredetails, see “securityGroups,” page 6-6
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
Program
6–47
ProgramQuick reference for all properties: Table A-68
abbrev: Prog
The Program object lets you build a custom
application program (control function) as areusable object. A Program object is defined
by a program that you write and compile
using “TRIPL” (Tridium Programming
Language). Each Program object has a
ProgramEditor and ProgramDebugger, used
to write and compile its particular program.
These views are available as right-click “Go
menu” options in the JDE Workspace.
The object’s TRIPL program defines both the
“external” view of the object (the number and
types of inputs and outputs, Config
properties, and right-click commands) and
also its “internal” workings—how the object
processes received data, uses properties, and
outputs values.
Simple uses for Program objects are to
convert data types (data species) from one
type to another. More complex applications
can also be accomplished—refer to the
standard Niagara tridiumx/lib JAR file of the
Local Library for various examples.
Parent Dependencies None (any container).
Resource Count Range: 52 and up
Notes • For detailed information on TRIPL, refer to the Niagara Framework TRIPL
Reference, available in the JDE Help system as one of the online manuals.
• In Release 2.3, the tridiumx/lib JAR includes new psychrometric and
thermistor functions. Refer to the programlanguageextensions.html
document in the tridiumx/lib/docs folder for more information.
Commands If any “commandable inputs” are included in the object’s custom TRIPL program,
right-click (user) commands for run-time operation may be made available.
In addition, all Program objects include these right-click Go > <commands> when
working in the Workspace of JDE:
Inputs
Default Object Shape
Outputs
(none) (none)
Inputs
All Inputs / Outputs
Outputs
(as defined) (as defined)
Input / Output Property Reference for Program Object(only input and output types, see Table 6-10 for all standard properties)
Type Label Property Name Data Species
input (as written) (as written) (as written)
The number of, names, and types of inputs vary among Program objects.All input types except TriggerType are allowed.
output (as written) (as written) (as written)
The number of, names, and types of outputs vary among Program objects.All output types (including TriggerType) are allowed.
Note: TRIPL is loosely based on the Java programming language.Using TRIPL requires a good working knowledge of the variousNiagara data species, plus a basic understanding of programmingtechniques (keywords, variables, operators, and conditionals).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
Program
6–48
• ProgramEditor —Opens the object’s TRIPL program in the full width of the
Workspace (Figure 6-21). The JDE toolbar and menu bar includes editing
commands, such as cut, copy, paste, find, replace, and goto. After making any
changes to the program, you must “Compile and Save.” Errors found by the
compiler, if any, appear in the status line at the window’s bottom.
• ProgramDebugger —Opens a two-pane view in the Workspace (Figure 6-22),with the left-side showing the object’s TRIPL program and the right-side
providing a “Watch” view. The JDE toolbar and menu bar includes commands
that allow you to run or “step” through the program, and right-click commands
provide removable break points and the ability to change values.
PropertiesTable 6-10 Program object properties (standard, not counting those properties added in TRIPL).
Tab Property Name Description Valid Values Default Notes
S t a t u s objectType,
statusFlags,description
See Table 6-1 on page 6-5 for informationon these properties common to all appsobjects.
— —
C o n
f i g
executionParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 6-5.
normal,processor
foreignAddress Read-Write: Does not apply to this object. -1 -1
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
typeString Read-Write: Defines the name of an HTMLfile used for “on context” Help when theobject’s property sheet is open in the JDE.
This file must have a tridium\docs file path.
Program Program
displayTypeString Read-Write: Defines the text label thatappears inside the top of the object’s shapewhen viewed in the JDE Workspace. Alsoused as the “Type” field (and filter) for the
Status servlet of the WebUiService.The default is “Prog” (for Program).
Examples: “Pulse Gen” or “Num Ramp.”
Any desiredASCII text
string, includingspaces
Prog Short text strings arerecommended,because the objectshape expands to
accommodate longtext strings.
V i s u a
l
position Read-Write: See “position,” page 6-6. — —
decimalFormat Read-Write: Sets decimal posit ion from 0 to6 places, and optionally force (+) sign forpositive values.
0 to 6,
(+) sign,no (+) sign
2,
no (+) sign
icon Read-Write: Defines the “icon” used torepresent the object in the JDE Tree View.
The default is the standard “scroll” graphiccontained in the coreUI module JAR file:
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
Program
6–50
Notes • You can also use standard Windows shortcuts to copy (CTRL-C) blocked text
and paste (CTRL-V) when working in the ProgramEditor.
• The “Compile and Save” button remains dimmed until you make a change.
• Any change in the program text must successfully compile before it is saved.If a compile error occurs, you will see a message in the status line giving you
a reason, and the cursor will move to the line with the offending statement.
• When editing an existing Program object, you may need to remove links to
inputs or outputs first (if changes to the TRIPL program affect them).
ProgramDebugger
The Program Debugger provides two separate panes in the Workspace (Figure 6-22).
• The left pane shows the lines in the TRIPL program and provides
run/break/step control. Break points can be inserted by lines in the left margin.
• The right pane is a “Watch” view. It shows the values of outputs, inputs,
variables, and properties as you run or step through the program.
Figure 6-22 Program object Program Debugger is used to step through and analyze.
TRIPL ProgramOverview
From a high-level perspective, a typical TRIPL program includes:
• A number of comment lines, which begin with either:
– Two slashes (//) and continue to the end of that line, or
– Slash-asterisk (/*), continuing as needed to the next asterisk-slash (*/).
Right click menusallow setting breakpoints and addingitems to the Watchpane.
Line numbersappear as youmouse over theleft margin.
Tool bar buttons for:Edit Mode, Run, Break, and Step.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
Schedule
6–54
PropertiesTable 6-11 Schedule object properties.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType,
statusFlags,description
See Table 6-1 on page 6-5 for information
on these properties common to all appsobjects.
— —
isActive Read Only: Required for BACnet. Reflectswhether the object is capable of providingevent-time scheduling control (is operatingwithin its effectivePeriod).
False, True True See the ConfigpropertyeffectivePeriod.
C o n
f i g
executionParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 6-5.
fixed_minutely,
processor
foreignAddress Read-Write: BACnet usage only. Set to apositive integer for this object to appear as aBACnet Schedule object to other BACnetdevices. See “foreignAddress,” page 6-6,for more information.
0 to 4194302
or -1(not exposed)
-1 If set, must be aunique numberamong all otherSchedule objects instation.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
priorityForWriting Read-Write: Defines the priority level usedat the prioritizedOutput.
Any prioritylevel,
from 1 to 16
Schedule(16)
effectivePeriod Read-Write: Defines a “to” and “from”date range, in which the object’s outputs areallowed to be made active from scheduledactive event-times.
The date format is <day <mo> <year>, withwildcards set by asterisks (*).
Typically left at default (year-round).
See descrip. 1 Jan ****to
31 Dec****
If a slave object, thisrange is read-only(set in master).
The effectivePerioddoes not apply toactive valuesreceived at theoverrideIn input.
activeInactiveText Read-Write: Defines how states display atthe statusOutput and prioritizedOutput.
Any desireddescriptors forthe two states.
Active,Inactive
State descriptors candisplay at a linkedGxText object.
specialCleanup (d) Read-Write: Defines the number of daysthat must transpire before any expiredspecial events are removed from theobject’s EventCalendar (when using theobject’s command cleanupSpecials).
positive integernumber of days
14
(2 weeks)
0 is up to previousday. Negativenumbers can be usedto remove up to thecurrent day’s (-1) orbeyond (future).
trueCommand Read-Write: Defines how an activeschedule event-time or overrideIn inputappears at the object’s outputs.
true, false, auto true Selection of autoapplies to theprioritizedOutputonly—this isequivalent to a false
for the statusOutput.
falseCommand Read-Write: Defines how an inactive
schedule event-time or overrideIn inputappears at the object’s outputs.
true, false, auto false
V i s u a
l
position Read-Write: See “position,” page 6-6. — —
activeColor Read-Write: Defines the color used in theevent-time columns of the ScheduleEditor to denote active (On) event times.
Any colorselectable in
the Edit dialog.
green
inactiveColor Read-Write: Defines the color used in theevent-time columns of the ScheduleEditor to denote inactive (Off) event times.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
Schedule
6–55
Schedule NotesThe Schedule object is typically linked to one or more BinaryOutput (BO) objects,
using the prioritizedOutput. This provides regular “time-of-day, day-of-week”
control for any linked BO-type objects. As shown in Figure 6-24, it is also typical for
a Schedule object to have its holidayOverride input linked to a Calendar object,
which defines holiday dates that override regular schedule operation.
Note The holiday action (for example, Inactive) is defined in the Schedule object itself.
See Figure 6-25 on page 6-58 for a typical example.
The following Schedule topics are explained ahead:
• Schedule Object Processing and Priorities
• Output Configuration
• Master / Slave Operation
• ScheduleEditor Notes
V i s u a
l , c o
n t .
templateUrl Read-Write: Specifies the swid to an HTMLtemplate used to frame the object’sschedule in the schedule applet (when
viewing it in a Web browser).If left blank, the station’s schedule templateis used (WebUIService’s Config property,scheduleTemplateUrl). If that property isblank, the stations “defaultTemplateUrl” isused—also a WebUIService property.
Valid swid to anappropriate
HTML
template.
— Does not apply if theSchedule objectresides in a station
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
Schedule
6–58
ScheduleEditorNotes
In the JDE, the ScheduleEditor view for a Schedule object provides three separate
tabs to enter event-times, as shown in Figure 6-25.
• Weekly —Provides 7 columns, one for each day of the week.
• Holiday —Provides a single column, which describes the schedule events (if
any) that occur for any day designated as a holiday.• SpecialEvents —Provides a single column, used to define the schedule events
for the day (or days) for the currently selected special event.
Figure 6-25 ScheduleEditor in JDE has 3 tabs for entering schedule event-times.
Notes • On a special event day, all normal time-of-day (weekly) events are replaced .
• To add a special event using the JDE, click the day or days on the calendar side,
then select ScheduleEditor > Add Special Event from the menu bar. This
produces a dialog in which you can enter a descriptor and priority level.
Note that the priority level applies only to “overlapping” special events, and
does not affect the prioritizedOutput level (defined by priorityForWriting).
• Browser access to a Schedule object differs somewhat in that a Schedule
Summary (with links) replaces the tabs approach. See Figure 6-26.
Weekly schedulehas 7columnsfor all thedays ofthe
week. The Holiday tab isa single column thatdefines theschedule actionwhenever theholidayOverrideinput is active.
It is recommendedthat you do notleave this blank (no event times),but instead enter anevent—even if just“Inactive” starting at12am midnight andcontinuing for therest of the day (asshown here).
Otherwise, loadsmay unexpectedlycontinue operationover a holiday.
In the JDE, the right side of theScheduleEditor showscalendar with any specialevent days or holidaysindicated by shading.
The SpecialEvents tab workswith the currentlyselected day (ordays) on theright-sidecalendar view todefine specialevent actions.
In this case, theday selected isnot a SpecialEvent day.
When a SpecialEvent day isactive, eventsreplace all normaltime-of-dayevents.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 6 Apps Objects
StringLog
6–61
Properties
StringLog NotesRecorded logs differ from other log objects in that only two fields are present:
• timestamp —When the log was recorded. The format is:<time> <day-mo-year> <time zone>, for example:
12:07:49 25-Jun-2001 EDT
• value —The ASCII string at the log object’s statusInput.
Also, there is no LogChart view for a StringLog object. The default view is the
LogTable view.
Table 6-13 Str ingLog object propert ies.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType,
statusFlags,description
See Table 6-1 on page 6-5 for information
on these properties common to all appsobjects.
— — If description is
entered, it is used tolist the log in thestation’s log index:http://<sta>/log/index
lastArchiveTimestamp Read Only: Shows a date/timestamp forwhen the last archive occurred. Shows “null”if there have been no archives or if theclearLastArchive command was given.
— null
C o n
f i g
executionParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 6-5.
normal,processor
foreignAddress Read-Write: Does not apply to this object. -1 -1
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 7 Container Objects
Common Container Object Things
7–4
In this case, you could use layer assignments in the container so that the Gx objects
are visible only in the WorkspaceEditor, but not in the Workspace (Figure 7-2).
Note To access the layer editor in the WorkspaceEditor or Workspace view of any
container, right-click on the background and select Layers.
Browser Views
The Workspace view of a GxPage is available through a Web browser connection (ifthe station is running the WebUIService). This feature is unique among all container
objects. It is the basis for a universal user interface provided by a Niagara station.
Common Container Object ThingsContainer objects have properties common to all Niagara object types, such as the
status properties “objectType” and “description”. A few common properties have
special significance for containers. Rather than cover these things in detail for each
object type, they are explained in this section. Several container object types can also
be given a “composite” interface, this feature is explained in the “Containers That“Composite”” section on page 7-8.
The following common things apply to container objects:
• Security Groups and Containers
• Alarm and Alert Text
• Commands
• Common Container Object Properties
Figure 7-2 Layer control can be used in any type of container, but applies mainly to Gx objects.
GxText objects(layer_3) are visiblein theWorkspaceEditor .
In the container’s Workspace,layer_3 (used by GxTexts) has
Niagara Standard Programming Reference Revised: April 20, 20047–5
Security Groups and Containers
Like Niagara primitive objects, container objects have a securityGroups property.
This property is available on the object’s property sheet, on the Security tab.
Security settings for a container determine the following things:
• Whether or not a JDE user has Tree View access to it—including all child
objects. Note that it makes no difference if a user has security rights to child
objects, if security rights to the container are not assigned. If (read) security
rights are missing, the container does not appear in the Tree View of the JDE.
• Whether a browser user has access to the container (GxPage). If the user does
not have security rights, an HTTP “403: Access Denied” error appears upon
any link or URL direction to it.
Alarm and Alert Text
All containers have alarmText and alertText properties, found on Alarm Setup tab ofthe object’s property sheet. This feature allows you to use the same (global) alarm or
alert message text for any alarm or alert-capable child object in that container.
• Alarm-capable objects include the AI, AO, BI, BO, Loop, MSI, and MSO.
• Alert-capable objects include the BI, BO, MSI, and MSO.
The requirement is that the child object(s) use the default value for their alarmText
or alertText properties. The default is a single hyphen (-), and no other characters.
For example, a Container object is given an alarmText property of “Investigate alarm
condition in AHU-1.” The object contains two BI objects configured for alarming,
AHU1_Filter and AHU1_sLock.
• The BI object named AHU1_sLock has the default alarmText of “-”.
• The BI object named AHU1_Filter has an alarmText of “Check AHU-1 Filter,
note that a maintenance schedule is posted on the side of unit.”
When these BI objects alarm, only the first (AHU1_sLock) includes the Container
object’s (global) alarm message text in the alarm record sent to the Alarm Console.
Because the other BI has a non-blank, non-default alarmText value, it is used instead.
Pass UpProcess
If both the container’s alarmText or alertText and a child object’s alarmText or
alertText is at the default hyphen (-), the next (higher) parent container’s alarmText
or alertText value is used. This “pass up” process continues, potentially all the wayto the Station object, until the first “non-default” alarmText or alertText is found.
Note that a “blank” alarmText or alertText is not the same as the default hyphen (-).
Instead, a blank alarmText or alertText will stop the “pass up” process and result in
an empty messageText field in the alarm or alert record.
Commands > dump —Sends data about the object to the Standard Output window,
including the objects swid, handle, name, parent, properties, links, and children.
Common Container Object Properties
Table 7-1 lists common properties organized in the property sheet tab in which you
can find them. In the case where some property variation exists for a particular type
of object, that difference is noted in the property table for that object type.
Table 7-1 Common propert ies for al l container objects.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType Read Only: The container object type. Bydefault, a newly added object uses thisstring in its name (until renamed).This textappears inside the object’s shape in JDE.
The full string for the object type is shown,for example, Composite or GxPage.
See description reflectsobject type
For any of the complexcontainers (Bundle,Composite, GxPage),you can edit this usingthe displayTypeStringproperty.
statusFlags Read Only: Current state of the object’sstatus flags. A “normal” state (no flags set)is where the status flags value is “ok”, andthe object’s color is gray.
The only status flag that can be set is:
• down—The station is down or offline.
The object ‘s shape and outputs areyellow.
either:
ok (no flags)
or
down
ok Unlike many controlobjects, containers donot have alarm states.
In the case ofcomposited containers,they do not “assume”alarm or fault conditionsfrom linked inputs.
description Read-Write: Permits a user-defined textdescriptor for describing the container. Anyprintable characters, including spaces andmixed case characters, are allowed.
See description — For a GxPage container,this is sometimes linkedto a GxText object in thatcontainer (or anotherGxPage).
C o n
f i g
executionParameters
Read-Write: Applies to a Bundle,Composite, or GxPage only. Defines thefrequency and order for the object as it isexecuted by the station’s control engine.
• freq (frequency)—Specifies how often theobject is executed. For most containers,
the default frequency (normal) isacceptable.
• order—Specifies the order of execution ineach cycle. On each cycle of the controlengine, objects specified as inputs areprocessed first, then processors next, andlastly the outputs.
By default, the Bundle, Composite, andGxPage containers default to theprocessor order.
freq:never slower normalfaster fastest
minutelyon_trigger
order:input
processor output
freq:normal
order:<see
descrip>
Not available for any ofthe simpler containertypes, namely theContainer, PollAlways,and PollOnDemand.
Usually, default values
are recommended.The selection on_triggeris not valid forcontainers.
For related details, seeControlEngineServiceConfig property“executionFrequency”.
Niagara Standard Programming Reference Revised: April 20, 20047–7
C o n f i g ,
c o n
t .foreignAddress Read-Write: BACnet usage only. Exposes
the Niagara object as a BACnet object.
Note: Currently, this property does notapply to any container object.
-1
(not used)
-1
(not used)
These properties are notshown for the simplercontainers.
Leave at default settings.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2
V i s u a
l
position Read-Write: The x-y coordinates for theobject’s position on the JDE Workspace.
Coordinate values are in pixels, and arerelative to the upper-left corner of theWorkspace and the upper-left corner of theobject shape (including its input area).
An object with a position of “0,0” is in the topleft corner of the Workspace.
Some positivex, y value less than the parent
(container)object’s “size”property value.
Near themousepointer
when theobject is
firstcreated.
Typically, you don’tmanually enter positionvalues, but use themouse to drag the objectas needed on the JDEWorkspace.
However, if needed, youcan enter values directlyto “tweak” an object’sposition.
E n g
i n e e r i n g
minExecuteTime Read-Write: Can show the object’sminimum execution time, in milliseconds.
Shows MAX_VALUE if “profileNodes” in theControlEngineService was not previouslyset (since the last station start).
integer, 0 to n Seedescrip.
Providing that theControlEngineServicewas set to“profileNodes”, theseproperties show theobject’s executionstatistics. Typically, youdo not leave theControlEngineServiceconfigured this wayexcept for brief periodsto collect these values.
This properties are notavailable (nor apply to)
any of the simplercontainers.
maxExecuteTime Read Only: Can show the object’smaximum execution time, in milliseconds.
Shows MIN_VALUE if “profileNodes” in theControlEngineService was not previouslyset (since the last station start).
integer, 0 to n Seedescrip.
averageExecuteTime
Read Only: Can show the object’s averageexecution time, in seconds.
Shows 0.0 if “profileNodes” in the
ControlEngineService was not previouslyset (since the last station start).
valid float Seedescrip.
userData Read-Write: Stores a user entered string.Can be used by servlets and the API forconfiguration information.
Any desiredtext string forservlet/API
usage.
<blank>
S e c u r i t y
securityGroups Read-Write: Shows the security groups towhich the container is assigned. A usermust have the appropriate privileges in atleast one security group to view and modifyproperties and issue commands.
Refer to the “Security Tab” section onpage 1-20 (Station object UserAdmin topic)
for more details on how securityGroupssettings apply.
Any mix ofthese types:
•General
•HVAC
•Security
•Life Safety
•Group 4•Group 5
•Group 6
•Group 7
General For more information,see the “Security Groupsand Containers” sectionon page 7-5.
Also refer to the “AboutSecurity” section onpage 1-21.
Table 7-1 Common properties for all container objects. (continued)
Tab Property Name Description Valid Values Default Notes
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 7 Container Objects
Containers That “Composite”
7–10
CompositeEditor
As shown in Figure 7-5, the composite editor is where you choose properties (inputs
and outputs) of the container’s child objects to expose at the container level—an
optional task. However, for Bundle and Composite containers, this ability is what sets
them apart from simple “Container” objects. For a GxPage, this is usually done only
if also preparing composited Bundle objects.
About Composite Property Names
When you click (select) a property of a child object, a default property name appears
in the “Selected Property” field. This names the input or output at the container level.
The default name format is: <property name or abbreviation><object name>
For example, for an AI object named AirFlow, a few default property names are
• sOutAirFlow —for the statusOutput of AirFlow.
• eventTriggerAirFlow —for the eventTrigger output of AirFlow.
When adding a property, you can accept the default name or simply retype it.
Notes • Typically when adding properties, you should not use default names. This is
important when making composites for Bundles and GxPages, where the“Match” feature (in the Link Editor) depends on identical property names.
For example, you might change the default name of “sOutAirFlow” in a
Bundle to simply “AirFlow.” In the composite of a GxPage, you could change
the default name of “bindingAirFlowValue” to a matching “AirFlow.”
• Use the Rename option to change the name of a selected property. This can be
done after it is added (or even after it has been linked). Note that when
renaming, the Rename button remains grayed until you type in a new name.
Figure 7-5 Composite editor has a Properties side and an Exposed side.
The Properties side lists allinputs and outputs for one child object. Select any childobject using the drop-downlist, which refreshes the liston the Properties side.
The Exposed side lists allinputs and outputs that arecurrently exposed. Thisincludes inputs and outputsfrom all child objects.
This figure shows thecomposite editor for a Bundlebefore any inputs or outputshave been exposed—theExposed side is blank. Also,no property is currentlyselected on the Propertiesside—the Selected Propertyis blank and its action buttonsare grayed (unavailable).
Niagara Standard Programming Reference Revised: April 20, 20047–11
AddingProperties
Adding (exposing) new inputs and outputs is straightforward. In the composite
editor, these properties do not show a “composite” icon ( ) beside the input or
output symbol (as the property appears on the Properties side). They are also not
listed on the Exposed side.
Note Any input must be unlinked (unless a trigger type) before it can be added.
Procedure 7-1 Adding (exposing) a property at the container level.
Step 1 In the composite editor, click the drop-down list of child objects and select an
object.
Step 2 Click a property to select it.
The default name appears in the Selected Property field.
Step 3 Edit the default name, as needed (or optionally accept it).
Step 4 Click Add.
The property appears on the exposed side. It will be exposed when you click OK toclose the composite editor (as well as any other changes done while in the editor).
DeletingProperties
Deleting existing composite properties can be more involved, particularly when
properties are linked. Understand that deleting a property means that it is removed
from the container’s exposure (shape)—however, the associated child object
property is not affected. Exposed properties are listed on the Exposed side of the
editor, and also appear on the Properties side with the “composite” icon ( ).
Notes • Any composite property must be unlinked before you can delete it.
• Furthermore, you cannot delete a property if another composite property islisted below it (in the Exposed side), and that property is linked .
• In either case above, the same type of Error popup appears (Figure 7-6).
Procedure 7-2 Deleting a composite (exposed) property.
Step 1 In the composite editor, click the property in the Exposed list side to select it.
The Properties side updates to show all properties of that child object.
Step 2 Click Delete.
a. If the property is unlinked (and no other properties listed below it are linked),
it is removed from the Exposed properties list. It will be removed when youclick OK to close the composite editor.
b. If the property is linked, or another property listed below it is linked, an Error
dialog appears (Figure 7-6). You will need to close the composite editor and
unlink one or more properties (depending on what is found after opening the
WorkspaceEditor of the object containing the container object).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 7 Container Objects
Bundle
7–15
PropertiesTable 7-2 Bundle object proper ties.
Tab Property Name Description Valid Values Default Notes
S t a
t u s objectType,
statusFlags,description
See Table 7-1 on page 7-6 for information on
these properties common to all control objects.
— —
C o n
f i g
executionParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 7-6.
normal,processor
foreignAddress Read-Write: Does not apply to this object. -1 -1
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
typeString Read-Write: (Future Use) Defines the name ofan HTML file used for “on context” Help whenthe object’s property sheet is open in the JDE.This file must have a tridium\docs file path.
Bundle Bundle Not currentlyimplemented.
displayTypeString Read-Write: Defines the text label that appearsinside the top of the object’s shape whenviewed in the JDE Workspace.
The default is “Bundle.”
Examples: “VAV1 Logic” or “AHU Logs.”
Any desiredASCII text
string, including
spaces
Bundle Short text stringsare recommended,to keep the object
shape from undulyexpanding.
A l a r m
S e
t u p
alarmText Read-Write: The message text used in thealarm record for a child object alarm, providingthat object has a default hyphen (-) alarmText.
Any desiredASCII text
string, includingspaces
- For either, if left atdefault hyphen (-),the alarmText oralertText of thenext (up) parentcontainer is used.
alertText Read-Write: The message text used in the alertrecord for a child object alert, providing thatobject has a default hyphen (-) alertText.
-
V i s u a
l
position Read-Write: See “position,” page 7-7. — —
decimalFormat Read-Write: Sets decimal precision for floatvalues of exposed inputs and output as seen onthe object’s shape in the JDE.
0 to 6,
(+) sign,no (+) sign
2,no (+) sign
Has little practicaluse—does notaffect links to
outputs.icon Read-Write: Defines the “icon” used to
represent the object in the JDE Tree View.
The default is the standard “jigsaw” graphiccontained in the coreUI module JAR file:
/tridium/images/icons/composite.gif
Any .gif fileaccessible bythe station,
using a size of16 x 16 pixels.
SeeDescrip.
size Read-Write: Defines (in pixels) the overall sizeof the container’s Workspace. Dimensions arespecified by x (width) and y (height).
x: 10 to 1500
y: 10 to 1500
x:800 y:550
backgroundColor Read-Write: Specifies the background color ofthe container’s Workspace.
Any color, asset in the
Color Editor
(white)r255, g255
b255
alarmPageUrl Read-Write: (Future Use) Specifies the URL todisplay on alarm.
— — Not currentlyimplemented.
E n g
i n e e r i n g minExecuteTime,
maxExecuteTime,averageExecuteTimeuserData
Properties common to Bundle, Composite, andGxPage container objects. For moreinformation, see Table 7-1 on page 7-6.
— —
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For more details,see “securityGroups,” page 7-7
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 7 Container Objects
Bundle
7–16
Bundle NotesThe following topics apply to Bundle objects:
• When to Use
• Bundle Issues
• Example
When to Use In this particular scenario, using Bundle objects can save engineering time:
1. An application with GxPages is replicated many times.
2. The Web Supervisor contains the GxPages, but control logic resides in JACEs.
In this case, you can save considerable linking time between stations by using the
“Match” feature to link between composited GxPages (Web Supervisor) and
application control logic in JACEs (residing in Bundles). However, note that
consistency is required when assigning names to composite properties in both the
Bundle and the GxPage. See “Example” on page 7-17.
Bundles (or Composites) are not recommended for links between control objects,however, because of known issues. See “Bundle Issues.”
Notes • Bundles are used in all of the standard Niagara applications (tridiumx/lib JAR,
applications folder). In these applications, Bundles are the containers used to
hold control objects and log objects. The Bundle scheme supports division of
an application between two stations—bundled control logic in the JACE
station, and the composited GxPages (and perhaps bundled logs) in the Web
Supervisor. The time-saving feature is realized when linking graphics-to-logic
(or logs-to-logic) between stations, using the “Match” command.
• The lib applications demonstrate good techniques for using Bundle objects.
Bundle Issues Bundle (and Composite) objects have several known limitations and issues. Please
review Table 7-3 carefully to avoid incorrect use when exposing child objects.
Table 7-3 Bundle (and Composite) object l imitations, general guidelines.
Known Limitations General Guidelines
Exposed inputs and outputs that use the following dataspecies do not work consistently.
Therefore, do not expose inputs or outputs of these types:
• Any that use a “non-native” Niagara types, such as:LON (SNVT) types. For example, LonOccupancyEnum,
SnvtSwitchValueType, and so forth.• slaveIn
• slaveOut
• priorityArray
• prioritizedOutput
Avoid exposing inputs (of any type) to any contained control
objects and apps objects (Calendar, Schedule, and Program). Ifan input is exposed, then any link to it must pass through theBundle. This adds an extra overhead of Bundle processing.
Instead, when bundling these objects for linkage to composited
GxPages, it is recommend to expose only outputs (not inputs).This is only logical, as a composited GxPage has only inputs.Note you can still link directly to outputs of exposed objects toinputs of other control objects. Control response does not suffer,because additional Bundle object execution time is not a factor.
Note: Inputs to log objects (AnalogLog, BinaryLog, etc.) can besuccessfully exposed in a Bundle.
A Bundle within a Bundle does not operate correctly. Never “nest” a Bundle or Composite object within anotherBundle or Composite object.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 7 Container Objects
Bundle
7–17
Example The following example is from a standard applications in the tridiumx/lib JAR
(tridiumx/lib/applications//tridiumx/lib/applications/VAV_Type_1.sns). This
application uses two Bundle objects—one with control logic, the other with logs.
Figure 7-8 Dividing a “bundled” application between two Niagara stations.
At right, the sns file for theapplication has been copiedfrom the Local Library andpasted into the station for theWeb Supervisor (MyStation).
Also, the container“FunctionGenerators” wasmoved under the Bundleobject named “Control”(using the Tree View anddragging the container to theControl container, selecting“Move” after dropping).
This was done because the
“Control” Bundle will be cutand pasted next, and theFunctionGenerator links arewanted intact.
At right, the Tree View is usedto cut the “Control” Bundlefrom the Web Supervisorstation.
This leaves the Bundle forlogs (“Logs”) and thecomposited GxPage in theWeb Supervisor.
At right, the Tree View is usedto paste the “Control” Bundleinto a JACE controller station(CntrlEngSvcTest). In thiscase, the Bundle is pastedinside a Container named
“Logic.”Because this application wasbuilt using Bundles, thenecessary external linksbetween the GxPage(graphics), logs, and controllogic can be done quicklyusing the “Match” feature(Figure 7-9).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 7 Container Objects
Bundle
7–18
This example continues as the interstation (external) links are made.
Left to do in this specific application: link (or cut, paste, and link) the Schedule object
(in the Web Supervisor) to the “OccStatus” object inside the “Control” Bundle.
Figure 7-9 Using the “Match” feature when linking a Bundle object.
Linking between objects indifferent stations is doneusing the Tree View and
right-click commands“Link From”, “Link To <obj>”.
At right, the compositedGxPage (“Graphics”) isselected as “From”, and theBundle “Control” (in the JACEstation) is selected as “To.”(This order can be reversedwith the same results.)
The Link Editor appears,showing the exposed inputsin the GxPage and theexposed outputs of theBundle.
Because exposed propertiesof the GxPage and theBundle were named carefully,a single “Match” commandarranges for 7 links to bemade. Selecting OK results inall 7 external links to be madefrom the Bundle to the
GxPage.
Note: In this specific app, theinput “ZoneTempText” shouldalso be linked to the output“ZoneTemp”.
At right, the externalpublications are shown in theBundle outputs, and theexternal subscriptions areshown in the compositedGxPage.
The same type of “Match” link
can also be made betweenthe “Logs” Bundle (in the WebSupervisor) and the “Control”Bundle in the JACE station.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 7 Container Objects
Composite
7–19
CompositeQuick reference for all properties: Table A-17
abbrev: (none); Composite
The Composite object is mostly for legacy
support—it is largely replaced by the Bundle object . The Composite object provides the
identical method to encapsulate child objects,
however (unlike the Bundle object), it does
not provide command or view access to
exposed child objects. Composites are used
mostly for simple logic applications.
Note: The Composite has the same link
and performance issues as the Bundle.
As with Bundle and GxPages objects, a
“Match” (by-name) feature is available when
linking exposed inputs and outputs.
Parent Dependencies: None (any
container).
Resource Count Range: 48 to 74, plus the
sum of all resource counts of child objects.
Caution As with Bundles, Composites have known problems associated with some link
types. In addition, performance can degrade if control logic passes through
Composite links. See the “Bundle Issues” section on page 7-16.
Commands None from the Workspace containing the Composite object.
For a JDE user with Admin-level write privileges, the WorkspaceEditor for a
Composite provides these right-click menu commands:
• Layers —Produces the Layer Options editor for the Workspace. Not typically
used for a Bundle, as numbered layer settings apply only to Gx objects.
• Arrange —Produces the Arrange Glyphs editor, which allows you to globally
position child objects within the container’s Workspace, using display order,
name, or type. Typically used before links between objects are made.
• Reorder —Produces the Reorder editor. Allows you to change the order thatchild objects are listed under the Bundle when expanded in the Tree View. It
does not affect placement of child objects on the Workspace.
• Composite —Produces the composite editor (see page 7-10).
Inputs
Default Object Shape
Outputs
(none) (none)
Inputs
Example Inputs / Outputs
Outputs
(as exposed fromchild objects)
(as exposed fromchild objects)
Input / Output Property Reference for Bundle Object(only input and output types, see Table 7-4 for all properties)
Type Label / Property Name Data Species
input (as exposed in Composite Editor) (as in the exposed chi ld object)output (as exposed in Composite Editor) (as in the exposed child object)
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 7 Container Objects
Composite
7–21
Composite NotesComposite objects offer less features than Bundles, but have the same types of link
and performance issues. For this reason, they are seldom used. Exceptions include
legacy support (older Niagara stations) or only the simplest logic applications.
Note In general, control logic that requires fast processing should not be engineered with
links passing through Composite objects. Instead, these types of links should be
made directly between the primitive control objects.
Example The Composite shown in Figure 7-10 is used to simplify an 8-input AND logicoperation. This example Composite contains only cascaded Logic objects. Likely,
this Composite application will be reused in the station.
Figure 7-10 Example Composite object representing 8-input logic gate.
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For more details,see “securityGroups,” page 7-7
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 7 Container Objects
GxPage
7–25
PropertiesTab le 7-6 GxPage proper ti es .
Tab Property Name Description Valid Values Default Notes
S t a
t u s objectType,
statusFlags,description
See Table 7-1 on page 7-6 for information on
these properties common to all control objects.
— —
C o n
f i g
executionParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 7-6.
normal,processor
foreignAddress Read-Write: Does not apply to this object. -1 -1
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
typeString Read-Write: (Future Use) Defines the name ofan HTML file used for “on context” Help whenthe object’s property sheet is open in the JDE.
This file must have a tridium\docs file path.
GxPage GxPage Not currentlyimplemented.
displayTypeString Read-Write: Defines the text label that appearsinside the top of the object’s shape whenviewed in the JDE Workspace.
The default is “GxPage.”
Examples: “GxP1” or “AHU1 Gx.”
Any desiredASCII text
string, includingspaces
GxPage Short text stringsare recommended,to keep the objectshape from undulyexpanding.
A l a r m
S e
t u p alarmText Read-Write: Does not apply to this object. — - Child objects (Gx
types) are notalarmable.
alertText Read-Write: Does not apply to this object. -
V i s u a
l
position Read-Write: See “position,” page 7-7. — —
decimalFormat Read-Write: Sets decimal precision for floatvalues displayed at exposed inputs (as seen onthe object’s shape in the JDE).
0 to 6,
(+) sign,no (+) sign
2,no (+) sign
No real use—doesnot affect GxPagedisplay of analogs.
icon Read-Write: Defines the “icon” used to
represent the object in the JDE Tree View.The default is the standard “3 Blocks” graphiccontained in the coreUI module JAR file:
/tridium/images/icons/gxPage.gif
Any .gif file that
can beaccessed bythe station,
using a size of16 x 16 pixels.
See
descrip.
size Read-Write: Defines (in pixels) the overall sizeof the container’s Workspace. Dimensions arespecified by x (width) and y (height).
x: 10 to 1500
y: 10 to 1500
x:800 y:550
backgroundColor Read-Write: Specifies the background color ofthe container’s Workspace.
Any color, asset in the
Color Editor
(white)r255, g255
b255
Often set to acolor, especially ifbackground layerimage is not used.
alarmPageUrl Read-Write: (Future Use) Specifies the URL to
display on alarm.
— — Not currently
implemented.templateUrl Read-Write: Specifies the swid to an HTML
template used to frame the GxPage graphic (bythe Gx servlet). If left blank, the global HTMLtemplate referenced in the WebUIService(config property gxPageTemplateUrl) is used.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 7 Container Objects
GxPage
7–26
GxPage NotesGxPage objects provide the graphical user interface for a Niagara system. They can
depict everything from site maps, floor plans, mechanical equipment, or virtually any
needed graphic. For some examples, refer to the Niagara demo and demoR2
databases that are distributed on the Niagara installation CD.
Typically, you engineer GxPages only on stations running the WebUIService, so that
its GxServlet can make their graphics available to ordinary Web browsers. For largersystems, GxPages are typically the primary function of the Web Supervisor station.
Refer to GxPages, Gx objects, and related topics are explained in detail in the document
Niagara Web Solutions Guide. Please refer to it for specific examples.
Layer Control Unlike with other containers, use of layers is typical in a a GxPage, and corresponds
to layer assignments given child (Gx) objects. Layer control for a GxPage is available
using the Layers command, listed in the right-click menu of its WorkspaceEditor.
E n
g i n e e r i n g minExecuteTime,
maxExecuteTime,averageExecuteTime
userData
Properties common to Bundle, Composite, andGxPage container objects. For moreinformation, see Table 7-1 on page 7-6.
— —
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the GxPage is assigned. See “SecurityGroups and Containers,” page 7-5.
General,
7 others
General
Table 7-6 GxPage propert ies. (continued)
Tab Property Name Description Valid Values Default Notes
Niagara Standard Programming Reference Revised: September 30, 2006 (Notes this page only)
Chapter 7 Container Objects
PollOnDemand
7–33
Figure 7-12 PollOnDemand containers for BACnet shadow objects linked to Gx objects.
Caution Shadow objects in PollOnDemand containers should only be linked to Gx objects,
and not to other control objects (or log-type objects). If the linked Gx objects are in
a GxPage container, this provides dynamic system monitoring for a user, including
right-click command access. However, when not being polled, shadow object’s
output(s) typically go to an outOfService status. Also, following a station restart,outputs of unpolled objects may initialize as “0” if analog, or “inactive” if binary.
Notes • After viewing linked Gx objects in JDE, polling will continue for the
associated shadow objects in PollOnDemand containers until that view is
removed from the view cache. Typically, this means 4 view changes before
polling stops.
• Polling can continue for up to 45 seconds after the linked shadow object is no
longer being viewed, or after the JDE view cache is overwritten.
• Shadow objects must be directly contained in a PollOnDemand container forthe poll on demand effect. Being in another container type under a
PollOnDemand container is not a valid poll-on-demand configuration.
• Linkage to any of the single-input type Gx objects is supported when using
shadow objects in a PollOnDemand container. This includes types GxText,
GxBoolean, GxDamper, GxFan, GxFloat, and GxInteger.
• Linkages to multi-input Gx types, such as GxSpectrum and GxTimePlot, are
not supported from shadow objects in a PollOnDemand container.
BACnetDevice objectoperates like aPollAlways container forany directly contained
shadow objects.
You can create otherPollOnDemand and/orPollAlways containersunder the BACnetDeviceand move (or cut and paste)shadow objects to them.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 8 Gx Objects
About Gx Objects
8–2
About Gx ObjectsGx objects are the building blocks for the graphical user interface to a station. When
placed in a GxPage container, they are the individual graphical elements of a graphic
seen in the JDE. If the station has the WebUiService, the same GxPage graphics are
viewable using a Web browser (aka the BUI, or browser user interface).
Worth mentioning is that you can use Gx objects in other containers, that is, besides
just GxPages. For example, Gx objects can be used in containers with control logic
to observe output actions or just for general annotation while using the JDE.
However, only Gx objects in GxPage containers can be viewed using the BUI.
Execution of Gx Objects
Gx objects are executed by the UiEngineService, a core service of any station. All
other types of executable objects are executed by the ControlEngineService.
Typically, the default cycleTime (500 ms) of the UiEngineService provides optimum performance. The Status tab of the UiEngineService provides statistical data,
including the total number of Gx objects in the station (objectCount property).
Usually, even Niagara stations without the WebUiService will have some Gx
objects—just few (if any) GxPages. Stations with the WebUiService typically have
GxPages, and therefore, many Gx objects. The largest holder of GxPages and Gx
objects is typically a Web Supervisor station, as this station is usually engineered to
be the “interface provider” of a multi-JACE job.
Gx Object Categories
There are several ways to categorize the 11 types of Gx objects. The basic twocategories are by shape appearance, and are:
• Pre-Designed Shapes
• Graphic File / Color-Based Shapes
Pre-DesignedShapes
Gx objects in this category have a “known form,” meaning that they do not reference
a graphics (.gif) file. However, you can change the object’s shape, including color,
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 8 Gx Objects
Common Gx Object Things
8–4
Common Gx Object Properties
Table 8-1 lists common Gx object properties, organized under appropriate property
sheet tabs. In the case where some property variation exists for a particular type of
object, that difference is noted in the property table for that object type.
Table 8-1 Common propert ies for Gx objects.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType Read Only: The Gx object type. By default,a newly added Gx object uses this string inits name (until renamed).
The full string for the object type is shown,for example, GxBoolean or GxFan.
See description reflectsobject type
It is recommended thatyou rename any Gxobject that is to be linked,and not use defaultnames (GxText_2, etc.).
statusFlags Read Only: Current state of the object’sstatus flags. A “normal” state (no flags set)is where the status flags value is “ok”, andthe object appears normally.
The only status flag that can be set is:• down—The station is down or offline.
In the JDE, the text “Down” appearswherever real-time values would be. NoBUI access to a down station is possible.
either:
ok (no flags)
or
down
ok Unlike other someobjects, Gx objects donot directly have alarmstates. However, someGx objects are capable
of indicating the“offnormal” condition of alinked (source) object.
isVisible Read Only: Reflects the boolean statecurrently at the object input isVisible. If thisinput not linked, the default state is true.
Linking to the isVisible input offers a methodto toggle the visibility of the object. If thisinput is linked, the object is visible only whilea true (active) is present. Likewise, theobject becomes invisible while a false(inactive) is present.
false, true :status flags
true: ok The input isVisible usesa BooleanStatusTypedata species.
See “Input “isVisible”” onpage 8-7.
C o n
f i g
font
name
size
style
Read-Write: Specifies the font used for textelements within selected Gx objects. Hasthree separate elements, as follows:
• name —Selections list with font types:
– Courier
– TimesRoman
– Helvetica
– MonoSpaces
– SansSerif
– Dialog
– DialogInput
– ZapfDingbats
• size —Selection list with (from smallest tolargest): 8, 10, 12, 14, 16, 18, 20, 24, 32
• style —Selection list with:
– Plain
– Italic
– Bold
– Italic-Bold
Anycombination
Helvetica,10,
Plain
The font property appliesonly to these Gx objecttypes:
Niagara Standard Programming Reference Revised: April 20, 20048–5
V i s u a
l
position Read-Write: The x-y coordinates for theobject’s position on the JDE Workspace.
Coordinate values are in pixels, and are
relative to the upper-left corner of theWorkspace and the upper-left corner of theobject shape.
An object with a position of “0,0” is in the topleft corner of the Workspace.
Some positivex, y value less than the parent
(container)object’s “size”property value.
Near themousepointer
when theobject isfirst
created.
Typically, you don’tmanually enter positionvalues, but use the
mouse to drag the objectas needed on the JDEWorkspace.
You can also use the“nudge” key shortcuts (ALT-<arrow>) to make1-pixel position changes.See “KeyboardShortcuts,” page 8-9.
size Read-Write: Defines (in pixels) the overallsize of the object: x (width) and y (height).
When working in the WorkspaceEditor, youtypically use the mouse to drag shapehandles, as needed, to resize Gx objects.Also see “Keyboard Shortcuts,” page 8-9.
x:, y:as needed forappropriate
display
varies byGx object
For Gx objects thatreference image file(s),the right-click optionGx > Size to Image, isthe best method.
layer Read-Write: The layer of the parentcontainer to which the object is assigned.
Although layers apply to most containerobjects, it is the GxPage where most layerusage is typically used.
See the “Layer Control” section onpage 7-26 for more information.
layer_3 Be aware that if youoverlap Gx objects, youshould assign them to
different layers.
Otherwise, things maylook OK based on orderof creation (last on top),but after a station export(upgrade) and reinstall,Gx objects will notoverlap as intended.
hyperlinkOnClick Read-Write: Specifies if the cursor changes
to a “pointing hand” when a user mousesover, providing a hyperlink on mouse click.Choices are one of the following:
• disabled —no hyperlink (or “pointinghand”).
• binding —provides a hyperlink to thesource object’s default view (typically itsproperties).
If linked to a Schedule, Calendar, orlog-type object, this selection is oftenused. The default view for these objectstypes are not “properties,” but specialpurpose views like ScheduleEditor,CalendarEditor, and ChartLog.
• url —provides a hyperlink to the URLspecified in the hyperlinkUrl property.
disabled,
binding,url
disabled The hyperlinkOnClick
and hyperlinkUrlproperties apply to all Gxobject types except GxPipe and GxTimePlot.
If selection is url, a validURL is required in thehyperlinkUrl property.
hyperlinkUrl Read-Write: URL of the target to displayupon a mouse click, providing thathyperlinkOnClick is set to “url.”
Typically, this is a station URL (swid), butcan be any URL accessible by a user. Forexample, http://www.tridium.com.
valid URL — The hyperlinkOnClick property must be set to“url” to use this entry.
Applies to all Gx objecttypes except GxPipe andGxTimePlot.
Table 8-1 Common propert ies for Gx objects. (continued)
Tab Property Name Description Valid Values Default Notes
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 8 Gx Objects
Common Gx Object Things
8–6
General Gx Object Notes
The following general topics apply to all Gx object types:
• Providing Command Access
• Input “isVisible”
• Gx Object Shortcuts
ProvidingCommand
Access
A Gx object linked to a commandable object can provide command access to a
station user, offering a right-click command menu. However, command access
requires security group command-rights to the Gx object (Figure 8-1).
Note The importance and use of Gx objects’ securityGroup properties was incorrectly
described in older (r2.1 and r2.2) versions of this document.
V i s u a l ,
c o n
t .
highlightCommandable
Read-Write: Specifies if the object’s outlinebecomes highlighted in a “mouse over” toindicate right-click commands are available.
Works only if the linked object iscommandable. If set to True, when a usermouses over the Gx object, a thin redoutline appears around the object’s border.
False, True True If False, this does notprevent any availableright-click commands.
It just doesn’t “advertise”that any are available.
S e c u r i t y
securityGroups Read-Write: Shows the security groups towhich the Gx object is assigned. A usermust have the appropriate privileges in atleast one security group to view and modifyproperties.
Note: securityGroup properties are
important for any Gx object linked to anothercommandable object. It is the Gx object
securityGroup settings that are checked
against the user’s privileges, and determinewhat (if any) right-click command menu ismade available. This is the only check oncommands through a Gx object. See“Providing Command Access.”
Any mix ofthese types:
•General
•HVAC
•Security
•Life Safety
•Group 4
•Group 5
•Group 6
•Group 7
General If the user has rights tothe parent GxPage, allGx objects will beaccessible.
If a Gx object is linked toa commandable object,the securityGroupssettings of thecommandable object arenot checked (at least forany commands through
the Gx object).
Table 8-1 Common propert ies for Gx objects. (continued)
Tab Property Name Description Valid Values Default Notes
Niagara Standard Programming Reference Revised: April 20, 20048–7
Figure 8-1 Command access depends on Gx object securityGroup settings.
Input “ isVisible” Each Gx object has an “isVisible” input. This is in addition to the more typically-used
“binding” input that most Gx objects have.
The isVisible input uses a “BooleanStatusType” data species. This means it is
compatible with the statusOutput properties of a number of Niagara object types,
including object types BI, BO, BinaryOverride, Calendar, Logic, and Schedule (for
example). In addition, Program objects can be made with outputs using this data
species.
Input Operation
• If a Gx object’s isVisible input is not linked , it is always evaluated as True.By default, this means a Gx object is always visible.
• If a Gx object’s isVisible input is linked:
– An active (true) must be present at isVisible for the object to display.
– Whenever inactive (false), the Gx object disappears from display.
This occurs dynamically, meaning that Gx objects (shapes) may disappear
and appear while a GxPage is being viewed, for example.
Note Whenever a Gx object is not visible (isVisible = false), it disappears
completely, and right-click commands to a linked object, if any, are not
available. However, if the Gx object’s property highlightCommandable
is True, a user still sees the object’s outline when “mousing” over it.
Applications for isVisible
Applications for linking to isVisible inputs of Gx objects are up to the imagination of
the engineer designing a user interface.
This Gx object has itssecurityGroups propertyset to “HVAC” only.
Right-clickcommandmenu of thelinked object.
This user has command access because thesecurity mask provides “Std” and “Emer”Command access to the HVAC group.
Note: The securityGroup settings for the commandable object make nodifference (at least for command access through any Gx object).
If this Gx object’s securityGroups propertywas left at default (General only), this userwould not have command access throughthis object, as Command rights for theGeneral group are cleared.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 8 Gx Objects
Common Gx Object Things
8–8
Gx ObjectShortcuts
Working with Gx objects in the WorkspaceEditor (Edit mode), you should be familiar
with the following time-saving features:
• Tree View Image Reference
• Gx Submenu
• Current Selected Color • Keyboard Shortcuts
Tree View Image Reference
For Gx objects that reference one or more image (.gif) files, config properties require
a valid file path entry. Rather than typing a long file path for each image, you can use
the JDE Tree View to open the Local or Remote Library and locate the image.
To copy its file path in the Tree View, right-click on the .gif file and select Copy. You
can then use CNTRL-V to paste this file path in the appropriate property field of the
Gx object (with its property sheet opened).
Gx Submenu
Every Gx object has a right-click “Gx” submenu. The Gx submenu provides quick
access to certain properties without having to open the object’s property sheet.
Available commands (Gx > <command>) for any selected Gx object are:
• Layer —Applies to all Gx objects. It allows you to quickly to review (and if
needed), change the layer in which the object resides.
• Set String —Only for GxText (text) and GxTimePlot (displayNameA to D).
• Set Color —Applies to all Gx objects, for any color-based property. Works
with the “Current Selected Color” feature (see next section). Every Gx object
has at least one such property (borderColor or color).
• Size to Image —Applies to any graphic file-based Gx object. Automatically
sizes the object to the pixel dimensions of the referenced .gif file.
Current Selected Color
In the lower right corner of the JDE window while in Edit mode, are two small
rectangles. These show the current “selected color” and the current “active color,”
respectively.
• The active color continuously reflects the color under your mouse cursor.
• The selected color is locked, until you reset it to match the active color.
The selected color is used for any Gx > Set Color command.
By learning how to reset the current “selected color,” you can save time by using theGx > Set Color command for setting the value of color-based property (avoiding the
property sheet access). It is particularly useful for “matching” colors, as you can
capture the underlying color of whatever the cursor is resting over.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 8 Gx Objects
GxBarGraph
8–11
C o n
f i g ,
c o n
t .
orientation Read-Write: Specifies how the bar moveswithin the object’s shape.
If auto (default), the bar moves in the direction
of the longest side.• horizontal causes the value bar to always
move sideways ( left-to-right).
• vertical causes the value bar to alwaysmove up and down.
auto,horizontal,
vertical
auto
minValue Read-Write: Minimum value range for the bararea. This value shows (in text) at the lowerend of the bar area, if showLabels = True.
Values received that are less than minValuedisplay as minValue (no bar).
<valid float> 0.0 maxValue must begreater thanminValue.
Otherwise, thedisplay is alwaysminValue (no bar).maxValue Read-Write: Maximum value range for the bar
area. This value shows (in text) at the upperend of the bar area, if showLabels = True.
Values received that are greater thanmaxValue display as maxValue (full bar).
<valid float> 100.0
showLabels Read-Write: Specifies whether the minValueand maxValue values display near the ends ofthe bar area, and if the current real-time valuedisplays inside the bar area.
False, True True
V i s u a
l
position Read-Write: See “position,” page 8-5. — —
size Read-Write: See “size,” page 8-5.
If showLabels = True, this includes the“min/max” label area outside of the bar area.
— x:100 y:120
layer Read-Write: See “layer,” page 8-5. — layer_3
hyperlinkOnClick Read-Write: See “hyperlinkOnClick,” page 8-5. — disabled
hyperlinkUrl Read-Write: See “hyperlinkUrl,” page 8-5. — —
statusColorEnabled Read-Write: Specifies if bar and backgroundcolors change during “offnormal” status of thesource (linked) object.
• If False, object colors are always the same.
• If True, colors change by status, where:
– red and white indicate ans alarm condition.
– orange and black indicate fault condition.
False, True True Must be linked to astatusOutput forcolor changes.
flashingEnabled Read-Write: Specifies if a statusOutputflashing of the source object (unacknowledgedalarm) should be reflected by periodicallyflashing the entire GxBarGraph shape.
The entire shape flashes between visible (red)and invisible at a 1 Hz frequency, during analarm (until alarm acknowledgment).
False, True False If used, the object
must be set for
statusColorEnabled
displayUnits Read-Write: Specifies if (and how) engineeringunits of the source object display in the innerbar label (current real-time value).
Tab Property Name Description Valid Values Default Notes
GxImage object that references a .gif graphicshowing a graduated scale. This object isusually assigned to a lower layer.
Typically (as done here), the background
color of the .gif is designated as transparent.
The GxBarGraph object shown selected here.It is typically assigned to a higher layer thanthe “graduated scale” GxImage object, andthen sized and aligned as needed.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 8 Gx Objects
GxBoolean
8–13
GxBooleanQuick reference for all properties: Table A-29
abbrev: (none); GxBoolean
The GxBoolean object displays one of two
images (or colors) for the boolean state of alinked object. It is commonly used with two
varying image (.gif) files of the same size.
Alternately, it can be configured to display
different colors for the two states, and set to
either a square or elliptical shape.
Note: GxBooleans can be used with an
“animated .gif” for one or both states.
However, be aware that display issues
may result when accessed by a browser
running in an older/slower client PC.
See “Animated .gif Notes,” page 8-15,for more details.
Change is typically keyed by a state (value)
change of the linked object’s output,
however, configuration permits keying from
“in_alarm”, “fault,” “unacked_alarm” and
other status flags of a statusOutput.
Visual properties permit indication of alarm
conditions and define user-access behavior.
Parent Dependencies: None (any
container).
Resource Count Range: 47 to 82
PropertiesTable 8-4 GxBoolean ob ject proper ties.
Tab Property Name Description Valid Values Default Notes
S t a t u s objectType,
statusFlags,isVisible
See Table 8-1 on page 8-4 for information onthese properties common to all Gx objects.
— —
C o n
f i g
activeImage Read-Write: Swid of the image to display duringan active state of the linked boolean output. An“animated .gif” is sometimes used.
valid stationswid to .gif file
— See preceding Note about limiting use ofanimated .gif files.
inactiveImage Read-Write: Swid of the image to display duringan inactive state of the linked boolean output.
valid stationswid to .gif file
—
activeColor Read-Write: Color to represent the active stateof the linked boolean output.
(for each)
Any color, set inthe Color Editor
(transparent)
inactiveColor Read-Write: Color to represent the inactivestate of the linked boolean output.
(transparent)
Inputs
Default Object Shape
Outputs
isVisible
binding
(none)
Display Examples
Input / Output Property Reference for GxBoolean Object(only input and output types, see Table 8-4 for all properties)
Type Label Property Name Data Species
input — isVisible BooleanStatusType
— binding BooleanFlexBindingType
output — — —
Both objects shown selectedhere are GxBooleans.
Each uses two differentimage (.gif) files to showdifferent states. The fan’sactive state is an “animated.gif”, showing spinning fanblades. See related Note.
The active state for theheating coil GxBoolean is a.gif with brighter red color(to indicate that it is On).
This “status lamp” is made withoverlapping Gx objects—a GxTexton top, and a GxBoolean (definedwith colors) on a lower layer. Anactive cycle is indicated by green.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 8 Gx Objects
GxBoolean
8–14
GxBoolean NotesThe GxBoolean object is widely-used with whatever desired .gif files are needed to
represent the two boolean states. If using with animated .gif files, see the next section
“Animated .gif Notes.”
C o n
f i g ,
c o n
t .
shape Read-Write: Specifies whether the shapeboundaries (inside the border area) arerectangular or elliptical. This is the area
occupied by the active and inactive colors, andbound by the border color.
rectangle,ellipse
rectangle If set to ellipse, theobject’s “footprint” isstill rectangular
(does not crop anyassigned image file).
booleanKey Read-Write: Specif ies what type of booleanstatus causes the object to change state. Thedefault, value, is typically used to show theactive or inactive status of the linked output.
Other selections show the active image/coloronly upon (one) the following conditions:in_alarm, fault, overridden, out_of_service,unacked_alarm, down.
valuein_alarm
faultoverridden
out_of_serviceunacked_alarm
down
value The value selectionworks with a bindingto any boolean typeproperty, includingstatusOutput.
Other selectionsrequire statusOutputbinding, exclusively.
borderColor Read-Write: Color of the outline around theshape (rectangle or ellipse).
Any color, set inthe Color Editor
(transparent)
borderWidth Read-Write: Width, in pixels, of the outline
around the shape (rectangle or ellipse).
0 to 100 2
(pixels)
V i s u a
l
position Read-Write: See “position,” page 8-5. — —
size Read-Write: See “size,” page 8-5.
If referencing image files, use “Size to Image.”
— x:32 y:32
layer Read-Write: See “layer,” page 8-5. — layer_3
hyperlinkOnClick Read-Write: See “hyperlinkOnClick,” page 8-5. — disabled
hyperlinkUrl Read-Write: See “hyperlinkUrl,” page 8-5. — —
statusColorEnabled Read-Write: Does not apply to this object. False, True True
flashingEnabled Read-Write: Specifies if the statusOutputflashing of the source object (unacknowledgedalarm) should be reflected by periodically
flashing the entire GxBoolean shape.The entire shape flashes between visible andinvisible at a 1 Hz frequency, during an alarm(until alarm acknowledgment).
False, True False If True, the Gx objectmust be linked to astatusOutput for
flashing.
highlightCommandable
Read-Write: See “highlightCommandable,” page 8-6.
False, True True
E n g
i n e e r i n g
binding Read Only: Shows the boolean value receivedon the binding link.
Inactive, Active —
boundHandle Read Only: The handle of the “linked to” object. valid ID —
boundUrl Read Only: Shows the complete station swid ofthe linked “object.property”.
valid swid Unbound
debugOn Read-Write: Allows debug on processing. False, True False Internal use only.
S e c u r i
t y
securityGroups Read-Write: Shows the security groups towhich the object is assigned. For more details,see “securityGroups,” page 8-6
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 8 Gx Objects
GxBoolean
8–15
Animated .gifNotes
GxBoolean objects are commonly used with animated .gif files, for example, to show
an “On” state as a running fan, pump, and so on. Animated .gif files are also
commonly used with GxFloat and GxInteger objects in a similar manner.
Prior to Niagara Release 2.3, it was recommended to limit the use of animated .gifs
to no more than two (2) Gx objects per GxPage. This was based upon a “lowest
common denominator” approach to allow client (browser user) access from a variety
of platforms. In particular, some client PCs (typically slower/older PCs) were found
to have problems displaying a GxPage.
What happened was only a few Gx objects would get “painted” on the screen
(including a few with animated .gifs), and then the processor in the client PC would
get tied up in showing the animation effect—the remainder of Gx objects on the
GxPage would not get downloaded (displayed). Typically, the faster the client PC, the
less likely this problem would occur. A user with a 120 MHz Pentium PC would be
more likely to encounter this problem than one, say, with a 1 GHz Pentium III PC.
gx.properties File
Using a “gx.properties” file on a Niagara host, you can specify a delay between the
station’s WebUIService serving of Gx objects. The delay is typically not perceptable
to a user—a GxPage will display in about the same time. However, a delay does
allow GxPages with more than two animated .gifs to display correctly across a wide
range of client PCs, including those with slower/older processors.
In r2.3.4 and later, the Admin Tool includes a menu command to access and/or create
this file on an Niagara host. Refer to “Host > Edit File,” page 1-28.
The “gx.properties” file typically has a single line in this that reads:
gi f Del ay=n
where n is the time in milliseconds. It is recommended to use 50 as a starting point, and then adjust upwards if some client PCs still encounter problems.
(Note this need will be determined by the slowest browser client.)
For example:
(nre/lib/gx.properties)
gi f Del ay=50
Note In r2.3.4 (r2.301.428), a fix was added to stop flickering of Gx objects in GxPages,
particularly objects referencing animated .gif files. Internally, this fix tracked a list of
images used during viewing, then upon Gx applet shutdown, disposed of the images.
It is possible that the original (pre-fix) behavior may work better in some cases.Starting in 2.301.429, you can disable this fix with the following additional line in
the Niagara host's gx.properties file:
di sposeI mages=f al se
If not in the host’s gx.properties file, this equates as if the value were “true.”
Note that a station restart is needed after any changes to the gx.properties file.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 8 Gx Objects
GxDamper
8–16
GxDamper Quick reference for all properties: Table A-30
abbrev: (none); GxDamper
The GxDamper object provides a scalable
“side-view” graphic of a parallel-blade typedamper, for linking to a single analog value.
Blades inside the damper appear, in real-time,
angled in proportion to the received value
(90º movement from full closed to full open).
In the WorkspaceEditor, the object can be
resized by dragging, and be oriented either
horizontally or vertically. Configuration
properties specify close and open values, and
the different colors for the damper blades
(foreground) and background.
Visual properties allow color changes upon“offnormal” conditions. Additional
properties specify hyperlink-related actions.
Parent Dependencies: None (any
container).
Resource Count Range: 44 to 73
PropertiesTable 8-5 GxDamper ob ject proper ties.
Tab Property Name Description Valid Values Default Notes
S t a t u s objectType,
statusFlags,isVisible
See Table 8-1 on page 8-4 for information onthese properties common to all Gx objects.
— —
C o n
f i g
foregroundColor Read-Write: Color of damper blades (interiorlines) that can change angle in real-time.
Any color, set inthe Color Editor
(green)r0, g255,
b0
backgroundColor Read-Write: Color of the background color inthe rectangular damper shape.
Any color, set inthe Color Editor
(gray)r127, g127,
b127
orientation Read-Write: Specifies how the interior blades(lines) are oriented within the object’s shape.If auto (default), when full open, blades areperpendicular to the longest side.
• vertical shows blade(s) as vertical when fullopen (regardless of shape aspect).
• horizontal shows blade(s) as horizontalwhen full open (regardless of shape aspect).
auto,horizontal,
vertical
auto Typically, auto isrecommended. Thisprovides a typicalschematic for aparallel-bladedamper.
Inputs
Default Object Shape
Outputs
isVisible
binding
(none)
Display Examples
Input / Output Property Reference for GxDamper Object(only input and output types, see Table 8-5 for all properties)
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 8 Gx Objects
GxDamper
8–17
GxDamper NotesThe GxDamper object provides a continuously proportional graphic with built-in
alarm/fault status indication. It is useful whenever a side-view schematic of a
parallel-blade type damper is needed.
C o n
f i g ,
c o n t
.
closeValue Read-Write: The minimum value range, wheredamper vanes are shown fully closed.
Values received that are less than closeValue
display as closeValue (fully closed).
valid float 0.0 If the received valueis between thesetwo values, the
angle of the vanesproportionallyadjusts.
If you set closeValueto be greater thanopenValue, themin/max operationis reversed.
openValue Read-Write: The maximum value range, wheredamper vanes are shown fully opened.
Values received that are greater thanopenValue display as openValue (fully open).
valid float 100.0
V i s u a
l
position Read-Write: See “position,” page 8-5. — —
size Read-Write: See “size,” page 8-5. — x:25 y:100
layer Read-Write: See “layer,” page 8-5. — layer_3
hyperlinkOnClick Read-Write: See “hyperlinkOnClick,” page 8-5. — disabled
hyperlinkUrl Read-Write: See “hyperlinkUrl,” page 8-5. — — statusColorEnabled Read-Write: Specifies if foreground and
background colors change during “offnormal”status of the source ( linked) object.
• If False, object colors are always the same.
• If True, colors change by status, where:
– red and white indicate ans alarm condition.
– orange and black indicate fault condition.
False, True True If True, the Gx objectmust be linked to astatusOutput forcolor changes.
flashingEnabled Read-Write: Specifies if a statusOutput flashingof the source object (unacknowledged alarm)will be reflected by periodically flashing theentire GxDamper shape.
The entire shape flashes between visible (red)
and invisible at a 1 Hz frequency, during analarm (until alarm acknowledgment).
False, True False If used,statusColorEnabledmust be set to True.
highlightCommandable
Read-Write: See “highlightCommandable,” page 8-6.
False, True True
E n g
i n e e r i n g
binding Read Only: Shows the analog value receivedon the binding link.
<float value> —
boundHandle Read Only: The handle of the “linked to” object. valid ID —
boundUrl Read Only: Shows the complete station URL ofthe linked “object.property”.
valid swid Unbound
debugOn Read-Write: Allows debug on processing. False, True False
S e c u r i t y securityGroups Read-Write: Shows the security groups to
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 8 Gx Objects
GxFan
8–19
GxFan NotesThe GxFan object provides an resizable graphic with built-in animation and
alarm/fault status indication. It is useful whenever a side-view schematic of a rotating
fan is needed.
V i s u a
l
position Read-Write: See “position,” page 8-5. — —
size Read-Write: See “size,” page 8-5. — x:110 y:80
layer Read-Write: See “layer,” page 8-5. — layer_3
hyperlinkOnClick Read-Write: See “hyperlinkOnClick,” page 8-5. — disabled
hyperlinkUrl Read-Write: See “hyperlinkUrl,” page 8-5. — —
statusColorEnabled Read-Write: Specifies if the fan colors changeduring “offnormal” status of the source object.
• If False, object colors are always the same.
• If True, colors change by status, where:
– red and white indicate an alarm condition.
– orange and black indicate fault condition.
False, True True If True, the Gx objectmust be linked to astatusOutput forcolor changes.
flashingEnabled Read-Write: Specifies if the statusOutputflashing of the source object (unacknowledgedalarm) should be reflected by periodicallyflashing the entire GxFan shape.
The entire shape flashes between visible andinvisible at a 1 Hz frequency, during an alarm(until alarm acknowledgment).
False, True False If used, the objectmust be set forstatusColorEnabled.
highlightCommandable
Read-Write: See “highlightCommandable,” page 8-6.
False, True True
E n g
i n e e r i n g
binding Read Only: Shows the boolean value receivedon the binding link.
Inactive, Active —
boundHandle Read Only: The handle of the “linked to”object.
valid ID —
boundUrl Read Only: Shows the complete station swidof the linked “object.property”.
valid swid Unbound
debugOn Read-Write: Allows debug on processing. False, True False Internal use only.
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For more details,see “securityGroups,” page 8-6
General,
7 others
General
Table 8-6 GxFan object propert ies. (continued)
Tab Property Name Description Valid Values Default Notes
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 8 Gx Objects
GxInteger
8–24
GxInteger Quick reference for all properties: Table A-34
abbrev: (none); GxInteger
A GxInteger object is very similar to a
GxFloat, but is for linkage to an integervalue. It displays one of multiple images (or
colors) depending on the received value.
Each different image (or color) is assigned to
a specific integer. In this manner, display
change is “incremental” (discrete).
Note: If used with referenced .gif files,
the right-click Gx > Size to Image
option from the WorkspaceEditor will
size the object to the size of the image
Like the GxBoolean and GxFloat, a
GxInteger can be configured to display aseither a square or elliptical shape.
Visual properties allow color changes upon
“offnormal” conditions, as well as various
hyperlink related actions.
Parent Dependencies: None (any
container).
Resource Count Range: 43 to 80
PropertiesTable 8-9 GxInteger ob ject proper ties.
Tab Property Name Description Valid Values Default Notes
S t a t u s objectType,
statusFlags,isVisible
See Table 8-1 on page 8-4 for information onthese properties common to all Gx objects.
— —
C o n
f i g
mapping
Value
Color
Image
Read-Write: Specifies the different possibleinteger values, and the associated shape coloror image for each.
Value:<valid integer>
Any color, set inthe Color Editor
valid stationswid to gif file
0,
transparent,
(no image)
If using animated .giffiles, please see“Animated .gifNotes,” page 8-15.
shape Read-Write: Specifies whether the shapeboundaries (inside the border area) arerectangular or elliptical. This is the areaoccupied by the assigned value colors, andbound by the border color.
rectangle,ellipse
rectangle If set to ellipse, theobject’s “footprint” isstill rectangular(does not crop anyassigned image file).
borderColor Read-Write: Color of the outline around theshape (rectangle or ellipse).
Any color, set inthe Color Editor
(transparent)
borderWidth Read-Write: Width, in pixels, of the outlinearound the shape (rectangle or ellipse).
0 to 100 2
(pixels)
Inputs
Default Object Shape
Outputs
isVisible
binding
(none)
Display Example
Input / Output Property Reference for GxInteger Object(only input and output types, see Table 8-9 for all properties)
Type Label Property Name Data Species
input — isVisible BooleanStatusType
— binding IntegerFlexBindingType
output — — —
The selected object is aGxInteger that receives aLonWorks occupancy valueas an integer (from 0 to 3).A different image (.gif) ismapped to each possibleinteger state, as shown here.
Each room in this floor plan isoverlaid with a GxSpectrumobject. These objects areconfigured to show roomtemp deviation from setpoint.They also provide the room
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 8 Gx Objects
GxSpectrum
8–29
GxSpectrum NotesThe GxSpectrum object is typically configured to show temperature setpoint
deviation. Often, the midpoint value is defined as white.
If displayText is set to True (default), the binding value automatically displays in the
center of the object shape. In this case, the source object’s engineering units are
available, depending on the setting of the displayUnits property of the GxSpectrum.
C o n
f i g ,
c o n
t .
midPointDefault Read-Write: Specifies a midpoint value used ifthe midPointInput is not linked, or if it is linkedbut has a current status of “fault” or “down.”
<valid float> 50.0
valueDelta Read-Write: Specifies the gradient value rangeused, from the midpoint to a gradient endpoint.
The total value range, from one gradientendpoint to another, is twice this amount.
<valid float> 25.0
font
name, size, style
Read-Write: Applies to the displayed text forthe binding value (if displayText = True).See Table 8-1 on page 8-4 for moreinformation on font settings.
Anycombination
Helvetica,12, Plain
displayText Read-Write: Specifies if the primary value(binding input) displays in the center of thegradient rectangle, using the selected font.
False, True True
V i s u a
l
position Read-Write: See “position,” page 8-5. — —
size Read-Write: See “size,” page 8-5. — x:110 y:80layer Read-Write: See “layer,” page 8-5. — layer_3
hyperlinkOnClick Read-Write: See “hyperlinkOnClick,” page 8-5. — disabled
hyperlinkUrl Read-Write: See “hyperlinkUrl,” page 8-5. — — —
displayUnits Read-Write: Specif ies if (and how) engineeringunits of the source object display in the innerbar label (current real-time value).
none,abbreviated,
full
abbreviated Refer also to “AboutUnits,” page 5-6.
highlightCommandable
Read-Write: See “highlightCommandable,” page 8-6.
False, True True
E n g
i n e e r i n g
binding Read Only: Shows the analog (float) valuereceived on the binding link.
<valid float> —
boundHandle Read Only: The handle of the “linked to”
object.
valid ID —
boundUrl Read Only: Shows the complete station swidof the linked “object.property”.
valid swid Unbound
debugOn Read-Write: Allows debug on processing. False, True False Internal use only.
midPointInput Read Only: Shows the analog (float) valuereceived on the midPointInput link.
<valid float> — If midPointInput isnot linked, themidPointDefaultvalue is seen.
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For more details,see “securityGroups,” page 8-6
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 8 Gx Objects
GxText
8–31
C o n
f i g ,
c o n
t .
text Read-Write: Static text to display, if any.
This is optional if l inking to another object forreal-time value display. In this case, the value of
that object’s property will automatically be usedas the text, providing that thedisplayBindingText property is True (default).
If needed, additional text can be entered beforeand/or after the “property value text,” using thisentry method:
optional text <value> optional textwhere “<value>” is the literal string.
For example, a text property value of:Room temperature is <value>.
would display like:Room temperature is 71.8 ºF.
(if the displayUnits property is abbreviated.)
any charactersfrom keyboard
—
displayBindingText Read-Write: If the GxText object is linked toanother object’s property, this determines if thatproperty’s value is used as the text.
False, True True True (default) istypical. If False, onlythe text (property)value is seen.
justification Read-Write: Specifies how the displayed text isaligned (left/right), within the GxText rectangle.
center, left,right
left
borderColor Read-Write: Color of the outline around therectangular GxText shape.
Any color, set inthe Color Editor
(transparent)
borderWidth Read-Write: Width, in pixels, of the outlinearound the rectangular GxText shape.
0 to 100 2
(pixels)
V i s u a
l
position Read-Write: See “position,” page 8-5. — —
size Read-Write: See “size,” page 8-5. — x:100 y:120
layer Read-Write: See “layer,” page 8-5. — layer_3
hyperlinkOnClick Read-Write: See “hyperlinkOnClick,” page 8-5. — disabled
hyperlinkUrl Read-Write: See “hyperlinkUrl,” page 8-5. — — —
statusColorEnabled Read-Write: Specifies if text and backgroundcolors change during “offnormal” status of thesource (linked) object.
• If False, object colors are always the same.
• If True, colors change by status, where:
– red and white indicate an alarm condition.
– orange and black indicate fault condition.
False, True True If used, the objectmust be linked to astatusOutput.
flashingEnabled Read-Write: Specifies if a statusOutput flashing
of the source object (unacknowledged alarm)should be reflected by periodically flashing theentire GxText shape.
The entire shape flashes between visible (red)and invisible at a 1 Hz frequency, during analarm (until alarm acknowledgment).
False, True False If used, the object
must be set forstatusColorEnabled.
displayUnits Read-Write: Specifies if (and how) engineeringunits of the source object display with the value.
none,abbreviated,
full
abbreviated Refer also to “AboutUnits,” page 5-6.
Table 8-12 GxText object properties. (continued)
Tab Property Name Description Valid Values Default Notes
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 9 Notification Objects
About Notification Objects
9–2
About Notification Objects Notification objects are used for event routing within the Niagara alarming
subsystem. They can reside only in (or under) the NotificationService container, one
of the core Niagara services.
There are two main categories of notification objects:
• Classes
• Recipients
Classes
The NotificationClass object is used to define different classes of notification. It is
modeled closely after the BACnet “Notification_Class” object. Largely, classes
differentiate priority levels. Classes can also delineate needs for acknowledgment.
Each NotificationClass object requires a unique notificationClass number , which is
an integer from 0 to 8388607. Classes from 0 to 255 are often used. Alternately, largernumbers can be used, for example, 1000, 12877, 56010 and so forth.
Each alarmable object can be assigned to any (one) notification class. Such objects
include the “event-type” control objects (AI, AO, BI, BO, Loop, MSI, MSO), the
Station object, and the protocol-type service objects (LonWorksService,
BACnetService, JohnsonN2CommService, plus many others).
The Niagara alarming subsystem (featuring the alarm console) requires at least one
NotificationClass defined in the NotificationService.
Master/Slave
Operation
Each NotificationClass object has a masterOut output and slaveIn input. The
application of master/slave operation is for multi-station jobs, where a configurationchange can be made in the NotificationClass in one station (usually Web Supervisor).
The change is then replicated in linked NotificationClass objects in JACE controllers.
Recipients
Several types of notification recipient objects exist, for linkage to one or more
NotificationClass objects. Recipient objects define where, how, and when a classes’
notifications are sent (in addition to the alarm console) , with the following types
available:
• ApiRecipient
• MailRecipient
• PrinterRecipient
• RemotePrinterRecipient
• SnmpRecipient1
• VasRecipient (applies only if a Web Supervisor station)
1. Requires optional “snmp” feature with SnmpService (tridiumx, snmp JAR).
Niagara Standard Programming Reference Revised: April 20, 20049–3
Notification SchemesA station’s notification objects can define alarm/alert distribution schemes that range
from simple to complex.
• The simplest scheme uses only a single NotificationClass object, for example,the “class_0” object created by default by the New Station wizard. By default,
priorities for the three event transition types are all assigned to 255 (lowest).
Without additional NotficationClass objects (or any recipient objects), event
notifications can occur to the alarm console for any alarmable object assigned
to notificationClass 0 (also the default). For any event-type control object (AI,
AO, BI, BO, Loop, MSI, MSO) one provision is that the object must also have
flags set in its eventEnable property. These flags specify the event
transition-types upon which to send notifications.
• More complex schemes use multiple NotificationClass objects to provide
different priority levels for the same type of event transition (“to-offnormal”,
for example). Alarmable objects could then be assigned to the appropriatenotification class, as needed.
Also, recipient objects are often added and linked to NotificationClass objects.
This provides additional alarm/event routing options (in addition to the
automatic routing to the alarm console). Each recipient object has
configuration properties that define valid days and times of operation.
Linking Notes
When linking NotificationClass objects to notification recipient objects, note that
“many-to-one” links are supported, in addition to the more typical “one-to-many.”
This means that a MailRecipient object, for example, can send event notificationsreceived from multiple notification classes (Figure 9-1).
Figure 9-1 Notification links to a recipient object support multiple notification classes.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 9 Notification Objects
Notification Schemes
9–4
Common Notification Object Properties
Notification objects each have a small group of properties standard to most Niagara
objects. They are explained in detail here, rather than in the section on each
notification type object.
Table 9-1 lists common properties organized in the property sheet tab in which you
can find them. In the case where some property variation exists for a particular type
of object, that difference is noted in the property table for that object type.
Table 9-1 Common propert ies for al l noti ficat ion objects.
Tab Property Name Description Valid Values Default Notes
S
t a t u s
objectType Read Only: The notification object type. Bydefault, a newly added object uses thisstring in its name (unless renamed).
The full string for the object type is shown,for example, RemotePrinterRecipient.
See description reflectsobject type
statusFlags Read Only: Current state of the object’sstatus flags. A “normal” state (no flags set)is where the status flags value is “ok”.
The only status flag that can be set is:
• down—The station is down or offline.
either:ok (no flags)
or
down
ok Unlike some other objecttypes, notificationobjects do not havealarm states.
V i s u a
l position Read-Write: Specifies the x-y coordinates(in pixels) for the object’s position in theNotificationService container (JDEWorkspace).
— —
S e c u r i
t y
securityGroups Read-Write: Shows the security groups towhich the object is assigned. A user musthave the appropriate privileges in at leastone security group to view and modifyproperties and issue commands.
Any mix ofthese types:
•General
•HVAC
•Security•Life Safety
•Group 4
•Group 5
•Group 6
•Group 7
General More notes onsecurityGroup settingswill go here.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType,
statusFlags
See Table 9-1 on page 9-4 for information on
these common properties.
— —
description Read-Write: Permits a user-defined textdescriptor for describing the notification class.Any printable characters, including spaces andmixed case characters, are allowed.
Seedescription
nodescription
C o n
f i g
notificationClass Read-Write: The assigned notification classnumber, reflected inside the object’s shape.
Must be a unique number among allNotificationClass objects in the station.
0 to 8388607
0 to 255typical
-1(not
functional)
Numbers can beskipped, e.g. 100,200, 300, ... 900,1000 and so on area valid collection.
ackRequired Read-Write: (BACnet application) Flags thatspecify the types of event transitions, as theyoccur, that require acknowledgment.
Events still appear in the alarm console evenfor objects using a notification class whereackRequired is cleared (not set). Also, they arestored in the EVENT.UNACKEDALARMS table(SQL db) until acknowledgment, regardless ofthis setting. In their alarm record, however, the“ackRequired” field will always show “false.”
In addition, objects that are assigned to a classwhere ackRequired is cleared (for one or moretransitions), have associated flags permanentlyset in their ackedTransitions property.
On the other hand, an event transaction typerequiring acknowledgment causes thealarmable object to send receipt of an
acknowledgment back to the supervisor’sNotificationService (upon receipt). Thisconfirms acknowledgment. The alarm/event isnot removed from the alarm console until thisreceipt of acknowledgment is received.
selection ofany or all:
to-offnormal
to-faultto-normal
(allselected)
Selection”to-offnormal”applies to any
alarm state, e.g.“high-limit” or”low-limit” for anAI, AO, or Loopobject, or“offnormal” for aBI, BO, MSI, orMSO object.
eventPriorities
toOffnormal
toFault
toNormal
Read-Write: The priority assigned to each typeof event transition, namely:
• to-offnormal
• to-fault
• to-normal
Lower numbers indicate higher priority, where 0is the highest priority and 255 the lowest.
Often, higher priorities (lower numbers) are
assigned to “to-offnormal” or “to-fault” types.
(for each)
0 to 255
(for each)
255
In the alarmconsole (or alarmURL from abrowser), higherpriority alarms andevents are listedfirst (above) lowerpriority ones, evenif they are older.
V i s u a
lposition Read-Write: See “position,” page 9-4. — —
E n g
i n e e r i n g masterOut Read Only: Always shows “SlaveSync.” SlaveSync SlaveSync No real-time status
(or indication of amaster/slave link)is provided on theproperty sheet.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 9 Notification Objects
NotificationClass
9–7
NotificationClass Notes NotificationClass objects provide the necessary associations from alarmable Niagara
objects to the Niagara alarming subsystem.
The typical Niagara alarming subsystem includes these main components:
• NotificationService, including NotificationClass child objects, plus any of the
various recipient objects. Each station requires its own NotificationService.
• DatabaseService (of the Web Supervisor), which archives all received alarms
and alerts in an SQL database (Cloudscape, MS SQL, or MSDE).
• Alarm Console (from the Web Supervisor), which displays unacknowledged
alarms and alerts, referencing the SQL database. Users acknowledge alarmsand alerts, which are removed from display in the alarm console.
• Vykon Alarm Service (and Clients), where the service runs on the Web
Supervisor, and client applications can run on remote PCs to allow browser
access to monitor and acknowledge alarms and alerts. Extensive features
include pop-up notifications, links to graphics, and audible signals.
Also, an ordinary web browser user can display/acknowledge unacknowledged
alarms and alerts, again referencing the SQL database on the Web Supervisor.
This is done through the alarm servlet (URL htt p: \ \ <WebSupHost >\ al arm).
Standalone
JACE-4/5Operation
A standalone JACE-4/5 with WebUiService offers a reduced alarming subsystem,
which requires only the NotificationService (set to “archive_local_no_sql”) andwhatever required NotificationClass and recipient objects. In this case, alarms and
events are stored in a rotating buffer. Storage capacity is limited to about 250 records
for each (250 alarms and 250 alerts). Access and acknowledgment of alarms and
events is done using the alarm servlet running in the JACE-4/5 (URL
ht t p: \ \ <J ACE- 4/ 5host >\ al ar m).
Master/SlaveUsage
In a multi-station job, a “master/slave” scheme can be used among NotificationClass
objects. Typically, “master” NotificationClass objects reside in the Web Supervisor
station, and “slave” NotificationClass objects reside in JACE stations. You link them
using the masterOut (output) and slaveIn (input) properties.
A change made to any of the following properties of the “master” NotificationClassobject are replicated to the corresponding properties in linked “slave” objects:
• description
• notificationClass
• ackRequired
• eventPriorities
These properties appear as read-only slaved in the slave NotificationClass objects.
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For more details,see “securityGroups,” page 9-4
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 9 Notification Objects
ApiRecipient
9–8
ApiRecipientQuick reference for all properties: Table A-6
abbrev: (none); ApiRecipient
The ApiRecipient object provides event
registration for alarms and alerts via the NodeApi. In general terms, this allows
servlets written in Java to get a “callback”
when an alarm is generated.
Application of the NodeApi and the
ApiRecipient requires Java and Javadoc
programming knowledge. For more details
on the Niagara NodeApi, refer to the online
documentation in the tridiumx subfolder,
manuals, api.
Parent Dependencies: NotificationService.
Resource Count Range: 16 to 21
Trigger Properties Like other recipient objects, this object has a single input using data species
NotificationTriggerType. It can be linked to one or more NotificationClass objects.
Commands(none)
Properties
Inputs
Default Object Shape
Outputs
(none shown) (none)
Inputs
All Inputs / Outputs
Outputs
notificationInput (none)
Input / Output Property Reference for ApiRecipient Object(only input and output types, see Table 9-3 for all properties)
Type Label Property Name Data Species
input — notificationInput NotificationTriggerType
output — — —
Table 9-3 ApiRecipient object propert ies.
Tab Property Name Description Valid Values Default Notes
S t a t u s objectType,
statusFlagsSee Table 9-1 on page 9-4 for information onthese common properties.
— —
C o n
f i g
validDays Read-Write: Defines the days of the week inwhich event notifications can be sent to thenode API. Can be set in any combination.
Sun, Mon,Tue, Wed,
Thu, Fri, Sat
(all daysselected)
timeRange Read-Write: Defines the time period in whichevent notifications can be sent to the node API(on valid days of week), using a start time andend time.
If you check exclusive, event notifications aresent only outside of the defined period.
12:00 AMto
12:00 AM
(entirerange),
notexclusive
V i s u a
lposition Read-Write: See “position,” page 9-4. — —
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For more details,see “securityGroups,” page 9-4
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 9 Notification Objects
MailRecipient
9–9
MailRecipientQuick reference for all properties: Table A-45
abbrev: (none); MailRecipient
The MailRecipient object is used to route
alarms and alerts as e-mail messages. Note: The MailService must be
installed and properly configured
(referencing a working SMTP host).
Configuration properties specify the
destination addresses (To: CC: BCC:), the
“subject” header, valid days and times of
operation, and whether acknowledgments
should also be routed. Additional properties
specify which fields in the notification record
are to be included in an e-mail for an alarm,
alert, and acknowledgment.
Parent Dependencies: NotificationService.
Resource Count Range: 24 to 47
Trigger Properties Like other recipient objects, this object has a single input using data species
NotificationTriggerType. It can be linked to one or more NotificationClass objects.
Commands(none)
Properties
Inputs
Default Object Shape
Outputs
(none shown) (none)
Inputs
All Inputs / Outputs
Outputs
notificationInput (none)
Input / Output Property Reference for ApiRecipient Object(only input and output types, see Table 9-4 for all properties)
Type Label Property Name Data Species
input — notificationInput NotificationTriggerType
output — — —
Table 9-4 Mai lRecipient object propert ies.
Tab Property Name Description Valid Values Default Notes
S t a t u s objectType,
statusFlagsSee Table 9-1 on page 9-4 for information onthese common properties.
— —
C o n f i g
validDays Read-Write: Defines the days of the week inwhich routed event notifications can be sent ase-mails. Can be set in any combination.
Sun, Mon,Tue, Wed,
Thu, Fri, Sat
(all daysselected)
timeRange Read-Write: Defines the time period in whichrouted event notifications can be sent ase-mails (on valid days of week), using a starttime and end time.
If you check exclusive, event notifications aresent only outside of the defined period.
12:00 AMto
12:00 AM
(entirerange),
notexclusive
addressToCcBcc
Read-Write: (For each) specifies the e-mailaddress(es) to which the notification is sent.A primary (To) address is required; otheraddresses are optional.
If multiple addresses are needed in an entry,use a semicolon (;) between addresses, e.g:
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 9 Notification Objects
MailRecipient
9–12
Example E-mails The following examples show how the “body text” for e-mail notifications appear
when default field selections (all) are selected.
• Alarm Example
• Acknowledgment Example
• Alert Example
Alarm Example
Al ar m r ecei ved f r om MySt at i on.
Ti me: 10: 28 3- Oct - 2001 EDTSwi d: / MyStat i on/ Temp/ VAV_Type_1/ Cont r ol / ZoneTempName: ZoneTempMessage: Zone Temp i s out of r angeSt atus: i nAl ar m Type: Out of r angeOl d st ate: nor malNew st ate: l ow_l i mi t
Exceedi ng Val ue: 65. 5Deadband: 5. 0Exceeded Li mi t : 66. 0Cl ass I D: 0Pr i or i ty: 5Ack r equi r ed: f al se
Acknowledgment Example
Al arm acknowl edged.
Swi d: / MyStat i on/ Temp/ VAV_Type_1/ Cont r ol / ZoneTempName: ZoneTempAl arm Ti me: 10: 38 3- Oct - 2001 EDT
Type: Out of r angeAcked st at e: l ow_l i mi tSt atus: okCl ass I D: 0Pr i or i ty: 5Acked by: Admi ni st r ator ( admi n)Ack Ti me: 10: 39 3- Oct - 2001 EDT
Alert Example
Al er t r ecei ved f r om MySt at i on.
Ti me: 10: 47 3- Oct - 2001 EDTSwi d: / MySt at i on/ AHU_Type_1/ Cont r ol / SFan
Name: SFanMessage: Mai nt enance check on AHU_1 r ecommendedCl ass I D: 0Pr i or i t y: 255 Type: Change of st at e countLi mi t : 100
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 9 Notification Objects
RemotePrinterRecipient
9–16
RemotePrinterRecipient NotesThe RemotePrinterRecipient can be used to route alarms and alerts to any networked
(LAN) printer available to the host’s Windows operating system.
The recommended printer type is a dot-matrix style, using continuous feed paper.
Other printer type typically results in a separate piece of paper for each notification.
The Niagara notification record for each alarm and alert routed is printed in full.Acknowledgments are also printed, providing that routeAcks property is set to True.
In the case of a printer failure (network down, out-of-paper, offline, powered off,
etc.), the RemotePrinterRecipient sends an alert to the named alertNotificationClass.
For such an alert, the alertType is “equipmentFailure” and the messageText is
“Printer failure.”
C o n
f i g ,
c o n
t .
printerName Read-Write: Defines the networked printer, byname known to the Windows operating system.
A list of available networked printers
automatically appears in a drop-down selectionlist. Printers typically appear listed as:
• \\<printerHost>\DIRECT
or
• \\<PChost>\<PrinterName>(if a “shared” printer).
Any printerthat appears inthe drop-down
selection list.
noselection
Recommendedprinters aredot-matrix types.
A l a r m
S e
t u p
alertNotificationClass Read-Write: The notification class number usedin routing an alert when a problem occurs withthis RemotePrinterRecipient.
Likely scenarios would include network offlineconditions, “out of paper” printer conditions,printer offline, or printer turned off.
0 to 8388607 0
V i s u
a l
position Read-Write: See “position,” page 9-4. — —
S e c u r i t y securityGroups Read-Write: Shows the security groups to
which the object is assigned. For more details,see “securityGroups,” page 9-4
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 10 Ndio Objects
Ndio Primitives
10–6
For a JACE-4 with a JACE-IO-32 (32 point) expansion module, you need to assign
ioIndex numbers to the 16 Ndio UI objects according to the parent NdioProcessor
container. See “Processor Responsibilities,” page 10-4.
Notes • If engineering a running JACE-4 station and you attempt to assign a duplicate(already assigned) ioIndex number for an Ndio object, you receive an error
message. The ioIndex property value remains unchanged.
• If engineering offline, there is no checking for duplicate ioIndex property
numbers. You must be careful when assigning them.
Ndio outputs
Currently, there are two types of Ndio outputs: Binary Outputs and Analog Outputs.
In addition, the JACE-IO-32 Expansion Module provides output override switches.
Binary Outputs The NdioBinaryOutput controls a digital output (DO) on the JACE controller or I/O
expansion module. Depending on the hardware platform, the DO type will vary:
• Form-C Relay
• Triac
Form-C Relay
A JACE-401 and -403 has four (4) form-C relay, SPDT outputs. The JACE-IO-32
expansion module has eight (8) form-C relay, SPDT outputs.
You can (and typically do) add the same number of NdioBinaryOutput objects for use
in the JACE-4 station database. Assign each object a unique hardware address (1–4)
again using the ioIndex property on the Config tab (Figure 10-5).
In the case of the JACE-IO-32, you must place 4 NdioBinaryOutput objects
addressed 1—4 under each of the two NdioProcessors. See Table 10-1 on page 10-4.
Figu re 10-5 The index property (Config tab) in a NdioBinaryOutput determines the digital output (1 to 4) used.
JACE-403 has four Form-Crelay outputs, 1 through 4.
N04
C4Normally open (N.O.)contacts of output 4 wired tocontrol equipment load.
This NdioBinaryOutput objecthas been assigned to ioIndex 4(digital output 4).
Niagara Standard Programming Reference Revised: April 20, 200410–7
Triac
A JACE-IO-20 expansion module has eight (8) solid state Triac outputs for on/off
control only (floating control not supported). You can (and typically do) add the same
number of NdioBinaryOutput objects for use in the JACE-4 station.
All eight NdioBinaryOutput objects are placed under the same NdioProcessor object.Assign each NdioBinaryOutput object a unique hardware address (ioIndex 1—8).
Analog Outputs Currently, only expansion boards (JACE-IO-20 and JACE-IO-32) have proportional
analog outputs, or AOs. These are voltage-only outputs, providing from 0 to 10Vdc.
• The JACE-IO-32 has eight (8) AOs; each of the two I/O processors controls 4.
See “Processor Responsibilities,” page 10-4.
• The JACE-IO-20 has four (4) AOs, controlled by its single I/O processor.
You can (and typically do) add the same number of Ndio0to10VOutput objects in the
JACE-4 station database.
Output OverrideSwitches
Currently, the JACE-IO-32 Expansion Module is the only JACE hardware that
provides on-board manual override switches. Each output (8 DO, 8 AO) has its own
local override capability, as follows:
• Each DO has a 3-position switch: 0—Auto—Hand, where the center “Auto”
position is normal, meaning the DO is under Niagara control.
While the switch is physically moved to 0 (Off) or Hand (On), that DO is
manually overridden and removed from Niagara control. In the JACE station,
the current DO state is unknown—however, there is override indication.
• Each AO has a 3-position switch: 0—Auto—Hand, where the center “Auto”
position is normal, meaning the AO is under Niagara control.In addition, each AO has an adjustable potentiometer (pot).
– If the AO switch is set to 0, the AO output is 0 volts.
– If the AO switch is set to Hand, the AO output can be manually adjusted
by turning the potentiometer.
While the switch is physically moved to either 0 or Hand, that AO is manually
overridden and removed from Niagara control. In the JACE station, the current
value of that AO is unknown—however, there is override indication.
Override Indication
Whenever the manual override switch for a DO or AO on a JACE-IO-32 is moved
away from the center (Auto) position, the corresponding NdioBinaryOutput or
Ndio0to10VOutput object in the JACE-4 station changes color to magenta (purple),
as does its statusOutput (Figure 10-6).
This results from a statusFlags property change to “overridden.”
Niagara Standard Programming Reference Revised: April 20, 200410–9
Please refer to the four control objects above for details on topics such as alarming.
In addition, the following sections provide detailed information about topics
common to both control objects and Ndio objects:
• “Common Control Object Things,” page 5-5
• “Common Control Object Properties,” page 5-8
• “Event-Type Objects,” page 5-11
Note If performing a BACnet integration with a JACE-4, you can directly expose Ndio
objects as BACnet objects (BACnet server operation). They appear as the equivalentstandard objects as shown in Table 10-2 above. See the Niagara BACnet Integration
Reference for more information.
General Ndio Object Differences
Each Ndio primitive differs from a standard control object chiefly by the additional
ioIndex property, as previously shown in Figures 10-4 and 10-5. In addition, a few
other properties may vary, as noted below.
statusFlags An Ndio object has a “fault” status whenever its ioIndex property is the default 0(unconfigured), such as when initially copied from the Local Library. After
configuration, fault status can occur if the object has been assigned min and
maxPresentValue limits, and the scaled statusOutput is outside such a limit.
Fault status also occurs globally for Ndio objects if the parent NdioProcessor has
been disabled ( procEnable property on the General, Config tab set to False).
Manual Override (JACE-IO-32 Only)
As previously explained, the JACE-IO-32 expansion module features onboard
override-switches that allow individual AOs and DOs to be removed from Niagara
control. During such periods, corresponding Ndio objects have statusFlags value of
“overridden.”
statusInput Ndio UI objects differ from standard control objects because the statusInput (sIn) is
absent —the onboard physical input (JACE I/O processor) supplies the raw data.
BinaryInput NdioBinaryInput
BinaryOutput NdioBinaryOutput
1. The HighSpeedCounterInput is the only Ndio object without alarming (Event-type) properties.
Table 10-2 Standard control objects most like the various Ndio objects. (continued)
See Table 5-4 on page 5-12 for informationon these properties common to allevent-type objects.
— — presentValue can bewritten to directlywhenever the objectis set tooutOfService.
syncFlag Read Only: Shows whether the objectsuccessfully updated the configuration ofthe JACE’s dedicated I/O processor.
False, True False False until ioIndex value is assigned tonon-zero value.
C o n
f i g
executeParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 5-9.
normal,input
foreignAddress Read-Write: BACnet usage only. Set to apositive integer for this object to appear as aBACnet Analog_Input object to otherBACnet devices. See “foreignAddress,” page 5-9, for more information.
0 to 4194302
or -1(not exposed)
-1 If set, must be aunique numberamong all other AIobjects in station.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
units Read-Write: Selection of engineering unitsfor display purposes. Choose from a logicalgrouping, then a specific unit.
Select any(BACnet-typeunit choices)
Other,no_units
For selections see“About Units,” page5-6.
covIncrement Read-Write: The minimum required inputchange (since the last output change)before outputs and presentValue update.Affects the outputs statusOutput andcovTrigger (fires at change of value).
valid float 0.0
(no
minimum)
covIncrement valueis expressed insame units asscaled output value(not in voltage).
ioIndex Read-Write: I/O processor-to-terminalnumber for the UI configured by this object.
See Table 10-1 on page 10-4 for moredetails by hardware platform.
0(unconfigured)
1—6 (401, 403)1—8 (IO-XX)
0 Must be uniquenumber among allNdio UI objects forthe I/O processor.
linearization
Points
Voltage Value
Read-Write: The physical input signal(voltage) to output (value) response curve.
A linear response can be achieved with onlytwo (2) points, the default. Up to 20 pointscan be specified. Voltage rules are:
• Voltage value range is 0.0 to 10.0.
• Voltage must increase in each new point(must be greater than preceding point).
If a 4-to-20mA sensor, a linear (2 point)linearization is typically used, where:Voltage is 2.0 (4mA) and 10.0 (20mA), andValues are as defined by the sensor.
There is no“extrapolation” ofoutput values whenthe input signal isoutside the definedVoltage range.
offset Read-Write: Value added to the internallycalculated value before it passes to theobject’s statusOutput. Allows for wiring orsensor-to-system compensation.
valid float 0.0 Can be positive ornegative, asneeded.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 10 Ndio Objects
Ndio0to10VInput
10–15
0to10VInput NotesThe 0to10VInput object is used for either a 0–10 Vdc or 4–20 mA sensor.
A l a r m
S e
t u p
timeDelay,notificationClass,eventEnable,
notifyType,eventTriggerEnable,alarmText
See Table 5-5 on page 5-13 for informationon these properties common to allevent-type control objects.
— — * See specific detailson inhibitTime, thenext property.
inhibitTime Read-Write: Duration (Hr:Min:Sec) of thealarm inhibit timer, which applies only if theobject’s input statusInhibit is linked.Refer to “AI Alarm Inhibit,” page 5-19, formore information.
any practicalvalue in
Hr:Min:Sec
00:00:00(no inhibit)
A minimum of 1second (00:00:01) isrecommendedwhenever thestatusInput is linked.
minPresentValue Read-Write: Valid processing low range forthe received input value. Below this value,the object and its output have a fault status.
valid float MIN_VALUE is default, meaningno effective minimum.
maxPresentValue Read-Write: Valid processinghigh range forthe received input value. Above this value,the object and its output have a fault status.
valid float MAX_VALUE is default, meaningno effective maximum.
highLimit Read-Write: Value above which the object isevaluated in high-limit alarm. Above thisvalue (if not in fault), the object and outputhave inAlarm status.
valid float 0.0 The limitEnable flag(for high-limit) mustalso be set.
lowLimit Read-Write: Value below which the object isconsidered in low-limit alarm. Below thisvalue (if not in fault), the object and outputhave inAlarm status.
valid float 0.0 The limitEnable flag(for low-limit) mustalso be set.
deadband Read-Write: Differential value applied tohigh and low limits before return-to-normal.Deadband is subtracted from highLimit andadded to lowLimit.
valid float 0.0 Deadband does notapply to faultconditions.
limitEnable Read-Write: Flags that enable low-limit andhigh-limit alarms, as needed. (select)low-limit,high-limit
(none)
V i s u a
lposition Read-Write: See “position,” page 5-9. — —
decimalFormat Read-Write: Sets decimal posit ion from 0 to6 places, and optionally force (+) sign forpositive values.
0 to 6,
(+) sign’no (+) sign
2,
no (+) sign
Effects display valueonly (no effect onprecision).
See Table 5-4 on page 5-12 for informationon these properties common to all
event-type control objects.
— — presentValue isalways read-only.
P r i o r i t i e s
priorityArray(input: pIn )
Read Only: Shows values present on eachof the 16 priority level slots for thepriorityArray (pIn) input.
<valid float> orauto,
levels 1 to 16
auto
1 to 16
relinquishDefault Read-Write: Defines the output value whenall 16 priority level slots have an “auto”.
valid float 0.0
C o n
f i g
executeParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 5-9.
normal,output
foreignAddress Read-Write: BACnet usage only. Set to apositive integer for this object to appear as aBACnet Analog_Output object to otherBACnet devices. See “foreignAddress,” page 5-9, for more information.
0 to 4194302
or -1(not exposed)
-1 Must be a uniqueamong allBACnet-exposedAnalogOutput objectsin station.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
units Read-Only: Fixed at “volts” (Electrical). Electrical,volts
Electrical,volts
covIncrement Read-Write: The minimum requiredchange-of-value at the priorityArray input (since the last output change) before theoutputs and presentValue update. Affectsthese outputs:
• prioritizedOutput
• statusOutput
• covTrigger (fires at change of value)
valid float 0.0
(nominimum)
A small value, say0.1, may be desiredto prevent unduemovement ofcontrolled devicefrom inputfluctuations.
ioIndex Read-Write: I/O processor-to-terminalnumber for the AO configured by this object.
JACE-IO-32 has two I/O processors, eachwith 4 AOs. (Physical AOs 5, 6, 7, 8 also useioIndex 1, 2, 3, and 4 respectively).
0(unconfigured)
1, 2, 3, 4
0 Must be uniquenumber among allAnalog Outputs forthat I/O processor.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 10 Ndio Objects
NdioBinaryInput
10–20
NdioBinaryInputQuick reference for all properties: Table A-54
abbrev: ndioBI
The NdioBinaryInput (ndioBI) object
configures a JACE universal input (UI) toread the binary status of dry contacts,
typically used for equipment-status
monitoring. Apart from an “ioIndex”
property for its physical terminal address, it is
nearly identical to standard BinaryInput (BI)
object, including all alarm and event
capabilities.
Note: COS (change-of-state) frequency
must be low (1 Hz or less) for this object.
To configure a JACE UI for high-speed
count (and analog rate) of dry contacts, use
a NdioHighSpeedCounterInput object.
An NdioBinaryInput object can be exposed
directly as a BACnet Binary_Input object1.
Parent Dependencies: NdioProcessor
Resource Count Range: 90 to 146
Trigger Properties This object has the standard input property, executeTrigger , (typically not used) and
also 2 other trigger-type inputs:
• resetChangeOfStateCountTrigger —Any received trigger pulse clears the
object’s current count of COS (changes of states), resetting it to zero (0).
• resetElapsedActiveTimeTrigger —Any received trigger pulse clears the
object’s accumulated runtime (elapsed active time), resetting it to zero (0.0).
In addition, there are 4 available trigger-type outputs, described as follows:
• eventTrigger —Fires upon each event transition (to-offnormal, to-fault,
to-normal) that has been specified in the property “eventTriggerEnable.”
• changeOfStateTrigger —Fires upon each change-of-state at the statusOutput.• changeOfStateAlertTrigger —Fires each time a change-of-state alert is issued
(COS count has reached the “changeOfStateAlertLimit” value, or a “multiple”
of this value if “periodicAlerts” is set to True).
1. For direct exposure as a BACnet object, the JACE-4 requires both the BACnetService and the BACxNdioService.
Inputs
Default Object Shape
Outputs
(none) statusOutput
Inputs
All Inputs / Outputs
Outputs
executeTrigger
statusInhibit
resetCOSCountTrigger*
resetElpActTimeTrigger*
*abbreviations,see chart below
eventTrigger
statusCOSCount*
statusElpActTime*
COSTrigger*
COSAlertTrigger*
ElpActAlertTrigger*
statusOutput
*abbreviations,see chart below
Input / Output Property Reference for NdioBinaryInput Object(only input and output types, see Table 10-7 for all properties)
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 10 Ndio Objects
NdioBinaryInput
10–22
C o n
f i g
executeParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 5-9.
normal,input
foreignAddress Read-Write: BACnet usage only. Set to a
positive integer for this object to appear as aBACnet Binary_Input object to otherBACnet devices. See “foreignAddress,” page 5-9, for more information.
0 to 4194302
or -1(not exposed)
-1 Must be a unique
number among allBI objects instation.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
ioIndex Read-Write: I/O processor-to-terminalnumber for the UI configured by this object.
See Table 10-1 on page 10-4 for moredetails by hardware platform.
0 (unconfigured)
1—6 (401, 403)1—8 (IO-XX)
0 Must be uniquenumber among allNdio UI objects forthe I/O processor.
polarity Read-Write: Determines whether the outputvalue directly reflects the binary input state(normal) or “reverses” the binary state.
Typically, normally open (N.O.) equipmentcontacts are monitored using normal logic.
normal, reverse normal If normal, UI inputclosure=Active,open=Inactive.
timeOfActiveReset Read Only: Shows a date/timestamp forwhen the accumulated runtime (elapsedactive time) was last cleared.
valid timestampor null (none)
null
P r i o r i t i e s
priorityArray(input: pIn )
Read Only: Shows commands present oneach of the 16 priority level slots for thepriorityArray (pIn) input.
Active, Inactive,or auto,
levels 1 to 16
auto
1 to 16
relinquishDefault Read-Write: Defines the output state whenall 16 priority level slots have an “auto”.
Active, Inactive Inactive
inInterstartDelay Read Only: Indicates if an interstart delay iscurrently active (True) or not (False).
False, True False
C o n
f i g
executeParameters Read-Write: The object’s execution frequency and order. For
more details, see “execution Parameters,” page 5-9.
normal,
outputforeignAddress Read-Write: BACnet usage only. Set to a
positive integer for this object to appear as a
BACnet Binary_Output object. See
“foreignAddress,” page 5-9, for more details.
0 to 4194302
or -1(not exposed)
-1 Must be a uniquenumber among allBO objects instation.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
ioIndex Read-Write: I/O processor-to-terminalnumber for DO configured by this object.See Table 10-1 on page 10-4 for moredetails by hardware platform.
0 (unconfigured)
1—4 (401, 403,IO-32)
1—8 (IO-20)
0 Must be uniquenumber among allDO outputs for thatI/O processor.
polarity Read-Write: Determines if the sameboolean state at the statusInput is reflectedat the statusOutput (normal), or if the output
remains opposite from the input (reverse).
normal, reverse normal
minimumOnTime Read-Write: Upon a command frominactive to active, results in an activecommand stored at the Minimum On Offpriority level (6) for this time (Hr:Min:Sec).
Any practicaltime needed.
00:00:00
minimumOffTime Read-Write: Upon a command from activeto inactive, results in an inactive commandstored at the Minimum On Off priority level(6) for this duration (Hr:Min:Sec).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 10 Ndio Objects
NdioBinaryOutput
10–27
C o n
f i g ,
c o n
t .
restartDisable Read-Write: Determines whether the outputis automatically restarted following a stationrestart (reboot) or power failure. If set to
True, an inactive at manual level (8) isissued following such an occurrence.
False, True False
interstartDelayTime Read-Write: Defines the time period theoutput is held inactive following an activecommand. Used to prevent multiplesimultaneous starts. Applies to commandsat all priority levels except Emergency (1).
See Table 5-5 on page 5-13 for informationon these properties common to allevent-type control objects.
— — * See specificdetails oninhibitTime, thenext property.
inhibitTime Read-Write: Duration (Hr:Min:Sec) of thealarm inhibit timer, which applies only if theobject’s input statusInhibit is linked.The purpose is to prevent nuisance alarmson equipment startup and shutdown.
The inhibitTime is triggered by a transitionat the statusInhibit input.
• When statusInhibit goes false-to-true,alarm processing is delayed for this time.
• When statusInhibit goes true-to-false,alarm processing is delayed for three
times the inhibit time.
any practicalvalue in
Hr:Min:Sec
00:00:00(no inhibit)
A minimum value of1 second(00:00:01) isrecommended ifthe statusInhibitinput is linked.
Alarm processingcompares thestatusInput(feedback) value tothe priorityArray(command) value.
changeOfStateAlertLimit Read-Write: Number of COS occurrences
that generate a changeOfStateCount alert.
Positive integer 0
activeTimeAlertLimit Read-Write: Amount of runtime (elapsedactive time), in Hr:Min:Sec, that generates aruntime alert.
Any value up to9999:59:99
(Hr:Min:Sec)
00:00:00
alertNotificationClass Read-Write: The assigned notification classnumber, used in routing alerts. ANotificationClass object using the samenumber should exist in theNotificationService object’s container.
0 to 8388607 0
periodicAlerts Read-Write: Determines if both COS countalerts and runtime alerts are generatedeach time a respective limit occurs.
False, True False
alertText Read-Write: Text descriptor included ineither a COS count alert or runtime alert.
If left at the default hyphen (-), the parentcontainer object’s alertText is used.
Any text string,including spacesand mixed case
characters.
-(hyphen) 255 charactersmaximum.
V i s u a
l
position Read-Write: See “position,” page 5-9. — —
activeInactiveTextactive,inactive
Read-Write: Defines the displayed states atthe statusInput, statusOutput, andpresentValue, and also how they appear onthe object’s property sheet.
Tab Property Name Description Valid Values Default Notes
S t a t u s
objectType,
statusFlags,description
See Table 5-3 on page 5-8 for information
on these properties common to all controland Ndio objects.
— —
reliability,outOfService
See Table 5-4 on page 5-12 for informationon these two properties.
— —
presentValue Read Only: Shows the current accumulatedtotal value (as on the totalOutput).
presentValue can be written to directlywhenever the object is set to outOfService.
valid float(positive)
0.0
syncFlag Read-Write: Shows whether the objectsuccessfully updated the configuration ofthe JACE’s dedicated I/O processor.
False, True False Remains False untilthe ioIndex value isassigned.
C o n
f i g
executeParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 5-9.
normal,input
foreignAddress Read-Write: BACnet usage only. Set to apositive integer for this object to appear as aBACnet Analog_Input object to otherBACnet devices. See “foreignAddress,” page 5-9, for more information.
0 to 4194302
or -1(not exposed)
-1
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
units Read-Write: Selection of engineering unitsfor display of the total value. Choose from alogical grouping, then a specific unit.
For example, in a typical electric meterapplication, units is set to:
Energy,kilowatt_hours
Select any(BACnet-typeunit choices)
Other,no_units
units can bedisplayed by alinked GxTextobject.
For selections see“About Units,” page5-6.
ioIndex Read-Write: I/O processor-to-terminalnumber for the UI configured by this object.
See Table 10-1 on page 10-4 for moredetails by hardware platform.
0(unconfigured)
1—6 (401, 403)1—8 (IO-XX)
0 Must be uniquenumber among allNdio UI objects forthe I/O processor.
countScale Read-Write: The scale (multiplier) for thecount total, where:
totalOutput = count x countScale
valid float 1.0
rateHistory Read-Write: Number of rate intervalsamples stored and used for calculating therateOutput. The higher the number, themore normalized the rate calculation will be.
1 to 100,integer
1 See Figure 10-7 onpage 10-32 for moredetails.
rateInterval Read-Write: Time period (in seconds)
between samples from which each newrateOutput calculation is performed. Thehigher the number, the more normalized therate calculation will be.
1 to n,
integer
10 See Figure 10-7 on
page 10-32 for moredetails.
rateScale Read-Write: The scale (multiplier) for therate value, where:
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 10 Ndio Objects
NdioHighSpeedCounterInput
10–31
HighSpeedCounterInput NotesThe HighSpeedCounterInput object is used for pulse-metering applications. Outputs
for both a scaled count value and rate value are available.
Limits for the “raw” (physical) count are 232 unsigned (4,294,967,296), above whicha count “rollover” (to zero) would occur. Limits for the scaled count is the Java
“long” implementation of 263 (9,223,372,036,854,775,808) above which a “+Inf”
would appear at the countValue output. In practical usage, neither count limit is
approached.
Figures 10-7 and 10-8 illustrate example usage of rate properties rateInterval and
rateHistory to achieve “normalized” rate values.
C o n
f i g ,
c o n
t .
rateUnits Read-Write: Selection of engineering unitsfor display of the rate value. Choose from alogical grouping, then a specific unit.
For example, in a typical electric meterapplication, rateUnits is set to:
Power,kilowatts
Select any(BACnet-typeunit choices)
Other,no_units
rateUnits can bedisplayed by alinked GxText
object.
V i s u a
lposition Read-Write: See “position,” page 5-9. — —
decimalFormat Read-Write: Sets decimal posit ion from 0 to6 places, and optionally force (+) sign forpositive values.
0 to 6,
(+) sign’no (+) sign
2,
no (+) sign
Effects display valueonly (no effect onprecision).
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 10 Ndio Objects
NdioHighSpeedCounterInput
10–32
Figure 10-7 Sample graph of raw rate versus normalized rate.
This graph shows the“smoothing” effect of a ratevalue when “normalized.”
In both cases, therateInterval = 10 (seconds).
When rateHistory = 1,(default), the rate reflectsan instantaneous rate ateach rate interval, shownby the “Raw rate.”
When rateHistory = 5, therate becomes “normalized,”meaning the rateOutputlags, but is noticeablysmoother. See Figure 10-8 for the data used in thisgraph.
Raw rate Normalized rate
4.000
3.500
3.000
2.500
2.000
1.500
1.000
R a t e
50 100 150 200
R a t e
Time seconds
Figure 10-8 Example of time, pulse count and rate - raw and normalized.
Actual Time
sec.
Delta Time
sec.
Raw Count
pulses
Delta Count
pulses
Instant. Rate
pulse/sec.
Normal. Rate
pulse/sec.
This figure shows the datafor the Figure 10-7 graph.
The bolded rectanglesrepresent a sliding“window” that marchesdown the rows, showinghow the normalized rate iscalculated.
Note that for simplicity, thisexample uses defaultrateScale (1), where therate is the same as thepulses per second. Moretypically, the rateScaleproperty is set to anothervalue.
See Table 5-4 on page 5-12 for informationon these properties common to allevent-type objects.
— — presentValue can bewritten to directlywhenever the object
is set tooutOfService.
syncFlag Read Only: Shows whether the objectsuccessfully updated the configuration ofthe JACE’s dedicated I/O processor.
False, True False False until ioIndex value is assigned tonon-zero value.
C o n
f i g
executeParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 5-9.
normal,input
foreignAddress Read-Write: BACnet usage only. Set to apositive integer for this object to appear as aBACnet Analog_Input object to otherBACnet devices. See “foreignAddress,” page 5-9, for more information.
0 to 4194302
or -1(not exposed)
-1 If set, must be aunique numberamong all other AIobjects in station.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
units Read-Write: Selection of engineering unitsfor display purposes. Choose from a logicalgrouping, then a specific unit.
Select any(BACnet-typeunit choices)
Other,no_units
For selections see“About Units,” page5-6.
covIncrement Read-Write: The minimum required inputchange (since the last output change)before outputs and presentValue update.Affects the statusOutput and covTrigger(fires at change of value).
valid float 0.0
(nominimum)
covIncrement valueis expressed insame units asscaled output value(not in resistance).
ioIndex Read-Write: I/O processor-to-terminalnumber for the UI configured by this object.
See Table 10-1 on page 10-4 for moredetails by hardware platform.
0(unconfigured)
1—6 (401, 403)1—8 (IO-XX)
0 Must be uniquenumber among all
Ndio UI objects forthe I/O processor.
linearization
Points
Resistance Value
Read-Write: Physical input signal(resistance, ohms) to output (value). Up to20 points can be specified. Default setupprovides 11 points (10 segments):
See Table 5-5 on page 5-13 for informationon these properties common to allevent-type control objects.
— — * See specific detailson inhibitTime, thenext property.
inhibitTime Read-Write: Duration (Hr:Min:Sec) of thealarm inhibit timer, which applies only if theobject’s input statusInhibit is linked.Refer to “AI Alarm Inhibit,” page 5-19, formore information.
any practicalvalue in
Hr:Min:Sec
00:00:00(no inhibit)
A minimum of 1second (00:00:01) isrecommendedwhenever thestatusInput is linked.
minPresentValue Read-Write: Valid processing low range forthe received input value. Below this value,the object and its output have a fault status.
valid float MIN_VALUE is default, meaningno effective minimum.
maxPresentValue Read-Write: Valid processinghigh range forthe received input value. Above this value,the object and its output have a fault status.
valid float MAX_VALUE is default, meaningno effective maximum.
highLimit Read-Write: Value above which the object isevaluated in high-limit alarm. Above thisvalue (if not in fault), the object and outputhave inAlarm status.
valid float 0.0 The limitEnable flag(for high-limit) mustalso be set.
lowLimit Read-Write: Value below which the object isconsidered in low-limit alarm. Below thisvalue (if not in fault), the object and output
have inAlarm status.
valid float 0.0 The limitEnable flag(for low-limit) mustalso be set.
deadband Read-Write: Differential value applied tohigh and low limits before return-to-normal.Deadband is subtracted from highLimit andadded to lowLimit.
valid float 0.0 Deadband does notapply to faultconditions.
limitEnable Read-Write: Flags that enable low-limit andhigh-limit alarms, as needed.
(select)low-limit,high-limit
(none)
V i s u a
lposition Read-Write: See “position,” page 5-9. — —
decimalFormat Read-Write: Sets decimal posit ion from 0 to6 places, and optionally force (+) sign forpositive values.
0 to 6,(+) sign’
no (+) sign
2,
no (+) sign
Effects display valueonly (no effect onprecision).
Tab Property Name Description Valid Values Default Notes
Example 10-1 NidoResistiveInput setup for 10K3A1 type thermistor sensor to display degrees Celsius.
10K3A1 thermistor temperature curve(from sensor vendor) NdioResistiveInput object(linearization configuration, where points = 20)
Deg. C Ohms Deg. C Ohms Resistance Value
-50 667828 23 10923 3601 50
-40 335671 24 10450 5325 40
-30 176683 25 10000 6530 35
-20 96974 26 9572 8056 30
-15 72895 27 9165 8777 28
-10 55298 28 8777 9165 27
-5 42314 29 8408 9572 26
0 32650 30 8056 10000 25
1 31030 35 6530 10450 24
2 29500 40 5325 10923 23
3 28054 45 4367 11420 22
4 26688 50 3601 12494 20
5 25396 55 2985 13623 18
6 24173 60 2487 15001 16
7 23016 65 2082 17257 13
8 21921 70 1751 19904 10
9 20885 75 1480 25396 5
10 19904 80 1256 32650 0
11 18974 85 1070 55298 -10
12 18092 90 916.1 96974 -20
13 17257 95 787.0
Note that Resistance entries in the points (linearization table) must be enteredin an increasing manner, as shown here.
Also, the UI input is optimized to provide the best resolution around the 10Kohm range. For any sensor with a range far from 10K ohms (such as a 100-ohmor 1000-ohm type), use of this object will not perform well.
If such a sensor must be used, it is recommended that it be outfitted with atransmitter to produce a Vdc or mA output, and used instead with a UI inputconfigured by a Ndio0to10VInput object.
See Table 5-4 on page 5-12 for informationon these properties common to allevent-type objects.
— — presentValue can bewritten to directlywhenever the object
is set tooutOfService.
syncFlag Read Only: Shows whether the objectsuccessfully updated the configuration ofthe JACE’s dedicated I/O processor.
False, True False Remains False untilthe ioIndex value issuccessfullyassigned.
C o n
f i g
executeParameters Read-Write: The object’s execution frequency and order. Formore details, see “execution Parameters,” page 5-9.
normal,input
foreignAddress Read-Write: BACnet usage only. Set to apositive integer for this object to appear as aBACnet Analog_Input object to otherBACnet devices. See “foreignAddress,” page 5-9, for more information.
0 to 4194302
or -1
(not exposed)
-1 If set, must be aunique numberamong all other AIobjects in station.
membershipGroups Read-Write: (Future use only.) niagaraR2 niagaraR2 Leave at default.
covIncrement Read-Write: The minimum required inputchange (since the last output change)before outputs and presentValue update.Affects the outputs statusOutput andcovTrigger (fires at change of value).
ioIndex Read-Write: I/O processor-to-terminalnumber for the UI configured by this object.
See Table 10-1 on page 10-4 for moredetails by hardware platform.
0(unconfigured)
1—6 (401, 403)1—8 (IO-XX)
0 Must be uniquenumber among allNdio UI objects forthe I/O processor.
offset Read-Write: Value added to the internallycalculated temperature value before itappears at the object’s statusOutput. Allowsfor sensor-to-system compensation forfactors such as sensor wiring, etc.
valid float 0.0 Can be positive ornegative, asneeded. See Note inTable 10-12 onpage 10-40.
tempUnits Read-Write: Specifies the internalcalculation used on the raw input value toformat it in the correct numeric range.
Also specifies the displayed unit descriptor.For example, a linked GxText object candisplay either the “abbreviated” or “full”versions as follows:
°C degrees_Celsius,°F degrees_Fahrenheit,K degrees_Kelvin
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 10 Ndio Objects
NdioThermistorType3Input
10–39
ThermistorType3Input NotesThe ThermistorType3Input object is used for any Type 3 thermistor temperature
sensor. The offset property allows for calibration/compensation, typically for wiring
resistance.
A l a r m
S e
t u p ,
c o n
t .
inhibitTime Read-Write: Duration (Hr:Min:Sec) of thealarm inhibit timer, which applies only if theobject’s input statusInhibit is linked.
Refer to “AI Alarm Inhibit,” page 5-19, formore information.
any practicalvalue in
Hr:Min:Sec
00:00:00(no inhibit)
A minimum of 1second (00:00:01) isrecommended
whenever thestatusInput is linked.
minPresentValue Read-Write: Valid processing low range forthe received input value. Below this value,the object and its output have a fault status.
valid float MIN_VALUE is default, meaningno effective minimum.
maxPresentValue Read-Write: Valid processinghigh range forthe received input value. Above this value,the object and its output have a fault status.
valid float MAX_VALUE is default, meaningno effective maximum.
highLimit Read-Write: Value above which the object isevaluated in high-limit alarm. Above thisvalue (if not in fault), the object and outputhave inAlarm status.
valid float 0.0 The limitEnable flag(for high-limit) mustalso be set.
lowLimit Read-Write: Value below which the object is
considered in low-limit alarm. Below thisvalue (if not in fault), the object and outputhave inAlarm status.
valid float 0.0 The limitEnable flag
(for low-limit) mustalso be set.
deadband Read-Write: Differential value applied tohigh and low limits before return-to-normal.Deadband is subtracted from highLimit andadded to lowLimit.
valid float 0.0 Deadband does notapply to faultconditions.
limitEnable Read-Write: Flags that enable low-limit andhigh-limit alarms, as needed.
(select)
low-limit,high-limit
(none)
V
i s u a
lposition Read-Write: See “position,” page 5-9. — —
decimalFormat Read-Write: Sets decimal posit ion from 0 to
6 places, and optionally force (+) sign forpositive values.
Niagara Standard Programming Reference Revised: April 20, 2004
Chapter 10 Ndio Objects
NdioThermistorType3Input
10–40
The temperature-to-resistance response curve for a Type 3 thermistor sensor is shown
in Table 10-12.
Table 10-12 Type 3 Thermistor Temperature Sensor Response Curve.
Deg. F Ohms Deg. C Ohms Notes
-22 135200.0 -30 125233.0 Outside the NDIO software upper-limit of 100K ohms. Any input above100K (for example, open circuit) displays a set value. See note below.-13 102863.0 -25 102890.0
5 61012.0 -15 61030.0
JACE input circuitry is optimized to provide best resolution around theroom temperature range (10K ohms, 25 C, 77 F).
Issue #2652 NdioThermistorType3Input accuracy
Starting in r2.301.429, a fix/extension was made to the NDIO's internalresponse curve for a ThermistorType3 input object such thattemperature accuracy above 55C (131F) was greatly improved. Boilerapplications up to 120C (248F) can now be handled with little error.
Note that in r2.3.5, an NdioThermistorType3Input object with 0 (no)offset, when reading an open-circuit UI, should read exactly -13.00F or-25.00C. This varies from any object using the pre-428f curve, whichwhen reading an open-circuit UI, displays -11.92F.
Note: If upgrading a JACE with NDIO that is currently runningr2.301.428e (or earlier) to r2.3.5, please note that existingNdioThermistorType3 objects will likely need sensor calibration (offsetchange), as the old curve had about 3.5 degF error at 77F/10K ohms.In some cases, simple elimination of offset may work..If upgrading a JACE with NDIO that is currently running r2.301.429f orlater to r2.3.5, existing NdioThermistorType3 objects used in roomtemperature applications should not require any change to offset.
Niagara Standard Programming Reference Revised: April 20, 2004 A–61
Resource Count RangeTable A-79 lists the resource count range for various Niagara objects. Realize that
these values will vary from object to object, depending on the number of properties
(in each) that are set to non-default values. Note also the following:
• Container-type objects do not list collective resource counts for child objects.
• Ranges for log-type objects (AnalogLog, BinaryLog, etc.) assume the default
bufferSize of 60. Add 1 resource count for each 1-increase in bufferSize.
• Links also consume resource counts. Refer to “Link Resources,” page 2-13..
Table A-79 Resource count ranges for various Niagara objects.
AdminTool 31 to 53 GxImage 42 to 64 PollAlways 30 to 42
AnalogInput 63 to 116 GxInteger 43 to 80 PollArchiveService 33 to 47
AnalogLog 115 to 160 GxPage 54 to 77 PollOnDemand 30 to 42
AnalogOutput 72 to 132 GxPipe 18 to 33 PrinterRecipient 22 to 34
AnalogOverride 41 to 57 GxSpectrum 48 to 81 Program 52 and up
ApiRecipient 16 to 21 GxText 49 to 86 RemotePrinterRecipient 27 to 39
AuditLogService 38 to 1043 GxTimePlot 58 to 94 Schedule 72 to 132
BackupService 22 to 28 IntegerLog 115 to 160 ServiceContainer 600 and up
BinaryInput 80 to 136 IntToFloat 35 to 51 Station 89 to 200
BinaryLog 115 to 160 LogService 33 to 47 StringLog 115 to 160
BinaryOutput 91 to 155 Logic 67 to 101 TimeSyncService 41 to 63
BinaryOverride 41 to 55 Loop 75 to 137 Totalizer 42 to 62
Bundle 48 to 74 MailRecipient 24 to 47 UiEngineService 40 to 47
Calendar 72 to 132 MailService 29 to 50 WebUiService 25 to 33
Command 32 to 42 Math 67 to 101 Note: Program objects are typicallylarge consumers of resource counts.Whenever possible, use standardcontrol or apps objects whenengineering a station database.
The resource count for any portion of arunning station (container or primitiveobject) can be checked by clicking theobject in the JDE Tree View, andselecting from the menu bar Search >
Resource Count.
You can also open a host connection
using a browser and use the prismresources page to check a station’sresource count allocations. See“Checking Resource Count,” page1-25.
Comparison 48 to 80 MultistateInput 79 to 141
Composite 48 to 74 MultistateLog 115 to 160
Container 30 to 42 MultistateOutput 93 to 161
ControlEngineService 60 to 70 MultistateOverride 39 to 55