Technical Publications

Niagara Standard Programming Reference

Niagara Release 2.3.5 Revised: April 20, 2004

Tridium, Inc. 3951 Westerre Parkway Suite 350 Richmond, Virginia 23233 USA http://www.tridium.com Phone 804.747.4771 Fax 804.747.5204

Copyright Notice: The software described herein is furnished under a license agreement and may be used only in accordance with the terms of the agreement. Copyright 2004 Tridium, Inc. All rights reserved. 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, and system 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 rights 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-Conditioning 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, and LonWorks 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. Niagara Standard Programming Reference Copyright 2004, Tridium, Inc. All rights reserved.

C O N T E N T S

PREFACE

About This Document Intended Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Prerequisite Knowledge. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Formatting Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Commonly Used Terms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Related Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Document Updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

ix ix x x xi xii xvii xvii

CHAPTER

Station and Objects A Station Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Niagara Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Model (Integration Platform) . . . . . . . . . . . . . . . . . . . . . . . . . . Data Modeling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Hierarchies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Name and SWID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Names (and Rules) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Swid. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Object Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Station . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Station Limits and Guidelines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Monitoring JACE-NX, JACE-NP Environment Variables . . . . . . . . Niagara Properties Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Host > Edit File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Archiving Properties Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . List of Niagara Properties Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

1-1 1-2 1-3 1-3 1-4 1-4 1-5 1-5 1-6 1-7 1-7 1-8 1-9 1-24 1-27 1-27 1-28 1-30 1-31

CHAPTER

Data Species and Links Data Species . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-1 2-1

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

iii

Contents

Data Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Enumerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Variable Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Property Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Links. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Link Editor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Link Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Link Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Link Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Link Data Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Link Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CHAPTER

2-2 2-2 2-3 2-5 2-5 2-6 2-7 2-10 2-11 2-12 2-13

Commands and Views Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Control Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Admin Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . All Available Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Standard Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Special Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . All Available Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-1 3-1 3-1 3-2 3-3 3-6 3-6 3-7 3-8

CHAPTER

Services About Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Core Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Additional Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Notes on Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Adding or Removing Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Service Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . AuditLogService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BackupService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ControlEngineService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DatabaseService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ErrorLogService. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LogService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MailService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NotificationService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4-1 4-2 4-2 4-2 4-3 4-3 4-4 4-5 4-6 4-8 4-10 4-16 4-28 4-31 4-36 4-39

iv

Niagara Standard Programming Reference

Niagara Release 2.3.5 Revised: April 20, 2004

Contents

PollArchiveService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . TimeSyncService. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . UiEngineService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WebUiService . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

CHAPTER

4-41 4-45 4-47 4-49

Control Objects About Control Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BACnet Heritage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selecting Control Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Control Object Things . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Trigger Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Debug Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . About Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Control Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . Event-Type Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AnalogInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AnalogOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AnalogOverride . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BinaryInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BinaryOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BinaryOverride . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CpAnalogNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CpBinaryNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CpIntegerNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . CpStringNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . DateTimeTrigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . FunctionGenerator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IntToFloat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loop. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Math. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MultistateInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MultistateOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MultistateOverride. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PeriodicTrigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Totalizer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-1 5-2 5-3 5-4 5-5 5-5 5-5 5-6 5-8 5-11 5-15 5-23 5-29 5-33 5-42 5-53 5-57 5-59 5-62 5-65 5-67 5-69 5-71 5-73 5-77 5-79 5-83 5-95 5-101 5-112 5-124 5-128 5-130

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

Contents

CHAPTER

Apps Objects About Apps Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BACnet Heritage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Selecting Apps Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Apps Object Things . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Apps Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Log Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AdminTool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . AnalogLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BinaryLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Calendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IntegerLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MultistateLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Schedule . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . StringLog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

6-1 6-2 6-2 6-3 6-4 6-5 6-7 6-18 6-26 6-32 6-35 6-41 6-44 6-47 6-52 6-60

CHAPTER

Container Objects About Container Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tree View Controls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Container Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inputs and Outputs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Layers in Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Browser Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Container Object Things . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Security Groups and Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Alarm and Alert Text. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Container Object Properties. . . . . . . . . . . . . . . . . . . . . . . . . . Containers That Composite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . To Composite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Or Not to Composite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Bundle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Composite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Container . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GxPage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PollAlways . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

7-1 7-2 7-2 7-3 7-3 7-3 7-4 7-4 7-5 7-5 7-6 7-6 7-8 7-9 7-13 7-14 7-19 7-22 7-24 7-29

vi

Niagara Standard Programming Reference

Niagara Release 2.3.5 Revised: April 20, 2004

Contents

PollOnDemand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ServiceContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CHAPTER

7-31 7-34

Gx Objects About Gx Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Execution of Gx Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Gx Object Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Gx Object Things. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Gx Object Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Gx Object Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GxBarGraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GxBoolean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GxDamper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GxFan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GxFloat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GxImage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GxInteger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GxPipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GxSpectrum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GxText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . GxTimePlot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

8-1 8-2 8-2 8-2 8-3 8-4 8-6 8-10 8-13 8-16 8-18 8-20 8-22 8-24 8-26 8-28 8-30 8-33

CHAPTER

Notification Objects About Notification Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Recipients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Notification Schemes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Linking Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Notification Object Properties . . . . . . . . . . . . . . . . . . . . . . . NotificationClass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ApiRecipient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MailRecipient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PrinterRecipient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . RemotePrinterRecipient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SnmpRecipient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VasRecipient . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

9-1 9-2 9-2 9-2 9-3 9-3 9-4 9-5 9-8 9-9 9-13 9-15 9-17 9-18

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

vii

Contents

CHAPTER

10

Ndio Objects About Ndio Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ndio Containers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ndio Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Processor Responsibilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ndio UI objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ndio outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Common Ndio Object Things . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General Ndio Object Differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . NdioContainer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NdioProcessor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ndio0to10VInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Ndio0to10VOutput. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NdioBinaryInput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NdioBinaryOutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NdioHighSpeedCounterInput. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NdioResistiveInput. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NdioThermistorType3Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

10-1 10-2 10-2 10-3 10-4 10-5 10-6 10-8 10-9 10-10 10-11 10-13 10-16 10-20 10-24 10-29 10-33 10-37

APPENDIX

Object Property Quick Reference

Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Attribute Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Attribute Notation Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Property Quick References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Resource Count Range. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

A-1 A-1 A-1 A-2 A-3 A-61

INDEX

viii

Niagara Standard Programming Reference

Niagara Release 2.3.5 Revised: April 20, 2004

About This Document

This document is intended to help you understand and use the standard Niagara object set for programming a Niagara station. Included is reference information for all objects in the standard tridium JAR, plus those in the tridiumx, ndio JAR.

This preface includes the following sections: Intended Audience Prerequisite Knowledge Document Summary Formatting Conventions Commonly Used Terms Related Documentation Document Updates

Intended Audience
The following people should use this document: Vykon systems integrators and installers responsible for initial setup and ongoing configuration of JACE controllers and Web Supervisors. Vykon application programmers.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

ix

Preface Prerequisite Knowledge

About This Document

Prerequisite Knowledge
Readers of this document should know or have experience with the following: Basic Niagara concepts, such as stations, nodes (objects), properties and links. Niagaras Java Desktop Environment (JDE, formerly called WorkPlace Pro), including the necessary tasks to provide system control and user interface. Ideally, you should be Niagara-certified, that is, have successfully passed Tridiums formal Niagara Technical Certification Program.

Document Summary
This 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 objects are 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 Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Preface

About This Document Formatting Conventions

Formatting Conventions
This document uses the following text formatting conventions: Bold text indicates an important keyword, user entries, and so forth. CAPITAL letters are used for acronyms, such as WPP (WorkPlace Pro). They are also used to identify keyboard keys in instructions, such as press ENTER or press CTRL-C. Italic text is used for emphasis. It is also used to refer to the titles of other publications and document filenames. Italic text also appears for non-literal text that represents a variable, for example, station_name or DONOFF_n. Quotation marks are used to refer to other sections within the document. <text between brackets> means a variable placeholder or part of a general running commentary, for internal Tridium use only.

Important Information Indicators

In addition to text formatting, this document uses two types of important information indicators and three types of additional information indicators, as listed below: Notes typically contain significant details related to the topic in the nearby text. They alert you to important information that might otherwise be overlooked.

Note

Caution

Cautions remind you to be careful. There is a chance that you could perform an action that cannot be undone, might produce unexpected results, or might cause lost data. Cautions typically explain why the action is potentially problematic. Additional Information IndicatorsThe following note additional information: Refer to references point to other documents that contain additional information on the current topic. The reference includes the name of the document, and if applicable, the chapter name and number where the additional information appears.

Refer to

Tip

Means a best practice or other helpful instruction. Tips typically contain recommendations that will help you use the product more effectively.

Timesaver

Means a shortcut. Timesavers typically tell you a quicker or shorter way to perform a task. They might include keyboard combinations or buttons that can be used instead of menu selections to perform the same action.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

xi

Preface Commonly Used Terms

About This Document

Commonly Used Terms

Throughout 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. 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. An off-normal condition for an object when it meets alarm criteria, such as alarm low (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. A warning-type exception message generated when an object reaches some predefined limit, for example, hours of runtime or COV , COS count limit. Data represented by a continuously-variable value, typically a floating-point (float). Control object types AnalogInput, AnalogOutput, and AnalogOverride (among others) use analog data. Application objects. A class of Niagara objects that include global control objects (Calendar and Schedule), various data logging (log) types, and the Program object. 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. Data represented by only two discrete states (boolean), either active or inactive. Control object types BinaryInput, BinaryOutput, and BinaryOverride (among others) use binary data. In general Niagara terms, any object contained inside another objects Workspace. A child object can be a primitive object or a container object (with its own children). A primitive object is always a child object.

Admin Tool

alarm

alert

analog

apps objects

BACnet

binary

child object

xii

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Preface

About This Document Commonly Used Terms

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. If all lowercase (container), it refers to any Niagara container-type object, including Bundle, Composite, Container, GxPage, PollAlways, and PollOnDemand types. All typically contain child objects. If capitalized (Container), refers to that specific type. 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. Change-of-value, change-of-state. Niagara data types, of which there are many. Data species include primitive data types, data enumerations, and structured data types (variable types). Each property of a Niagara object is implemented with a specific data species. 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. 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). 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). Generic term for one of two binary (boolean) states, typically synonymous with Off, Stop, or False. The complimentary term is active. An object property designed for linking to the output of another object. Data received on an input is typically used in the objects algorithm (purpose). 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.

container object

control objects

COV, COS data species

dependencies

enumerations

events

inactive

input

JAR file

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

xiii

Preface Commonly Used Terms

About This Document

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). 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, and control 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. 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. 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. 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. 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 child objects that make up a station database. Niagara objects are of particular known types. For readability purposes, leading and internal caps are used when referring to object typesfor example, AnalogInput, GxPage, FunctionGenerator, and so on. An object property designed for linking to the input of another object. Data produced at an output typically reflects the results of the objects algorithm (purpose). 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 Ndio Objects, used to interface with the hardware I/O points. 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 characteristicseach 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.

links

Local Library

LonWorks

multistate

object

object types

output

Ndio

node

xiv

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Preface

About This Document Commonly Used Terms

parent

In general Niagara terms, a child objects 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. In the context of objects, a primitive object is any object that is not a containerfor 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. 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). 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 stations JVM (Java virtual machine). Each object description in this document lists the objects Resource Count Range. 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. 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. 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). An Admin Tool option providing a special window to view and save a running stations 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. 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. 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 Stations 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:
http://<hostnameOrIP>/db/<stationName>/<containerName>/<objectName>

primitive

properties

resource count

Remote Library

service

sns

Standard Output

station

swid

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

xv

Preface Commonly Used Terms

About This Document

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 Time (and date) stamp, typically generated within an objects 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. 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. 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. 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. 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. 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. 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. 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.

timestamp

trigger

URL

views

Web Supervisor

WebUiService

Workspace

WorkspaceEditor

xvi

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Preface

About This Document Related Documentation

Related Documentation
For additional information, please refer to the following other Niagara Technical Publications: Niagara Concepts GuideExplains the various concepts and tools that comprise the Niagara Framework. This document is a good starting-point for anyone new to Niagara and the JDE (Java Desktop Environment). JDE Users GuideExplains how to use the JDE, including the Admin Tool and the Alarm Console. Procedures for common tasks used in engineering and monitoring Niagara stations are provided. Using the Niagara Admin ToolExplains features and tasks performed in the Admin Tool, which can be run either standalone or within the JDE. Niagara Networking & Connectivity GuideA complete guide on Ethernet/IP networking, including configuration details for any Niagara host, firewall considerations, modem (dialup) setup, reference data, and troubleshooting tips. Niagara Web Solutions GuideProvides 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 ReferenceProvides 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 ReferenceProvides 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 NotesProvides details on sysmon configuration for the JACE-NP and JACE-NX platforms, including special shadow objects found in the tridiumx/systemMonitor JAR.

Document Updates
Updates to this document are listed below. Date
11/15/2001 05/09/2002 05/14/2002 09/30/2002 06/13/2003

Update, Notes
Initial document revision for Release 2.2. Revised document for Release 2.3. Minor update, still Release 2.3. Various corrections, still Release 2.3. Initial document revision for Release 2.3.4. For details about changes in Release 2.3.4 from the previous release, please refer to 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 on engineering units (About Units, page 5-6). Various other small changes. For details about changes in Release 2.3.5 from the previous release, please refer to the Release Notes document for Niagara r2.3.5.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

xvii

Preface Document Updates

About This Document

Date
04/14/2004

Update, Notes
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. Revision. Minor change in Appendix A, Object Property Quick Reference, adding enum type DatabaseTypeEnum and updating DatabaseService properties list.

04/20/2004

xviii

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

CHAPTER

Station and Objects

A Niagara station runs in a JVM executing a station database defined by nodes (objects). What makes one station unique from another is the specific collection of objects used, their specific configurations, and their defined relationships. Although every station database will be unique, the object building blocks used are common and reusable. In addition, the way information is structured in a Niagara station follows a definite patternwhether primitive values, property structures, object entities, or services provided. This section provides the following main topics:

A Station Overview Niagara Objects Object Model (Integration Platform) Data Modeling Object Hierarchies Object Name and SWID Object Names (and Rules) Object Swid Object Categories Station Object AddressBook View UserAdmin View ActiveUsers View Alarms View Station Limits and Guidelines Monitoring JACE-NX, JACE-NP Environment Variables Niagara Properties Files

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

11

Chapter 1 A Station Overview

Station and Objects

A Station Overview
A Niagara station runs in a specific host, the platform being either a JACE controller (JACE-NP, JACE-NX, JACE-5, JACE-4) or a Web Supervisor (PC). With few exceptions, the target host platform makes little difference in how you use the JDE to engineer a station database. The same standard Niagara objects and libraries apply. One notable exception is the DatabaseService, which provides an SQL application database for archiving log data, alarms, and alerts. Due to the significant storage requirements for archiving this data, the DatabaseService cannot run in a JACE-4/5 station. However, any Niagara station (including one in a JACE-4/5) can be configured to archive remotely to another Niagara station running the DatabaseService. Typically, the archiving station is the Web Supervisor. Another notable exception is the ndio module (Ndio objects), which provide the station interface to the physical onboard I/O points on a JACE-4 or JACE-IO expansion module (or any future JACE model with onboard I/O). Currently, Ndio applies only to a JACE-4 station.

12

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 1

Station and Objects Niagara Objects

Niagara Objects
Objects 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 the same 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. 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 station database with common behaviors.

Note

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

13

Chapter 1 Niagara Objects

Station and Objects

Although not covered in this document, most Niagara integrations include these types of objects: Service objectprovides 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 objectprovides a container for all foreign device-types objects specific to an integrated network. Device-level objectseach 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 objectseach 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: PrimitiveA 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). ObjectThe 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. StationThe 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 bidirectionalprimitives 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. By definition, 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

14

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 1

Station and Objects Object Name and SWID

objects, and notification recipient objects. Most integration objects are also primitive objects, which shadow data values, commands, or status in a foreign (integrated) device. Examples include most LonWorks objects and BACnet objects.

Object Name and SWID

In a Niagara station, each object has a name and an associated SWID (system-wide identifier). To improve readability, all other references to the system-wide identifier will use lower case, that is swid. Object Names (and Rules) Object Swid

Object Names (and Rules)

Niagara object names must follow these rules: Letters, numerals, and underscores (_) are the only allowable characters. (This means spaces are not permitted.) The name must begin with a letter. The objects name must be unique within its Workspace, that is, within its parent container (level of hierarchy in the stations database). However, within a station there may be many objects with the same name. Each object is at a different level (branch) of the station database. For example, there may be many objects named SupplyFan in a station. However, each object will have a unique swid, because the path of the object will vary from one instance to another.

It is recommended that no child object be given the same name as its parent container object, to avoid a possible name duplication error. Names are case-sensitive. For example, SupplyFan and supplyFan are considered different names. The JDE automatically enforces the uniqueness of object names when you duplicate or copy objects in the same container. This is done by appending a unique numeral to object names, for example, SupplyFan_1 and SupplyFan_2. When naming objects, brevity is encouraged. This is particularly true for parent (container) objects, which are included in the swid for any child object. See the related Caution in the next section. With one exception, the JDE allows you to rename any object in the station. The exception is the Station object, named only in the New Station wizard. You typically rename objects as needed only when first engineering a station. Renaming an object after a station database is engineered may cause problems, particularly if there are URL (swid) references to that object in other objects.

Notes

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

15

Chapter 1 Object Name and SWID

Station and Objects

Object Swid
An objects swid includes the objects name, but is morea complete and unique address of where it resides in the station database. It is similar to both a file path and a URL (uniform resource locator), due to the Web-server nature of a Niagara station. For any Niagara object, a swid uses the following format:
http://<host IP or name>/db/<station name>/<path of object>

The first part of the swid indicates what protocol to use, namely, http:/. The next part specifies the IP address (or the domain name) of the Niagara host. The next part is always /db for any Niagara object. The next part is the station name. The last part reflects the station hierarchy of the object. This includes not only the object (by name), but also its complete tree location. In other words, before the objects name are the names of any proceeding parent (container) objects. Consider the following swid for a NotificationClass object named class0.

http://192.168.1.34/db/NetSup2000/services/NotificationService/class0

This swid shows that the object class0 is a child of the object named NotificationService, which in turn is a child of the object named services. The stations name is NetSup2000meaning that the foundation (Station) object named NetSup2000 contains all other objects. Keep object swids under 128 characters, inclusive of the station name. Do this by using shorter names for objects (particularly container objects) and fewer levels of containers. Table and index views list objects by swid, and are easier to use this way. Also, a log object with a swid over 128 characters can cause archive problems. A variety of Niagara objects have internal properties that accept a swid, for example, hyperlinkUrl and boundUrl (most Gx objects) and rootNode (AdminTool object). When entering a swid that references another object in the station, the swid format is shortened to drop the leading http://<hostname or IP address> portion. Instead, the swid begins with the /db string portion (root of the stations database). As an example (instead of the complete URL), a swid used as the property value:
/db/NetSup2000/services/NotificationService/class0

Caution

Swid in Property Sheets

Tip

To avoid manually typing a swid in a property sheet field, you can simply use Tree View to select the target object, right-click, and choose Copy. You can then paste the properly-formatted swid in the property field, using CNTRL-V.

16

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 1

Station and Objects Object Dependencies

Object Dependencies
In 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. In addition, 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 Categories
Standard 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.
Object categories seen when adding new objects.

The different object categories are: FoundationOnly one type, the Station object. Each station has only one. Control ObjectsSeveral 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 Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

17

Chapter 1 Object Categories

Station and Objects

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 ObjectsSeveral 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 ObjectsSeveral standard types, each can be used as a component of a graphical view built to show real-time values and status (user interface). Container ObjectsSeveral standard types, used to hierarchically organize and provide specific functionality to contained objects (children). Notification ObjectsSeveral standard types, each provides unique functions to a stations NotificationService (a particular type of service object). ServicesSeveral 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: programsHolds 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 each available Program object. applicationsA 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.

18

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 1

Station and Objects Station

Station
Quick reference for all properties: Table A-72 Inputs
(none)

Object Shape
Outputs
(none)
(none)

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

Input / Output Property Reference for Station Object

(only input and output types, see Table 1-1 for all properties)

Type
input output

Label

Property Name

Data Species

Station Icon Meanings (Tree View) Icon Description

Station icon is black.

Typical Meaning
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. Station is open offline. Gray cylinder. Gray cylinder with red shading. Station is open offline, and changes have been made but not saved.

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.

Commands
Users with Command, Admin privileges have the following available command: BackupXMLCauses 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). BackupSNSCauses the station to locally backup its running database to SNS format (backup there). Applies to any selected Niagara station, including a JACE-4/5. BackupSubordinatesXMLApplies if the selected station is configured as supervisor (typically, Web Supervisor). Backs up the running station database in each subordinate-designated station, to the appropriate stations subfolder, in XML format (a global-backup here). All station types are supported. BackupSubordinatesSNSApplies 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.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

19

Chapter 1 Station

Station and Objects

RestartCauses an immediate restart of the selected station. If this command is given from the JDE, a Confirm dialog appears first. Applies to JACE-NP and Web Supervisor stations only (not JACE-4/5 stations).
Note

Restarts are not typically needed, except after adding a new service.

RebootCauses an immediate system reboot of the stations host machine. If this command is given from the JDE, a Confirm dialog appears first. Applies to all station types. Typically, this command is given only to a JACE-4/5 station, as the method of restarting the station. A reboot command to a Web Supervisor or JACE-NP station is the same as restarting Windows on that host! Generally, not recommended.

Note

Stack DumpCauses a dump of all station threads for use as an aid to debug deadlocks and CPU usage. Currently, this command is for internal (development) use only, as a non-standard JVM is required. dumpCauses a dump for the Station object to be sent to Standard Output.

Properties
Table 1-1 Station object properties.

Tab Property Name

objectType statusFlags

Description
Read Only: The object type. Read Only: Current state of the objects status flags. A normal state (no flags set) is where the statusFlags value is {ok}. Read-Write: Permits a user-defined descriptor for the station. Any printable characters are allowed. Read-Write: The current time and date for the host running the station. Format is: date: dd Mon yyyy (ex: 18 Oct 20001) time: hr:min AM/PM (ex: 8:21 AM) Allows review/change of system (host) time, as in System Time tab of the Admin Tool.

Valid Values
Station {ok} or {down} See Descrip.

Default
Station {ok}

Notes

description

Niagara station. Unlike when using the Admin Tool to set system time, the time zone is not modifiable here.

currentTime (date) at (time) Status

valid time and date

bootTime lastDownTime lastAliveTime

Read Only: Timestamp of the last station startup. (Station has been running since.) Read Only: Timestamp of when the station last stopped (prior to recorded bootTime). Read Only: Timestamp of last station health check. Should be within 1 minute of the currentTime. Read Only: Indicates whether station is running properly.

See Notes See Notes See Notes

(for each) format is: hh:mm dd-mo-yyyy TimeZone

isRunning

False, True

True

110

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 1

Station and Objects Station

Table 1-1

Station object properties. (continued)

Tab Property Name

osArch

Description
Read Only: Operating system architecture. Is x86 for JACE-NP or Web Supervisor, or ppc for JACE-4/5. Read Only: Operating system name. Is Windows NT for JACE-NP, NX, or Web Supervisor, and VxWorks for JACE-4/5. Read Only: Operating system version. JACE-NP (NT) is 4.0 JACE-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. 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 River Systems Inc. Read Only: Version of JVM used by station. At 2.3.5 release time, version is 1.4.1 (Sun Hostspot) or 1.1 (Wind River Systems). Read Only: Niagara Release level in use. For example, 2.301.507.v1

Valid Values
x86 or ppc Windows NT or VxWorks See Descrip.

Default
See Descrip. See Descrip. See Descrip. and Note.

Notes

osName

osVersion Status, cont.

At time of 2.3.5 release, VxWorks version is 5.4.2.

javaVendor

See Descrip.

See Descrip.

Prior to r2.3.5, Win32 platforms used Microsofts JVM.

javaVersion

See Descrip.

See Descrip. See Descrip. 80 If using a port other than 80, you also need a line in the station.properties file, for example: httpPort=85 Otherwise, you will not be able to do DbAdmin functions. An httpPort change becomes active after station restart.

release httpPort

valid release level

80 Read-Write: Number of logical port used for (recommended) TCP/UDP connections in HTTPD access. Applies to normal station communications. or other unused port The JDE and browsers, by default, assume the well known port of 80. If you assign a different port, you need to append this number (with colon) after the hostname or IP address when opening the station in the JDE, or when accessing in a browser.

For example: http://192.168.1.25:85 for a browser connection on port 85. httpsPort Config Read-Write: (Future Use) Number of logical port for TCP/UDP connections in HTTPS access. Applies if enableSSL is True. Port 443 is the well known standard. enableSSL Read-Write: (Future Use) Allows SSL (secure socket layer) HTTPS connections. Requires the Niagara SSL service plus additional configuration, including certificate from a Certificate Authority (CA). defaultPage Read-Write: Specifies the HTML page (or valid swid to station swid) to display with browser access HTML page or to the station, if no specific URL is provided. GxPage, for example Applies if the user has no Browser Home entry (UserAdmin view, General Tab). Absolute references or release directory "/" should be used for linking in all interfaces. False, True False 443 or other unused port 443

SSL will be supported in a future Niagara release.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

111

Chapter 1 Station

Station and Objects

Table 1-1

Station object properties. (continued)

Tab Property Name

pstoreFlushTime

Description
Read-Write: Applies to JACE-NP and Web Supervisor stations only. Specifies the interval, in milliseconds, between automatic saves of persistently-stored properties. Updates the Config.db file in the proper stations subdirectory, at this frequency.

Valid Values
1000 to MAX_VALUE

Default
5000 (ms)

Notes
Does not apply to a JACE-4/5. Only properties modified since the last flush are saved.

snsBackupTime

Read-Write: Specifies the interval, in minutes, between automatic backups of the station database to sns (serialized nodeset) format. All persistently-stored properties are saved. Each backup updates the Config.sns file in the proper stations subdirectory. The previous Config.sns is renamed to Config.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 sns backups 0 or negative to disable auto sns backup

180 (minutes)

Applies to Niagara station on any host platform.

Config, cont.

interstationSendTime

Read-Write: Specifies the interval, in milliseconds, between sending change of value updates to external subscriptions (external links, i.e., links between stations). Read-Write: (Future use) Read-Write: (Future use) Read-Write: (Future use) Leave at False (default) to avoid unnecessary messaging. Read-Write: (Future use) Minimum announcement frequency.

integer, 500 to n

5000 (ms)

More properties that affect external links are adjusted in system.properties. These properties are related to a future release of Niagara software. Their application will be explained at a later date.

membershipGroups announcementTTL enableAnnouncement minAnnouncementFreq

niagaraR2 False, True (for each)

niagaraR2 3 False 55000 (ms) 65000 (ms)

-

maxAnnouncementFreq Read-Write: (Future use) Maximum announcement frequency. alarmText Read-Write: The (final) top-level alarmText available for any alarmable child objects.

Alarm Setup

alertText

255 characters For child objects to use this, their alarmText maximum. properties must have only the default Any text string, hyphen (-). See Alarm and Alert Text on including page 7-5 for more information. spaces and mixed case Read-Write: The (final) top-level alertText characters. available for any alert-capable child objects. For child objects to use this, their alertText properties must have only the default hyphen (-). See Alarm and Alert Text on page 7-5 for more information.

The alarmText value is not used in change-of-state events of Station objects. Instead, the messageText in alarm records for these events uses the enumerated descriptor, such as stationDown or stationUp. See Station Alarm Types on page 1-23.

112

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 1

Station and Objects Station

Table 1-1

Station object properties. (continued)

Tab Property Name

notificationClass Alarm Setup, cont.

Description
Read-Write: The notification class used for change-of-state events for the station (for example, coming Up after going Down). This class is also used in notifications of station events occurring for remote stations, meaning those monitored by this station (AddressBook view). If a JACE-NP on JACE-NX and environment monitoring is enabled (1-27), associated alarms are sent to this notification class.

Valid Values
0 to 8388607

Default
0

Notes
A NotificationClass object with this same notification class number is required in the stations NotificationService container.

position Visual alarmPageUrl nextHandle Engineering

Read-Write: Has no practical application for the Station object. Read-Write: (Future Use) Specifies the URL to display on alarm. Read Only: Shows the handle (number) that will be automatically assigned to the next object added to the station database. Each object has a unique handle. The 0 handle is reserved for the Station object. Handles are seen in Standard Output following a dump command.

<integer> greater than 0

-2147483648 x 0

Not currently implemented. The integer value of nextHandle approximates the number of objects in the station.

securityGroups

Read-Write: Shows the security groups to which the Station object is assigned.

Any mix of these types:

General

General In the JDE, these security settings affect access to the Station object, and not all child HVAC objects (unlike with other container objects). Security A JDE user without any rights to the Station Life Safety object can still expand the station in Tree Group 4 View and see other container objects Group 5 (assuming that rights exist to securityGroups assigned to those objects). Group 6 Group 7
Security strongPasswords Read-Write: Specifies whether station users each require a strong password (True). The rules for entering a strong password (in the UserAdmin view of the station): False, True False

A JDE user with only operator-level property read access to the Station object can still use UserAdmin to change their logon password, JDE Home, and Browser Home.

Must be a minimum of 8 characters, with

no spaces permitted.

At least 1 character must be uppercase. At least 1 character must be lowercase. At least 1 character must be a special
character, meaning either a numeral 0 to 9, or one of the following: ! @ # $ % Some examples of strong passwords: J%ohn9Tv 1toGoHome GroovyBaby!

If strongPasswords is enabled after users are already created, existing (non-strong) passwords will continue to work OK. However, no changes for a user (UserAdmin view) can be made until a strong password is assigned to them.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

113

Chapter 1 Station

Station and Objects

Station Notes
Special Go menu views of a Station object are described in the following sections: AddressBook UserAdmin ActiveUsers Alarms

The following additional topics, while not specifically about the Station object, are closely related. Station Limits and Guidelines, page 1-24, provides information about the capacities of the various Niagara host platforms. Monitoring JACE-NX, JACE-NP Environment Variables, page 1-27, provides information on configuring a JACE-NX or JACE-NP to allow a hosted station to monitor the internal (CPU) temperature and voltages. It applies to these Niagara platforms only.

114

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 1

Station and Objects Station

AddressBook

A Station objects AddressBook stores information about other Niagara stations that are part of a job, and describes relationships among them.
Figure 1-2 AddressBook view lists currently defined remote stations.

For a Web Supervisor station, entries are required for each JACE station. For each JACE station, an entry is required for the Web Supervisor station, at a minimum. If external links are made between JACE stations, entries are required for those stations too. Figure 1-3 shows an example edit dialog.

Figure 1-3 Edit dialog (Add Address/Change Address) has several sections.

Entry fields are in main sections:

Station AccessInformation
about the remote station, including its name, a user account, and user password. NetworkIP address/hostname of the remote host running the station. If not HTTP port 80, also the HTTP port number n, as :n DialupApplies only if modem dialup access is required to connect to the remote station. Poll Archive GroupApplies only if the local station is running the PollArchiveService. (Station relationship) Peer, Subordinate, or Supervisor. Defines the relationship of the remote station. MonitorWhether the local station should monitor (ping) the remote station, and what non-response time is tolerated before an alarm occurs.

Station Access: This section has the following fields:

Station NameThe Niagara station name of the remote station. Must be unique from other station entries in the AddressBook. User NameAn existing user account in the remote station. This user requires admin-read (General) security rights to support the backupSubordinates command and Status Index from a Web Supervisor.

Note

By convention, a gdp user is often created in each station and assigned General Admin read rights and also a password. This user is referenced in AddressBook entries in other stations.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

115

Chapter 1 Station

Station and Objects

PasswordPassword for the user in the remote station. See the Note above. Confirm PasswordSame password again, repeated.

Network: One field, namely:

Host AddressIP address (recommended) or hostname for the remote stations 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 hosts 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 NameLogon user name for the host machine. Host PasswordPassword for the user name above, to access the host machine. Confirm PasswordSame password again, repeated.

Poll Archive Group: Applicable only if this station has the PollArchiveService. Provided is a drop-down list of poll archive groupseach remote station can be assigned to any (including disabled). See PollArchiveService on page 4-40. (Station relationship): Drop-down list with description of the remote stations relationship to this station. Selections include:

PeerTypical 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. SubordinateWhen in the AddressBook of a Web Supervisor station, this is typical for each JACE station entry. SupervisorWhen 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 objects Alarms view.
Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

116

Chapter 1

Station and Objects Station

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. A JDE user logged on as the default administrator can effectively replace the administrator account, using the menu bar command UserAdmin > Change Admin User. 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).

Note

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 tridiumx/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 Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

117

Chapter 1 Station

Station and Objects

General TabThe General tab provides user password access and home page logon preferences.
Figure 1-5 Example General tab of a user selected in UserAdmin view.

Entry fields are as follows: User NameThe user name, as used in the station. Case-sensitive, it must begin with a letter, and have no spaces. It must be unique among user names in the station. A user logs on using this name (often, a users initials are used). Once created, this name cannot be changedonly the entire account deleted. Full NameA descriptive name for the user, it is editable by the user. Initially, it is set to match the entered user name for a new user. Java Desktop Environment Home(optional) Swid to object (for example, GxPage) to display in the JDE Workspace after user logon, or whenever the standard Go menu option Home is selected. Editable by the user. Browser Home(optional) Swid or URL to object, HTML page, or other resource to display in a Web browser after user logon. Editable by the user. If left blank, the Station objects defaultPage swid or URL is used.

PasswordUsers login password. Unless strong passwords are enabled, can be any number of characters needed, including 0 (blank, or no password). Password is case-sensitive, cannot have spaces, and uses letters or numerals. Editable by the user. Also see the property strongPasswords, page 1-13. Confirm PasswordSame password again, repeated. Logoff Period (mins)Specifies the time, in minutes, in which a users JDE session with the station must be inactive before the user is automatically logged off. A popup warning with a 15-second countdown appears at the end of this period (allows the user to cancel the logoff, resetting this period). Editable only by the administrator or a user designated as a Security administrator. Can be any positive integer, in minutes, up to 999999999.

Note

If set to 0, automatic logoff is disabled (the user is never logged off due to inactivity).

118

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 1

Station and Objects Station

Hot LinksThe Hot Links tab provides a method of adding Go menu options, available to the user when using the JDE (Figure 1-7). Editable by the user.
Figure 1-6 Example Hot Links tab for a user (a new hot link is shown being added).

Toolbar controls in the Hot Links tab are as follows:

Add Hot Link

Produces the New Hot Link dialog box.

Delete

Move Up

Move Down
Moves the selected hot link down in the JDE Go pull-down menu.

Deletes the Moves the selected hot link. selected hot link up in the JDE Go pull-down menu.

When adding or changing a hot link, the two fields in the Hot Link dialog are: NameHow the link appears listed on the JDE Go pull-down menu, below the Previous, Next, and Home menu options (Figure 1-7). TargetThe swid of the object to display in the JDE Workspace when this link is selected. Typically copied in Tree View, and then pasted in this field.

Figure 1-7 Example Go pull-down menu showing hot links.

Hot links appear listed in the JDEs Go menu, either user right-click access (as shown here) or from the Go menu on the JDE menu bar.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

119

Chapter 1 Station

Station and Objects

Security TabThe most critical edit tab for any user. A users 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 default administrator. 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:

AdminGives the user Read (R), or Read and Write (W) permissions for all properties of the object, including admin-level properties. In an objects 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 access for Operator-level properties.

120

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 1

Station and Objects Station

OperatorGives the user Read (R) or Read and Write (W) permissions for any operator-level properties of the object. In an objects property sheet, these are typically only properties on the Status tab. CommandGives the user access to various commands or actions, depending on selections, as follows: StdStandard 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.

AlarmAlarm acknowledgment. Gives the user alarm acknowledgment permissions for alarmable objects. EmerEmergency 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.

AdminAdministrator 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 Security
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 Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

121

Chapter 1 Station

Station and Objects

ActiveUsers

A Station objects 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 stations user name, full name, host machine name (IP address) on which the JDE is running, and the station logon time.

User Messages
In the stations 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:

Send Message
When a single user is selected (highlighted)

Broadcast Message
A user does not need to be highlighted.

Either selection produces a dialog box in which you can enter text for the message. When you type your message and click OK: Send MessageThe message appears as a pop-up at the selected users JDE. Broadcast MessageThe 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.

122

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 1

Station and Objects Station

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 objects 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). Unless the station is configured to monitor other stations (AddressBook setup), often only a single alarm existsa stationBoot Down ...Up alarm with a timestamp of when the station was last started. There are relatively few types of station alarmsall are change-of-state event types. The following types exist:

Note

Station Alarm Types

(StationAlarmEnum)
stationUp stationDown stationBoot powerLost powerLostShutdown powerRestored batteryTestFailed batteryTestPassed 0 1 2 3 4 5 6 7

For any station alarm, the enumerations description appears in the message field of the alarm record. If a JACE-NP configured for sysmon (internal environment monitoring), additional types of station alarms are possible. These alarms can apply to the JACE-NPs CPU temperature, various voltage levels, or CPU fan speed. For more information, see Monitoring JACE-NX, JACE-NP Environment Variables, page 1-27.

Note

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

123

Chapter 1 Station Limits and Guidelines

Station and Objects

Station Limits and Guidelines

Refer to

Refer to the Engineering Notes document, Niagara Capacities, for a more complete discussion about this topic. Also, please note that capacity information for the newer JACE platforms (JACE-NX, JACE-NX-UPS, JACE-403, 404, 405, others) 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).

Table 1-2

Rough limits for station resource allocations, by Niagara platform.

Niagara Platform
PC (Web Supervisor) 500MHz PIII, 256MB RAM 1GHz P4, 512MB RAM JACE-NP (earlier, 64MB) JACE-NP (current, 128MB) JACE-401 JACE-501, JACE-502 JACE-501-UI, JACE-502-UI JACE-511, JACE-511-UI, JACE-512, JACE-512-UI
1. 2. 3. 4.

Resource Count
1,000,0001 2,000,0001 400,0002 600,000
2

CPU utilization
Not applicable. Not applicable. Not applicable. 20% (or greater) CPU Idle is required by all embedded JACEs. A JACE-501 or 502 is also constrained by resource count. CPU utilization is the key constraint for any Jeode VM-based JACE (40x, 51x).

Disk/Flash Space
2GB minimum. Not applicable. Not applicable. n KB free /tffs n KB free /tffs4 n KB free /tffs n KB free /sm n KB free /tffs n KB free /sm Some free file space (n KB) is required to allow database backups. See Checking JACE-4/5 Flash Space on page 1-26.

External Links
25,000 50,000 ? ? ? ? ?

600,0003

300,000

600,0003

PC (Web Supervisor) maximum resource count limits are predicated upon (typical) DatabaseService resource loads. Tridium Systems Engineers (who provide technical support to the field) think these numbers are more realistic than ones previously published, which were: 600,000 for earlier (64MB) JACE-NP and 1,000,000 for current (128MB) JACE-NP. Chances are that various engines (control, ui) and poll threads will need to be slowed down to reach this600,000 resource count for a JACE-401 or JACE-51x. Refer to the Engineering Notes document, Niagara Capacities, for more detailed information. JACE-501 and JACE-502 models without WebUI are the most prone to flash memory limitations (database space limitations).

These limits apply to the four areas of resource boundaries, namely: RAM memoryThe 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 UtilizationThe 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.

124

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 1

Station and Objects Station Limits and Guidelines

Disk storageTypically 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 linksTypically 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 dedicated Ethernet 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 CountThe 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 CountCheck 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 Objects n line provides the stations total resource count. The Children section provides individual resource counts and percentages of total resource counts.

Checking JACE-4/5 CPU UtilizationCheck 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. Failure conditions (less than 20% IDLE) typically result in: Slow or sluggish station. Many timeout messages in Standard Output. Devices being marked up or down.

Notes

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

125

Chapter 1 Station Limits and Guidelines

Station and Objects

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 SpaceUse the Admin Tools Summary tab to check free file space on a JACE-4/5. This panel lists that total number of bytes left on 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 stations config.sns file size. For example, if config.sns is 144KB, the minimum required free space is >16KB. where 144KB - 128KB(reserve) = 16KB 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).

Notes

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 LinksUse 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).

126

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 1

Station and Objects Monitoring JACE-NX, JACE-NP Environment Variables

Monitoring JACE-NX, JACE-NP Environment Variables

A station in a JACE-NX or JACE-NP has the ability to monitor the JACEs 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 objects 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 JACEs 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 SysMonX object that you can place in the stations database. Linkable outputs provide currently monitored environment variables, including alarm indications. For up-to-date configuration details for sysmon and power monitoring, please refer to the Engineering Notes document: Niagara System and Power Monitoring. That document also contains details on the optional SysMonX and PowerMon2 objects found in the tridiumx/systemMonitor JAR file. 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 objects notification class. Also like sysmon, power monitoring is configured in the JACE-NX-UPSs drivers.properties file. In r2.3.4 and later, the systemMonitor JAR also provides a PowerMon2 object that you can place in the stations database. This object has linkable outputs that provide currently monitored UPS variables for the JACE-NX-UPS, including alarm indications.

Refer to

JACE-NX-UPS, UPS Monitoring

Niagara Properties Files

With 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 be edited 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: Host > Edit File Archiving Properties Files List of Niagara Properties Files

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

127

Chapter 1 Host > Edit File

Station and Objects

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 (PCs) directory: D:\niagara\<release>\nre\lib (or equivalent). A standard r2.3.5 file is this:
# # # # # # # # # # # # #

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. text is the name of the file. If excluded the menu item

BACnet Properties;/rel/nre/lib/bacnet.properties Status Color Properties;/rel/nre/lib/statusColors.properties Time Zones;/rel/nre/lib/timezones.txt

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.

128

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 1

Station and Objects Host > Edit File

If necessary, you can define additional properties files to allow editing or creation on a JACE. For example, you may wish to modify niagarad.properties on a host. In this case, using the syntax
[Menu Item Text;]file path

add the following line to adminfiles.txt:

Niagarad Properties;/rel/nre/lib/niagarad.properties

so that the uncommented portion of adminfiles.txt would look like this:

BACnet Properties;/rel/nre/lib/bacnet.properties Status Color Properties;/rel/nre/lib/statusColors.properties Time Zones;/rel/nre/lib/timezones.txt Niagarad Properties;/rel/nre/lib/niagarad.properties

Then, after saving adminfiles.txt, you must close and restart the JDE. Thereafter, when you select a JACE in the Admin Tool and use the Host > Edit File command, you will have access to the new properties file you added.
Figure 1-13 Host > Edit File command in Admin Tool, showing added Properties file.

Notes

The adminfiles.txt file resides only your Niagara PC (Web Supervisor, JDE engineering workstation, BACnet Supervisor, etc.), and not on a JACE. This is an important feature, especially for properties files on JACE-4/5 hosts, as previously you had to use (and enable) FTP on the JACE to put or get some of these properties files (gx.properties, bacnet.properties, etc). FTP can be a security riskand now you can disable it (system.properties file on the JACE). In general, you should not edit any properties file on a Niagara host unless you have been specifically directed.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

129

Chapter 1 Niagara Properties Files

Station and Objects

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 hosts 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. 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 files (drivers.properties, etc.)

Note

Step 1 Step 2

Open the JACE host in the Admin Tool. Using the recommended access method for that properties file (Table 1-3), open that properties file in the editor. 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). Open Notepad (or similar text editor) to start a New file. Click in the Notepad editor and press CTRL-V (to paste from clipboard). 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 3

Step 4 Step 5 Step 6

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 Supervisor Considerations

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.

130

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 1

Station and Objects Niagara Properties Files

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 files, listed alphabetically.

File Name
bacnet.properties

Access Method
Admin Tool, command Host > Edit File (default in r2.3.4 and later Admin Tool)

Description / Notes
Applies only if the Niagara host is running a station with the BACnet service. In the initial r2.3.5 release of BACnet, very few parameters are accessed through the hosts bacnet.properties file. However, as later r2.3.5 build updates become available, this may change. For more information about bacnet.properties, refer to the Niagara BACnet Integration Reference, r2.3.4 or later.

ddns.properties

Admin Tool, Network Settings tab, Edit DDNS Properties

Starting in r2.3.4, DDNS (dynamic domain name service) support was extended to include LAN/WAN support, in addition to the previous RAS (dialout with captive ISP). This configuration file holds the DDNS parameters. More information may be found in the Niagara Networking & Connectivity Guide, 2.3.x (as an updated version becomes available).

drivers.properties

Admin Tool, Installation tab, Edit drivers.properties

This is an essential file for any Niagara host. It is used to configure/specify various low-level communications drivers used by the Niagara host and the JDE. You may need to edit this 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. Refer to Engineering Notes doc, Niagara Sysmon and Power Monitoring. JACE-4/5: To configure power monitoring limits, BACnet MS/TP driver for VxWorks. Some integration drivers for JACEs may also require editing of drivers.properties (details in specific Niagara Integration documents).

Note: If your PC-based Niagara host (Web Supervisor/JDE engineering PC/BACnet Supervisor) requires edits to drivers.properties, after upgrading to a new Niagara build, you should copy and paste the old (edited) drivers.properties into the new niagara\<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 old properties files are retained.

Note: Changes to drivers.properties do not become effective for a station running on the host until the station is restarted.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

131

Chapter 1 Niagara Properties Files

Station and Objects

Table 1-3

Niagara properties files, listed alphabetically. (continued)

File Name
gx.properties

Access Method
Admin Tool, command Host > Edit File

Description / Notes
Applies if the Niagara host is running a station with the WebUiService. Currently, this file allows you to specify a small delay between serving Gx objects to a client browser, useful to avoid issues with animated .gif files. For more details, refer to gx.properties File, page 8-15. Lists the features licensed for the Niagara host, plus other information about the host. You should never edit this file. If you do, you will render your Niagara host unusable! Typically, you do not need to edit this file on any Niagara host. It is used by the web server to notify client browsers about the mapping of file extensions to MIME file types, so that client browsers can use appropriate applications. If you decide to add it to adminfiles.txt, use this entry:
Mime Properties;/rel/nre/lib/mime.properties

license.properties

Read Only! Admin Tool, Installation tab, View License

mime.properties

Admin Tool, command Host > Edit File (can add entry, see notes)

ndio.properties

Read Only!

Starting in r2.3.4, it applies only to JACE-4 hostseither models with onboard I/O or that accept I/O expansion modules. It is used by the Menu access not recommended. Found in the JACE and its ndio module to map indexes of Ndio objects correctly. rel/nre/lib folder of a JACE-4, You should never edit this file. If you do, you will render I/O on the JACE-4 or JACE-IO-XX as inoperable! with other properties files. Typically, you do not need to edit this file. Includes optional parameter to specify the TCP Admin Port for the host (default port is 3011). This is the port used for most operations from the Admin Tool.

niagarad.properties

Admin Tool, command Host > Edit File (can add entry, see notes)

adminPort=nnnn (where nnnn is TCP port number).

Another parameter is for the initial buffer-size, in charcters, of a Standard Output window (opened for a station running on that host):

bufferSize=5000
Another parameter can specify the name of the NT Administrator group, typically for non-US installations (localization). For French, e.g.:

adminGroup=administrateurs
If you decide to add this to adminfiles.txt, use this entry:
Niagarad Properties;/rel/nre/lib/niagarad.properties

nre.properties

Menu access not recommended.

Applies only to Win32 hosts, to specify which JVM is used. Automatically set upon r2.3.5 installation, where the default (and Found in the nre/lib folder of supported) setting is: vm=hotspot any r2.3.5 Win32 host. Admin Tool, Network Settings tab, Edit Port Properties Admin Tool, Network Settings tab, Edit Modem Properties Applies only to JACE-4 hosts, to specify how serial port assignments COM1 and COM2 are mapped to physical ports RS-232, RS-485, and internal modem. Refer to the Niagara Networking & Connectivity Guide, or to the Installation Instructions document for that JACE-4. Sometimes referred to as modem.properties. Applies only to JACE-4 or JACE-5 hosts. Used to both configure modems and enable the direct-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 Authentication Protocol), used to authenticate a user of dialup (PPP) connection. Previously, PAP (Password Authentication Protocol) was the only configuration option. Certain limitations apply to this feature. For more details, please refer to issue #3182 CHAP support in the r2.3.5 Release Notes document (section Core, dialup).

port.properties

ras.properties

132

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 1

Station and Objects Niagara Properties Files

Table 1-3

Niagara properties files, listed alphabetically. (continued)

File Name
station.properties

Access Method
Admin Tool, command

Description / Notes

Unlike other properties files, which configure the host, this file is Station > Edit > Properties specific to a selected station, and is stored under that station directory. Included is whether the station auto starts (after a host reboot), (station must be selected) and/or auto restarts. (Note that Auto start is configured using a checkbox dialog, with Admin Tool command Station > Configure.) If the station is configured to use an HTTP port other than the default port 80, (Station object, config property: httpPort), a line is needed that specifies 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 later Admin Tool) Starting in r2.3.4, this file allows global customizing of the status colors used by any station running on that host. Status colors are reflected in object and object output colors in the JDE, linked Gx objects in GxPages (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 other

status>/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 dark gray (bg) from the defaults black (000000) on magenta (ff00ff):

overridden.fg=ffafaf overridden.bg=404040
system.properties (continues next) Admin Tool, command Host > Edit File

(pink) (dark gray)

See the comments in the statusColors.properties file for more details. In earlier releases, this file was primarily used to enable or disable FTP and Telnet in embedded (JACE-4/5) hosts; this usage still applies. For example: ftpEnable=false telnetEnable=false In Niagara r2.3.3 (2.3), various timeout properties were added, and the file had wider host applications (all JACEs, Web Supervisor). Also, a garbage collection daemon property became available for use with a host running a station with the DatabaseService and Cloudscape. In Niagara r2.3.4, more properties were added, including several that affect publications (sending) of external links (interstation links) and control the number of processing threads to the stations web server.

Note: Starting in r2.3.4, changes to the following properties become immediately effective, without a system reboot: connectionTimeout requestTimeout readTimeout sessionTimeout gc.daemon webServer.traceLevel webServer.resolveIPAddress interstationLink.reassert interstationLink.reassert.trace interstationLink.maxSendTime.enable interstationLink.maxSendTime.lo interstationLink.maxSendTime.hi

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

133

Chapter 1 Niagara Properties Files

Station and Objects

Table 1-3

Niagara properties files, listed alphabetically. (continued)

File Name
system.properties (continued)

Access Method
Admin Tool, command Host > Edit File

Description / Notes
In Niagara r2.3.5, more properties were added, including one for disabling 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 between hosts running different Niagara releases. Log archive tracing was also added, as was a configurable steady state delay to permit a station, upon startup, to allow all objects adequate 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 related memory leak (DatabaseService with Cloudscape appdb). Be sure to disable this entry if present, otherwise, station performance may slow.
See the comments lines (#) in the r2.3.4 and later system.properties file for explanations of the various properties. Please note that additional coverage of when (and why) you would change properties in this file are planned in a future Engineering Notes document.

Note: Changes to the following properties added in r2.3.5 become immediately 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 servlet available 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/systemProperties to review currently effective system.properties values. time.properties Menu access not recommended. Reflects the currently selected Java time zone for the Niagara host, by time zone ID. The hosts time zone database is customizable, and is For r2.3.5 host only, in nre/lib stored locally in a file named timezones.txt. folder if Win32, or /sys folder if JACE-4/5 host. Admin Tool, command Host > Edit File > Time Zones (default for r2.3.5 and later Admin Tool) New in r2.3.5, not exactly a .properties file, but the hosts source time zone database, stored in its nre/lib folder as a plain text file. Useful mainly for localization scenarios. Applies to all Niagara platforms. Allows editing of individual time zones, where each line represents one time zone. Each time zone begins with a time zone ID, which is visible when selecting the hosts 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 in milliseconds, and various start/end changeover points for Daylight Savings Time (if DST is used at all). All parameters in each time zone are delimited using the pipe (|) symbol. For more details, including translated values for each available time zone in the standard r2.3.5 timezones database, please refer to the localization document Java Time Zones for Niagara r2.3.5.

timezones.txt

134

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

CHAPTER

Data Species and Links

A Niagara object is a collection of properties. Each property represents a piece of data, and is typically a name/value pair. Properties are implemented using data types, known in Niagara as data species. Properties that are inputs or outputs are linkable. This chapter explains the components of properties, including data species and attributes. Links between objects are also explained. The following main topics are provided: Data Species Property Attributes Links

Data Species
Properties are implemented with data types (species), which fall under three general classifications: Data Primitives Data Enumerations (Enums) Variable Types (Types)

Note

This section explains Niagara data species, but provides only a few examples. For a complete listing of all documented variable types and enumerations, refer to Appendix A, Object Property Quick Reference.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

21

Chapter 2 Data Species

Data Species and Links

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: booleanEither 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.

Stringan ASCII text string (no theoretical character limit).

For example, the property description (a property of most object types) uses a data species 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:

normal (0) fault (1) offnormal (2) high_limit (3) low_limit (4) unknown (64)
Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

22

Chapter 2

Data Species and Links Data Species

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 primitive data 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 and Priority 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 TypesEach is a primitive value and a status flags enumeration. Priority TypesEach 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). Status flags for a statusOutput (sOut) property are reflected by the objects statusFlags property (visible on the objects property sheet, Status tab).

Note

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

23

Chapter 2 Data Species

Data Species and Links

Status flag enumerations include: inAlarm, fault, overridden, outOfService, unackedAlarm, down. Depending on object type, these may be set in combination. The normal or ok condition is for all status flags to be cleared. If viewing objects in the JDE Workspace, any statusOutput in ok condition shows the value, in normal color. However, if status flag(s) become set, this is indicated by color change of the statusOutput and the object shape, as follows:

orangefault yellowdown redinAlarm cyan (light blue)OutOfService magentaoverridden

Note

If a fault or down condition is received at a linked statusInput (or other input using a status type data species), the object uses its configured default input value, if available. Object types such as AnalogInput, BinaryInput, Comparison, IntToFloat, Logic, Loop, Math, MultistateInput, and Totalizer, have such configuration properties.

Priority Types
Priority-variable types are used in object input and output properties named priorityArray (pIn) and prioritizedOutput (pOut), with these variable types: BooleanPriorityType FloatPriorityType IntegerPriorityType

Priority variable types each have these three components: valueThe primitive data, either boolean, float or integer. autoA boolean, true only while all control-priority slots are empty. priorityThe active control priority-level, whether received (priorityArray), or generated from the object itself (prioritizedOutput). Control priority enumerations include 16 levels, from highest (1) to lowest (16). Objects that have both priorityArray inputs and prioritizedOutputs include the commandable types, such as AnalogOutput, BinaryOutput, and MultistateOutput. Other objects have prioritizedOutputs, including the BinaryOverride, Comparison, FunctionGenerator, Logic, Loop, Math, MultistateOverride, and Schedule objects.

Note

For an explanation of how the Niagara control priority scheme operates, refer to the Priority Levels section on page 5-46. Although this explanation references the BinaryOutput (BO) object, priority levels are evaluated in the same way for the AnalogOutput and MultistateOutput objects (objects with priorityArray input).

24

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 2

Data Species and Links Property Attributes

Property Attributes
Apart from the data species a property uses, it also has a number of attributes. These attributes determine the following about the propertys usage: Read/Write accessread-only (status) or read-write. Station storage optionsPropertys 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/Internalwhether 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) Accesswhether 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 propertys attributes, as well as an explanation of Attribute Notation.

Links
Most Niagara objects have one or more properties that you can link to another object to establish data relationships. Examples include control objects, apps objects, Gx objects, and integration (shadow) objects. 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:

Note

Link Editor Link Categories Link Types Link Rules Link Data Flow Link Resources

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

25

Chapter 2 Links

Data Species and Links

Link Editor
The JDE provides a Link Editor you use to establish links between any two selected objects. The Link Editor simplifies link choices by indicating, by color, which properties of an object are available (after you select a property of the other object). As shown in Figure 2-1, selecting the first property (in this case, prioritizedOutput) of one object results in the isolation (using the color green) of the properties in the other object can be selected for a link. In this case, only one property is available for linking, namely, the priorityArray input. Properties that cannot be selected are colored red. Reasons for properties showing as unlinkable (red) include: Incompatible data species, which must match (except for Gx object links). An input property is already linked, and can accept only one source (typical).

Figure 2-1 Link Editor pre-validates links by showing only linkable properties as green.

After selecting two compatible properties, the pending link is listed on the Links side. This lists the link type and the properties to be linked.

After you select a compatible property in the second object, the link to be made appears listed in the right-side, showing the link type, object names and properties (the Service column applies only if a LonWorks shadow object is involved). You can select multiple links to be made before selecting the OK button, if needed. An OK makes the link between the selected properties and closes the Link Editor. In the property lists, the arrow icons must point in the same direction for a link. Color of the arrow icons indicates the general type of the property, either boolean, float, integer, or trigger. In the JDE, these property colors are adjustable, using the menu bar options View > Options > Property Colors.

Note

26

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 2

Data Species and Links Links

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 links:

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:
http://192.168.1.2/db/demoR2/Sim/Logic/AirHandler/coolingCoil$Links

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 as well.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

27

Chapter 2 Links

Data Species and Links

Local Link

A link between objects in the same container. When using the JDE and viewing the container in the either the Workspace or WorkspaceEditor, each link shows as a line connecting the two objects (Figure 2-3). When you mouse over the link, the status bar reports the logical type of the link, either normal, ui, or trigger.
Figure 2-3 Local links are the only kinds visible in the Workplace view.

Status bar shows the type of local link when you mouse over.

Internal Link

A link between two objects in the same station, but in different containers. When using the JDE and viewing either object in the WorkspaceEditor, the link appears at the objects input or output as a small shaded box with a letter, a to z (or if needed, aa to az) as shown in Figure 2-4. When you mouse over the link box, the status bar shows the swid of the linked object.property.
Figure 2-4 Internal links show in the WorkspaceEditor as shaded boxes with letters.

Status bar shows Internal Link and the target swid of the linked property when you mouse over.

28

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 2

Data Species and Links Links

External Link

Sometimes called an interstation link, an external link is between objects in different stations. When using the JDE and viewing either object in the WorkspaceEditor, the link appears at the objects input or output as a small box with a numeral (0 to n). The default color of the link box is white. When you mouse over the external link box, the status bar shows the link as either: externalSubscription (at an input), plus the swid of the linked object.property. externalPublication (at an output), plus the swid of the linked object.property.

Figure 2-5 External links show in the WorkspaceEditor as shaded boxes with numbers.

Status bar shows the target swid of the linked property when you mouse over.

Notes

External link processing requires AddressBook setup in both stations. Refer to the AddressBook section on page 1-15. Only receiving (externalSubscription) link configuration is persistently stored in a station database. Output (externalPublication) links are transient, and are visible only while an external station is actively subscribed. The interstationSendTime property of the Station object specifies the wait time used before pushing change-of-value updates to externally linked objects in subscribed stations. The default send time is every 5 seconds (5000 ms); the minimum send time is every 500ms. In r2.3.4 and later, other parameters affecting interstation links can be set in the hosts system.properties file. The prism servlet provides a special snapshot listing of external links in a station, useful for troubleshooting purposes. It is available from the JDE or a Web browser connection to any Niagara station, at URL: http://<host>/prism/externalLinks (also from new r2.3.5 debug servlet). No more than 50,000 external links should be made in a Web Supervisor station. This limit was empirically established based on data from actual jobs. See the Link Rules section on page 2-11 for special restrictions that apply to external links.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

29

Chapter 2 Links

Data Species and Links

Link Types
Links are further categorized logically, with the following types possible.

Normal UI Trigger Composite LonTalk Local Bindings LonTalk Network Bindings

Normal: A normal link describes most links made between objects except one including a Gx object. This includes links between other object types, typically control objects, apps objects, and integration objects. When using the JDE and looking at the Links sheet for either object, the link type shows as normal. UI: User Interfaceany link between a Gx object and another type of object. Typically, the other object is a control object, apps object, or integration object. When using the JDE and looking at the Links sheet for either object, the link type shows as ui. Trigger: A link between trigger-type properties of the two objects. Trigger links initiate actions of objects, instead of moving data (values, status, strings). When using the JDE and looking at the Links sheet for either object, the link type shows as trigger. Composite: A link to an object inside a Bundle, Composite, or GxPage container

that allows it to be exposed on the parent object. This scheme allows encapsulation of important inputs and outputs to be represented on a simplified object (the parent Bundle, Composite, or GxPage object). When using the JDE and looking at the Links sheet for the exposed child objects and the parent object, the link type shows as composite.
LonTalk Local Bindings: A link between a standard Niagara object (typically a

control or apps object) and a Lon device (shadow) object. The Lon shadow object resides under the LonTrunk container in the station database. When using the JDE and looking at the Links sheet for either object, the link type shows as localLonBind.
LonTalk Network Bindings: A link between two Lon device objects. The Lon device objects reside under the LonTrunk container in the station database. When using the JDE and looking at the Links sheet for either object, the link type shows as lonNetBind.

210

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 2

Data Species and Links Links

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. 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 > Options menu.

Note

The Background color for each link type is the main color used. The default Background color for each link type is as follows: Link Type normal link trigger link Lontalk Local Binding Lontalk Network Binding ui link composite link external link Color blue black black green gray yellow white

Link Rules
In most cases, in order for two properties to be linked, they must use the same data species. In a link, one objects 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. 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.

Note

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

211

Chapter 2 Links

Data Species and Links

The Link Editor also enforces additional link rules, which you may wish to know when attempting links.
1. 2.

You can link as many inputs to a single output as needed (one-to-many). For any input property that is already linked, no further link to it is permitted unless the property is a priorityArray type or trigger type (or certain types of Lon properties). Only then is a many-to-one link allowed. External links (between stations) have further restrictions. The following types of external links are not permitted (nor are they shown in the Link Editor): Links between prioritizedOutputs and priorityArray input properties. Links between properties using triggerType data species. Links from a GxText object to an internal property of another object (only inputs or outputs are available).

3. a. b. c.

Link Data Flow

All links are configured the same way, using the Link Editor in JDE. However, data flow in a link occurs in one of several ways, depending on linked properties. All data flow in a link occurs as one of the following: Pull data Push data Event-based (trigger) data Master/slave data

Pull data: This is the typical method of data transfer in a link. When an object

executes, it reads all of its inputs, and pulls the data into its input properties. The input (receiving side of the link) can be linked to only one object output. However, any output can be, and often is, linked to multiple inputs (one-to-many).
Push data: This occurs when linking prioritizedOutputs to priorityArray inputs.

The priority array scheme allows an input to receive a command plus a priority level from more than one source, that is, the input can be linked to multiple outputs (many-to-one). The command at the input with the highest priority wins control of the object. (Priority levels are from 1-to-16, highest-to-lowest). When you link multiple prioritizedOutputs to the priorityArray input of a controllable object (for instance, a BO, AO, or Loop), these links push values (active/inactive/auto) into their respective array slots of the input.
Event-based (trigger) data: This occurs when linking a trigger-type output and

input. A fired trigger typically initiates an action in another object. For example, each log-type object has two special trigger-type inputs (doArchiveTrigger and doClearTrigger) that perform special actions (as named). These inputs can be connected to the trigger-type outputs available in the Command, PeriodicTrigger, and/or DateTimeTrigger object, as needed. Note that trigger-type properties are similar to priority-array properties in that many-to-one links are allowed.

212

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 2

Data Species and Links Links

Master/slave data: The Calendar, Schedule, and NotificationClass objects have

masterOut and slaveIn properties for establishing special links between like-type objects. This feature allows changes in the master object to be replicated in slave objects. These properties are especially suited for linking between different stations (external links). Note that if the communications link between stations is broken, the slave object retains its current configuration and continues its operation.

Link Resources
Each link between objects consumes a small amount of RAM memory. In the JDE, a running stations usage of RAM is measured with resource count. The resource count is a numerical value that can be viewed for the entire station, or any object-level portion of it. In further sections where each object type is described, a Resource Count Range figure is provided. For example, an AnalogInput (AI) object is listed as having a:
Resource Count Range: 63 to 116

It is important to note that this range does not include link resources, only what resources are consumed by the object itself (by editing internal properties from default values). Each link to (or from) the object consumes additional RAM, incrementally adding to resource count. While values at the object-level are small (typically a resource count of 2 or 3 for each link) it is worth noting. Remembering that a link affects two objects, the following resource count values show the approximate station-level resource counts, per link.
Table 2-1 Link resource counts, station-level, per link.

normal
5

ui
5

trigger
8

composite
12

external
3

Check the resource count for a station by opening it in the JDE, selecting the station (or portion of) in the Tree View, and selecting Search > Resource Count from the menu bar (or use the ALT-R shortcut). For related topics on station resources, refer to the Station Limits and Guidelines section on page 1-24.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

213

Chapter 2 Links

Data Species and Links

214

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

CHAPTER

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

Commands
Commands 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, a BinaryOutput (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). Command access through a Gx object is validated using the Gx objects securityGroups property. Refer to Providing Command Access, page 8-6.

Note

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

31

Chapter 3 Commands

Commands and Views

Figure 3-1

Right-click Control commands are available for many Niagara objects.

Admin Commands
Administrative (Admin) commands apply to various standard Niagara objects, including the Station object, and various apps, service, control objects. For example, if a JDE user is signed on with sufficient command privileges, an AnalogLog object provides the user with right-click commands to clear (the log buffer), archive, or clear the last archive (Figure 3-2, left). If the object is linked to a Gx object in a GxPage, the same command menu may be available from a browser, by right-clicking a linked Gx object (Figure 3-1, right). Gx object securityGroup settings apply (see Providing Command Access, page 8-6.)
Figure 3-2 Right-click Admin commands are available for many Niagara objects.

Note

Typically, these commands are available only if the user has Admin-level command rights for a security group assigned to that object (or to the Gx object). Admin-level commands are available in the JDE using two methods: From the pull-down Command menu on the JDE menu bar, when the objects property sheet is displayed in the Workspace. All commands are included. From a right-click menu for the object, from its Workspace (monitor mode). Depending on the object type, not all Admin commands may be available on an objects right-click menu (for example, with the BinaryOutput object). However, commands that are right-click-accessible are also typically available through a linked Gx object, using a Web browser connection.

32

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 3

Commands and Views Commands

All Available Commands

Table 3-1 alphabetically lists all standard (and Ndio) Niagara objects that have runtime commands. Included are default commands, whether they are available as right-click commands or from the JDE only, and the users required security rights. Control commands require Std or Emer level security command rights. Admin commands typically require Admin level security command rights. Control commands for AnalogOutput, BinaryOutput, and MultistateOutput objects have editable command tags. Menu commands provided in Table 3-1 are merely defaults. Dump commands are not listed. A debug-type command, it is available for most objects (from the JDE menu bar). It has development use only.
Commands for standard (and Ndio) Niagara objects.

Notes

Table 3-1

Object Type
AdminTool AnalogInput AnalogLog

Default Menu Commands

searchAndReplace resetAckedTransitions clear archive clearLastArchive resetAckedTransitions Set Auto Emergency Set Emergency Auto

Right JDE Security Command Rights Click Only Std Alarm Emer Admin

AnalogOutput

AnalogOverride

override cancel setOverrideValue clear archive clearLastArchive ForceBackup CancelBackup resetAckedTransitions resetChangeOfStateCount resetActiveTime setChangeOfStateAlertLimit setRuntimeAlertLimit clear archive clearLastArchive

AuditLogService

BackupService BinaryInput

BinaryLog

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

33

Chapter 3 Commands

Commands and Views

Table 3-1

Commands for standard (and Ndio) Niagara objects. (continued)

Object Type
BinaryOutput

Default Menu Commands

resetAckedTransitions resetChangeOfStateCount resetActiveTime setChangeOfStateAlertLimit setRuntimeAlertLimit Active Inactive Auto EmergencyActive EmergencyInactive EmergencyAuto

Right JDE Security Command Rights Click Only Std Alarm Emer Admin

BinaryOverride

override Active override Inactive cancel (outputTriggerTextA)* (outputTriggerTextB)* (outputTriggerTextC)* (outputTriggerTextD)*

Command
*(commands do not appear unless these properties are edited)

ControlEngineService resetStatistics CpAnalogNode CpBinaryNode CpIntegerNode CpStringNode DatabaseService DateTimeTrigger ErrorLogService (commandText)* (commandText)* (commandText)* (commandText)* Open Close clear clear archive clearLastArchive clear archive clearLastArchive clearLastDailyArchive archiveAll resetAckedTransitions enableDebug disableDebug MailService MultistateInput deleteOutbox resetAckedTransitions resetChangeOfStateCount resetActiveTime setChangeOfStateAlertLimit setRuntimeAlertLimit

IntegerLog

LogService Loop

34

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 3

Commands and Views Commands

Table 3-1

Commands for standard (and Ndio) Niagara objects. (continued)

Object Type
MultistateLog

Default Menu Commands

clear archive clearLastArchive resetAckedTransitions resetChangeOfStateCount resetActiveTime setChangeOfStateAlertLimit setRuntimeAlertLimit Set Auto Emergency Set Emergency Auto

Right JDE Security Command Rights Click Only Std Alarm Emer Admin

MultistateOutput

MultistateOverride

override cancel setOverrideValue resetAckedTransitions resetAckedTransitions Set Auto Emergency Set Emergency Auto

Ndio0to10VInput Ndio0to10VOutput

NdioBinaryInput

resetAckedTransitions resetChangeOfStateCount resetActiveTime setChangeOfStateAlertLimit setRuntimeAlertLimit resetAckedTransitions resetChangeOfStateCount resetActiveTime setChangeOfStateAlertLimit setRuntimeAlertLimit Active Inactive Auto EmergencyActive EmergencyInactive EmergencyAuto

NdioBinaryOutput

NdioHighSpeed CounterInput NdioResistiveInput NdioThermistorType3 Input PeriodicTrigger Schedule ServiceContainer

resetAckedTransitions resetCounter resetAckedTransitions resetAckedTransitions reset cleanupSpecials Restart Station

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

35

Chapter 3 Views

Commands and Views

Table 3-1

Commands for standard (and Ndio) Niagara objects. (continued)

Object Type
Station

Default Menu Commands

Backup XML Backup SNS Backup Subordinates XML Backup Subordinates SNS Restart Reboot Stack Dump clear archive clearLastArchive syncToServer resetTotal resetStatistics

Right JDE Security Command Rights Click Only Std Alarm Emer Admin

StringLog

TimeSyncService Totalizer UiEngineService

General Command Notes

In general, commands are particularly important with control objects, apps objects, integration objects, the Station object, and in some instances, service objects. Commands are less important for container-type objects, and do not apply to notification objects. Gx objects have no commands. However, remember that if linked to another object (typically a control object or apps object), the Gx object effectively assumes the identity (including commands) of the linked object during runtime. Commands are explained in context for each particular object type, in sections ahead.

Views
Niagara objects have different views, which appear in the right pane of the JDE. Some views are also accessible using a Web browser connection. Object views can be generally classified into two classes: Standard Views Special Views (facets)

Note

Each object type has a default view. The default view that appears in the right pane of the JDE after you double-click the object in the Tree View.

Standard Views
When working in the JDE, every Niagara object has the following standard Go menu views:

PropertiesThe objects Property Sheet. This is the default view for many object types, including all control objects. Depending on your security rights for the object, all or only some properties may be shown and/or modifiable.
Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

36

Chapter 3

Commands and Views Views

LinksLists all links made to (and from) the selected object, as shown in Figure 2-2. Not the default view for any object type. ReportProvides 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) to a 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:
http://192.168.1.2/db/demoR2/Sim/Logic/VAVs/VAV1/Damper$Properties

Standard Container Views

For all container-type objects (except for the ServiceContainer), the following additional JDE Go views are also available: WorkspaceAlso called monitor mode, this is the runtime view showing the containers child objects, with values updating in real time. This is the default view for most container-type objects. WorkspaceEditorThe 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 objects 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) provide a LogChart view to show the objects 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 using a Web browser.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

37

Chapter 3 Views

Commands and Views

JDE-Only Special Views

Other types of objects have special views that are accessible only when using the JDE. Typically, these are system-configuration views, such as the Station objects AddressBook and UserAdmin views. Some special views are called managers. For example, the ServiceContainer object has a ServiceManager view (page 7-35) shows a tabular listing of all station services, providing central access to commands for any selected service. Manager views are also typical for integration services, such as for LonWorks and BACnet. For example, the LonWorksService object has three right-click views: LonDeviceManager LonLinkManager LonUtilityManager

Refer to the appropriate integration reference for more details on manager views.

All Available Views

Table 3-2 alphabetically lists all standard (and Ndio) Niagara objects with available views. Included is each objects default view and any special views. A minimum of Operator-level read privileges is needed to access most standard and special views.

Notes

Admin-level write privileges are needed to access: Any container objects WorkspaceEditor view. The Station objects AddressBook view. The DatabaseBrowser view for DatabaseService. A Program objects Program Editor and Program Debugger views. Admin-level write privileges are also needed to add, delete, or modify Calendar or Schedule events, using those objects special views.

Table 3-2 Available views for standard (and Ndio) Niagara objects.

Object Type
AdminTool AnalogInput AnalogLog AnalogOutput AnalogOverride ApiRecipient

Default View
Properties Properties LogChart Properties Properties Properties

Special Views
(* if JDE Only)

Standard Views
Properties Links Report Workspace Workspace Editor

LogChart LogTable

38

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 3

Commands and Views Views

Table 3-2

Available views for standard (and Ndio) Niagara objects. (continued)

Object Type
AuditLogService BackupService BinaryInput BinaryLog BinaryOutput BinaryOverride Bundle Calendar

Default View
LogTable Properties Properties LogChart Properties Properties Workspace Calendar

Special Views
(* if JDE Only) LogTable

Standard Views
Properties Links Report Workspace Workspace Editor

LogChart LogTable Calendar CalendarSummary* EntryList* DatabaseBrowser* LogTable

Command Comparison Composite Container

ControlEngineService CpAnalogNode CpBinaryNode CpIntegerNode CpStringNode

Properties Properties Workspace Workspace Properties Properties Properties Properties Properties DatabaseBrowser Properties LogTable Properties Properties Properties Properties Properties Properties Properties Properties Properties Properties Properties Properties

DatabaseService DateTimeTrigger ErrorLogService FunctionGenerator GxBarGraph GxBoolean GxDamper GxFan GxFloat GxImage GxInteger GxPage GxPipe GxSpectrum GxText

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

39

Chapter 3 Views

Commands and Views

Table 3-2

Available views for standard (and Ndio) Niagara objects. (continued)

Object Type
GxTimePlot IntegerLog IntToFloat LogService Logic Loop MailRecipient MailService Math MultistateInput MultistateLog MultistateOutput MultistateOverride Ndio0to10VInput Ndio0to10VOutput NdioBinaryInput NdioBinaryOutput NdioContainer NdioHighSpeedCounter Input NdioProcessor NdioResistiveInput NdioThermistorType3 Input NotificationClass NotificationService PeriodicTrigger PollAlways PollArchiveService PollOnDemand PrinterRecipient Program RemotePrinterRecipient

Default View
Properties LogChart Properties Properties Properties Properties Properties Properties Properties Properties LogChart Properties Properties Properties Properties Properties Properties Workspace Properties Workspace Properties Properties Properties Workspace Properties Workspace Workspace Workspace Properties Properties Properties

Special Views
(* if JDE Only)

Standard Views
Properties Links Report Workspace Workspace Editor

LogChart LogTable LogChart LogTable ProgramEditor* ProgramDebugger*

310

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 3

Commands and Views Views

Table 3-2

Available views for standard (and Ndio) Niagara objects. (continued)

Object Type
Schedule ServiceContainer Station

Default View
ScheduleEditor ServiceManager Properties

Special Views
(* if JDE Only) ScheduleEditor EventCalendar* ServiceManager* AddressBook* UserAdmin* ActiveUsers* Alarms* LogTable

Standard Views
Properties Links Report Workspace Workspace Editor

StringLog TimeSyncService Totalizer UiEngineService WebUiService

LogTable Properties Properties Properties Properties

General View Notes

Views are discussed in context for each particular object type, in sections ahead. In particular, all properties for each object (as grouped on property sheet tabs) are explained.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

311

Chapter 3 Views

Commands and Views

312

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

CHAPTER

Services
This chapter provides information on each of the standard Niagara service objects, including all those provided in the tridium JAR file of the local library. General information on services is provided first, as follows: About Services Core Services Additional Services General Notes on Services About Licensing Adding or Removing Services Common Service Object Properties

Individual service object descriptions follow, arranged alphabetically as follows:

AuditLogService BackupService1 ControlEngineService DatabaseService ErrorLogService LogService MailService NotificationService PollArchiveService2 TimeSyncService UiEngineService WebUiService

Refer to

Refer to the Vykon Alarm Service Installation and Configuration Instructions for details about the VykonAlarmService, included with a Web Supervisor.
1. Requires Niagara release 2.2 or higher. 2. The PollArchiveService is found in the tridiumx folder, under the multisite JAR file.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

41

Chapter 4 About Services

Services

About Services
Niagara services are special types of objects that publish themselves to other objects in a station. As plug-in modules, they enable a station to accomplish its application mission. There are two basic categories of Niagara service: Core Services Additional Services

Core Services
The following services be considered core, as they exist by default in any stations ServiceContainer (added automatically by the New Station wizard). This applies to any Niagara station, regardless of platform (Web Supervisor, JACE-NP, JACE-4/5).

NotificationServiceAlarm delivery to supervisor. ControlEngineServiceExecution engine for most objects (control included). UiEngineServiceExecution engine for Gx objects. LogServiceProvides log support. AuditLogServiceLogs user modifications made to the station database. ErrorLogServiceLogs configuration and software errors.

Core services are licensed by the coreRuntime entry in the license.properties file. See the About Licensing section on page 4-3 for more information.

Optional Core Services

In addition to the basic core services listed above, optional core services can also be added. These include the BackupService, MailService, and TimeSyncService. You can select them when running the New Station wizard, or add them anytime later by copying and pasting from the Local or Remote Library. The New Station wizard preselects the WebUiService by default, as well. However, be aware that for a JACE controller, this service requires a host license, and the necessary hardware configuration (models ready and licensed for the WebUiService have a UI model-number suffix, such as JACE-512-UI, JACE-401-UI, and so on).

Note

Additional Services
A Niagara station will have additional services besides just core services. These additional services vary by the host platform.

A Web Supervisor station includes the DatabaseService and WebUiService, which are individually licensed features. A Web Supervisor also typically has some number of optional core services. Starting in r2.3 (build 2.301.330b), a Web Supervisor also included the VykonAlarmService, and in r2.3.4 and later could (optionally) include Ethernet-connected Protocol Services such as BACnet or OPC.
Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

42

Chapter 4

Services General Notes on Services

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.

Protocol Services

JACE controller stations require additional services for protocol support of networked 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. 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.

Note

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). 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 its licensed features, as shown in Figure 4-1. Licensed features are separated from each other by a semicolon (;).

Caution

Note

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

43

Chapter 4 General Notes on Services

Services

Figure 4-1

Niagara services are licensed by inclusion in the features line of the hosts license.properties file.

This license.properties is for a JACE-NP, which in addition to core services (coreRuntime) and device-related services, is licensed for the WebUIService and DatabaseService (webUi, database). features=lonworks;bacnet;webUi;coreRuntime;vlon;database

All services explained in this document are licensed by the coreRuntime entry in the features line of license.properties, with the following exceptions: WebUiServiceRequires a feature line entry of: webUi DatabaseServiceRequires a feature line entry of: database PolledArchiveServiceRequires 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. 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.

Notes

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.
Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

44

Chapter 4

Services General Notes on Services

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 Properties

Service 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 properties for all service objects.

Tab Property Name

objectType

Description
Read Only: The service object type. By default, 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.

Valid Values
See description

Default
reflects object type

Notes

statusFlags Status

Read Only: Current state of the objects status flags. A normal state (no flags set) is where the status flags value is {ok}. The only status flag that can be set is:

either: {ok} (no flags) or {down} See description

{ok}

Unlike some other object types, service objects do not have alarm states.

downThe station is down or offline.

description Read-Write: Permits a user-defined text descriptor for describing the service. Any printable characters, including spaces and mixed case characters, are allowed. Read-Write: For other object types, this is the x-y coordinates (in pixels) for the objects position on the JDE Workspace. However, the position property does not apply to service objects. securityGroups Read-Write: Shows the security groups to which the object is assigned. A user must have the appropriate privileges in at least one security group to view and modify properties and issue commands. Refer to the Security Tab section on page 1-20 (Station object UserAdmin topic) for more details on how securityGroups settings apply.

position Visual

-2147483648 x

Because the parent (ServiceContainer) object has no Workspace, the position property for any service has no real application. Also refer to the About Security section on page 1-21.

Any mix of these types:

General

General HVAC Security Life Safety Group 4 Group 5 Group 6 Group 7

Niagara Release 2.3.5 Niagara Standard Programming Reference

Security

Revised: April 20, 2004

45

Chapter 4 AuditLogService

Services

AuditLogService
Quick reference for all properties: Table A-7 Inputs
doArchiveTrigger doClearTrigger

Object Shape
Outputs
(none)
recordedTrigger archivedTrigger

abbrev: (none); AuditLogService The AuditLogService keeps a record of configuration and operator changes to the station database. All changes are logged, even position changes for objects. The log for each change includes a timestamp, user name (of the changer,) swid of the source, and a description of the change action. The default view for the AuditLogService is its LogTable, which lists the most recent changes (stored in the objects buffer). As with other logs, the LogService provides archive support for the accumlated log data. This allows the stations audit logs to be periodically archived to an application (SQL) database in the supervisor station.
Parent Dependencies: ServiceContainer

Input / Output Property Reference for AuditLogService Object

(only input and output types, see Table 4-2 for all properties)

Type
input input output output

Label

Property Name
doArchiveTrigger doClearTrigger recordedTrigger archivedTrigger

Data Species
TriggerType TriggerType TriggerType TriggerType

Only one AuditLogService per station.

Resource Count Range: 38 to 1043, depending on the bufferSize (138 if default bufferSize of 100). Trigger Properties

The AuditLogService has two available trigger-type inputs: doArchiveTriggerA received pulse causes the log data currently held in the objects log buffer to be archived (sent to the LogService archive destination). doClearTriggerA received pulse causes all log data currently held in the objects log buffer to be cleared. In addition, there are 2 available trigger-type outputs, described as follows:

recordedTriggerFires upon each recorded change (log). archivedTriggerFires each time the objects log buffer is archived.

Note

Although this service object has no Workspace shape in the JDE, you can still link to its trigger properties listed above, if needed. Use the Tree View and the right-click Link From or Link To menu commands.

Commands
Users with Command, Admin privileges have the following available commands: clearClears all log data currently held in the objects log buffer. archiveArchives all log data currently held in the objects log buffer. clearLastArchiveResets 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).

46

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services AuditLogService

Properties
Table 4-2 AuditLogService properties.

Tab Property Name

objectType, statusFlags, description

Description
See Table 4-1 on page 4-5 for information on these properties common to all service objects.

Valid Values

Default

Notes
description default Logs records of user modifications.

Status

lastArchiveTimestamp Read Only: Shows a date/timestamp for when the last archive occurred. Shows null if there have been no archives or if the clearLastArchive command was given. bufferSize Read-Write: Defines the number of logged changes that can reside locally (in RAM). An allocation of resource counts (RAM) is set aside based upon the entered number. stopWhenFull Read-Write: If set to True, logging stops when the number of logged changes equals the configured bufferSize. If set to False (the default), the log buffer rotatesthis means that the oldest recorded change is overwritten as each new change continues to be recorded. Read-Write: Defines the events that cause the objects log data to be archived. Flags can be set in any combination.

valid timestamp or null 1 to 1000

null

100

False, True

False

Config

archiveSetup

selection of any or all: nearFull, daily, polled

daily

nearFullArchive occurs at 80% of the log

buffer size.

dailyArchive occurs daily, at the time

configured in the LogService.

polledApplies only if another (remote)

Niagara station is configured with the Polled Archive (multisite) service. Security Visual position Read-Write: See position, page 4-5.
-2147483648 x 0

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 4-5

General, 7 others

General

AuditLogService Notes
Each log record created by the AuditLogService has the following fields: tstampTimestamp of the recorded change, for example, 10:05:20 4-Sep-2001 EDT. userNameStation user that affected the change, for example, admin. sourceSwid of the changed object, for example, /demoR2/Services/Notification. auditActionDescription of the database change (with new value), for example, Property changed: "debug" = "true".

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

47

Chapter 4 BackupService

Services

BackupService
Quick reference for all properties: Table A-8 Inputs
(none)

Object Shape
Outputs
(none)
(none)

abbrev: (none); BackupService The BackupService1 zips up a stations entire directory into a WinZip-compatible file. It is recommended for a Web Supervisor, or any JACE-NP with the DatabaseService. It is not intended for a JACE-4/5. During a backup, station operation continues normally, and the stations connection with its application (SQL) database remains coordinated. Configuration allows for a daily zip file to be created at an assigned time. Backup zip files are placed in a
<niagaraRelease>\backups\<stationName>

Input / Output Property Reference for BackupService Object

(only input and output types, see Table 4-3 for all properties)

Type
input output

Label

Property Name

Data Species

directory. Two backups are stored: the last (backup.zip) and previous (backupOld.zip). Typically, you should copy the backup.zip file to removable media on a daily basis.
Parent Dependencies: ServiceContainer

Only one BackupService per station.

Resource Count Range: 22 to 28 Trigger Properties

None.

Commands
Users with Command, Admin privileges have the following available commands: ForceBackupPerforms an immediate zip of the entire stations folder into a file named backup.zip. The previous backup.zip file is renamed backupOld.zip. The previous backupOld.zip file is overwritten. CancelBackupUseful only if the stations DatabaseService databaseType is not Cloudscape (MSDE or MS SQL Server). Allows user breakout if a backup is taking an excessive amount of time due to ongoing archive traffic.

Properties
Table 4-3 BackupService properties.

Tab Property Name

Status objectType, statusFlags, description lastBackupTime

Description
See Table 4-1 on page 4-5 for information on these properties common to all service objects. Read Only: Shows a date/timestamp for when the last backup zip file was created. Shows null if there have been no backups.

Valid Values

Default

Notes
description default: Backup Support.

null

1. Requires Niagara release 2.2 or higher.

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

48

Chapter 4

Services BackupService

Table 4-3

BackupService properties. (continued)

Tab Property Name

backupEnabled Config

Description
Read-Write: Toggles the ability to perform a daily backup as On (True) or Off (False).

Valid Values
False, True

Default
True

Notes
If False, a manual forceBackup command still works.

scheduledBackupTime

Read-Write: Specifies the time of day, in 24-hour format, for the BackupService to create the backup.zip file for this station. Read-Write: See position, page 4-5.

00:00 to 23:59

00:00 (midnight)
-2147483648 x 0

Security Visual

position

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 4-5

General, 7 others

General

BackupService Notes
The 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 stations station directory, including the entire app (application database) folder. 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.
Figure 4-2 The backups directory is created under the Niagara <release> directory.

Note

Two backups are stored: the last (backup.zip) and previous (backupOld.zip). Typically at a job, the backup.zip file is copied to removable media on a daily basis. If a failure scenario requires a restore, the most recent backup.zip file can be unzipped back to the Niagara host.

Note: To restore, unzip the backup.zip to the root of the Niagara release directory, with the Use Folder Names option selected.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

49

Chapter 4 ControlEngineService

Services

ControlEngineService
Quick reference for all properties: Table A-19 Inputs
(none)

Object Shape
Outputs
(none)
(none)

abbrev: (none); ControlEngineService The ControlEngineService is the main service run by a Niagara station. This service executes most objects in a Niagara station, including standard control objects, apps objects, and executable container objects. Each object executed by this service has configurable execution parameters, including frequency for a continuously cycling-type execution (normal, slower, faster, or fastest). The target cycle time for each frequency group is a configuration property of the ControlEngineService. Numerous status properties provide statistics, including the stations object counts (by assigned frequency group) and associated execution times. A profileNodes feature can be used to make all executed objects locally store their minimum, maximum, and average execution times.
Parent Dependencies: ServiceContainer

Input / Output Property Reference for ControlEngineService Object

(only input and output types, see Table 4-4 for all properties)

Type
input output

Label

Property Name

Data Species

Only one ControlEngineService per station.

Resource Count Range: 60 to 70 Trigger Properties

None.

Commands
Users with Command, Std privileges have the following available command:

resetStatisticsClears (zeroes) accumulated statistics for each of the four execution frequency groups, 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
Table 4-4 ControlEngineService properties.

Tab Property Name

objectType, statusFlags, description startTime

Description
See Table 4-1 on page 4-5 for information on these properties common to all service objects. Read Only: Shows the time of the last station startup. Status statistics accumulate from this point (until a resetStatistics is given).

Valid Values

Default

Notes
description default: Execution engine for control objects.

Status

format is: hh:mm dd-mo-yyyy TimeZone

410

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services ControlEngineService

Table 4-4

ControlEngineService properties. (continued)

Tab Property Name

totalObjectCount

Description
Read Only: The total number of objects executed by the ControlEngineService. This equals the sum of all objects grouped by execution frequency (fastest, normal, etc.).

Valid Values

Default

Notes
Equals the total number of objects in the station, minus Gx objects and simple container types. minutely types include all Calendar and Schedule objects.

fastestObjectCount, fasterObjectCount, normalObjectCount, slowerObjectCount, onTriggerObjectCount, minutelyObjectCount fastestCycles, fasterCycles, normalCycles, slowerCycles, minutelyCycles totalOverruns

Read Only: Shows the number of objects in each execution frequency group, including the continuous-types (fastest, faster, normal, slower) and others (onTrigger, minutely).

(each) integer, 0 to

Read Only: The accumulated number of execution cycles for each frequency group listed. The minutelyCycles value equals the number of minutes of operation that the statistics are based upon. Read Only: The total number of overruns counted, across all four of the continuous-type frequency groups. Equal to the sum of the next four overrun properties (fastest, faster, normal, slower).

(each) integer, 1 to

Statistics globally update every 10 seconds.

integer, 0 to

Status, cont.

fastestOverruns, fasterOverruns, normalOverruns, slowerOverruns

Read Only: The overruns counted for each individual execution frequency group. An overrun is counted when the actual cycle time for a group exceeds its target execution time, as defined by executionFrequencies property settings (on the Config tab).

integer, 0 to

fastestAverageExecute Read Only: For each repeating-type execution group, shows the average Time, fasterAverageExecute execution time (in milliseconds) for one complete object cycle. Time, normalAverageExecute Time, slowerAverageExecute Time, minutelyAverageExecute Time lateStarts Read Only: The number of object execution cycles that started later than anticipated, (after the next cycle should have begun). LateStarts occur as a result of other asynchronous events that require processor time. Examples are performing a database backup, or the periodic garbage collection performed by the JVM.

floating point value

If profileNodes is enabled (for a short period only), each object accumulates its individual average execution time. The sum of these times, per frequency group, equals the values in these properties.

integer, 0 to

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

411

Chapter 4 ControlEngineService

Services

Table 4-4

ControlEngineService properties. (continued)

Tab Property Name

executionFrequencies

Description
Read-Write: Target execution cycle times for each 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

Valid Values
100ms to 999 seconds (See Rules) 100ms steps up to 2 seconds, thereafter 1 second steps False, True

Default
See descrip.

Notes
Cycle times set too short are reflected by numerous overruns. For any group, if the number of overruns stays lock step with the number of cycles, the cycle time is set much too short. Do not leave at True for extended periods (uses station resources).

Config

profileNodes

Read-Write: If True, causes all objects executed by the ControlEngineService to locally maintain their own execution statistics in properties minExecuteTime, maxExecuteTime, and avgExecuteTime (found on the Engineering tab of each objects property sheet). Read-Write: If True, causes a period (dot) written to Standard Output after each completion of the object execution cycle. Read-Write: See position, page 4-5.

False

displayDots

False, True

False

Security Visual

position

-2147483648 x 0

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 4-5

General, 7 others

General

ControlEngineService Notes
The ControlEngineService executes all executable objects in the station except for Gx objects (executed by the UIEngineService). Within the Java virtual machine execution 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. 2. 3.

Read inputs1Values are pulled from outputs linked to inputs. CalculationThe objects algorithm, using its configuration properties. Write outputs1Values are updated at outputs.

All three phases occur within the objects execution time.

1. For shadow (integration) objects, outputs are written directly from the Poll service running for each particular integration.
Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

412

Chapter 4

Services ControlEngineService

Note

The third phase (write outputs) is skipped whenever the difference between the objects calculated value and its last written value is less than the objects 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 objects 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.

Scheduling Execution

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:

freqFrequency. Most types of objects provide the following selections: never slower normal (the default) faster fastest minutely on_trigger For more information, see Execution Frequency. orderThe 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 Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

413

Chapter 4 ControlEngineService

Services

In addition, many objects can be configured to execute only upon receiving a trigger pulse, using the common input executeTrigger. In this case, both of these conditions must be met: The objects executeTrigger input must be linked. The objects executionParameters, freq property must be set to on_trigger.

Note

Frequency selections are exclusive. You cannot, for example, configure an object to execute both continuously (for example, normal) and also on trigger.

Tip

Often, overall execution efficiency can be improved by assigning objects that are not critical to the slower category, for example, objects with values that are monitored for display purposes only. This allows more processor time for normal objects, plus more time for various integration (polling) services. Also, if a station includes many Gx objects, you can also improve overall station efficiency by assigning the UiEngineServices cycleTime to a higher value (than the default 500ms). A value of 2000 (or higher) is typically acceptable.

Execution Order
For continuously-executing objects, and within each frequency group, are three distinct divisions of order: inputThese objects are executed first. By default, most are input type objects, for example, AI, BI, and MSI. processorThese objects are executed next. Most are software type objects, such as Math, Loop, Logic, log types, and Program objects, to name a few. By default, most object types are in this category. outputThese objects are executed last. By default, most are output type objects, for example, AO, BO, and MSO.

Typically, default execution order settings are recommended for most objects. This allows the most efficient control response for the execution of control logic.

414

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services DatabaseService

DatabaseService
Quick reference for all properties: Table A-24 Inputs
(none)

Object Shape
Outputs
(none)
(none)

abbrev: (none); DatabaseService The DatabaseService provides an RDBMS (relational database management system) for archiving log object data, plus events such as alarms and alerts. Referred to as an application database (or appdb) it is separate from the stations 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 index to 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 objects default view. This provides access to summary, data, and SQL query commands from within the JDE.
Parent Dependencies: ServiceContainer

Input / Output Property Reference for DatabaseService Object

(only input and output types, see Table 4-5 for all properties)

Type
input output

Label

Property Name

Data Species

Note: Starting with Niagara 2.301.321.v1, additional (and optional) support for Microsoft MSDE or MS SQL databases was introduced, as an alternative to the standard Cloudscape SQL database. Configuration properties relating to these options are not explained here, but are covered in another document, MSDE or SQL Server 2000 Database Installation and Configuration Instructions.

Only one DatabaseService per station.

Resource Count Range: 55 to 63 Trigger Properties

None.

Commands
If a Cloudscape appdb, users with Command, Admin privileges have the following available commands (these commands do not apply if MSDE or MS SQL appdb):

OpenOpens 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. CloseCloses the connection from the station to the application database. 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

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

415

Chapter 4 DatabaseService

Services

Properties
Table 4-5 DatabaseService properties.

Tab Property Name

objectType, statusFlags, description isConnected Status databaseProductName

Description
See Table 4-1 on page 4-5 for information on these properties common to all service objects. Read Only: Shows whether a connection exists between the station and database. Read Only: Product name and vendor.

Valid Values

Default Notes
description default: Relational database management.

False, True DBMS: <type> (valid version number) (valid name)

True Valid value 3.5.11 (example) see Descrip. 3.5 (example) appdb

databaseProductVersion Read Only: Database product version. driverName Read Only: Name for the embedded database driver, such as Cloudscape Embedded JDBC Driver. Read Only: Database driver version. Read Only: String used within URLs for browser access to the application database. For example: http:/<host>/<urlPrefix>/index.html databaseType Read-Write: Specifies the SQL database type for the appdb, with following choices:

driverVersion urlPrefix

(valid version number) appdb

(see descrip).

Cloudscape

Config

Cloudscape MSDE MS_SQL_Server Oracle (currently not supported)

Cloudscape is the standard SQL database type. MSDE or MS_SQL_Server are specially licensed options.

General

Note: If Cloudscape, see Memory Usage Notes, page 4-26.

orderByTimestamp Descending Read-Write: Specifies how data records in an archive are ordered in table views, either: False, True True

Most recent data first (at top of table),

orderByTimestampDescending=True

Oldest data first (at top of table)

orderByTimestampDescending=False Visual position Read-Write: See position, page 4-5.
-214748364 8 x 0

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 4-5.

General, 7 others

General

Note: In r2.3.4 and later, any browser user running a query (Using the SQL Query Form, page 4-21) must have Admin Write privileges to issue any SQL command besides Select. Previously, any station user could issue any SQL command.

Any JDE user requires Admin Write privileges to access the DatabaseBrowser view. Command, Admin privileges are required to issue commands Open and Close.

Security

416

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services DatabaseService

Table 4-5

DatabaseService properties. (continued)

Tab Property Name

jdbcDriverClassName Cloudscape jdbcConnectionUrl Config

Description
Read-Write: Name for ODBC database driver (COM.cloudscape.core.JDBCDriver). Read-Write: ODBC database used, with format <jdbc>:<odbc>:<databasename>. Default is:
jdbc:cloudscape:app;create=true;upgrade=true

Valid Values
see Descrip. see Descrip.

Default Notes
see Descrip. see Descrip. Do not change default jdbc property settings.

databaseUser databasePassword msJdbcDriverClass Name msJdbcConnectionUrl MS SQL Server

Read-Write: Not implemented. Read-Write: Not implemented. Read-Write: MS SQL database driver name
com.microsoft.jdbc.sqlserver.SQLServerDriver

see Notes see Notes

see Descrip. see Descrip.

For configuration details for this appdb option, please refer to the document: MSDE or SQL Server 2000 Database Installation and Configuration Instructions.

Read-Write: Connection url to MSDE or MS SQL database. Default value is:

jdbc:microsoft:sqlserver://localhost:1433;Select Method=cursor

Config

msDatabaseUser msDatabasePassword msCreateNewDatabase msDatabaseData Filename msDatabaseLog Filename

Read-Write: Typically default sa. Read-Write: Password for databaseUser. Read-Write: See Notes. Read-Write: See Notes. Read-Write: See Notes. Read-Write: Name for Oracle database driver (oracle.jdbc.driver.OracleDriver). Read-Write: Connection URL to Oracle database. Default value is:
<jdbc>:oracle:thin:@<localhost>1521:ORCL

see Notes see Notes False, True see Notes see Notes see Notes see Notes

sa True see Descrip. see Descrip. tridium niagara

Oracle (future usage)

orJdbcDriverClassName Config orJdbcConnectionUrl

Oracle appdb configuration not supported in initial Niagara 2.3.5 Release.

orDatabaseUser orDatabasePassword

Read-Write: See Notes. Read-Write: See Notes.

DatabaseService Notes
The following main topics are covered in this notes section:

DatabaseBrowser Database Tables Archive Data Format Accessing Archives SQL Queries DatabaseBrowser vs. Web Browser Summary Information and Useful URLs Memory Usage Notes

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

417

Chapter 4 DatabaseService

Services

DatabaseBrowser The default view for the DatabaseService in the JDE is the DatabaseBrowser, which
provides a two-sided window into the application database (Figure 4-3).
Figure 4-3 DatabaseBrowser is the default view for the DatabaseService.
Left side lists the tables in the database, available for selection. Right side provides three tabs for the selected database table.

Double-click to open the DatabaseBrowser.

Database Tables

In a relational database, data resides in multiple tables. In the Niagara appdb, most tables correspond one-to-one with individual log objects (that have archived). Database schemas (and therefore table names) differ between Cloudscape and MSDE/MS SQL appdbs. All examples shown here (and in later sections) are Cloudscape-specific. However, all of the operations and sample queries also apply to an MSDE or MS SQL appdb, providing you use the appropriate table names. By default, tables (archives) are listed alphabetically from top-to-bottom, and are named using the format: <SCHEMA>.<TABLE> where all characters appear capitalized. Most tables are schema type ARCHIVE, using the format: ARCHIVE.<STATION>_<LOG_OBJECT_SWID> where an underscore (_) replaces the slash (/) used in normal swid syntax. For example: ARCHIVE.DEMOR2_SIM_LOGICSCREENS_AIRHANDLER_AH1CLG For the log object ah1Clg in station demoR2, at swid: /demoR2/Sim/LogicScreens/AirHandler/ah1Clg

Note

Notes

If an object name includes an underscore, it appears as two underscores inside the table name. For example: ARCHIVE.MY__STATION_LOGS_VAV__LOGS_ROOM__101 for swid: /My_Station/Logs/VAV_Logs/Room_101 In addition to ARCHIVE, other schema types are ALERT, EVENT, and APP.

418

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services DatabaseService

Archive Data Format

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. Starting in r2.3.4, the default order for archive records are most recent data first. If needed, 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 Falsethis duplicates the previous sort method used in older Niagara releases. For archives of log types AnalogLog, BinaryLog, IntegerLog, and MultistateLog, there are three fields (columns) total: TSTAMP(Timestamp), formatted HH:MM:SS DD-MMM-YYYY TMZ using 24-hour time. For example, 17:00:03 10-Sep-2001 EDT. VALUEWithout engineering units (if analog/integer), or state descriptor if binary/multistate (only true or false if binary, integer value if multistate). For example: 71.3457 (analog), false (binary), 2 (integer or multistate).

Note

STATUS1The statusFlags value for the source object. Typically, this is {ok}, meaning normal. However, other values are possible, either singly or in combination. For example, {inAlarm} or {inAlarm, unackedAlarm}.

Standard Archives
Table 4-6 shows standard archives that are not associated with a particular data log object. Typically, these are listed in any station running the DatabaseService.
Table 4-6 Standard archives, in addition to archived log objects.

Format as listed (SCHEMA.TABLE)

ALERT.ALERTHISTORY ALERT.UNACKEDALERTS ARCHIVE.<STATION>_AUDITLOGSERVICE ARCHIVE.<STATION>_ERRORLOGSERVICE EVENT.EVENTHISTORY EVENT.UNACKEDALARMS

Description
Alert History Unacknowledged Alerts Station audit log Station error log Alarm History Unacknowledged Alarms

Data Sourced From

NotificationService (must be set to archive) AuditLogService (must be set to archive) ErrorLogService (must be set to archive) NotificationService (must be set to archive)

Notes

The four tables sourced from the NotificationService (alerts and alarms) can hold records from multiple remote stationsproviding that each stations NotificationService is configured to archive_remote (and to the Supervisor station entered in its addressBook). Normal user access to data in the tables ALERT.UNACKEDALERTS and EVENT.UNACKEDALARMS is through the JDEs Alarm Console, Vykon Alarm Service client, or using the URL http://<station>/alarm with a browser connection.

1. Archives for StringLog objects have only the TSTAMP and VALUE fields.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

419

Chapter 4 DatabaseService

Services

Accessing Archives

Archived data can be viewed (a table at a time), using either the DatabaseBrowser view in the JDE, or from a Web browser connection to the station. To select an archive in the DatabaseBrowser view in the JDE, merely click it. To see the archived data, click the Data tab on the right side. To select an archive from a Web browser, open the index to the available archives using either URL: http://<stationName or IP address>/appdb/index (lists all schema-type tables, including ARCHIVE, ALERT, and EVENT)

or http://<stationName or IP address>/archive/index (shows only ARCHIVE (log) tables). for example, http://192.168.1.195/appdb/index Click on any table to see the archived data. Due the size (width) constraints encountered in the DatabaseBrowser, using the browser method typically provides better viewing of archives. This is particularly true for certain logs, such as the audit and error logs, that contain extended values in fields such as AUDITACTION or STACKTRACE. If an archive contains more records, only the first 25001 will be shown. A message (in red) appears in the DatabaseBrowser or browser window saying: WARNING: More records available, only displaying first 2500 records. You can view more records in a browser only by appending this string at the end of the URL: &limit=n (where n is some number larger than 2500) and then refreshing the browser.

Notes

SQL Queries

The application database supports standard SQL queries, using either the DatabaseBrowser (JDE) or a Web browser connection. Query results are identical whether run from the DatabaseBrowser or a Web browser. The following subsections apply to SQL queries. Running a Query Using the SQL Query Form Query Output Types Example SQL Queries

Running a Query
SQL queries can be run from a Web browser by typing in a specific URL directly, using the following basic syntax:
http://<hostIP>/appdb/query?sql=<query>&content-type=<mimeType>

1. Niagara r2.2 and later limit is 2500 records. In previous releases, the limit is 1000 records.
Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

420

Chapter 4

Services DatabaseService

Where standard MIME types are text/plain, text/comma-separated-values, text/tab-separated-values, text/xml, and text/html. If content-type is not specified, the default is text/html. Additional parameters can be appended to this basic URL query, using the syntax:
&limit=<size>&after=<yyyy-mm-dd>T<hh:mm:ss>&before=<yyyy-mm-dd>T<hh:mm:ss>

where limit specifies the maximum number of records returned. If not specified, the maximum limit is 2500 records. For example, the following URL retrieves the first 20 archived records in the audit log of station demoR2, and displays them in XML format:
http://192.168.1.100/appdb/query?sql=select%20*%20from%20ARCHIVE.DEM OR2_SERVICES_AUDITLOG&content-type=text/xml&limit=20

Note

Spaces are not permitted in URLs. Instead, the characters %20 (without quotes) must be used in a URL wherever a space would otherwise be used in a query.

Using the SQL Query Form

Using an SQL query form is much easier than typing in a URLhowever, knowing the SQL syntax needed is still the challenge. See Table 4-7 for some example queries. SQL commands and syntax are beyond the scope of this document. See the SQL Tutorial in the online Niagara Help system for a good introduction. JDE Access Browser Access

Note

JDE AccessFrom the JDEs DatabaseBrowser, use the following procedure:

Procedure 4-1 Running an SQL query from the DatabaseBrowser

Step 1

Click the Query tab on the right side. The currently selected table (if any) makes no difference with a query.

Note 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' Click Execute. Query results appear in the window.

Step 3

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

421

Chapter 4 DatabaseService

Services

Browser AccessFrom 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/queryForm for example, http://192.168.1.195/appdb/queryForm 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' Select the MIME type output (see Query Output Types). Click Execute. Query results appear in the same browser window. When using a browser connection, you can save query results by using the browsers 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.

Step 2

Step 3 Step 4

Note

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/htmlData is pre-formatted within an HTML table, using standard HTML tags. Included are column headers for each record field. text/plainData is formatted in plain text, one record per row, with each field separated by a comma (,). Header (field name) information is not included. text/xmlData 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-valuesData 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-valuesData 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-dataxData 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).

422

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services DatabaseService

Notes

There is no output difference between text/comma-separated-values and text/plain selections. When using the DatabaseBrowser and the Save Results command, the following file extensions (by default) are assigned to the different MIME types:

text/html .html text/plain .cvs text/xml .xml text/tab-separated-values .tvs text/comma-separated-values .cvs application/x-tridium/datax .dx You can save comma- and tab-separated output selections and import them into spreadsheet programs that accept delimited data, and manipulate as needed.

Example SQL Queries

Table 4-7 shows some example SQL queries, referencing the demoR2 station. Note that queries are in lowercaseonly strings in quotes ( ') are case sensitive. Typically, queries similar to these (after being successfully run) have the URLs saved to a file. Then, the URL text can be used in URL link references in whatever HTML navigation is provided to the system owner.
Table 4-7 SQL query examples with descriptions.

Query Entry Example

select * from archive.demoR2_services_auditlog where source not like 'Position' select username,tstamp,auditaction from archive.demoR2_services_auditlog where username=admin' select * from archive.demoR2_services_auditlog where tstamp>'2001-09-12 00:00:00' select * from archive.demoR2_sim_logicscreens_energymgmt_oaolog where value='true' select * from archive.demoR2_sim_logicscreens_energymgmt_schlog where ((extract(month from tstamp))=(extract(month from current_date)-1) and (extract(day from tstamp))>=(extract(day from current_date)) or (extract(month from tstamp))=(extract(month from current_date)) and (extract(day from tstamp))<=(extract(day from current_date))) and (extract(year from tstamp))=(extract(year from current_date))

What It Does
Lists all fields (*) for all audit log records, except those related to repositioning objects. Lists only the fields specified (in that particular order), for all audit log records for user admin.

Command, Selections, Operators

command select selection source condition not like command select selection username operator =

Lists all fields (*) for all audit log records command select that have timestamps after midnight, selection tstamp September 12, 2001. operator > Lists all fields (*) for records of the command select BinaryLog object OAOLog created by a selection value transition to On (true). operator = An advanced level query using a command select combination of functions and operators selection tstamp (thanks to author Gerard Huff). operators =, AND, OR Lists all fields (*) for all records in the Also uses functions: selected archive (in this case, extract BinaryLog object SCHLog) for a rolling months worth of data. Note: This query works for all months except for In other words, lists all archived records from todays date in last month retrieving December data in January. until todays date.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

423

Chapter 4 DatabaseService

Services

Table 4-7

SQL query examples with descriptions. (continued)

Query Entry Example

delete from archive.demoR2_services_auditlog where tstamp<'2001-01-01 00:00:00'

What It Does
Deletes all audit log records with timestamps for years prior to 2001.

Command, Selections, Operators

command delete selection tstamp operator <

Note: Be careful when using the delete command. There is no undo.

delete from alert.unackedalerts where tstamp>'1980-01-01 00:00:00' Deletes all unacknowledged alerts (currently pending acknowledgment). command delete selection tstamp operator >

Note: This would be used only to free up the alarm console before job turnover. However, it does not write an acknowledgment timestamp to alerts collected in the alert history.
drop table archive.demoR2_sim_logicscreens_energymgmt_oaolog Deletes the entire table (archive) for the named table, in this case, for the AnalogLog object OAOLog. command drop table selection (none) operator (none)

Note: Be careful when using the drop table command. There is no undo.

Timesaver

To avoid typing a table name in a query, open a browser connection to the database index (http://<host>/appdb/index) and copy the table name to the clipboard. Do this by dragging backwards (right-to-left) over the tables 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.

DatabaseBrowser For the most part, everything in the application database that can be accessed using vs. Web Browser 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 JDEs 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 http://<station>/appdb/index.

424

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services DatabaseService

Figure 4-4

Example of using filters to list only audit logs for the various stations.

The schemaFilter and tableFilter fields can be used to limit which tables appear listed.

Summary Information: The Summary tab in the DatabaseBrowser provides SQL table structure information for any selected table. Included are the following four categories for each of the different fields (columns) in a table:

nameThe columns name (header), for example, TSTAMP or VALUE. Often used in an SQL select... where name statement (case is insensitive). typeNameThe SQL data type for the field, for example such as INT (integer), VARCHAR (character string), or TIMESTAMP. sizeData field size, as an integer. Boolean data (true or false) has a size of 1. isNullable(YES or NO) Specifies whether data in the field can be null, that is, the column can be empty. Typically, this is YES.

Summary information may be useful when someone with extensive SQL knowledge is examining the application database.

Summary Information and Useful URLs

The DatabaseService provides an embedded RDBMS plus browser-accessible mechanisms for accessing archived data. The following URLs provide universal browser access to the services application database:

http://<host>/appdb/index

Index listing all tables in the application database; each is a hyperlink to data.
http://<host>/archive/index

Index listing only archive (log) tables in the application database; each is a hyperlink to data.

http://<host>/appdb/queryForm

HTML form for entering an SQL query, with selectable output options. The URL for any customized query can be saved and incorporated in an HTML link for an end user, if desired. Be aware that any browser connection requires entry of a valid user name for the station, however, no specific security rights are required.

Note

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

425

Chapter 4 DatabaseService

Services

The station requires an open connection with the application database to support normal operation, which includes support for Niagara alarming and archiving of log data. By default, this connection is opened when the station starts, and remains open (unless manually closed by a user with Command, Admin rights). Archived data is stored in tables, where the vast majority of tables correspond one-to-one to log objects that are configured to archive. Such a table does not exist in the database until the log object has actually archived. In addition to log (object) archives, standard archives associated with the NotificationService, AuditLogService, and ErrorLogService typically exist.

Memory Usage Notes

For some Web Supervisors using the default Cloudscape appdb, (databaseType is Cloudscape), data archiving has been noted to markedly increase memory usage of the host PC. In a few cases, the Web Supervisors performance became sluggishthis was found be related to garbage collection issues. Starting in r2.3.5, these issues were resolved as a result of the JVM change to Sun Hotspot (vs. the previous Microsoft VM). A Web Supervisor running r2.3.5 or later should not experience this problem. If a Web Supervisor is running an earlier (pre-r2.3.5) Niagara release, for example r2.3.4 or r2.3.3, it is recommended that you uncomment (remove leading #) from this line in the hosts system.properties file:
gc.daemon=600000

This forces a periodic garbage collection by the JVM every 600,000 ms (10 minutes). If running r2.3.5 or later, you should disable the garbage collection entry described above in the Web Supervisors nre\lib\system.properties file, to prevent needless periodic garbage collection. To do this, add a comment (#) in front of this line, such as:
#gc.daemon=600000

Caution

For additional information about this and other Niagara properties files, refer to List of Niagara Properties Files, page 1-31.

426

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services ErrorLogService

ErrorLogService
Quick reference for all properties: Table A-26 Inputs
doArchiveTrigger doClearTrigger

Object Shape
Outputs
(none)
recordedTrigger archivedTrigger

abbrev: (none); ErrorLogService The ErrorLogService keeps a record of software errors which are caused by invalid configurations and software bugs. Different priority levels are logged, ranging from MESSAGE (informational) to WARNING and ERROR (high). Each log record includes a timestamp, source (swid), message, and stackTrace pointer (if a warning or error). The default view for the ErrorLogService is its LogTable, which lists the most recent errors (stored in the objects buffer). As with other logs, the LogService provides archive support. This allows the stations error logs to be periodically archived to an application (SQL) database, meaning the supervisor station running the DatabaseService.
Parent Dependencies: ServiceContainer

Input / Output Property Reference for AuditLogService Object

(only input and output types, see Table 4-8 for all properties)

Type
input input output output

Label

Property Name
doArchiveTrigger doClearTrigger recordedTrigger archivedTrigger

Data Species
TriggerType TriggerType TriggerType TriggerType

Only one ErrorLogService per station.

Resource Count Range: 38 to 1043, depending on the bufferSize (54 if default bufferSize of 25). Trigger Properties

The ErrorLogService has two available trigger-type inputs: doArchiveTriggerA received pulse causes the log data currently held in the objects log buffer to be archived (sent to the LogService archive destination). doClearTriggerA received pulse causes all log data currently held in the objects log buffer to be cleared. In addition, there are 2 available trigger-type outputs, described as follows:

recordedTriggerFires upon each recorded error message (log). archivedTriggerFires each time the objects log buffer is archived.

Note

Although this service object has no Workspace shape in the JDE, you can still link to its trigger properties listed above, if needed. Use the Tree View and the right-click Link From or Link To menu commands.

Commands
Users with Command, Admin privileges have the following available commands: clearClears all log data currently held in the objects log buffer. archiveArchives all log data currently held in the objects log buffer. clearLastArchiveResets 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).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

427

Chapter 4 ErrorLogService

Services

Properties
Table 4-8 ErrorLogService properties.

Tab Property Name

objectType, statusFlags, description Status

Description
See Table 4-1 on page 4-5 for information on these properties common to all service objects.

Valid Values

Default

Notes
description default Logs configuration and software errors.

lastArchiveTimestamp Read Only: Shows a date/timestamp for when the last archive occurred. Shows null if there have been no archives or if the clearLastArchive command was given. bufferSize Read-Write: Defines the number of logged changes that can reside locally (in RAM). An allocation of resource counts (RAM) is set aside based upon the entered number. stopWhenFull Read-Write: If set to True, logging stops when the number of logged changes equals the configured bufferSize. If set to False (the default), the log buffer rotatesthis means that the oldest recorded change is overwritten as each new change continues to be recorded. Read-Write: Defines the events that cause the objects log data to be archived. Flags can be set in any combination.

valid timestamp or null 1 to 1000

null

25

False, True

False

Config

archiveSetup

selection of any or all: nearFull, daily, polled

daily

nearFullArchive occurs at 80% of the log

buffer size. dailyArchive occurs daily, at the time configured in the LogService. polledApplies only if another (remote) Niagara station is configured with the Polled Archive (multisite) service. Security Visual position Read-Write: See position, page 4-5.

-2147483648 x 0

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 4-5

General, 7 others

General

ErrorLogService Notes
Each log record created by the ErrorLogService has the following fields: tstampTimestamp of the recorded error or event, for example, 10:05:20 4-Sep-2001 EDT. severityCan 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.

428

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services ErrorLogService

sourceSwid of the object involved in the error or event (most typically a service object). For example: /demoR2/Services/MailService. messageDescription of the error or event, for example, Cannot send mail, Cannot send packet, or Station started successfully. (HTTP port=80). stackTracePopulated 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:

javax.mail.SendFailedException: No recipient addresses at javax/mail/Transport.send0 (Transport.java:96) at javax/mail/Transport.send (Transport.java:71) at tridium/services/MailService.sendImpl (MailService.java:230) at tridium/services/MailService

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

429

Chapter 4 LogService

Services

LogService
Quick reference for all properties: Table A-42 Inputs
doArchiveAllTrigger doClearLastDailyArchiveTrigger

Object Shape
Outputs
(none)
(none)

abbrev: (none); LogService The LogService provides archive management for station logs (all log objects, the audit log and error log). The log archive destination is configurable as remote or local, depending on the location of the application database (station with the DatabaseService). A configurable archive time allows for a daily periodic archive (for all logs so configured). The service also has an archive_disabled mode, in which case log data is not archived. In addition to archive management, the LogService also provides Web browser access to the log data of any log in the station. The URL for a tabular index to all station logs is http://<host>/log/index. Output for a selected log is text-based, and available in several formats including plain, HTML, XML, tab-separated, and comma-separated.
Parent Dependencies: ServiceContainer

Input / Output Property Reference for LogService Object

(only input and output types, see Table 4-9 for all properties)

Type
input input

Label

Property Name

Data Species

doArchiveAllTrigger TriggerType doClearLastDailyArchiveTrigger TriggerType

Only one LogService per station.

Resource Count Range: 33 to 47 Trigger Properties

The LogService has two available trigger-type inputs: doArchiveAllTriggerA received pulse is equivalent to the archiveAll command, described below. doClearLastDailyArchiveTriggerA received pulse is equivalent to the clearLastDailyArchive command, described below.

Note

You can link to trigger properties listed above, if needed. Use the Tree View and the right-click Link From or Link To menu commands.

Commands
Users with Command, Admin privileges have the following available commands: archiveAllCauses the log data currently held in every log object to be immediately archived (sent to the LogService archive destination). Note this applies even to logs that are not configured to archive (daily and/or near full)! clearLastDailyArchiveResets the config property lastDailyArchive from a valid timestamp value to a null value. In a subsequent daily archive, each log object archives all log records accumulated since its lastArchiveTime.

430

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services LogService

Properties
Table 4-9 LogService properties.

Tab Property Name

objectType, statusFlags, description logUrlPrefix Status

Description
SeeTable 4-1 on page 4-5 for information on these properties common to all service objects. Read Only: String used within URLs for browser access to log buffered data. For example: http:/<host>/log/index Read Only: String used within URLs for browser access to archived log data. For example: http:/<host>/archive/index Read-Write: Determines whether logs are archived, and if so, where.

Valid Values

Default

Notes
description default Provides log support.

log

log

archiveUrlPrefix

archive

archive

Applies only if the station has the DatabaseService. If archive_disabled, the LogService does not archive, nor is polled archiving (from a polling station with the PollArchiveService) performed.

archiveMode

A Web Supervisor station should always be

set to archive_local. JACE controllers are typically set to archive_remote (unless a JACE-NP with the DatabaseService). archiveAddress Read-Write: Specifies the station with the DatabaseService where logs are archived. Uses the stations AddressBook setup. The property has two parts:

archive_disabled archive_local archive_remote

archive_ disabled

Note: Change requires a station restart.

Supervisor, none

Config

Supervisor checkboxCheck if archiving

remotely to a station already defined as the Supervisor in the AddressBook. station drop-down listLists stations available when archiving remotely. These stations are defined as peers or subordinates in the AddressBook. A none selection is also included. archiveTime Read-Write: Specifies the archive time for all logs configured to archive daily. Uses a 24-hour format (Hr:Min) from 00:00 (midnight) to 23:59 (11:59 PM). lastDailyArchive minRetryTime Read Only: Shows a date/timestamp for the last daily archive. Read-Write: Specifies the minimum time, in minutes, for the retry window following a failed archive. A retry is made within this window. Read-Write: Specifies the maximum time, in minutes, for the retry window following a failed archive. A retry is made within this window. 00:00 to 23:59 valid timestamp or null (none) 1 to n 02:00

null 5 (minutes) 15 (minutes) Archives may fail due to connection problems to the archive host. The retry window scheme prevents server floods upon a reconnection.

maxRetryTime

1 to n

Security Visual

position

Read-Write: See position, page 4-5.

-2147483648 x 0

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 4-5

General, 7 others

General

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

431

Chapter 4 LogService

Services

LogService Notes
Notes on the LogService include the following four topics: About the LogService Log Servlet Troubleshooting Archive Activity Additional r2.3.5 Archive Debug Features

About the LogService

The LogService coordinates the archiving of buffered log data in the station to the archive destination, whether local (station is running the DatabaseService) or remote (as in a typical JACE controller). The LogService uses a push mechanism that automatically opens a connection with the application database and populates (or creates and populates) the necessary archive tables with log data. This process occurs at these times: Daily (at the configured archiveTime), for all log objects set to archive daily. On an individual near full basis (80% of the configured bufferSize), for any log object set to archive nearFull. Upon a manual archive command given to any log object. Upon receipt of a trigger pulse at the archiveTrigger input of any log object. Upon receipt of a trigger pulse at the doArchiveAllTrigger input of the LogService object (causes an archive of all log objects set to archive). If the archiveMode is set to archive_disabled, no log data is archived, but the LogService still provides HTTP access to buffered log data.

Log Servlet

The log servlet provides HTTP access to data currently residing in the buffers of the stations log objects. An index to all log objects in the station is provided by the URL:
http://<host>/log/index

Logs are listed by description property (if entered) or object name (if not). The HTML index provides links to view each logs data in the following formats:

text/htmlData is pre-formatted within an HTML table, using standard HTML tags. Included are column headers for each record field. text/plainData is formatted in plain text, one record per row, with each field separated by a comma (,). Header (field name) information is not included. text/xmlData 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-valuesData 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-valuesData 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.)

432

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services LogService

application/x-tridium-dataxData is encapsulated in a binary file for use in another application. This output selection is directed to a saved file only (not viewable in a Web browser window).

Troubleshooting Archive Activity

The log servlet also provides HTTP access to the status of the log archive activity for a station, using the URL:
http://<host>/log/status

This provides a snapshot list of statistics for the LogServices archive activity, plus links to the Incoming Archives and Outgoing Archives pages (described ahead). Statistics can be useful when troubleshooting log archive activity, and are as follows:

archiveModeof the LogService. (archive_remote or archive_local). currentTimetimestamp for the statistics (refresh browser to update all). lastSuccessTimetimestamp for when the last successful archive transaction occurred. Shows null if archive active activity has not occurred since the last station restart. successCountnumber of successful archive transactions since station startup. lastFailureTimetimestamp of the last failed archive attempt. Typically, this is when the archive host (destination) became unreachable. Shows null if no failed archives since station startup. lastFailureReasonreason for the last failed archive. Typically, it is a network connection problem. Alternately, the archive station may have been stopped, or its DatabaseService closed. nextAttemptTimetimestamp for when a retry will occur for backlogged archives. nextAttempPeriodnumber of seconds after failed archive attempt before a retry attempt is made. This number was randomly derived within a window defined by the LogServices configured minRetryTime and maxRetryTime properties. (Does not change on refresh). backlogCountnumber of logs currently awaiting a retry to archive.

Incoming Archives: The incomingArchives link at the bottom of the log/status page applies if a Web Supervisor station, or JACE-NX/NP with DatabaseService. It lists stations that have archived to this station, along with a timestamp of last archive contact. Stations are hyperlinks to incomingArchives?station=<sta> screens.

Clicking on a station returns a list of archives for the selected station (as they exist in the SQL database of the archive host). Each displays the archives swid, and shows timestamps for the last archive contact and the last archive timestamp.
Outgoing Archives: The outgoingArchives link at the bottom of the log/status

page is useful for any station that is archiving logs (either locally or remotely). This page lists any backlogged logs for archiving, showing a total number in the Archive Backlog [n] at the top of the table. These are logs awaiting to be sent to the stations archive destination.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

433

Chapter 4 LogService

Services

Each log is named by swid, with a timestamp for the last archive and a Percent Unarchived number. Typically, these values range from 80% (the nearFull archive trigger point) and 100%, where 100% indicates possibility of lost (unarchived) data. Lesser percentages may also appear. The swid to each log is a hyperlink to the properties table for that log object.

Additional r2.3.5 Archive Debug Features

Starting in r2.3.5, any running station provides a central debug servlet, using URL:
http://<host>/debug

From this main debug page are several General links for use from a browser connection, including a Log Status link described in the previous section Troubleshooting Archive Activity. In addition, the debug servlet provides a stdout (Standard Output) link that provides a snapshot of that stations Standard Outputsomething previously that required an Admin Tool connection to a Niagara host. In r2.3.5, you can also send archive trace messages to the stations Standard Output by setting a property in that hosts system.properties file, namely:
archive.trace=true

Trace messages from archiving appear similar to:

Archive> Archive> Archive> Archive> archive /J403_428/test/AlmTest/CountLog_2 success! archive /J403_428/test/AlmTest/CountLog_3 success!

By default, trace archiving is disabled. In other words, if the archive.trace property is not present in system.properties, it is evaluated the same as if:
archive.trace=false

Like most entries in system.properties, any change to this particular property becomes immediately effective.

434

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services MailService

MailService
Quick reference for all properties: Table A-46 Inputs
(none)

Object Shape
Outputs
(none)
(none)

abbrev: (none); MailService The MailService provides the ability to send e-mail notifications of Niagara alarms and alerts. The stations NotificationService must be configured with MailRecipient objects to utilize this service. The MailService is typically run on a Web Supervisor station, but can also run on any JACE controller station. The MailService operates as a send-only mail client using the SMTP protocol and port 251. Configuration properties specify the SMTP server to be used, and the appropriate from address. If required, username and password properties are available to provide the necessary authentication to the SMTP server (see Authentication Notes, page 4-37). In a scenario where e-mails cannot be sent (SMTP server becomes unavailable, for example), they are stored locally in a mail outbox (outbox.mbx file). On a configurable basis, the MailService periodically attempts to resend pending e-mails in the outbox.
Resource Count Range: 29 to 50 Trigger Properties

Input / Output Property Reference for MailService Object

(only input and output types, see Table 4-10 for all properties)

Type
input output

Label

Property Name

Data Species

None.

Commands
Users with Command, Admin privileges have the following available commands:

deleteOutboxDeletes all pending (previously failed) e-mail notifications awaiting to be resent.

Properties
Table 4-10 MailService properties.

Tab Property Name

objectType, statusFlags, description enabled Status

Description
See Table 4-1 on page 4-5 for information on these properties common to all service objects. Read-Write: Must be True for operation of the MailService. If set to False, the MailService does not route alarms/alerts.

Valid Values

Default

Notes
description default: Service to store and send email.

1. Starting in r2.301.429.v1 and later, you can specify another non-default port for the SMTP server.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Config

False, True

False

Revised: April 20, 2004

435

Chapter 4 MailService

Services

Table 4-10

MailService properties. (continued)

Tab Property Name

smtpHost

Description
Read-Write: Specifies the SMTP host to use to send e-mail notifications.

Valid Values

Default
-

Notes
The SMTP host is read upon station startup. If station is running in a JACE-NX, review/adjust its security policy as needed if changing default port or using DNS.

valid hostname of SMTP server Starting in r2.301.429.v1 and later, you can also (and optionally) specify a TCP port different than 25 (default): TCP port if not 25 <hostname>:<port> ourMailSrv:40 for example:

Note:A station restart is required after entering (changing) the SMTP host name.
fromAddress Read-Write: Specifies the from address used in sent e-mail notifications. An e-mail account on the SMTP server is typically required using this same address. Often, an e-mail account using the stations name is created and used. outboxRetryTime Read-Write: Specifies the wait time, in minutes, that must occur before an unsuccessful e-mail notification is resent. Read-Write: Username associated with the e-mail account used on the SMTP server. May be left blank unless the SMTP server requires authentication on a send operation, in which case username must be entered. password Read-Write: Password for the user named by the username property. May be left blank unless the SMTP server requires authentication on a send operation, in which case the password must be the correct one used for the named user. Engineering debug Read-Write: When set to True, provides detailed information in the stations Standard Output relating to the connection to (and communication messages with) the designated SMTP server. Read-Write: See position, page 4-5. False, True False See descrip. See descrip. 5 (minutes) valid e-mail address nobody@no where.com

Config, cont.

username

An entry in the Niagara hosts system.properties file is also required. See Authentication Notes, page 4-37

Security Visual

position

-2147483648 x 0

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 4-5

General, 7 others

General

MailService Notes
The 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

436

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services MailService

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.mbx The 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 notificationsany 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. (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 correctly modified, and the station is restarted. If you do not want them sent, issue the deleteOutbox command to the MailService before restarting the station. If the target SMTP mail server is configured to require authentication for send requests, you must configure the services config properties username and password with the appropriate entries. Contact the mail servers system administrator for this information. In addition, the Niagara hosts system.properties file must have the following line present:
mail.smtp.auth=true

Note

Authentication Notes

For information on accessing Niagara properties files, refer to Host > Edit File, page 1-28.

Localization Notes

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 hosts 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 Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

437

Chapter 4 NotificationService

Services

NotificationService
Quick reference for all properties: Table A-62 Inputs
(none)

Object Shape
Outputs
(none)
(none)

abbrev: (none); NotificationService The NotificationService provides alarm and event routing, processing of alarm acknowledgments, and management of alarm archiving. It is a required service in any Niagara station. NotificationService properties define the alarm archive destination (typically, the Web Supervisor) and the archive mode (local, remote, disabled, local no SQL). A debug mode is available for troubleshooting. The NotificationService object is unique among service objects because it is a container object. Child (notification) objects define the stations notification scheme, and include the following types:

Input / Output Property Reference for NotificationService

(only input and output types, see Table 4-11 for all properties)

Type
input output

Label

Property Name

Data Species

NotificationClass ApiRecipient MailRecipient PrinterRecipient RemotePrinterRecipient SnmpRecipient

Parent Dependencies: ServiceContainer

Only one NotificationService per station.

Resource Count Range: 51 to 61, plus the sum of all resource counts of child objects. Trigger Properties

None.

Commands
None.

Properties
Table 4-11 NotificationService properties.

Tab Property Name

objectType, statusFlags, description Status

Description
See Table 4-1 on page 4-5 for information on these properties common to all service objects.

Valid Values

Default

Notes
description default: Alarm delivery to supervisor.

438

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services NotificationService

Table 4-11

NotificationService properties. (continued)

Tab Property Name

Description

Valid Values
See descrip.

Default
Supervisor, none

Notes

alarmArchiveAddress Read-Write: Specifies the station with the DatabaseService (and alarm console) where alarms and alerts are archived. Uses the stations AddressBook setup. The property has two parts:

Supervisor checkboxCheck if archiving

remotely to a station already defined as the Supervisor in the AddressBook. station drop-down listLists stations available when archiving remotely. These stations are defined as peers or subordinates in the AddressBook. A none selection is also included. archiveMode Read-Write: Specifies how notification and associated archiving occurs. The default disable selection prevents notification from occuring. The archive_local selection is valid only if the station is running the DatabaseService (typically, this is the Web Supervisor). Security Visual Engineering debug Read-Write: When set to True, provides detailed information in the stations Standard Output relating to routing and acknowledgment of alarms and events. Read-Write: See position, page 4-5. archive_disable archive_local archive_remote archive_local_no _SQL archive_dis A station in a typical able JACE controller requires the archive_remote selection. The local_no_SQL is for a standalone JACE-4/5 only. False

Config

False, True

position

-2147483648 x 0

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 4-5

General, 7 others

General

NotificationService Notes
By 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. 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.

Note

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

439

Chapter 4 PollArchiveService

Services

PollArchiveService
Quick reference for all properties: Table A-65 Inputs
pollGroup0Trigger pollGroup1Trigger pollGroup2Trigger pollGroup3Trigger pollGroup4Trigger pollGroup5Trigger pollGroup6Trigger pollGroup7Trigger

Object Shape
Outputs
(none)
(none)

abbrev: (none); PollArchiveService The PollArchiveService is an optional, individually licensed service that can be used on a station running the DatabaseService. It is needed by a Master Web Supervisor. This service is in the tridiumx/multisite JAR. This service pulls log data from target stations, where each station is assigned to a particular poll archive group. This differs from the standard push of log data that occurs through each stations LogService. Log data is acquired from remote log objects that have an archiveSetup that includes polled, or, if the target station is running the DatabaseService, (e.g. Web Supervisor) directly from that stations SQL appdb. Reasons for using the PollArchiveService include the following scenarios: Firewalls prevent the normal LogService push data approach. A tiered approach of archiving is needed, with one or more Web Supervisors and/or JACE-NP stations with the DatabaseService.

Input / Output Property Reference for PollArchiveService Object

(only input and output types, see Table 4-12 for all properties)

Type
input input input input input input input input

Label

Property Name
pollGroup0Trigger pollGroup1Trigger pollGroup2Trigger pollGroup3Trigger pollGroup4Trigger pollGroup5Trigger pollGroup6Trigger pollGroup7Trigger

Data Species
TriggerType TriggerType TriggerType TriggerType TriggerType TriggerType TriggerType TriggerType

For any poll archive group, log data is archived based upon any occurrence of: A configurable, repeating timer (every 1 to n hours). A trigger pulse received at the services pollGroupN input. A manual pollGroupN command.

Parent Dependencies: ServiceContainer

Only one PollArchiveService per station.

Resource Count Range: 33 to 47 Trigger Properties

The PollArchiveService has 8 available trigger-type inputs:

pollGroup0Trigger through pollGroup7TriggerA received pulse causes the associated poll archive group to be polled for archive data. (You assign a station to a poll archive group in the AddressBook of the polling station.) This input can be linked to a Command, Schedule, DateTimeTrigger or other object.

440

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services PollArchiveService

Note

Although this service object has no Workspace shape in the JDE, you can still link to its trigger properties listed above, if needed. Use the Tree View and the right-click Link From or Link To menu commands.

Commands
Users with Command, Admin privileges have the following available commands: pollGroupn (07)Immediately requests a poll for archive data from poll archive group n. Any commanded poll request is considered high priority. If poll archiving is currently not in progress, polling immediately begins for that poll archive group. If a poll archive is in currently in progress, the request is added to the high priority queue. If no other high priority requests are queued, polling begins for that poll archive group next (after the current poll archive completes). clearLowPriorityQueueRemoves all group archive requests from low priority queue (frequency-initiated group archives). clearHighPriorityQueueRemoves all group archive requests from high priority queue (command-initiated group archives).

Properties
Table 4-12 PollArchiveService properties.

Tab Property Name

objectType, statusFlags, description Status lowPriorityQueue Size highPriorityQueue Size group0 enabled, frequency through group7 enabled, frequency lowPriorityQueue Capacity highPriorityQueue Capacity Visual position

Description
See Table 4-1 on page 4-5 for information on these properties common to all service objects.

Valid Values

Default

Notes
description default Service to support multi-site log collection.

Read Only: Number of queued group archives initiated by regular frequency. Read Only: Number of queued group archives initiated by pollGroupn commands. Read-Write: (Separately configurable for each poll archive group.) Specifies whether that poll archive group is enabled for poll archiving, and if so, what regular, repeating frequency of archive should occur (in hourly increments).

0 to n 0 to n False, True 0 to n hours (integer)

0 0 False, 0

Typically, each is 0 or a low number. See Priority Queues, page 4-43.

Config

If False, poll archiving does not occur. If True but frequency is 0, poll archiving
occurs only upon a pollGroupTrigger pulse or a pollGroup command. Read-Write: Specifies group archive queue maximum size, for low priority (frequency initiated) group archives. Read-Write: Specifies group archive queue maximum size, for high priority (command initiated) group archives. Read-Write: See position, page 4-5. 10 to 60 50 Values much over defaults (50) should not be necessary. See Priority Queues, page 4-43.

10 to 60

50

10 x 10

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

441

Chapter 4 PollArchiveService

Services

Table 4-12

PollArchiveService properties. (continued)

Tab Property Name

Engineering debug

Description
Read-Write: When set to True, provides detailed information in the stations Standard Output relating to poll archive messages.

Valid Values
False, True

Default
False

Notes
Leave debug disabled except while troubleshooting the PollArchiveService.

Security

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 4-5

General, 7 others

General

PollArchiveService Notes
The PollArchiveService is required in the Master Web Supervisor station only, not in any polled (target) station (Figure 4-5). Special configuration for each target station is not needed, apart from its LogService being set to either archive_remote (typical) or archive_local (if Web Supervisor or JACE-NP, NX with DatabaseService).
Figure 4-5 Polled archive (Master Web Supervisor) configuration.
Pushed Archiving (LogService)

The PollArchiveService uses a pull approach. The Master Web Supervisor has the PollArchiveService, and is the poller. All the JACE controllers and/or Web Supervisors shown are entered in the Master Web Supervisors addressBook, and are assigned to a particular poll archive group (each may be assigned to the same group or a unique group, as needed). Web Supervisors or JACE-NPs or NXs with the DatabaseService each have their own SQL application database (appdb). When these stations are polled, new data from its log archives is pulled to the Master Web Supervisor. See the following subsections:

Polled Archiving (PollArchiveService)

Poller
Master Web Supervisor
PollArchiveService

Poll list generated from in-memory object database of logs with polled flag set.

JACE-4/5
Archive Remote

archiveAddress is undefined All logs set to polled

appdb SQL database

Poll list generated from tables of archived logs in Application Database (appdb) archiveAddress Web Supervisor or is local JACE-NP, NX w/ appdb

Archive Local

No logs set to polled

appdb SQL database

Normal archive of logs set to archive nearFull and/or daily

JACE-4/5
Poll list generated from in-memory object database of logs with polled flag set.

archiveAddress is JACE-NP polled

Configuration Operation

Archive Remote Some logs set to

archiveAddress is

JACE-NP, NX Web Supervisor or

Archive Remote other JACE-NP, NX
Some logs set to polled

442

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services PollArchiveService

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 stations 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 their archiveSetup. 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 groupsnote that in some cases, the poll archive for a single group may take up to an hour to complete. Low priority queueFor all regularly scheduled poll group archives, meaning each initiated at intervals defined for that groupns frequency, in hours. High priority queueFor 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 groupns frequency setting higher (longer interval).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

443

Chapter 4 TimeSyncService

Services

TimeSyncService
Quick reference for all properties: Table A-74 Inputs
(none)

Object Shape
Outputs
(none)
(none)

abbrev: (none); TimeSyncService The TimeSyncService provides both client and server support for time synchronization. As a client, the service can poll up to three designated Time Protocol servers, using the standard Internet Time Protocol (RFC 868). Polling occurs at a configurable frequency. The stations time is adjusted (synchronized) based upon a configurable error tolerance. As a server, the station operates as a Time Server, also using the standard Internet Time Protocol (RFC 868).

Input / Output Property Reference for TimeSyncService Object

(only input and output types, see Table 4-13 for all properties)

Type
input output

Label

Property Name

Data Species

Client and server operation can occur simultaneously, if desired. Because the Internet Time Protocol is widely implemented, client synchronization can occur in a number of ways. For example, to another Niagara station (typically, the Web Supervisor) or (for a Web Supervisor) to selected public atomic clock Time Servers.
Resource Count Range: 41 to 63 Trigger Properties

None.

Commands
Users with Command, Admin privileges have the following available commands:

syncToServerClient operation immediately obtains the current time from the specified timeProtocolServers, and adjusts the stations time if necessary.

Properties
Table 4-13 TimeSyncService properties.

Tab Property Name

objectType, statusFlags, description Status serverReport1, serverReport2, serverReport3

Description
See Table 4-1 on page 4-5 for information on these properties common to all service objects. Read Only: Each shows the results of the last (client) synchronization attempt with the associated timeProtocolServer. Format is: <result>:<yyyy-mm-dd>T<hr:min:sec:>.tripT Examples: Success:2001-09-07T06:34:28.02-4 No response:2001-09-07T06:34:28

Valid Values

Default

Notes
description default: Time synchronization.

See descrip.

unconfigured If a host cannot be found the value shows an error string, for example: Error:java.net.UnkownHostException: <hostname>.

444

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services TimeSyncService

Table 4-13

TimeSyncService properties. (continued)

Tab Property Name

serverEnabled

Description
Read-Write: Must be True for server operation. If False, client (time protocol) requests to the station are not answered. Read-Write: Specifies the application port used by the server operation. Read-Write: Must be True for client operation. If False, polling of time servers stops, station time is not adjusted, and status properties serverReportn show Disabled. Read-Write: Specifies, in minutes, the frequency of the polling of the named timeProtocolServers. Read-Write: Specifies, in seconds, the maximum time difference among multiple servers before their times are averaged, (else an ERROR, then avg. discarded), and then the minimum time difference required between this filtered average and stations time before stations time is resynchronized. Read-Write: Each property specifies a Time Server to use for synchronization (as client).

Valid Values
False, True

Default
True

Notes

serverPort clientEnabled

valid port number False, True

37 True

Port 37 is the well known Time port.

clientPollFrequency

1 to n

15

clientResetTolerance Config

1 to n

30

With mulitple time servers, a filtered average value is evaluated against the stations time. This filter is new starting in r2.3.4.

timeProtocolServer1, timeProtocolServer2, timeProtocolServer3

(each) Supervisor (if configured) or IP address or valid fully qualified hostname

If the stations AddressBook is configured naming another station as the Supervisor, Note: If not using the the Supervisor checkbox is a valid option. Supervisor choice, When entering server names, IP addresses you should specify are typically better than qualified hostnames. all three (different) For example, 132.163.4.101 instead of valid time servers to time-a.timefreq.bldrdoc.gov (NIST, Boulder, best enable filtering. Colorado). debug Engineering Read-Write: When set to True, provides detailed information in the stations Standard Output relating to the connection to (and communication messages with) the designated Time Protocol server(s). Includes roundtrip and oneway times, server and station times, and delta time (in ms). position Read-Write: See position, page 4-5.

If the Supervisor checkbox reads not configured, it is not a valid selection.

False, True

False

Leave debug disabled except while troubleshooting the TimeSyncService.

Security Visual

-2147483648 x 0

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 4-5

General, 7 others

General

TimeSyncService Notes
The 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:
http://www.boulder.nist.gov/timefreq/service/time-servers.html

Other public ITS servers are available on a world-wide basis.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

445

Chapter 4 UiEngineService

Services

UiEngineService
Quick reference for all properties: Table A-76 Inputs
(none)

Object Shape
Outputs
(none)
(none)

abbrev: (none); UiEngineService The UiEngineService executes all user interface objects (Gx objects) in the station. It is 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

Input / Output Property Reference for UiEngineService Object

(only input and output types, see Table 4-14 for all properties)

Type
input output

Label

Property Name

Data Species

Only one UiEngineService per station.

Resource Count Range: 40 to 47 Trigger Properties

None.

Commands
Users with Command, Std privileges have the following available command:

resetStatisticsClears (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
Table 4-14 UiEngineService properties.

Tab Property Name

objectType, statusFlags, description averageExecuteTime

Description
See Table 4-1 on page 4-5 for information on these properties common to all service objects. Read Only: Shows the average execution time, in milliseconds, for a complete cycle (totalExecuteTime/executionCycles). Read Only: Shows the total execution time, in milliseconds, since the last station startup. Read Only: The accumulated number of execution cycles since last station startup. Read Only: The total number of overruns counted. An overrun occurs when the actual cycle time exceeds its target time, as defined by the cycleTime property (on Config tab). Read Only: The total number of objects executed by the UiEngineService. This includes all Gx objects in the station (not just those in GxPage containers).

Valid Values

Default

Notes
description default: Execution engine for user interface objects.

float value (ms) integer (ms) integer integer

totalExecuteTime Status executionCycles overruns

objectCount

446

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services UiEngineService

Table 4-14

UiEngineService properties. (continued)

Tab Property Name

startTime Status, cont.

Description
Read Only: Shows the time of the last station startup. Status statistics accumulate from this point (until a resetStatistics is given).

Valid Values

Default

Notes
format is: hh:mm dd-mo-yyyy

averageInterCycleDelay Read Only: Shows the average delay time, in milliseconds, between cycle starts. lateStarts Read Only: The number of object execution cycles that started later than anticipated, (after the next cycle should have begun). Read-Write: Target execution time, in milliseconds, for a complete execution cycle (for all Gx objects in the station). integer value, in milliseconds (typically, not less than the default 500) False, True False 500 Commonly adjusted up (i.e. 2000) without adverse effect, to improve overall station efficiency.

cycleTime

Config

displayDots

Read-Write: If True, causes a tilde (~) written to Standard Output after each completion of an execution cycle. Read-Write: See position, page 4-5.

Security Visual

position

-2147483648 x 0

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 4-5

General, 7 others

General

UiEngineService Notes
The UiEngineService executes only Gx objectsall other executable objects in the station are executed by the ControlEngineService.

Object Execution When a Gx object is executed by the UiEngineService, usually there are three phases
of processing:
1. 2. 3.

Read inputsValues are pulled from outputs linked to inputs. CalculationThe objects algorithm, using its configuration properties. Write shape (behavior)The Gx object updates in appearance.

All three phases occur within the objects execution time. A Gx objects appearance is usually determined by its object type and the settings of its configuration properties.

Scheduling Execution

The Ui engine thread of the station periodically walks a list of objects and executes them in a sequential fashion.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

447

Chapter 4 WebUiService

Services

WebUiService
Quick reference for all properties: Table A-78 Inputs
(none)

Object Shape
Outputs
(none)
(none)

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:

Input / Output Property Reference for WebUiService Object

(only input and output types, see Table 4-15 for all properties)

Type
input output

Label

Property Name

Data Species

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
Table 4-15 WebUiService properties.

Tab Property Name

objectType, statusFlags, description defaultTemplateUrl Status

Description
See Table 4-1 on page 4-5 for information on these properties common to all service objects. Read-Write: References a swid file path to one of the 4 global HTML templates. This default template is used as the backup template. It frames a WebUi applet in case one of the other 3 global template properties (GxPage, Calendar, Schedule) is blank, and a local template is not specified. Default (new station) value: /tridium/services/defaultTemplate.html

Valid Values

Default

Notes
description default: Web browser interface support.

A valid swid referencing an HTML file that contains the appropriate server tags.

Config

See descrip. The default (new station) value points to an HTML file contained in the tridium JAR file.

448

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 4

Services WebUiService

Table 4-15

WebUiService properties. (continued)

Tab Property Name

gxPageTemplateUrl

Description
Read-Write: References a URL filepath to an HTML template used to globally display GxPages (graphics). It is used whenever a local override template (property available for each GxPage) is not referenced. Default (new station) value: (noneblank)

Valid Values
A valid swid referencing an HTML file with the appropriate server tags.

Default

Notes

See descrip. If left blank, the defaultTemplateUrl named HTML file is used instead.

calendarTemplateUrl

Read-Write: References a URL filepath to an HTML template used to globally display Calendar editor views. It is used whenever a local override template (property available for each Calendar object) is not referenced. Default (new station) value: (noneblank)

A valid swid referencing an HTML file with the appropriate server tags.

See descrip. If left blank, the defaultTemplateUrl named HTML file is used instead.

scheduleTemplateUrl

Read-Write: References a URL filepath to an HTML template used to globally display Schedule editor views. It is used whenever a local override template (a property for each Schedule object) is not referenced. Default (new station) value: (noneblank)

A valid swid referencing an HTML file with the appropriate server tags.

See descrip. If left blank, the defaultTemplateUrl named HTML file is used instead.

Security Visual

position

Read-Write: See position, page 4-5.

-2147483648 x 0

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 4-5

General, 7 others

General

WebUiService Notes
The WebUiService includes the following servlets:

GxBrowser access to Niagara graphics (GxPages). ChartBrowser 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. TextSupports 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.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

449

Chapter 4 WebUiService

Services

450

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

CHAPTER

Control Objects
This chapter describes each of the standard Niagara control objects, that is, those provided in the control folder of the tridium JAR file. General information on control objects is provided first, as follows: About Control Objects BACnet Heritage Selecting Control Objects Common Control Object Things Trigger Properties Debug Command About Units Common Control Object Properties Event-Type Objects Status Properties Alarm Setup Properties

Individual control object descriptions follow, arranged alphabetically as follows:

AnalogInput AnalogOutput AnalogOverride BinaryInput BinaryOutput BinaryOverride Command Comparison CpAnalogNode CpBinaryNode CpIntegerNode CpStringNode

DateTimeTrigger FunctionGenerator IntToFloat Logic Loop Math MultistateInput MultistateOutput MultistateOverride PeriodicTrigger Totalizer

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

51

Chapter 5 About Control Objects

Control Objects

About Control Objects

Control objects provide a common platform for integrating control logic. Whether a value or state occurs in a LonWorks device, a BACnet device, or another proprietary/legacy device, it can be linked into control algorithms developed using standard control objects. Some JACE models (JACE-4) have onboard I/O points for direct connection of sensors, meters, etc., and controlled loads. Special types of control objects provide the interface to this I/O. Refer to Chapter 10, Ndio Objects, for more details. Control objects are executed in the station by the control engine (managed by the ControlEngineService), as are all Apps objectsnotably the Calendar, log-types, Schedule, and Program objects. Most Niagara stations are engineered to use some control and apps objects, in addition to other child-only (primitive) objects. These other types of primitive objects include:
Shadow objects: These objects provide remote access to data in a foreign system,

Note

that is, non-Tridium devices. Depending on the integration, a primitive shadow object can exist at the device level or a lower, data-point level. Shadow objects are executed by both the stations integration-specific service, for example, LonWorksService, and by the stations ControlEngineService.
Gx objects: The building blocks to create a graphical user interface to the station,

accessible using the JDE or a standard Web browser. These objects are executed by the UIEngineService, and are also processed by the WebUIService. It is possible (but not likely), for a Niagara station to be engineered using only shadow objects and perhaps Gx objects, if only simple monitoring of values is needed. However, control objects are typically required to provide things such as: Alarming and event notification. Proper value formatting (such as selected decimal display). Commandable control (including a command prioritization scheme). Inter-device control routines.

In addition, the various apps objects are typically used to provide global scheduling control, data logging, and specialized routines typically needed when engineering a building automation system.

52

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects About Control Objects

BACnet Heritage
In general, Niagara control 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 several standard objects directly as BACnet objects, namely:

AnalogInput (AI) objects AnalogOutput (AO) objects BinaryInput (BI) objects BinaryOutput (BO) objects MultistateInput (MSI) objects1 MultistateOutput (MSO) objects1 All NDIO objects (see Chapter 10, Ndio Objects) Plus, these apps objects:

Calendar objects

Schedule objects Also, special BACnet log objects (found in bacnet JAR) similar to types AnalogLog, BinaryLog, IntegerLog, MultistateLog, and StringLog. When exposed to BACnet, they appear as a Trend_Log object. Niagara objects that represent analog data have assignable engineering units (for display purposes) based on BACnet engineering units. See About Units, page 5-6. In a BACnet integration, the BACnet service makes the Niagara station a BACnet server to provide client access to these objects (to other networked BACnet devices). At the same time, the BACnet service allows the station client access to standard BACnet objects in remote BACnet devices, by using BACnet shadow objects. For detailed information on Niagara and BACnet, refer to the Niagara BACnet Integration Reference document. Niagara control objects and their properties use BACnet terminology, which may not be immediately clear if you arent already familiar with BACnet. The following list cross-references more common terms to their BACnet equivalents. Common Use Term

Refer to

BACnet Terms

BACnet / Niagara Equivalent

Alarm On, Off / Running, Stopped Runtime Logically Disconnected Tri-state, 3-speed, 4-speed, etc.

Event, to-offnormal event Active, Inactive ElapsedActiveTime Overridden Multistate

1. Some state restrictions apply. See the MultistateInput and MultistateOutput sections.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

53

Chapter 5 About Control Objects

Control Objects

Selecting Control Objects

Until you become familiar with the different Niagara control objects, it may not be immediately clear which types provide common functions. The table below crosses some standard control routines to the appropriate object type. Control Routine Needed
3-speed, 4-speed, monitoring, alarm 3-speed, 4-speed, etc., control Adder (analog), up to 4-input Averager (analog), up to 4-input Analog monitoring, alarm Analog value simulator AND logic gate, 2-input Binary (2-state) monitoring, alarm Binary (2-state) control (Browser user) command access to another

Niagara Control Object Used MultistateInput (MSI) MultistateOutput (MSO) Math (function: summation) Math (function: average) AnalogInput (AI) FunctionGenerator Logic (function: A_AND_B) BinaryInput (BI) BinaryOutput (BO) CpAnalogNode (float value), CpBinaryNode (boolean value), CpIntegerNode (int value), CpStringNode (string) Comparison (select: A>B, A<B, A>=B, A<=B, A=B, A!=B) DateTimeTrigger Math (function: difference) Math (function: division) PeriodicTrigger Loop Math (function: maximum) Math (function: minimum) AnalogOverride, BinaryOverride Loop Logic (function: A_NOT_B) Logic (function: A_OR_B) Math (function: reset) AnalogOutput (AO) Math (function: difference) AnalogOverride, BinaryOverride, MulitstateOverride Totalizer Math (function: various types) Logic (function: A_XOR_B)

objects configuration (internal) property

Comparison (analog), 2-input Daily One-shot Difference (analog), 2-input Divider (analog), 2-input Interval One-shot Loop control Maximum Selector Minimum Selector Override PID control (or PI, P-only loop) NOT logic gate, 2 input OR logic gate, 2-input Reset Setpoint Adjuster Subtractor (analog), 2-input Timed Override Totalization Various trigonometric functions XOR logic gate, 2-input

54

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Common Control Object Things

Common Control Object Things

Control 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 objects available trigger properties. executeTriggerExcept 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 objects 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 objects property sheet displayed): Commands > dumpSends data about the object to the Standard Output window, including the objects swid, handle, name, parent, properties and values, and links. 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 objects available commands are listed in subsequent descriptions.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Note

Revised: April 20, 2004

55

Chapter 5 Common Control Object Things

Control Objects

About Units
Various Niagara objects have a units property to define how values are displayed. Table 5-1 and 5-2 list all units by category, full unit descriptor, and abbreviated unit. (By default, a linked GxText object displays a value with the abbreviated unit.) Unit types without an abbreviation are listed as , and display only with full units.
Table 5-1 Units (Area to MassFlow).

Category
Area Currency

Selections
square_meters square_feet currency1 currency2 ... currency10

Abbr.
sq m sq ft ... mA A ohms kohms Mohms V mV kV MV VA kVA MVA VAR kVAR MVAR kA J kJ kJ/kg MJ whr kwh btu Kbtu Mbtu Mwh kW/hr

Category
Enthaply

Selections
joules_per_kilogram_dry_air btus_per_pound_dry_air kilojoules_per_kilogram_dry_air

Abbr.
J/kg (da) btu/lb (da) KJ/kg hz khz mhz %RH kg/kg (da) mm m in ft um km W/sq ft W/m2 lm lux ft_can cd kg lb_mass g mg tonne tons kg/s kg/min kg/hr lb/min lb/hr

Entropy Frequency

joules_per_degree_Kelvin joules_per_kilogram_degree_Kelvin cycles_per_hour cycles_per_minute hertz kilohertz megahertz per_hour

Electrical

milliamperes amperes ohms kilohms megohms volts millivolts kilovolts megavolts volt_amperes kilovolt_amperes megavolt_amperes volt_amperes_reactive kilovolt_amperes_reactive megavolt_amperes_reactive degrees_phase power_factor kiloamperes

Humidity

grams_of_water_per_kilogram_dry_air percent_relative_humidity kg_of_water_per_kilogram_dry_air

Length

millimeters meters inches feet micrometers kilometers

Light

watts_per_square_foot watts_per_square_meter lumens luxes foot_candles candles

Energy

joules kilojoules kilojoules_per_kilogram megajoules watt_hours kilowatt_hours btus therms ton_hours Kbtus Mbtus megawatt_hours killowatts_per_hour

Mass

kilograms pounds_mass grams milligrams metric_tons

MassFlow

tons kilograms_per_second kilograms_per_minute kilograms_per_hour pounds_mass_per_minute pounds_mass_per_hour

56

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Common Control Object Things

Note
Table 5-2

By default, units in a newly-created object is typically category Other, no_units.

Units (Power to Other).

Category

Selection
milliwatts watts kilowatts megawatts btus_per_hour horsepower tons_refrigeration kilocalories_per_hour pascals hectopascals kilopascals millibars bars

Abbr.
mW W kW MW btu/hr hp tons_rfg kcal/h Pa hPa kPa mbar bar psi inwc C K F days_C days_F deltaF yrs mnths wks d hrs min sec ms m/s km/h ft/s ft/min mph

Category

Selection
cubic_feet cubic_meters

Abbr.
cu ft m3 igal l gal cfm m3/s m3/hr igal/min l/s l/min l/hr gal/min C/hr C/min F/hr F/min kwh/m2 MJ/m2 (blank) ppm ppb % %/s /min /sec psi/F rad rpm kg/m3 rad/s dB Raw pH

Volume

imperial_gallons liters us_gallons cubic_feet_per_minute cubic_meters_per_second cubic_meters_per_hour imperial_gallons_per_minute liters_per_second liters_per_minute liters_per_hour us_gallons_per_minute

Power

Volumetric Flow

Pressure

pounds_force_per_square_inch centimeters_of_water inches_of_water millimeters_of_mercury centimeters_of_mercury inches_of_mercury degrees_Celsius degrees_Kelvin degrees_Fahrenheit degree_days_Celsius degree_days_Fahrenheit delta_fahrenheit

Other

degrees_angular degrees_Celsius_per_hour degrees_Celsius_per_minute degrees_Fahrenheit_per_hour degrees_Fahrenheit_per_minute kilowatt_hours_per_square_meter kilowatt_hours_per_square_foot megajoules_per_square_meter megajoules_per_square_foot no_units parts_per_million parts_per_billion percent percent_per_second per_minute per_second psi_per_degree_Fahrenheit radians revolutions_per_minute kilograms_per_cubic_meter radians_per_sec decibels raw_value ph_value

Temperature

Time

years months weeks days hours minutes seconds milliseconds

watts_per_square_meter_degree_Kelvin W/m2K

Velocity

meters_per_second kilometers_per_hour feet_per_second feet_per_minute miles_per_hour

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

57

Chapter 5 Common Control Object Things

Control Objects

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 properties for all control objects.

Tab Property Name

objectType

Description
Read Only: The control object type. By default, a newly added object uses this string in its name (until renamed). The full string for the object type is shown, for example, AnalogInput or Comparison.

Valid Values
See description

Default

Notes

reflects For most object types, a object type standard abbreviation for that type appears inside the objects shape (near the top). This abbreviation is noted in the individual descriptions for each control object.

statusFlags

Read Only: Current state of the objects status flags, which reflect the general health of the object. Depending on conditions, status flags can be set in combinations. A dominant flag sets the objects color to something other than gray (the same color appears at its outputs). A normal state (no flags set) is where the status flags value is {ok}, and the objects color is gray. Outputs appear normally. Briefly, status flag values mean:

where values appear in braces { }: inAlarm fault overridden outOfService unackedAlarm down

{ok}

Not all object types can alarm, meaning that some objects have status flags that are never set. The total set of 6 status flags is a superset of the BACnetStatusFlag type, adding these 2 flags to the 4 BACnet types:

inAlarmAn alarm state currently exists.

The objects shape and outputs are red. Another property, alarmState, is True. faultA fault state occurs when another property, reliability, has any value except no_fault_detected. The objects shape and outputs are orange. overriddenThe objects properties presentValue and reliability are no longer tracking changes. outOfServiceThe objects property outOfService has been set to True. The objects shape and outputs are cyan. unackedAlarmAn alarm has occurred that is still pending acknowledgment. If the inAlarm flag is still set, the object outputs are red and also flashing. downThe station (or integration device) is down or offline. The object s shape and outputs are yellow. See description Status

unackedAlarm down

description

Read-Write: Permits a user-defined text descriptor for describing the object. Any printable characters, including spaces and mixed case characters, are allowed.

Not available for a Command object.

58

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Common Control Object Things

Table 5-3

Common properties for all control objects. (continued)

Tab Property Name

execution Parameters

Description
Read-Write: Defines the frequency and order for the object as it is executed by the stations ControlEngineService.

Valid Values
freq: never slower normal faster fastest minutely on_trigger order: input processor output

Default
freq: normal

Notes
This property is not available (nor applies to) a Command object.

freq (frequency)Specifies how often the

object is executed. Typically, the default frequency (normal) is acceptable. orderSpecifies the order of execution in each cycle. On each cycle of the control engine, objects specified as inputs are processed first, then processors next, and lastly the outputs. By default, the default order setting reflects the objects type. For example, 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. foreignAddress Read-Write: BACnet usage only. Exposes the Niagara object as a BACnet object.

order: <see Usually, default values descrip> are recommended.

Frequency selections are exclusive. For example, if on_trigger is selected, the object will execute only if the input executeTrigger is linked and a trigger pulse is received on that input. For related details, see ControlEngineService and its Config property executionFrequencies.

Config

See Description If assigned, this property value must be unique in the station, within the objects type (AI, AO, BI, BO, MSI, MSO, Calendar, Schedule, etc.)

-1 (not used)

Not shown for a Command object. Before using, the BACnet service must be installed and configured in the station. In the case of Ndio objects, the station must also have the BACxNdioService. Ndio objects count as either AI, AO, BI, or BO objectsrefer to Table 10-2 on page 10-8.

Note: Currently, this property has a practical application for these object types: AnalogInput (AI), AnalogOutput (AO), Binary Input (BI), BinaryOutput (BO), MultistateInput (MSI), MultistateOutput (MSO), Calendar, Schedule, and all Ndio Objects.
For these object types, a valid value is any integer from 0 to 4194302 (the maximum BACnet Instance Number for any object). membershipGroups Read-Write: (Future use only.) position Read-Write: The x-y coordinates for the objects position on the JDE Workspace. Coordinate values are in pixels, and are relative to the upper-left corner of the Workspace and the upper-left corner of the object shape (including its input area). An object with a position of 0,0 is in the top left corner of the Workspace.

niagaraR2 Some positive x, y value less than the parent (container) objects size property value.

niagaraR2 Leave at default. Near the mouse pointer when the object is first created. Typically, you dont manually enter position values, but use the mouse to drag the object as needed on the JDE Workspace. However, if needed, you can enter values directly to tweak an objects position.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Visual

Revised: April 20, 2004

59

Chapter 5 Common Control Object Things

Control Objects

Table 5-3

Common properties for all control objects. (continued)

Tab Property Name

minExecuteTime

Description
Read-Write: Can show the objects minimum execution time, in milliseconds. Shows MAX_VALUE if profileNodes in the ControlEngineService was not previously set (since the last station start).

Valid Values
integer, 0 to n

Default
See descrip.

Notes
Providing that the ControlEngineService was set to profileNodes, these properties show the objects execution statistics. Typically, you do not leave the ControlEngineService configured this way except for brief periods to collect these values. This properties are not available (nor apply to) a Command object.

maxExecuteTime Engineering

Read Only: Can show the objects maximum execution time, in milliseconds. Shows MIN_VALUE if profileNodes in the ControlEngineService was not previously set (since the last station start).

integer, 0 to n

See descrip.

averageExecute Time

Read Only: Can show the objects average execution time, in seconds. Shows 0.0 if profileNodes in the ControlEngineService was not previously set (since the last station start).

valid float

See descrip.

userData

Read-Write: Stores a user entered string. Can be used by servlets and the API for configuration information. Read-Write: Shows the security groups to which the object is assigned. A user must have the appropriate privileges in at least one security group to view and modify properties and issue commands. Refer to the Security Tab section on page 1-20 (Station object UserAdmin topic) for more details on how securityGroups settings apply.

Any desired text string for servlet/API usage. Any mix of these types:

<blank>

securityGroups

General

General HVAC Security Life Safety Group 4 Group 5 Group 6 Group 7

Also refer to the About Security section on page 1-21.

Security

510

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Common Control Object Things

Event-Type Objects
Many of the control object types are alarm-capable objects, or event-type objects. All have a common group of Status Properties and Alarm Setup Properties that have direct BACnet heritage, including property names and definitions. Event-type standard control objects include the following types1:

AnalogInput (AI) AnalogOutput (AO) BinaryInput (BI) BinaryOutput (BO) Loop MultistateInput (MSI) MultistateOutput (MSO)

Rather than cover the common properties in detail for each object type, they 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

In addition to the common status and alarm setup properties, all event-type objects have properties that are special, event-based, trigger outputs. Trigger outputs fire upon each occurrence of a particular event, change-of-state (or value), and so forth. Some event-type objects also have special trigger inputs. These properties are listed and described in the Trigger Properties section in each objects description. For any event-type object, a JDE user with Command, Admin privileges can access this menu bar command (the objects property sheet must be opened):

JDE Command

Commands > resetAckedTransitionsSets any of the three flags in the ackedTransitions property (to-offnormal, to-fault, to-normal) that are cleared. A rarely used command, it is necessary only in one possible scenario with a JACE-4/5 configured for standalone alarming (NotificationService is set to archive_local_no_sql). The symptom requiring this command is if the object indicates an unackedAlarm, and yet no alarm exists for acknowledgment. It is possible due to the size of the JACEs rolling alarm buffer (250 entries). If enough alarms are generated in this configuration, some unacked alarms could roll through, that is, get dropped. In this case, the ackedTransitions flags for the objects that generated the dropped alarm would get stuck in the clear state. The object will indicate an unackedAlarm in its status flags but the alarm can never be acknowledged. The resetAckedTransitions command will resolve this situation. It does not generate an alarm acknowledgment, it just cleans up the object.

1. Most Ndio objects (JACE-4 I/O) are also event-types. Refer to Chapter 10, Ndio Objects.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

511

Chapter 5 Common Control Object Things

Control Objects

Status Properties
Table 5-4

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. Description
Read Only: Shows the objects current alarm state, which is one shown at right.

Status properties for standard event-type objects (AI, AO, BI, BO, Loop, MSI, MSO).

Tab Property Name

eventState

Valid Values
normal fault offnormal high_limit low_limit See Description

Default
normal

Notes
offnormal applies to BI, BO, MSI, and MSO objects. The high_limit and low_limit states apply to AI, AO and Loop objects.

reliability

Read-Write: Required for BACnet usage. Indicates whether the presentValue or operation of the object is reliable, and if not, why. Selections include: no_fault_detected, no_sensor, overrange, under_range, open_loop, shorted loop, no_output_value, unreliable_other, process_error

no_fault_ detected

outOfService

Read-Write: Allows setting the object as out of service (when set to True). This allows logic testing of error conditions. While set to outOfService, you can then select a value for the reliability property. For example, you can set outOfService to True and reliability to unreliable_other, which will force a fault condition.

False, True

False

For input-type objects (AI, BI, MSI), you can set outOfService to True and then write to presentValue. This value appears at the output while the object is outOfService. Relates to the setup of the associated NotificationClass object. See also the notificationClass property description.

Status

ackedTransitions

Read Only: Flags, that when cleared, indicate that an unacknowledged event transition has occurred. Separate for event types: to-offnomal, to-fault, to-normal.

set or cleared

set

toOffnormal, toFault, toNormal

Read Only: For event transitions of type: to-offnormal (alarm), to-fault, to-normal. Each property has three fields:

eventTimeDate and timestamp for the

last alarm event.

ackTimeDate and timestamp for the last

acknowledgment. countTotal event count since the last acknowledgment. Resets to 0 upon receipt of acknowledgment. presentValue Read Only or Read Write: Required for BACnet. In normal usage, reflects the objects output. For input-type objects (AI, BI, MSI), this property is writable. When such an object is set to outOfService, an entered presentValue appears at the statusOutput. Setting outOfService back to False clears any previously entered presentValue.

valid date and timestamp for eventTime, ackTime, or null if the event has not occurred. 0 to <n> for any count

null for If an event-type is not date and set in the associated timestamp NotificationClass object to require acknowledgment, the 0 for count ackTime value remains null and the count value never resets to 0.

output value or state

Displays in the configured: units (if analog), activeInactiveText (if binary), or stateText (if multistate)

512

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Common Control Object Things

Alarm Setup Properties

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

timeDelay

Description
Read-Write: Minimum time period in Hr:Min:Sec, that an alarm (off-normal) condition must exist before the object alarms (statusFlag inAlarm becomes set and the object and its outputs turn red).

Valid Values
any practical value in Hr:Min:Sec

Default
00:00:00 (no delay)

Notes
This timeDelay period also applies to an object returning to-normal from an alarm state. However, the timeDelay period does not apply to transitions to (or from) fault conditions.

Typically, this is some number The delay timer begins when an alarm of seconds and condition, as configured, occurs. If the alarm or minutes condition clears before the delay timer expires, the object does not alarm and the delay timer is reset. notificationClass Read-Write: The assigned notification class number, used in routing alarms. A NotificationClass object using the same number must exist under the NotificationService (container) object. Configuration of this NotificationClass object 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 an ack, then it is always set (checked) in this objects status property, ackedTransitions. Such an event transition will never clear that field in ackedTransitions, meaning it will not set the statusFlag {unackedAlarm}. An alarm requiring acknowledgment results in a flashing red statusOutput (see Note). eventEnable Read-Write: Flags that define the types of event (alarm) transitions for this object that are sent to the alarm console. Selection to-offnormal applies to any alarm state, e.g. high-limit or low-limit for an AI, AO, or Loop object, or offnormal for a BI, BO, MSI, or MSO object. notifyType Read-Write: Required for BACnet compliance. In a Niagara system, it makes no difference which type is selected. (Either selection functions the same in the Niagara alarming subsystem.) However, if exposing the object as BACnet, and notifyType is set to event (not alarm), an active unacknowledged alarm is not reported by the stations BACnet service, GetAlarmSummary. selection of any or all: to-offnormal to-fault to-normal (none selected) 0 to 8388607 0

NotificationClass objects reside in or under the NotificationServices container (under the stations services). If the objects eventEnable flag is set for to-offnormal, AND the associated NotificationClass object is configured to require an ack for to-offnormal, the objects statusOutput flashes red during an unacknowledged alarm.

Alarm Setup

event or alarm

event

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

513

Chapter 5 Common Control Object Things

Control Objects

Table 5-5

Alarm Setup properties for standard event-type objects (AI, AO, BI, BO, Loop, MSI, MSO).

Tab Property Name

inhibitTime

Description
Read-Write: Duration (Hr:Min:Sec) of the alarm inhibit timer, which applies only if the objects inputs statusInhibit is linked. The purpose is to prevent nuisance alarms on equipment startup and shutdown.

Valid Values
any practical value in Hr:Min:Sec

Default

Notes

00:00:00 A minimum value of 1 (no inhibit) second (00:00:01) is recommended whenever the statusInhibit is linked.

Note: For further details specific to an object type, see the inhibitTime property description for that object.
eventTriggerEnable Read-Write: Flags that specify the types of selection of any event (alarm) transitions, as they occur, that or all: fire the objects eventTrigger output. to-offnormal Selection to-offnormal applies to any to-fault alarm state, e.g. high-limit or low-limit for to-normal an AI, AO, or Loop object, or offnormal for a BI, BO, MSI, or MSO object. Read-Write: Text descriptor included in a to-offnormal or to-fault alarm for this object, as sent to the alarm console. Appears in the messageText field of the alarm record. This text is not included in a return to-normal event sent to the alarm console. If left at the default hyphen (-), the objects container object (Container, Bundle, Composite, PollAlways, PollOnDemand) alarmText property value is used. 255 characters maximum. Any text string, including spaces and mixed case characters. (none selected) These flags operate independently of the eventEnable flags.

Alarm Setup, cont.

alarmText

(hyphen)

For BI, BO, MI, and MSO objects, another property, alertText, applies to runtime and COS alerts sent to the alarm console. If alarmText is default (-) for both the object and its container, the the next higher containers alarmText is used (and so on). If all parent container objects have the default (-) alarmText, the Station objects alarmText is used.

Note: If alarms or alerts will be routed from the object to a Web Supervisor running the Vykon Alarm Service, and a special alarm sound and/or URL is needed at VAS clients (associated with the object), you must append extra information at the end of the alarmText and/or alertText property. For details, see the Vykon Alarm Service Installation and Configuration Instructions.

Alarm Setup Properties Notes

Most alarm setup properties have direct BACnet heritage. However, two of these properties are unique to Niagara objects, namely:

inhibitTimeThis works in conjunction with the objects 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. eventTriggerEnableThis works in conjunction with the objects eventTrigger output (a triggerType property). Unlike eventEnable, which relates to alarm notification, the eventTriggerEnable flags determine which types of event transitions cause the objects eventTrigger output to fire.

514

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects AnalogInput

AnalogInput
Quick reference for all properties: Table A-2 Inputs
statusInput

Default Object Shape

Outputs
statusOutput

abbrev: AI AnalogInput (AI) objects are used to bring analog values into the control engine, format them for display, monitor them for an off-normal condition, generate an alarm, or pass the value onto some other control logic. As with Niagara AO, BI, BO, MSI, and MSO objects, you can expose any AI object in the database directly as a BACnet object.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs
executeTrigger statusInhibit statusInput

Outputs
eventTrigger covTrigger statusOutput

container).
Resource Count Range: 63 to 116
Type
input

Input / Output Property Reference for AI Object

(only input and output types, see Table 5-6 for all properties)

Label
exe sInh sIn eventTr covTrig sOut

Property Name
executeTrigger statusInhibit statusInput eventTrigger covTrigger statusOutput

Data Species
TriggerType BooleanStatusType FloatStatusType TriggerType TriggerType FloatStatusType

output

Trigger Properties

The AI object has the standard input property, executeTrigger, (typically not used) and also two trigger-type outputs: eventTriggerFires upon each event transition (to-offnormal, to-fault, to-normal) that has been specified in the property eventTriggerEnable. covTriggerFires upon each change of value at the statusOutput. As needed, these outputs can be linked to any input using TriggerType data species.

Commands
A JDE user with Command, Admin rights has this available menu bar command:

Commands > resetAckedTransitionsSets all three flags in the ackedTransitions property (to-offnormal, to-fault, to-normal). Rarely required, see the the JDE Command section on page 5-11 for more information.

Properties
Table 5-6 AnalogInput (AI) object properties.

Tab Property Name

objectType, statusFlags, description Status

Description
See Table 5-3 on page 5-8 for information on these properties common to all control objects.

Valid Values

Default

Notes

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

515

Chapter 5 AnalogInput

Control Objects

Table 5-6

AnalogInput (AI) object properties. (continued)

Tab Property Name

eventState, reliability, outOfService, ackedTransitions, toOffnormal, toFault, toNormal presentValue executeParameters foreignAddress Status, cont.

Description
See Table 5-4 on page 5-12 for information on these properties common to all event-type control objects.

Valid Values

Default

Notes
presentValue can be written to directly whenever the object is set to outOfService.

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: BACnet usage only. Set to a positive integer for this object to appear as a BACnet AnalogInput object to other BACnet devices. See foreignAddress, page 5-9, for more information. Read-Write: (Future use only.) Read-Write: Selection of engineering units for display purposes. Choose from a logical grouping, then a specific unit. For selections see About Units, page 5-6. Read-Write: The minimum required change-of-value at the statusInput (since the last output change) before outputs and presentValue update. Affects these outputs: 0 to 4194302 or -1 (not exposed)

normal, input -1 If set, must be a unique number among all other AnalogInput objects in station. Units can be displayed by a linked GxText object. Execution efficiency (of downstream objects) is typically increased by entering a small value here, say 0.1

membershipGroups units Config

niagaraR2 Select any (BACnet-type unit choices) valid float

niagaraR2 Leave at default. Other, no_units

covIncrement

0.0 (no minimum)

statusOutput covTrigger (fires at change of value)

defaultInput Read-Write: The input value used by the AI object if its statusInput link is broken or assumes a status that includes fault. See Table 5-5 on page 5-13 for information on these properties common to all event-type control objects. valid float 0.0

timeDelay, notificationClass, eventEnable, notifyType, inhibitTime*, eventTriggerEnable, alarmText inhibitTime Alarm Setup

* See specific details on inhibitTime, the next property.

Read-Write: Duration (Hr:Min:Sec) of the alarm inhibit timer, which applies only if the objects input statusInhibit is linked. The purpose is to prevent nuisance alarms on equipment startup and shutdown. The inhibitTime is triggered by a transition from false-to-true at the statusInhibit input.

any practical value in Hr:Min:Sec

00:00:00 A minimum of 1 (no inhibit) second (00:00:01) is recommended whenever the statusInhibit is linked.

When statusInhibit becomes true, alarm

processing is delayed for the inhibit time.

Whenever statusInhibit becomes false,

alarm processing remains inhibited. The alarm status of the object cannot change. This applies whether the objects statusFlags show a normal {ok} state or inAlarm and/or unackedAlarm states.

516

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects AnalogInput

Table 5-6

AnalogInput (AI) object properties. (continued)

Tab Property Name

minPresentValue

Description
Read-Write: Valid processing low range for the received input value. Below this value, the object and its output have a fault status (orange color).

Valid Values
valid float

Default

Notes

MIN_VALUE is default, meaning no effective minimum.

maxPresentValue

Read-Write: Valid processing high range for the received input value. Above this value, the object and its output have a fault status (orange color).

valid float

MAX_VALUE is default, meaning no effective maximum.

Alarm Setup, cont.

highLimit

Read-Write: Value above which the object is evaluated in high-limit alarm. Above this value (if not in fault), the object and output have inAlarm status (red color).

valid float

0.0

lowLimit

Read-Write: Value below which the object is considered in low-limit alarm. Below this value (if not in fault), the object and output have inAlarm status (red color).

valid float

0.0

deadband

Read-Write: Differential value applied to high and low limits before return-to-normal. Deadband is subtracted from highLimit and added to lowLimit.

valid float

0.0

Deadband does not apply to fault conditions.

limitEnable

Read-Write: Flags that enable low-limit and high-limit alarms, as needed. Read-Write: See position, page 5-9. Read-Write: Sets decimal position from 0 to 6 places, and optionally force (+) sign for positive values. Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows the current boolean state and status of the statusInhibit input. Read Only: Shows the current value and status received on the statusInput. Read Only: Shows the current value and status of the statusOutput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

(select) low-limit, high-limit 0 to 6, (+) sign no (+) sign

(none)

position Visual decimalFormat

2, Effects display value no (+) sign only (no effect on precision).

Engineering

minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInhibit (input sInh) statusInput (input sIn) statusOutput (output sOut)

false, true : {status flags} <float value> {status flags} <float value> {status flags} General, 7 others

false : {ok} 00.0 {ok} 00.0 {ok} General

Security

securityGroups

AnalogInput Notes
The AnalogInput (AI) object is typically used to display an analog value received from an integration (shadow) object, offering decimal place control and unit selection. In addition, the object provides Niagara alarm capability and the option to expose it as a BACnet Analog Input object.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

517

Chapter 5 AnalogInput

Control Objects

Alarming Functions

Any AI object can be configured for alarm indication, and optionally, event (alarm) notification. The object provides properties to set values for alarm limits, alarm deadband, alarm delay, and event notifications, using BACnet-type properties. The following subtopics apply to AI alarming: AI Alarm Detection AI Alarm Notification AI Alarm Inhibit AI Alarm Delay

Figure 5-1 AI objects have alarming functions with BACnet-type properties.

notificationClass, eventEnable, and notifyType apply to alarm notification. inhibitTime and eventTriggerEnable are Niagara-only properties. See AI Alarm Inhibit. fault limits, if any, are defined by minPresentValue and maxPresentValue These four properties (listed at the bottom of the Alarm Setup tab) define alarm detection.

AI Alarm Detection
Several properties on the Alarm Setup tab determine whether an alarm condition can be detected by the object. In order of relative importance, these properties include:

highLimitValue above which the object can be considered offnormal, with a status (eventState property) of high_limit. The object shape and its statusOutput are red in this state. The appropriate limitEnable flag must be set. lowLimitValue below which the object can be considered offnormal, with a status (eventState property) of low_limit. The object shape and its statusOutput are red in this state. The appropriate limitEnable flag must be set. limitEnableFlags that determine whether the object can alarm, using the respective highLimit and lowLimit properties. The default is for both flags cleared, meaning that the object cannot alarm. You must set flags as needed. deadbandDifferential value that must be applied to high and low limits before a return from a high_limit or low_limit status to normal status occurs. Deadband is subtracted from the highLimit and added to the lowLimit. timeDelayOptional time period that must be met before any alarm state change occurs with the object. See AI Alarm Delay on page 5-20.

518

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects AnalogInput

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. 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: notificationClassMust match an existing notificationClass object in the stations notificationServices container. The default class is zero (0). eventEnableFlags 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, etc. notifyTypeEither 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 clients GetAlarmSummary request, the station reports BACnet-exposed objects currently in alarm only if their notifyType properties are set to alarm.

Note

alarmTextText 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 objects 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 Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

519

Chapter 5 AnalogInput

Control Objects

Figure 5-2

Alarm inhibit feature requires linking to the statusInhibit input.

Upon a false-to-true (active) transition, the objects inhibitTime period becomes effective. Until this period expires, the object remains inhibited from any alarm status change. inhibitTime = 00:15:00 (15 minutes)

Whenever a logic false (inactive) is at the statusInhibit (sInh) input, the AI object cannot change status to (or from) an alarm condition.

After the inhibitTime period expires, the object is capable of changing alarm status to (or from) alarm.

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 objects 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 objects 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 objects 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.

520

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects AnalogInput

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). Note that the alarm delay feature does not apply to transitions to (or from) a fault status.

Examples
Figure 5-3

Figure 5-30 shows several examples of using AnalogInput objects.

AnalogInput examples.

The two AI objects at right are used to format the received decimal value to one place, and assign units (temperature, in this case).

By default, a linked GxText object shows the abbreviated units of the AI object.

This AI object passes a duct pressure value, as converted by a Math object (DIV) from Pascals to inches water column. Here, the AI object is necessary only for alarming capability and exposure as a BACnet object (as the Math object also has units and decimal values for display). The eventTrigger output of this AI object is linked to the doArchiveTrigger input at multiple log-type objects. If an alarm (or other status event) occurs, the log objects archive their accumulated data to the stations designated archive supervisor.

This AI object provides alarming capability and the ability to be exposed as a BACnet object.

This AI object is also configured for alarm inhibit. See See AI Alarm Inhibit on page 5-19.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

521

Chapter 5 AnalogOutput

Control Objects

AnalogOutput
Quick reference for all properties: Table A-4 Inputs
priorityArray statusInput

Default Object Shape

Outputs
statusOutput prioritizedOutput

abbrev: AO AnalogOutut (AO) objects provide a prioritized analog output signal to other control logic. Typically, an AO object is used to adjust a setpoint in an a foreign devices application. As with Niagara AI, BI, and BO objects, you can expose any AO object in the database directly as a BACnet object.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs
executeTrigger statusInhibit priorityArray statusInput

Outputs
eventTrigger covTrigger statusOutput prioritizedOutut statusFeedbackOutput

container).
Resource Count Range: 72 to 132 Note: Upon any link change (add or delete
Input / Output Property Reference for AO Object
(only input and output types, see Table 5-7 for all properties)

any link) to an AO object, commands at priority-slots (1-16) that were received from priorityArray links are momentarily cleared. The priorityArray input is now immediately rescanned; any input command found remains effective at the output.
Trigger Properties

Type
input

Label
exe sInh pIn sIn eventTr covTrig sOut pOut sFbOut

Property Name
executeTrigger statusInhibit priorityArray statusInput eventTrigger covTrigger statusOutput prioritizedOutput statusFeedbackOutput

Data Species
TriggerType BooleanStatusType FloatPriorityArrayType FloatStatusType TriggerType TriggerType FloatStatusType FloatPriorityType FloatStatusType

output

The AO object has the standard input property, executeTrigger, (typically not used) and also two trigger-type outputs: eventTriggerFires upon each event transition (to-offnormal, to-fault, to-normal) that has been specified in the property eventTriggerEnable. covTriggerFires upon each change of value at the statusOutput. As needed, these outputs can be linked to any input using TriggerType data species.

Commands
The right-click command menu provides these commands (note that default command names are shown, these are modifiable using the objects commandTags property): SetTo set an output value at the Manual level (8). Requires Command, Std privileges. AutoTo clear an output value set at the Manual level (8). Requires Command, Std privileges. EmergencySetTo set an output value at the Emergency level (1). Requires Command, Emer privileges. EmergencyAutoTo clear an output value set at the Emergency level (1). Requires Command, Emer privileges.

522

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects AnalogOutput

For a JDE user with Command, Admin privileges, the following object command is available from the menu bar:

Commands > resetAckedTransitionsSets all three flags in the ackedTransitions property (to-offnormal, to-fault, to-normal). Rarely required, see the the JDE Command section on page 5-11 for more information.

Properties
Table 5-7 AnalogOutput (AO) object properties.

Tab Property Name

objectType, statusFlags, description eventState, reliability, outOfService, ackedTransitions toOffnormal, toFault, toNormal, presentValue priorityArray (input: pIn) relinquishDefault executeParameters foreignAddress Status

Description
See Table 5-3 on page 5-8 for information on these properties common to all control objects. See Table 5-4 on page 5-12 for information on these properties common to all event-type control objects.

Valid Values

Default

Notes

presentValue is always read-only.

Priorities

Read Only: Shows values present on each of the 16 priority level slots for the priorityArray (pIn) input. Read-Write: Defines the output value when all 16 priority level slots have an auto.

<valid float> or auto, levels 1 to 16 valid float

auto 1 to 16 0.0 normal, output -1 Must be a unique number among all AnalogOutput objects in station.

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: BACnet usage only. Set to a positive integer for this object to appear as a BACnet AnalogOutput object to other BACnet devices. See foreignAddress, page 5-9, for more information. Read-Write: (Future use only.) Read-Write: Selection of engineering units for display purposes. Choose from a logical grouping, then a specific unit. For selections see About Units, page 5-6. Read-Write: The minimum required change-of-value at the priorityArray input (since the last output change) before the outputs and presentValue update. Affects these outputs: 0 to 4194302 or -1 (not exposed)

membershipGroups Config units

niagaraR2 Select any (BACnet-type unit choices) valid float

niagaraR2 Leave at default. Other, no_units

covIncrement

prioritizedOutput statusOutput covTrigger (fires at change of value)

timeDelay, notificationClass, eventEnable, notifyType, inhibitTime*, eventTriggerEnable, alarmText Alarm Setup See Table 5-5 on page 5-13 for information on these properties common to all event-type control objects.

0.0 Execution efficiency (of downstream (no minimum) objects) is typically increased by entering a small value here, say 0.1

* See specific details on inhibitTime, the next property.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

523

Chapter 5 AnalogOutput

Control Objects

Table 5-7

AnalogOutput (AO) object properties. (continued)

Tab Property Name

inhibitTime

Description
Read-Write: Duration (Hr:Min:Sec) of the alarm inhibit timer, which applies only if the objects input statusInhibit is linked. The purpose is to prevent nuisance alarms on equipment startup and shutdown.

Valid Values
any practical value in Hr:Min:Sec

Default

Notes

00:00:00 A minimum of 1 (no inhibit) second (00:00:01) is recommended whenever the statusInhibit is linked.

Note: Alarming is based solely on the value at the priorityArray input (unlike a BO or MSO object, the statusInput is ignored).
The inhibit timer is triggered by a transition at the statusInhibit input.

When statusInhibit becomes true, alarm

processing is delayed for the inhibit time.

When statusInhibit becomes false, alarm

processing remains inhibited. While alarm processing is inhibited or delayed, the alarm status of the object cannot change. This applies whether the objects statusFlags show a normal {ok} state or inAlarm and/or unackedAlarm states. minPresentValue Read-Write: Valid processing low range. Below this value, the object and its statusOutput have a fault status (orange). The minimum value that can be set for the object using its right-click command menu. maxPresentValue Read-Write: Valid processing high range. Above this value, the object and its statusOutput have a fault status (orange). The maximum value that can be set for the object using its right-click command menu. highLimit lowLimit deadband limitEnable position decimalFormat Read-Write: Value above which the object is considered in high-limit alarm. Read-Write: Value below which the object is considered in low-limit alarm. Read-Write: Differential value applied to off-normal limits before return-to-normal. Read-Write: Flags that enable low-limit and high-limit alarms. Read-Write: See position, page 5-9. Read-Write: Sets decimal position from 0 to 6 places, and optionally force (+) sign for positive values. Read-Write: Defines the command labels that show on the right-click command menu for the object. Default tags are: valid float valid float valid float valid float 0 to 6, (+) sign, no (+) sign Any desired text string, including spaces and numerals. 0.0 0.0 0.0 0.0 2, no (+) sign See descrip. If a tag is blank (no characters), the command is not available on the command menu. See Figure 5-2. Greater than min setting (above). Less than max See Notes Defaults are MIN and setting (below) MAX_VALUE. A non-default value is required for both of these properties in See Notes order to provide a slider adjustment from the JDE.

Alarm Setup, cont. Visual

commandTags

Set (manualSet level) Auto (manualAuto level) Emergency Set (emergencySet level) Emergency Auto (emergencyAuto level)

524

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects AnalogOutput

Table 5-7

AnalogOutput (AO) object properties. (continued)

Tab Property Name

minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInhibit (input: sInh) statusInput (input: sIn)

Description
Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows the current boolean state and status of the statusInhibit input. Read Only: Shows the current value and status received on the statusInput.

Valid Values

Default

Notes

false, true : {status flags} <float value> {status flags}

false : {ok} 00.0 {ok} If statusInput is not linked, reflects value at priorityArray.

Engineering

Note: This input value is not used in the AO objects alarm processing (no real use).
statusOutput (output: sOut) prioritizedOutput (output: pOut) statusFeedbackOutput (output: sFbOut) Read Only: Shows the current value and status of the statusOutput. Read Only: Shows the current value and status of the statusOutput. Read Only: Shows the current value and status at the statusFeedbackOutput. <float value> {status flags} 00.0 {ok}

<float value> @ 0.00 @ 16 <pri. level> <float value> {status flags} 00.0 {ok} Reflects statusInput value (if linked), otherwise shows the statusOutput value.

Security

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

General, 7 others

General

AnalogOutput Notes
The 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.

Command Related Properties

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: minPresentValueDetermines the minimum valid value that can be commanded, using the right-click Set command. maxPresentValueDetermines 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.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

525

Chapter 5 AnalogOutput

Control Objects

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 the default values for min and maxPresentValue. When using the JDE or a web browser to issue a right-click command to the object (either directly, or through a linked Gx object), any value can be entered.

Use the Alarm Setup tab to access min and maxPresentValue.

Default MIN and MAX values allow a Set command to any value.

This AO object has configured values for min and maxPresentValue. When using the JDE to issue a right-click command to the object (either directly or through a linked Gx object), a slider bar appears that can be dragged to change the value. The commanded value can only be between the configured limits.

Use the Alarm Setup tab to access min and maxPresentValue.

Slider bar appears because both min and maxPresentValue are configured.

No slider is available when issuing an AO command from a Web browser (through a linked Gx object). However, the popup control remains displayed if the commanded value is beyond min or maxPresentValue. In addition, the lower left corner of the browser window shows an Invalid Input while the cursor is over the OK button.

Popup control for right-click command when using a Web browser.

Whenever the entered value is out of range, the popup command control remains visible after clicking OK.

The lower left corner of the browser shows Invalid Input with the cursor over OK.

526

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects AnalogOutput

Command Tags

It is typical for AO objects to be configured with custom command labels, using the commandTags property, located on the Visual tab of the objects property sheet. Editing commandTags allows more meaningful right-click menu labels on the right-click menu than the default values, for example, Adjust Setpoint vs. Set. In addition, you can clear any tags to make those commands unavailable (Figure 5-5). This is often done for emergency-level commands, for example.

Figure 5-5

The commandTags property (Visual tab) determines how (and which) commands are listed.

Examples
Figure 5-6

Figure 5-6 shows two examples of using AnalogOutput objects.

AnalogOutput examples.

These AO objects are used for setpoint control of a LON VAV device. The commandTags property of the occupied setpoint AO object has been edited from defaults to provide only a manual level set command (Change Setpoint). AO objects at right are used to control physical AOs of a LON Honeywell XFL522 device. SnvtSwitchMux objects are needed between the AO objects and the XFL522 device object for binding to the devices associated NVIs.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

527

Chapter 5 AnalogOverride

Control Objects

AnalogOverride
Quick reference for all properties: Table A-5 Inputs
(none)

Default Object Shape

Outputs
statusInOverride prioritizedOutput

abbrev: AOvrd An AnalogOverride (AOvrd) object provides a prioritized analog output signal that is controlled 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

All Inputs / Outputs

Inputs
executeTrigger overrideTrigger

Outputs
inOverride statusInOverride prioritizedOutput

container).
Resource Count Range: 41 to 57

Input / Output Property Reference for AnalogOverride Object

(only input and output types, see Table 5-8 for all properties)

Type
input output

Label
exe override inOverr sInOv pOut

Property Name
executeTrigger overrideTrigger inOverride statusInOverride prioritizedOutput

Data Species
TriggerType TriggerType boolean BooleanStatusType FloatPriorityType

Trigger Properties

The AOvrd object has the standard input property, executeTrigger, (typically not used) plus an additional trigger-type input: overrideTriggerAny received trigger pulse starts an override at the objects 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 override would be started each time a trigger pulse is received at this input.

Commands
For any user with Command, Std privileges, an AOvrd object has a right-click command menu that provides these commands: overrideTo start an override and specify the duration, in minutes. cancelTo cancel any current override. setOverrideValueTo set the prioritizedOutput value used in an override.

Properties
Table 5-8 AnalogOverride (AOvrd) object properties.

Tab Property Name

statusFlags Status inOverride (output: inOverr)

Description
Read Only: See Table 5-3 on page 5-8. Read-Only: Indicates if an override is currently in effect (True) or not (False). Available as a linkable output.

Valid Values
False, True

Default
False

Notes
boolean data species.

528

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects AnalogOverride

Table 5-8

AnalogOverride (AOvrd) object properties. (continued)

Tab Property Name

executeParameters foreignAddress membershipGroups priorityForWriting

Description

Valid Values

Default
normal, input -1

Notes

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: Does not apply to this object. Read-Write: (Future use only.) Read-Write: Defines the priority level used at the prioritizedOutput during an override. When the override expires or is canceled, this level is autoed. -1 niagaraR2 Any priority level, from 1 to 16 Any positive integer from 1 up to 32-bit limit.

niagaraR2 Leave at default. Manual Operator (8) 60 If using the objects right-click command menu, this override time is displayed (and can be adjusted) each time an override is issued.

overrideTime (min) Config

Read-Write: Defines the duration of an override, in minutes. When an override is commanded, this time is initialized and begins counting down. If not canceled or re-initiated, the override will last this duration. This property is most important when using the input overrideTrigger.

overrideValue

Read-Write: Defines the value that appears at the prioritizedOutput during an override. This value will be issued at the priority level defined in the priorityForWriting property. When the override expires or is canceled, the output value expires (level is autoed). This property is most important when using the input overrideTrigger.

Any floating point value.

0.0

If using the objects right-click command menu, this override value can be adjusted (setOverrideValue).

position Visual decimalFormat

Read-Write: See position, page 5-9. Read-Write: Sets decimal position from 0 to 6 places, and optionally force (+) sign for positive values. Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows if an override is active and also the status of the object. Appears by default as a linkable output. Read Only: Shows the value and priority level currently on the prioritizedOutput. Appears by default as a linkable output. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

0 to 6, (+) sign no (+) sign

2, no (+) sign

Engineering

minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInOverride (output sInOv) prioritizedOutput (output pOut)

true or false {status flags} <ovrd value> @ <pri. level> General, 7 others

false {ok}

BooleanStatusType data species. FloatPriorityType data species.

auto @ 8

Security

securityGroups

General

AnalogOverride Notes
There are two basic ways to use an AnalogOverride object: Available directly to userssee Directly Available. Available through a Command objectsee Used with a Command object.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

529

Chapter 5 AnalogOverride

Control Objects

Directly Available The right-click menu for an AnalogOverride object provides the user a list of
commands, providing the ability to: Initiate an override, specifying the duration in minutes. Cancel an override. Change the analog value for an override (setOverrideValue).

Note

A setOverrideValue command does not affect an override in progress.

If changed, the duration of override and/or the override value are stored in the objects Config properties. These values become the defaults for the next command, and are seen when the commands popup control appears (Figure 5-7).
Figure 5-7 An override or setOverrideValue command shows the currently stored value.

Popup control for right-click override command when using the JDE.

Popup control for right-click override command when using a Web browser.

Popup control for right-click setOverrideValue command when using the JDE.

Popup control for right-click setOverrideValue command when using a Web browser.

530

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects AnalogOverride

Used with a Command object

In some scenarios, direct access to an AnalogOverride object may provide too much user control for changing override parameters (duration times and override values). In this case, linking a Command object to the objects overrideTrigger may be better. In this configuration, a user can be given access to the Command object (but not directly to the AnalogOverride object). This allows the initiation of an override, but no other control (including canceling an override). The outputTrigger text property of the Command object should be given a descriptive label for the configured override action (Figure 5-8).

Figure 5-8

Control from a linked Command object allows override initiation only.

Command object linked to overrideTrigger input. Popup right-click command to linked Command object, seen from the JDE. Popup right-click command to linked Command object, seen from a Web browser.

outputTriggerText of Command object.

Other Notes
Figure 5-9

The standard set of library (lib) Program objects includes an object used to derive the remaining override time. Two links are required to the AnalogOverride object.

RemainingOverrideTime object in Local Library (tridiumx/lib/programs/hvac) used with AnalogOverride.

Local Library opened with lib JAR expanded to reveal programs folders (hvac). Copy the object (sns file) and paste it into your station as needed.

Copied RemainingOverrideTime object.

Remaining override time value. Can be linked to a GxText to display to time to users.

Two links are required between the AnalogOverride object and the Program object (RemainingOverrideTime): overrideTime to overrideTime statusInOverride to statusInOverride

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

531

Chapter 5 BinaryInput

Control Objects

BinaryInput
Quick reference for all properties: Table A-9 Inputs
statusInput

Default Object Shape

Outputs
statusOutput

abbrev: BI BinaryInput (BI) objects are used to bring digital values into the control engine, generate an alarm on a digital state, or pass the value onto some other control logic. The BI object collects runtime (elapsed active time) and counts COS (changes-of-state). Based upon configurable limits, the object can be set to generate alerts for both runtime levels and COS counts. Trigger inputs allow the clearing of the COS count and the runtime value. Trigger outputs are available that fire upon each COS, COS alert, runtime alert, and alarm (event). As with Niagara AI, AO, and BO objects, you can expose any BI object in the database as a BACnet object.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs
executeTrigger statusInhibit resetCOSCountTrigger* resetElpActTimeTrigger* statusInput

Outputs
eventTrigger statusCOSCount* statusElpActTime* COSTrigger* COSAlertTrigger* ElpActAlertTrigger* statusOutput

*abbreviations, see chart below

*abbreviations, see chart below

Input / Output Property Reference for BI Object

(only input and output types, see Table 5-9 for all properties) Type input Label exe sInh resetCt resetElp sIn eventTr sCnt sCnt cosT cosAlrt elActAlr sOut Property Name executeTrigger statusInhibit resetChangeOfStateCountTrigger resetElapsedActiveTimeTrigger statusInput eventTrigger statusChangeOfStateCount statusElapsedActiveTime changeOfStateTrigger changeOfStateAlertTrigger elapsedActiveTimeAlertTrigger statusOutput Data Species TriggerType BooleanStatusType TriggerType TriggerType BooleanStatusType TriggerType IntegerStatusType IntegerStatusType TriggerType TriggerType TriggerType BooleanStatusType

container).
Resource Count Range: 80 to 136
output

Trigger Properties

The BI object has the standard input property, executeTrigger, (typically not used) and also 2 other trigger-type inputs: resetChangeOfStateCountTriggerAny received trigger pulse clears the objects current count of COS (changes of states), resetting it to zero (0). resetElapsedActiveTimeTriggerAny received trigger pulse clears the objects accumulated runtime (elapsed active time), resetting it to zero (0.0). In addition, there are 4 available trigger-type outputs, described as follows:

eventTriggerFires upon each event transition (to-offnormal, to-fault, to-normal) that has been specified in the property eventTriggerEnable. changeOfStateTriggerFires upon each change-of-state at the statusOutput. changeOfStateAlertTriggerFires 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).

532

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects BinaryInput

elapsedActiveTimeAlertTriggerFires each time a runtime alert is issued (activeTimeAlertLimit value has been reached), or when a multiple of this value occurs (if periodicAlerts is set to True). As needed, these trigger-type inputs and outputs can be linked to other objects.

Commands
For a JDE user with Command, Admin privileges, the following object commands are available from the menu bar (for example, Command > resetActiveTime):

resetAckedTransitionsSets all three flags in the ackedTransitions property (to-offnormal, to-fault, to-normal). Rarely required, see the the JDE Command section on page 5-11 for more information. resetChangeOfStateCountThis sets the changeOfStateCount property value to zero (0), clearing any COS count. resetActiveTimeThis sets the elapsedActiveTime property value to 00:00:00 (Hr:Min:Sec), clearing any accumulated runtime. setChangeOfStateAlertLimitAllows editing of the changeOfStateAlertLimit property value (Alarm Setup property). setRuntimeAlertLimitAllows editing of the activeTimeAlertLimit property value (Alarm Setup property).

Properties
Table 5-9 BinaryInput (BI) object properties.

Tab Property Name

objectType, statusFlags, description eventState, reliability, outOfService, ackedTransitions toOffnormal, toFault, toNormal, presentValue Status changeOfStateTime changeOfStateCount

Description
See Table 5-3 on page 5-8 for information on these properties common to all control objects. See Table 5-4 on page 5-12 for information on these properties common to all event-type control objects.

Valid Values

Default

Notes

presentValue can be written to directly whenever the object is set to outOfService.

Read Only: Shows a date/timestamp for the last COS (change of state). Read Only: Shows the total number of changes of state that have occurred since the last COS count reset (clear). Read Only: Shows a date/timestamp for when the COS count was last cleared. Read Only: Shows the accumulated runtime (elapsed active time) formatted in Hr:Min:Sec. Read Only: Shows a date/timestamp for when the accumulated runtime (elapsed active time) was last cleared.

valid timestamp or null (none) integer value

null 0

timeOfStateCountReset elapsedActiveTime

valid timestamp or null (none) Time period up to 9999:99:99 (Hr:Min:Sec) valid timestamp or null (none)

null 00:00:00

timeOfActiveReset

null

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

533

Chapter 5 BinaryInput

Control Objects

Table 5-9

BinaryInput (BI) object properties. (continued)

Tab Property Name

executeParameters foreignAddress

Description

Valid Values

Default
normal, input -1

Notes

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: BACnet usage only. Set to a positive integer for this object to appear as a BACnet BinaryInput object to other BACnet devices. See foreignAddress, page 5-9, for more information. Read-Write: (Future use only.) Read-Write: Determines if the same boolean state at the statusInput is reflected at the statusOutput (normal), or if the output remains opposite from the input (reverse). Read-Write: The input value used by the BI object if its statusInput link is broken or assumes a status that includes fault. See Table 5-5 on page 5-13 for information on these properties common to all event-type control objects. 0 to 4194302 or -1 (not exposed)

Must be a unique number among all BinaryInput objects in station.

Config

membershipGroups polarity

niagaraR2 normal, reverse

niagaraR2 Leave at default. normal

defaultInput

Inactive, Active

Inactive

timeDelay, notificationClass, eventEnable, notifyType, inhibitTime*, eventTriggerEnable, alarmText inhibitTime

* See specific details on inhibitTime, the next property.

Read-Write: Duration (Hr:Min:Sec) of the alarm inhibit timer, which applies only if the objects input statusInhibit is linked. The purpose is to prevent nuisance alarms on equipment startup and shutdown. The inhibitTime is triggered by a transition at the statusInhibit input.

any practical value in Hr:Min:Sec

00:00:00 A minimum value (no inhibit) of 1 second (00:00:01) is recommended whenever the statusInhibit input is linked. Alarm processing compares the statusInput value to the defined alarmValue.

Alarm Setup

When statusInhibit becomes true, alarm

processing is delayed for the inhibit time.

When statusInhibit becomes false, alarm

processing is delayed for three times the inhibit time. changeOfStateAlertLimit Read-Write: Number of COS occurrences that generate a changeOfStateCount alert. activeTimeAlertLimit Read-Write: Amount of runtime (elapsed active time), in Hr:Min:Sec, that generates a runtime alert. Read-Write: The assigned notification class number, used in routing alerts. A NotificationClass object using the same number should exist in the NotificationService objects container. periodicAlerts Read-Write: Determines if both COS count alerts and runtime alerts are periodically generated each time the respective limit is reached. False, True False Positive integer Value up to 99999:59:59 (Hr:Min:Sec) 0 to 8388607 0 00:00:00

alertNotificationClass

534

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects BinaryInput

Table 5-9

BinaryInput (BI) object properties. (continued)

Tab Property Name

alertText Alarm Setup, cont.

Description
Read-Write: Text descriptor included in either a COS count alert or runtime alert. If left at the default hyphen (-), the Station objects alertText is used.

Valid Values
Any text string, including spaces and mixed case characters. Active, Inactive False, True Any desired descriptors for the two states.

Default
(hyphen)

Notes
255 characters maximum.

alarmValue alarmValueEnabled position

Read-Write: Defines the digital state that is evaluated as an alarm. Read-Write: Determines if the BI object is configured for alarming. Read-Write: See position, page 5-9. Read-Write: Defines how states display at the statusInput, statusOutput, and presentValue, also how they appear on the objects property sheet. Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows the current boolean state and status of the statusInhibit input. Read Only: Shows the current COS count. Available as a IntegerStatusType output. Read Only: Shows the current runtime (elapsed active time), totaled in seconds. Available as a IntegerStatusType output. Read Only: Shows the current state and status received on the statusInput. Read Only: Shows the current state and status of the statusOutput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

Active False Active, Inactive State descriptors can display at a linked GxText object.

Visual

activeInactiveText active, inactive minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInhibit (input sInh) statusChangeOfState Count (output sCnt) statusElapsedActive Time (output sElpT) statusInput (input sIn) statusOutput (output sOut)

false, true : {status flags} <count> : {status flags} <seconds> : {status flags} Inactive, Active Inactive, Active

false : {ok} 0 : {ok}

Engineering

0 : {ok}

Inactive : {ok} Inactive : {ok} General

Security

securityGroups

General, 7 others

BinaryInput Notes
The BinaryInput (BI) object is typically used to display a binary state received from an integration (shadow) object, offering configurable display text for the two boolean states. In addition, the object provides Niagara alarm capability and the option to expose it as a BACnet Binary Input object. See the following main topics on configuring a BI object: Routinely Configured BI Properties BI Alarming Functions BI Alert Notifications

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

535

Chapter 5 BinaryInput

Control Objects

Routinely Configured BI Properties

Among all properties on a BI objects property sheet, the two most typically configured are: activeInactiveText (Visual tab)Defines the display descriptors used for the objects boolean states (active and inactive). Assigned descriptors appear in linked GxText objects and in the accumulated data of a linked BinaryLog. defaultInput (Config tab)Defines the statusOutput state produced whenever a fault is received on the statusInput. A fault may originate from the output of a shadow object, for example.

If alarming functions and/or alerts are needed, additional Alarm Setup properties are configured from default values.

BI Alarming Functions

Any BI object can be configured for alarm indication, and optionally, event (alarm) notification. The object provides properties to define the alarm state, alarm delay, and event notifications, using BACnet-type properties. The BI object can also generate alerts based on configurable limits for runtime (elapsed active time) and change-of-state transitions. See BI Alert Notifications on page 5-39 for more information. The following subtopics apply to BI alarming: BI Alarm Detection BI Alarm Notification BI Alarm Inhibit BI Alarm Delay

Figure 5-10 BI objects have alarming functions with BACnet-type properties.

notificationClass, eventEnable, and notifyType apply to alarm notification. inhibitTime and eventTriggerEnable are Niagara-only properties. See BI Alarm Inhibit.

Alert properties define alert notification, which includes change-of-state alerts and runtime (activeTime) alerts.

These two properties (listed at the bottom of the Alarm Setup tab) define alarm detection.

536

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects BinaryInput

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: alarmValueState at which the BI is considered offnormal (inAlarm), providing that the alarmValueEnabled property is set to True. The object shape and its statusOutput are red during this state. alarmValueEnabledDetermines if the BI is capable of an alarm condition. The default is False (no alarming capability). timeDelayOptional 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-mail addresses, and APIs. If the BI object is exposed as a BACnet object, BACnetRecipients can also be designated. 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: notificationClassMust match an existing notificationClass object in the stations notificationServices container. The default class is zero (0). eventEnableFlags 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. notifyTypeEither 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 clients GetAlarmSummary request, the station reports BACnet-exposed objects currently in alarm only if their notifyType properties are set to alarm.

Note

alarmTextText descriptor sent as an alarm record field whenever a to-offnormal or to-fault event transition occurs (not a to-normal).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

537

Chapter 5 BinaryInput

Control Objects

BI 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. Whenever the statusInhibit input is linked, the objects inhibitTime property should hold 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.
Upon a false-to-true (active) transition, the objects inhibitTime period becomes effective. Until this period expires, the object remains inhibited from any alarm status change. inhibitTime = 00:00:30 (30 seconds)

Note

Whenever a logic false (inactive) is at the statusInhibit (sInh) input, the BI object cannot change status to (or from) an alarm condition.

After the inhibitTime period expires, the object is capable of changing alarm status to (or from) alarm.

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 handler has been running at least 30 seconds, as defined in the objects 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 objects 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.

538

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects BinaryInput

BI Alert Notifications

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 Properties for Both Alert Types

Alarm Setup properties that apply to both types of BI alerts (runtime and COS) are: alertNotificationClassMust match a notificationClass object in the notificationServices container. The default is 0, the same default for alarms. periodicAlertsDetermines 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. alertTextAny 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 BIs statusInput increments the objects COS counter by 1. Assuming the objects 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. The total 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 objects resetChangeOfStateCountTrigger input, if needed. Properties on the Alarm Setup tab that apply to COS alerts include:

changeOfStateAlertLimitInteger 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 integerStatusType data species).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

539

Chapter 5 BinaryInput

Control Objects

Runtime is resettable (to 0) for any JDE user with Admin-level command rights. Runtime can also be reset using a Command object linked to the objects resetElapsedActiveTimeTrigger input, if needed. Properties on the Alarm Setup tab that apply to runtime alerts include:

activeTimeAlertLimitAmount 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-12

Figure 5-30 shows several examples of BinaryInput objects in use.

BinaryInput usage examples.

The two BI objects at right are used to format the received boolean values true/false to more recognizable states, e.g: On/Off and Dirty/Clean. The BI for the AHU filter is configured for alarming, including an alarm inhibit. These BI objects at right are also used to format true/false to more recognizable states, e.g: Frost/No Frost and Flow/No Flow. Both BI objects were assigned a polarity of reverse (and at the same time), had descriptors for activeInactiveText flipped. This was done to invert the output states for use in downstream logic, not shown here. BI objects are sometimes used to capture the logic results of other control objects, such as Logic and Comparison objects. Unlike these other objects, a BI object can be configured to alarm. It can also be exposed as a BACnet object.

By default, a linked GxText object shows the BIs activeInactiveText text strings.

This BI provides alarm capability. The alarmValue is inactive, or Frost, due to the assigned reverse polarity (output is NOT the input).

This BI object represents the logic results of a number of Logic objects. Its main purpose is for alarming capability. In this case, it provides a preheat-coil pump alarm.

540

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects BinaryOutput

BinaryOutput
Quick reference for all properties: Table A-11 Inputs
priorityArray statusInput

Default Object Shape

Outputs
statusOutput prioritizedOutput

abbrev: BO BinaryOutput (BO) objects provide a prioritized digital output signal to other control logic. Typically, BOs provide on/off control of a digital device. The BO object collects runtime (elapsed active time) and counts COS (changes-of-state). Based upon configurable limits, the object can be set to generate alerts for both runtime levels and COS counts. Trigger inputs allow the clearing of the COS count and the runtime value. Trigger outputs are available for each COS, COS alert, runtime alert, and event. As with Niagara AI, AO, and BI objects, you can expose any BO object in the database as a BACnet object.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs Outputs
eventTrigger statusCOSCount* executeTrigger statusInhibit resetCOSCountTrigger* resetElpActTimeTrigger* priorityArray statusInput statusElpActTime* COSTrigger* COSAlertTrigger* ElpActAlertTrigger* presentValue statusOutput prioritizedOutput *abbreviations, see chart below statusFeedbackOutput *abbreviations, see chart below

Input / Output Property Reference for BO Object

(only input and output types, see Table 5-10 for all properties)

container).
Resource Count Range: 91 to 155 Note: Upon any link change (add or delete
input

Type Label
exe sInh resetCt resetElp pIn sIn eventTr sCnt sCnt cosT cosAlrt elActAlr present sOut pOut sFbOut

Property Name
executeTrigger statusInhibit resetChangeOfStateCountTrigger resetElapsedActiveTimeTrigger priorityArray statusInput eventTrigger statusChangeOfStateCount statusElapsedActiveTime changeOfStateTrigger changeOfStateAlertTrigger elapsedActiveTimeAlertTrigger presentValue statusOutput prioritizedOutput statusFeedbackOutput

Data Species
TriggerType BooleanStatusType TriggerType TriggerType BooleanPriorityArrayType FloatStatusType TriggerType IntegerStatusType IntegerStatusType TriggerType TriggerType TriggerType boolean BooleanStatusType BooleanPriorityType BooleanStatusType

any link) to a BO object, commands at priority-slots (1-16) that were received from priorityArray links are momentarily cleared. The priorityArray input is now immediately rescanned; any input command found remains effective at the output. This is an improvement over previous releases, where a link change might produce an output cycle until a linked Schedule output updated.
Trigger Properties

output

The BO object has the standard input property, executeTrigger, (typically not used) and also 2 other trigger-type inputs: resetChangeOfStateCountTriggerAny received trigger pulse clears the objects current count of COS (changes of states), resetting it to zero (0). resetElapsedActiveTimeTriggerAny received trigger pulse clears the objects accumulated runtime (elapsed active time), resetting it to zero (0.0). In addition, there are 4 available trigger-type outputs, described as follows:

eventTriggerFires upon each event transition (to-offnormal, to-fault, to-normal) that has been specified in the property eventTriggerEnable.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

541

Chapter 5 BinaryOutput

Control Objects

changeOfStateTriggerFires upon each change-of-state at the statusOutput. changeOfStateAlertTriggerFires 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). elapsedActiveTimeAlertTriggerFires each time a runtime alert is issued (activeTimeAlertLimit value has been reached, or a multiple of this value if periodicAlerts is set to True). As needed, these trigger-type inputs and outputs can be linked to other objects that have properties using TriggerType data species.

Commands
The BO object provides a right-click command menu with these commands (default command names are shown, these are modifiable using the commandTags property):

ActiveTo set an active output at the Manual level (8). Requires Command, Std privileges. InactiveTo set an inactive value at the Manual level (8). Requires Command, Std privileges. AutoTo clear any active or inactive output at the Manual level (8). EmergencyActiveTo set an active output at the Emergency level (1). Requires Command, Emer privileges. EmergencyInactiveTo set an inactive output at the Emergency level (1). Requires Command, Emer privileges. EmergencyAutoTo clear any active or inactive output at the Emergency level (1). Requires Command, Emer privileges.

For a JDE user with Command, Admin privileges, the following object commands are available from the menu bar (for example, Command > resetActiveTime):

resetAckedTransitionsSets all three flags in the ackedTransitions property (to-offnormal, to-fault, to-normal). Rarely required, see the the JDE Command section on page 5-11 for more information. resetChangeOfStateCountThis sets the changeOfStateCount property value to zero (0), clearing the COS count. resetActiveTimeThis sets the elapsedActiveTime property value to 00:00:00 (Hr:Min:Sec), clearing the accumulated runtime. setChangeOfStateAlertLimitAllows editing of the changeOfStateAlertLimit property value (Alarm Setup property). setRuntimeAlertLimitAllows editing of the activeTimeAlertLimit property value (Alarm Setup property).

542

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects BinaryOutput

Properties
Table 5-10 BinaryOutput (BO) object properties.

Tab Property Name

objectType, statusFlags, description eventState, reliability, outOfService, ackedTransitions toOffnormal, toFault, toNormal, presentValue Status changeOfStateTime changeOfStateCount

Description
See Table 5-3 on page 5-8 for information on these properties common to all control objects. See Table 5-4 on page 5-12 for information on these properties common to all event-type control objects.

Valid Values

Default Notes

<cmd state> or auto, levels 1 to 16

auto 1 to 16

presentValue is always read-only.

Read Only: Shows a date/timestamp for the last COS (change of state). Read Only: Shows the total number of changes of state that have occurred since the last COS count reset (clear). Read Only: Shows a date/timestamp for when the COS count was last cleared. Read Only: Shows accumulated runtime (elapsed active time) in Hr:Min:Sec. Read Only: Shows a date/timestamp for when the accumulated runtime (elapsed active time) was last cleared. Read Only: Shows commands present on each of the 16 priority level slots for the priorityArray (pIn) input. Read-Write: Defines the output state when all 16 priority level slots have an auto. Read Only: Indicates if an interstart delay is currently active (True) or not (False).

valid timestamp or null (none) integer value

null 0

timeOfStateCountReset elapsedActiveTime timeOfActiveReset

valid timestamp or null (none) Time period up to 9999:99:99 valid timestamp or null (none) Active, Inactive, or auto, levels 1 to 16 Active, Inactive False, True

null 00:00:00 null

priorityArray (input: pIn) Priorities relinquishDefault inInterstartDelay executeParameters foreignAddress

auto 1 to 16 Inactive False normal, output -1 Must be a unique number among all BinaryOutput objects in station.

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: BACnet usage only. Set to a positive integer for this object to appear as a BACnet BinaryOutput object to other BACnet devices. See foreignAddress, page 5-9, for more information. Read-Write: (Future use only.) Read-Write: Determines if the same boolean state at the statusInput is reflected at the statusOutput (normal), or if the output remains opposite from the input (reverse). Read-Write: Upon a command from inactive to active, results in an active command stored at the Minimum On Off priority level (6) for this time (Hr:Min:Sec). 0 to 4194302 or -1 (not exposed)

Config

membershipGroups polarity

niagaraR2 normal, reverse

niagaraR2 Leave at default. normal

minimumOnTime

Any practical time needed.

00:00:00

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

543

Chapter 5 BinaryOutput

Control Objects

Table 5-10

BinaryOutput (BO) object properties. (continued)

Tab Property Name

minimumOffTime

Description
Read-Write: Upon a command from active to inactive, results in an inactive command stored at the Minimum On Off priority level (6) for this duration (Hr:Min:Sec). Read-Write: Determines whether the output is automatically restarted following a station restart (reboot) or power failure. If set to True, an inactive at manual level (8) is issued following such an occurrence. Read-Write: Defines the time period the output is held inactive following an active command. Used to prevent multiple simultaneous starts. Applies to commands at all priority levels except Emergency (1). See Table 5-5 on page 5-13 for information on these properties common to all event-type control objects.

Valid Values
Any practical time needed.

Default Notes
00:00:00

Config, cont.

restartDisable

False, True

False

interstartDelayTime

Any practical time needed.

00:00:00

Applied also following a station restart.

timeDelay, notificationClass, eventEnable, notifyType, inhibitTime*, eventTriggerEnable, alarmText inhibitTime

* See specific details on inhibitTime, the next property.

Read-Write: Duration (Hr:Min:Sec) of the alarm inhibit timer, which applies only if the objects input statusInhibit is linked. The purpose is to prevent nuisance alarms on equipment startup and shutdown. The inhibitTime is triggered by a transition at the statusInhibit input.

any practical value in Hr:Min:Sec

00:00:00 A minimum value of (no inhibit) 1 second (00:00:01) is recommended whenever the statusInhibit input is linked. Alarm processing compares the statusInput (feedback) value to the priorityArray (command) value.

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. changeOfStateAlertLimit activeTimeAlertLimit Read-Write: Number of COS occurrences that generate a changeOfStateCount alert. Read-Write: Amount of runtime (elapsed active time), in Hr:Min:Sec, that generates a runtime alert. Read-Write: The assigned notification class number, used in routing alerts. A NotificationClass object using the same number should exist in the NotificationService objects container. periodicAlerts Read-Write: Determines if both COS count alerts and runtime alerts are periodically generated each time the respective limit is reached. False, True False Positive integer Any value up to 9999:59:99 (Hr:Min:Sec) 0 to 8388607 0 0 00:00:00 Alarm Setup alertNotificationClass

544

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects BinaryOutput

Table 5-10

BinaryOutput (BO) object properties. (continued)

Tab Property Name

Alarm Setup, cont. alertText

Description
Read-Write: Text descriptor included in either a COS count alert or runtime alert. If left at the default hyphen (-), the Station objects alertText is used.

Valid Values
Any text string, including spaces and mixed case characters.

Default Notes
(hyphen) 255 characters maximum.

position activeInactiveText active, inactive commandTags Visual

Read-Write: See position, page 5-9. Read-Write: Defines the displayed states at the statusInput, statusOutput, and presentValue, and also how they appear on the objects property sheet. Read-Write: Defines the labels used to list commands that appear on the right-click command menu. Default text values for commandTags are:

Any desired descriptors for the two states. Any desired text string, including spaces and numerals.

Active, Inactive States can display at a linked GxText object. If a tag is blank (no characters), the command is not available on the command menu.

See descrip.

minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInhibit (input sInh) statusChangeOfState Count (output sCnt) Engineering statusElapsedActive Time (output sElpT) statusInput (input sIn) statusOutput (output sOut) prioritizedOutput (output pOut) statusFeedbackOutput (output sFbOut) Security securityGroups

Active (manualActive) Inactive (manualInactive) Auto (manualAuto) EmergencyActive (emergencyActive) EmergencyInactive (emergencyInactive) EmergencyAuto (emergencyAuto)

Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows the current boolean state and status of the statusInhibit input. Read Only: Shows the current value and status of the COS count. Available as a IntegerStatusType output. Read Only: Shows the current runtime (elapsed active time), totaled in seconds. Available as a IntegerStatusType output. Read Only: Shows the current state and status received on the statusInput. Read Only: Shows the current state and status of the statusOutput. Read Only: Shows the current state and priority level of the prioritizedOutput. Read Only: Shows the current state and status of the feedback value being supplied on the statusInput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

false, true : {status flags} <count> : {status flags} <seconds> : {status flags} Inactive, Active {status flags} Inactive, Active {status flags} Inactive, Active @ <pri. level> Inactive, Active {status flags} General, 7 others

false : {ok} 0 : {ok}

0 : {ok}

Inactive : {ok} Inactive : {ok} Inactive : @ def Inactive : {ok} General

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

545

Chapter 5 BinaryOutput

Control Objects

BinaryOutput Notes
The 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 objects is 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 Evaluated

The 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). 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.

Notes

546

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects BinaryOutput

Routinely Configured BO Properties

The three most typically configured properties for a BO object are: relinquishDefault (Priorities tab)Defines the BO objects 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 the objects 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 objects 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 Related Properties

The BO object includes several Config properties that directly determine the control operation of its main outputs (prioritizedOutput and statusOutput).

polarityThe default is normal. If set to reverse, this flips control such that an inactive at the control (priorityArray) input (or from a right-click command) produces an active at the objects outputs, and vice-versa. Note that the statusInput input, if used (for alarming), is then out-of-phase with control. minimumOnTimeDefines 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. minimumOffTimeDefines 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. restartDisableDetermines 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). interstartDelayTimeDefines 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 Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

547

Chapter 5 BinaryOutput

Control Objects

BO Command Tags

It is typical for BO objects to be configured with custom command labels, using the commandTags property, located on the Visual tab of the objects 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.

Figure 5-13

The commandTags property (Visual tab) determines how (and which) commands are listed.

BO Alarming Functions

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

548

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects BinaryOutput

Typically, another input is linked as well: statusInhibit (sInh), coming from the controlling source. See the BO Alarm Inhibit section on page 5-50.
Figure 5-14 BinaryOutput alarming.

Assuming normal polarity, a BO alarm condition is when the control command is not the same as the state at the statusInput input (feedback).

An alarm condition can occur at both active and inactive control states.

BO alarm condition occurs when statusInput (sIn) differs from control/command state. Feedback signal linked to statusInput (sIn)

Note

The BO object can also generate alerts based on configurable limits for runtime (elapsed active time) and change-of-state transitions. BO alert functions operate the same as for BinaryInput (BI) objects. See BI Alert Notifications on page 5-39. Figure 5-15 shows the grouping of Alarm Setup properties for a BO object.
Figure 5-15 BO objects have alarming functions with BACnet-type properties.

timeDelay specifies an alarm delay period for any sensed alarm condition. notificationClass, eventEnable, and notifyType apply to alarm notification. inhibitTime and eventTriggerEnable are Niagara-only properties. See BO Alarm Inhibit.

Alert properties define alert notification, which includes change-of-state alerts and runtime (activeTime) alerts.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

549

Chapter 5 BinaryOutput

Control Objects

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. Whenever the statusInhibit input is linked, the objects inhibitTime property should hold a defined value (not the default of 00:00:00 in Hr:Min:Sec).

Note

Figure 5-16

BinaryOutput statusInhibit input and inhibitTime property.

statusInhibit (sInh) link

The statusInhibit input is typically linked to the same source that is controlling the BO (linked to the priorityArray input). When the BO is commanded to active, any alarm status change is inhibited for the specified inhibitTime, in seconds. When commanded to inactive, any alarm status change is inhibited for 3 times the inhibitTime, in seconds. This extended period can be considered wind-down time.

priorityArray input link for control command Feedback signal linked to statusInput (sIn)

Example: inhibitTime = 30 (seconds) When under schedule control, and going from active to inactive (On to Off), the alarm inhibit delay will be 90 seconds.

BO Alarm Delay
Alarm delay is a BACnet-type property, separate from the alarm inhibit mechanism. It means that the objects 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.

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.

550

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects BinaryOutput

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: notificationClassMust match an existing notificationClass object in the stations notificationServices container. The default class is zero (0). eventEnableFlags 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. notifyTypeEither 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 clients GetAlarmSummary request, the station reports BACnet-exposed objects currently in alarm only if their notifyType properties are set to alarm.

alarmTextText 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

Figure 5-17 shows several examples of BinaryOutput objects in use.

BinaryOutput object examples.

The BO objects at right provide commandable access to occupancy modes for an air handler and VAV boxes. Upstream, a Logic object (AND function) provides override-OFF control from pump safeties.

This BO object has its runtime output (sElpT) linked to a Program object written to perform a lead/lag rotation. An output of the Program object clears the BOs runtime when its rotation is selected.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

551

Chapter 5 BinaryOverride

Control Objects

BinaryOverride
Quick reference for all properties: Table A-12 Inputs
(none)

Default Object Shape

Outputs
statusInOverride prioritizedOutput

abbrev: BOvrd A BinaryOverride (BOvrd) object provides a prioritized digital output signal that is controlled from a right-click command menu. Commands include starting a timed-override (either active or inactive) for a specified duration, and canceling an override. The priority level of an override is configurable to any level (from 1 to 16). In addition, text descriptors for the active and inactive states are editable. This allows the right-click command menu to show commands as needed, for example, override On and override Off instead of override Active and override Inactive.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs
executeTrigger overrideTrigger

Outputs
inOverride statusInOverride prioritizedOutput

Input / Output Property Reference

(only input and output types, see Table 5-11 for all properties)

Type
input output

Label
exe override inOverr sInOv pOut

Property Name
executeTrigger overrideTrigger inOverride statusInOverride prioritizedOutput

Data Species
TriggerType TriggerType boolean BooleanStatusType BooleanPriorityType

container).
Resource Count Range: 41 to 55 Trigger Properties

The BOvrd object has the standard input property, executeTrigger, (typically not used) plus an additional trigger-type input: overrideTriggerAny received trigger pulse starts an override, at the configured overrideValue (state), 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 at the configured overrideValue (state), but not to the opposite state. The linked Command object would also not allow a user to cancel an override, or change its duration. An override would be started each time a trigger pulse is received at this input.

Commands
For any user with Command, Std privileges, a BOvrd object has a right-click command menu that provides these commands (default state descriptors shown): override ActiveStart an override to Active, specifying a duration in minutes. override InactiveStart an override to Inactive, specifying a duration in minutes. cancelTo cancel any current override.

552

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects BinaryOverride

Properties
Table 5-11 BinaryOverride (BOvrd) object properties.

Tab Property Name

Status objectType, statusFlags, description inOverride (output: inOverr) executeParameters foreignAddress membershipGroups priorityForWriting

Description
See Table 5-3 on page 5-8 for information on these properties common to all control objects. Read-Only: Indicates if an override is currently in effect (True) or not (False). Available as a linkable output.

Valid Values

Default Notes

False, True

False

boolean data species.

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: Does not apply to this object. Read-Write: (Future use only.) Read-Write: Defines the priority level used at the prioritizedOutput during an override. When the override expires or is canceled, this level is autoed. -1 niagaraR2 Any priority level, from 1 to 16 Any positive integer from 1 up to 32-bit limit.

normal, input -1 Manual Operator (8) 60 If using the objects right-click command menu, this property value is displayed (and can be adjusted) each time an override is issued. Leave at default. niagaraR2 Leave at default.

overrideTime (min)

Read-Write: Defines the duration of an override, in minutes. When an override is commanded, this time is initialized and begins counting down. If not canceled or re-initiated, the override will last this duration. This property is most important when using the input overrideTrigger.

Config

overrideValue

Read-Write: Stores the last given override state (True for active, False for inactive). The override was issued at the level defined in the priorityForWriting property. When the override expires or is canceled, the output state expires (level is autoed).

True, False

False

If using the objects right-click command menu, this override value (state) is selectable. The selected state is stored in this property.

Note: Any pulse received at the overrideTrigger input causes an override at this state: True (active) or False (inactive).
position activeInactiveText active, inactive Read-Write: See position, page 5-9. Read-Write: Defines the override command arguments that appear on the objects right-click command menu. For instance: override On or override Off. Default values are: Any desired text string to describe the override state. See descrip. Blank properties (no characters) result in commands that say simply override. You should use text descriptors that make sense to the system users.

Visual

Active (active), shows as override Active Inactive (inactive) shows as override

Inactive minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInOverride (input sInOv) Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows if an override is active and also the status of the object. Available as a default object output.

Engineering

Inactive, Active {status flags}

Inactive : {ok}

booleanStatusType data species

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

553

Chapter 5 BinaryOverride

Control Objects

Table 5-11

BinaryOverride (BOvrd) object properties. (continued)

Tab Property Name

Security Engineering, cont. prioritizedOutput (input pOut)

Description
Read Only: Shows the state and priority level currently on the prioritizedOutput. Available as a default object output.

Valid Values
Inactive, Active @ <pri. level>

Default Notes
Inactive : @ def booleanPriorityType data species

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

General, 7 others

General

BinaryOverride Notes
There are two basic ways to use an BinaryOverride object: Available directly to userssee Directly Available. Available through a Command objectsee Used with a Command object.

Directly Available The right-click menu for a BinaryOverride object provides the user a list of
commands, providing the ability to: Start an override, either active or inactive, specifying the duration in minutes. Cancel an override.

Changes to the override duration, if any, are stored in the objects overrideTime property. This value becomes the default duration for the next command, and is seen when the commands popup control appears (Figure 5-18). In addition, the last override command (Active or Inactive) is also stored in the objects overrideValue property. Be aware that an override from the overrideTrigger input is always an override to this stored state.
Figure 5-18 An override active or inactive shows the override duration (and allows changing this stored value).

Popup control for right-click override command when using the JDE.

Popup control for right-click override command when using a Web browser.

554

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects BinaryOverride

Used with a Command object

In some scenarios, direct access to an BinaryOverride object may provide too much user control for changing override parameters (duration time or the override state). In this case, linking a Command object to the objects overrideTrigger may be better. In this configuration, a user can be given access to the Command object (but not directly to the BinaryOverride object). This allows the initiation of an override (to the state stored in the overrideValue property) but no other controlincluding canceling an override. The outputTrigger text property of the Command object should be given a descriptive label for the configured override action (Figure 5-19).

Figure 5-19

Control from a linked Command object allows override initiation only.

Command object linked to overrideTrigger input. Popup right-click command to linked Command object, seen from the JDE.

outputTriggerText of Command object.

Popup right-click command to linked Command object, seen from a Web browser.

Other Notes
Figure 5-20

The standard set of library (lib) Program objects includes an object used to derive the remaining override time. Two links are required to the BinaryOverride object.

RemainingOverrideTime object in Local Library (tridiumx/lib/programs/hvac) used with BinaryOverride.

Remaining override time value. Can be linked to a GxText to display to time to users.

Local Library opened with lib JAR expanded to reveal programs folders (hvac). Copy the object (sns file) and paste it into your station as needed.

Copied RemainingOverrideTime object.

Two links are required between the BinaryOverride object and the Program object (RemainingOverrideTime): overrideTime to overrideTime statusInOverride to statusInOverride

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

555

Chapter 5 Command

Control Objects

Command
Quick reference for all properties: Table A-15 Inputs
(none)

Default Object Shape

Outputs
statusInOverride prioritizedOutput

abbrev: Cmd A Command (Cmd) object provides up to 4 separate trigger outputs that are fired from a right-click command menu. Each trigger has an editable label for the associated command. A Cmd object can be linked to other objects with specialized trigger-type inputs to provide specific user commands. Typical examples include the doArchive and doClear trigger inputs on log-type objects. The Cmd object has no linkable input and few internal properties (no config properties). Other trigger-type objects include the DateTimeTrigger and PeriodicTrigger.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs
(none)

Outputs
outputTriggerA outputTriggerB outputTriggerC outputTriggerD

Input / Output Property Reference

(only input and output types, see Table 5-12 for all properties) Type input output Label outA outB outC outD Property Name outputTriggerA outputTriggerB outputTriggerC outputTriggerD Data Species TriggerType TriggerType TriggerType TriggerType

container).
Resource Count Range: 32 to 42

Commands
By default, a newly created Cmd object has no right-click command menu until you enter text values in the properties outputTriggerTextA through D. Each of these properties holds the command label that appears on the pop-up menu. You can use any alphanumeric characters needed, including spaces and mixed case characters. For a user with Command, Std privileges, any non-blank trigger command is available on the right-click command menu. When a menu selection is made, the associated trigger output fires.

Properties
Table 5-12 Command (Cmd) object properties.

Tab Property Name

Status objectType, statusFlags position outputTriggerTextA, Visual outputTriggerTextB, outputTriggerTextC, outputTriggerTextD Security

Description
See Table 5-3 on page 5-8 for information on these common object properties. Read-Write: See position, page 5-9.

Valid Values

Default

Notes

(none)

Read-Write: Defines how (and if) Any desired text commands appear on the objects right-click string to describe command menu. the trigger resulting from the By default, output trigger text properties are command. blank. Until you enter one or more text values, no trigger commands are available. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10 General, 7 others

securityGroups

General

556

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Command

Command Notes
The 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-21

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.

Command object examples.

Command object with 2 available commands.

This Command object is linked to a BO object and provides a menu to clear the BOs COS count and runtime (elapsed active time). Typically, such an object would be assigned only to select security Groups. Command descriptions are configured on the objects property sheet, (Visual tab). Any property left blank does not appear on the objects command menu.

Right-click command menu. Each command results in a trigger pulse from the Command object.

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 objects trigger input that is already linked, say, to a DateTimeTrigger 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.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

557

Chapter 5 Comparison

Control Objects

Comparison
Quick reference for all properties: Table A-16 Inputs
statusInputA statusInputB

Default Object Shape

Outputs
prioritizedOutput statusOutput

abbrev: (reflects function, e.g. A > B) Comparison objects allow you to compare two analog inputs and produce a digital result, both as a status type and a prioritized type output. You can configure a Comparison object to perform one of the following functions:

All Inputs / Outputs

Inputs
executeTrigger statusInputA statusInputB

Outputs
prioritizedOutput statusOutput presentValue

A > B (greater than) A < B (less than) A >= B (greater than or equal to) A <= B (less than or equal to) A = B (equal to) A != B (not equal to)

Property Quick Reference for Comparison Object

(only input and output types, see Table 5-13 for all properties)

Type
input

Label
exe sInA sInB pOut sOut present

Property Name
executeTrigger controlledVariable setpoint prioritizedOutput statusOutput presentValue

Data Species
TriggerType FloatStatusType FloatStatusType BooleanPriorityType BooleanStatusType boolean

The prioritizedOutput level is configurable to any priority level (1 to 16).

Parent Dependencies: None (any

output

container).
Resource Count Range: 48 to 80 Trigger Properties

None, apart from the standard input property, executeTrigger. In certain applications, this input may be used (with executionParameters, frequency, set to on_trigger). None.

Commands Properties
Table 5-13 Comparison object properties.

Tab Property Name

Status objectType, statusFlags, description, presentValue outOfService, reliability executeParameters Config foreignAddress membershipGroups defaultA

Description
See Table 5-3 on page 5-8 for information on these properties common to all control objects. See Table 5-5 on page 5-13 for information on these properties.

Valid Values

Default

Notes
presentValue is always read-only.

normal, processor -1 niagaraR2 0.0 Leave at default. Leave at default.

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: Does not apply to this object. Read-Write: (Future use only.) Read-Write: Acts as a constant value used for statusInputA, when that input is not linked (or if its value has a status fault). -1 niagaraR2 valid float

558

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Comparison

Table 5-13

Comparison object properties. (continued)

Tab Property Name

Config, cont. defaultB

Description
Read-Write: Acts as a constant value used for statusInputB, when that input is not linked (or if its value has a status fault).

Valid Values
valid float

Default
0.0

Notes

function

Read-Write: Defines the comparison function of the object. The selected function shows in the objects shape.

Config, cont.

A>B A<B A >= B A <= B A=B A != B 1 to 16 true, false, auto true, false, auto 0 to 6, (+) sign no (+) sign Any desired descriptors for the two states.

A>B

priorityForWriting trueCommand

Read-Write: Defines the priority level used at the prioritizedOutput. Read-Write: Determines the output state produced upon a true comparison. Auto applies only to the prioritizedOutput. Read-Write: Determines the output state produced upon a false comparison. Auto applies only to the prioritizedOutput. Read-Write: See position, page 5-9. Read-Write: Sets decimal position from 0 to 6 places, and optionally force (+) sign for positive values. Read-Write: Defines the displayed states at the statusOutput and presentValue, and also how they appear on the objects property sheet. Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows the current analog value and status at the statusInputA input. Read Only: Shows the current analog value and status at the statusInputB input. Read Only: Shows the current state and priority level of the prioritizedOutput. Read Only: Shows the current state and status of the statusOutput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

16 (Schedule) auto

falseCommand

auto

position decimalFormat Visual

2, no (+) sign true <active>, false <inactive>

activeInactiveText active, inactive minExecuteTime, maxExecuteTime, averageExecuteTime, userData

States can display at a linked GxText object.

Engineering Security

statusInputA (input sInA) statusInputB (input sInB) prioritizedOutput (output pOut) statusOutput (output sOut) securityGroups

General, 7 others

General

Comparison Notes
The Comparison object performs a simple math comparison on the float values at statusInputA and B, and sets the boolean prioritizedOutput and statusOutput according to its configured function. If an input is not linked, or its received status is in a fault state, the object uses the corresponding defaultA or defaultB config property value.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

559

Chapter 5 Comparison

Control Objects

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.

Boolean outputs to a Logic object

Comparison objects

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). 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.

Note

For this application, these Comparison objects can be left at default Config settings. By linking to the sInA input, any input value over 0.0 (the default sInB value) results in an Active state. The only properties edited from default settings were the Visual activeInactiveText properties. In this case, the active text is simply On and the inactive text is Off.

560

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects CpAnalogNode

CpAnalogNode
Quick reference for all properties: Table A-20 Inputs
cmdLink

Default Object Shape

Outputs
(none)

abbrev: CpAnalog (Found in the tridium JAR, control folder.) A CpAnalogNode object, if linked to an internal property (float data species) of another object, provides a user (right-click) command access to change that property value. This allows a browser user to have write access to a specific internal object property. Otherwise, a user must use the JDE to access the target objects property sheet. The CpAnalogNode also provides a minimum and maximum limit for a user command change to the linked property, as well as an editable command (menu). Typical usage is for user-access to a property such as lowLimit or highLimit (alarm limits) etc. It is one four command property object typesothers are the CpBinaryNode, CpIntegerNode, and CpStringNode.
Parent Dependencies
Type
input output

All Inputs / Outputs

Inputs
executeTrigger cmdLink value

Outputs

Property Quick Reference for CpAnalogNode Object

(only input and output types, see Table 5-14 for all properties)

Label
exe cmdLnk value

Property Name
executeTrigger cmdLink value

Data Species
TriggerType float float

Note: This object is nearly identical to the AnalogCmd object, which is included in the lonworks JAR (conversion folder). However, the CpAnalogNode object is a core (tridium) object, and so can be used in any Niagara station, without regard to module dependecies.

None (any container). Requires Niagara Release 2.3 or later.

Resource Count Range: 34 to 57 Trigger Properties

None, apart from the standard input property, executeTrigger (typically not used).

Commands
By 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
Table 5-14 CpAnalogNode object properties.

Tab Property Name

objectType, statusFlags, description, Status cmdLink (input: cmdLink) value (output: value)

Description
See Table 5-3 on page 5-8 for information on these common object properties. Read-Only: Current (float) value of the linked (target) property, as on the input. Read-Only: Current (float) value of the linked (target) property, as on the output. Link a Gx object to the value output to provide command access from a GxPage.

Valid Values

Default

Notes

valid float valid float

0.0 0.0 At all times equal to the cmdLink value.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

561

Chapter 5 CpAnalogNode

Control Objects

Table 5-14

CpAnalogNode object properties. (continued)

Tab Property Name

executionParameters membershipGroups Config maxValue

Description

Valid Values

Default
normal, processor

Notes

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: (Future use only.) Read-Write: Maximum value a user can command the linked (float) property to. Set to a higher value than the minValue. Read-Write: Minimum value a user can command the linked (float) property to. Set to a lower value than the maxValue. niagaraR2 valid float

niagaraR2 Leave at default. 0.0 Default values are not usable (only 0.0). Max and min limits affect access only from this object (not normal property sheet access).

minValue

valid float

0.0

position commandText Visual

Read-Write: See position, page 5-9. Read-Write: Defines how (and if) the command appears on the objects right-click command menu. By default, this property is blankyou must enter text to provide a user command.

Any desired text string for the command to change a linked prop. 0 to 6, (+) sign, no (+) sign

(none)

decimalFormat

Read-Write: Sets decimal position of the output from 0 to 6 places, and optionally force (+) sign for positive values. See Table 5-3 on page 5-8 for information on these common object properties.

2, no (+) sign

Security Engineering

minExecuteTime, maxExecuteTime, averageExecuteTime, userData securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

General, 7 others

General

CpAnalogNode Notes
The CpAnalogNode 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 the float data species. Among the four Cp (control property) objects, the CpAnalog may be the most useful. A typical application is to expose alarm limits for an AI or Loop object, as shown in Figure 5-24. No range check of a linked (target) property is performed. Therefore, you must set reasonable limits (maxValue, minValue) according to the property you are exposing. Cp objects are intended for occasional use, and should not be added to applications indiscriminately. A change to a property made through a Cp object is recorded by the AuditLogService exactly as if made from a property sheet in the JDE.

Notes

562

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects CpAnalogNode

CpAnalogNode Example

Figure 5-24 shows two CpAnalogNode objects used to expose the high and low alarm limits for an AI object.
Figure 5-24 CpAnalogNode objects used to provide highLimit and lowLimit access.
objectName: HiAlarmLimitRAT maxValue: 85.0 minValue: 75.0 commandText: Change RA temp High Alarm limit decimalFormat, precision: 1 objectName: LoAlarmLimitRAT maxValue: 65.0 minValue: 60.0 commandText: Change RA temp Low Alarm limit decimalFormat, precision: 1 Links shown here between Cp objects and the AI object appear unusual, as there is no output. Conceptually, the cmdLink input functions as an output, however, it is only for user commands from the Cp object (no direct linkage to other control logic).

The top CpAnalogNodes cmdLink input is linked to the highLimit property of the AI object. The second CpAnalogNodes cmdLink input is linked to the lowLimit property of the AI object.

By linking the value output of each CpAnalogNode to a Gx object on a GxPage, the internal property of the linked object can be changed by a browser user (Figure 5-25). Further, changes must be made within the range of the maxValue and minValue, as defined in each respective CpAnalogNode.
Figure 5-25 Browser user can view and modify the internal high and low alarm limits.
Right-click command shows the commandText string. Selecting the command produces an entry box.

In this example, two GxText objects are used to show the high alarm and low alarm limits. Each GxText is linked to a CpAnalogNode object.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

563

Chapter 5 CpBinaryNode

Control Objects

CpBinaryNode
Quick reference for all properties: Table A-21 Inputs
cmdLink

Default Object Shape

Outputs
(none)

abbrev: CpBinary (Found in the tridium JAR, control folder.) A CpBinaryNode object, if linked to an internal property (boolean data species) of another object, provides a user (right-click) command access to change (toggle) that property value. This allows a browser user to have write access to a specific internal object property. Otherwise, a user must use the JDE to access the target objects property sheet. The CpBinaryNode provides state descriptors (activeInactiveText), as well as an editable command (menu). Typical usage is for user-access to a property such as periodicAlerts or stopWhenFull. It is one four command property object typesothers are the CpAnalogNode, CpIntegerNode, and CpStringNode.
Parent Dependencies
Type
input output

All Inputs / Outputs

Inputs
executeTrigger cmdLink value

Outputs

Property Quick Reference for CpBinaryNode Object

(only input and output types, see Table 5-15 for all properties)

Label
exe cmdLnk value

Property Name
executeTrigger cmdLink value

Data Species
TriggerType boolean boolean

Note: This object is nearly identical to the N2BinaryCmd object, previously included in a johnson2 JAR. However, the CpBinaryNode object is a core (tridium) object, and so can be used in any Niagara station, without regard to module dependecies.

None (any container). Requires Niagara Release 2.3 or later.

Resource Count Range: 35 to 51 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
Table 5-15 CpBinaryNode object properties.

Tab Property Name

objectType, statusFlags, description, Status cmdLink (input: cmdLink) value (output: value)

Description
See Table 5-3 on page 5-8 for information on these common object properties. Read-Only: Current (boolean) value of the linked (target) property, as on the input. Read-Only: Current (boolean) value of the linked (target) property, as on the output. Link a Gx object to the value output to provide command access from a GxPage.

Valid Values

Default

Notes

Inactive, Active Inactive, Active

Inactive Inactive At all times equal to the cmdLink value. Displays using the activeInactiveText descriptors.

564

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects CpBinaryNode

Table 5-15

CpBinaryNode object properties. (continued)

Tab Property Name

Config executionParameters membershipGroups position commandText

Description

Valid Values

Default
normal, processor

Notes

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: (Future use only.) Read-Write: See position, page 5-9. Read-Write: Defines how (and if) the command appears on the objects right-click command menu. By default, this property is blankyou must enter text to provide a user command. niagaraR2 Any desired text string for the command to change a linked prop. Any desired descriptors for the two states.

niagaraR2 Leave at default. (none)

Visual

activeInactiveText

Read-Write: Defines how the linked propertys value displays (value output).

Active, Inactive

State descriptors can display at a linked GxText object.

Note: A browser user sees only false and true in the command selection box (pop-up from the objects right-click command menu, see Figure 5-26 below).
Security Engineering minExecuteTime, maxExecuteTime, averageExecuteTime, userData securityGroups See Table 5-3 on page 5-8 for information on these common object properties.

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

General, 7 others

General

CpBinaryNode Notes
The 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
objectName: PeriodicAlertsSF (linked to BOs periodicAlerts) commandText: Periodic Alerts? activeInactiveText: active:Yes inactive:No

Figure 5-26 shows a CpBinaryNode object used to toggle periodicAlerts for a BO.
CpBinaryNode object used to expose periodicAlerts for a BinaryOutput object.
value output is linked to a GxText object.

Note that the drop-down control in the popup command box always lists true and false.

See the CpAnalogNode Example, page 5-63, for another Cp object application.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

565

Chapter 5 CpIntegerNode

Control Objects

CpIntegerNode
Quick reference for all properties: Table A-22 Inputs
cmdLink

Default Object Shape

Outputs
(none)

abbrev: CpInteger (Found in the tridium JAR, control folder.) A CpIntegerNode object, if linked to an internal property (int data species) of another object, provides user (right-click) command access to change that property value. This allows a browser user to have write access to a specific internal object property. Otherwise, a user must use typically use the JDE to access the target objects property sheet. The CpIntegerNode also provides a minimum and maximum limit for a user command change to the linked property, as well as an editable command (menu). Typical usage is for access to integer values such as changeOfStateAlertLimit, or (log) interval etc. It is one four command property object typesothers are the CpAnalogNode, CpBinaryNode, and CpStringNode.
Parent Dependencies
Type
input output

All Inputs / Outputs

Inputs
executeTrigger cmdLink value

Outputs

Property Quick Reference for CpIntegerNode Object

(only input and output types, see Table 5-16 for all properties)

Label
exe cmdLnk value

Property Name
executeTrigger cmdLink value

Data Species
TriggerType int int

Note: This object is nearly identical to the N2IntegerCmd object, previously included in a johnsonn2 JAR. However, the CpIntegerNode object is a core (tridium) object, and so can be used in any Niagara station, without regard to module dependecies.

None (any container). Requires Niagara Release 2.3 or later.

Resource Count Range: 35 to 51 Trigger Properties

None, apart from the standard input property, executeTrigger (typically not used).

Commands
By 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
Table 5-16 CpIntegerNode object properties.

Tab Property Name

objectType, statusFlags, description, Status cmdLink (input: cmdLink) value (output: value)

Description
See Table 5-3 on page 5-8 for information on these common object properties. Read-Only: Current (integer) value of the linked (target) property, as on the input. Read-Only: Current (integer) value of the linked (target) property, as on the output. Link a Gx object to the value output to provide command access from a GxPage.

Valid Values

Default

Notes

valid integer valid integer

0 0 At all times equal to the cmdLink value.

566

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects CpIntegerNode

Table 5-16

CpIntegerNode object properties. (continued)

Tab Property Name

executionParameters membershipGroups Config maxValue

Description

Valid Values

Default
normal, processor

Notes

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: (Future use only.) Read-Write: Maximum value a user can command the linked (integer) property to. Set to a higher value than the minValue. Read-Write: Minimum value a user can command the linked (integer) property to. Set to a lower value than the maxValue. niagaraR2 valid float

niagaraR2 Leave at default. 0 Default values are not usable (only 0). Max and min limits affect access only from this object (not normal property sheet access).

minValue

valid float

position Visual commandText

Read-Write: See position, page 5-9. Read-Write: Defines how (and if) the command appears on the objects right-click command menu. By default, this property is blankyou must enter text to provide a user command.

Any desired text string for the command to change a linked prop.

(none)

Security Engineering

minExecuteTime, maxExecuteTime, averageExecuteTime, userData securityGroups

See Table 5-3 on page 5-8 for information on these common object properties.

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

General, 7 others

General

CpIntegerNode Notes
The CpIntegerNode 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 the int (integer) data species.
Note

No range check of a linked (target) property is performed. Therefore, you must set reasonable limits (maxValue, minValue) according to the exposed property. Figure 5-27 shows a CpIntegerNode that exposes a BOs changeOfStateAlertLimit.

Example
Figure 5-27

CpIntegerNode used to expose changeOfStateAlertLimit property for a BinaryOutput object.

value output is linked to a GxText object. Right-click command shows the commandText.

objectName: COSlimitSF (linked to BOs changeOfStateAlertLimit) maxValue: 200 minValue: 50 commandText: Change COS Limit

Selecting the command produces an entry box. A user can review/modify the changeOfStateAlertLimit in the target BO.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

567

Chapter 5 CpStringNode

Control Objects

CpStringNode
Quick reference for all properties: Table A-23 Inputs
cmdLink

Default Object Shape

Outputs
(none)

abbrev: CpString (Found in the tridium JAR, control folder.) A CpStringNode object, if linked to an internal text property (string type) of another object, provides user (right-click) command access to change that propertys text value. This allows a browser user to have write access to a specific internal object property. Otherwise, a user must use typically use the JDE to access the target objects property sheet. The CpStringNode also provides an editable command (menu). It can provide user access to properties such as description, alarmText, or other string types. It is one four command property object typesothers are the CpAnalogNode, CpBinaryNode, and CpIntegerNode.
Parent Dependencies

All Inputs / Outputs

Inputs
executeTrigger cmdLink value

Outputs

Property Quick Reference for CpStringNode Object

(only input and output types, see Table 5-17 for all properties)

Type
input output

Label
exe cmdLnk value

Property Name
executeTrigger cmdLink value

Data Species
TriggerType string string

Note: This object is new to Niagara release 2.3.5. Unlike the other Cp objects, it is not available in r2.3 or r2.3.4.

None (any container). Requires Niagara Release 2.3.5 or later.

Resource Count Range: 35 to 51 Trigger Properties

None, apart from the standard input property, executeTrigger (typically not used).

Commands
By default, a newly-created CpStringNode 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 objects right-click menu.

Properties
Table 5-17 CpStringNode object properties.

Tab Property Name

objectType, statusFlags, description, Status cmdLink (input: cmdLink) value (output: value)

Description
See Table 5-3 on page 5-8 for information on these common object properties. Read-Only: Current (string) value of the linked (target) property, as on the input. Read-Only: Current (string) value of the linked (target) property, as on the output. Link a Gx object to the value output to provide command access from a GxPage.

Valid Values

Default

Notes

valid string valid string

0 0 At all times equal to the cmdLink value.

Config

executionParameters membershipGroups

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: (Future use only.) niagaraR2

normal, processor niagaraR2 Leave at default.

568

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects CpStringNode

Table 5-17

CpStringNode object properties. (continued)

Tab Property Name

position Visual commandText

Description
Read-Write: See position, page 5-9. Read-Write: Defines how (and if) the command appears on the objects right-click command menu. By default, this property is blankyou must enter text to provide a user command.

Valid Values
Any desired text string for the command to change a linked prop.

Default
(none)

Notes

Security Engineering

minExecuteTime, maxExecuteTime, averageExecuteTime, userData securityGroups

See Table 5-3 on page 5-8 for information on these common object properties.

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

General, 7 others

General

CpStringNode Notes
The CpStringNode 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 the string data species. String-type properties typically allow any combination of printable characters, including spaces, mixed case characters, and numerals. However, when using a browser connection, please note that any entered string with a plus sign (+) or semicolon (;) is not accepted. Instead, the edit dialog remains open, and an error message explaining the invalid characters appears in the status bar of the browser. Figure 5-28 shows a CpStringNode that exposes a BOs alertText.
CpStringNode used to expose alertText property for a BinaryOutput object.
value output is linked to a GxText object.

Note

Example
Figure 5-28

Object Name: AlertTextMod (linked to BOs alertText property) commandText: Change Alert Text

Right-click command shows the commandText in the CpString.

Selecting the command produces an entry box. A user can review/modify the alertText in the target BO.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

569

Chapter 5 DateTimeTrigger

Control Objects

DateTimeTrigger
Quick reference for all properties: Table A-25 Inputs
(none)

Default Object Shape

Outputs
(none)

abbrev: (Dtrig) DateTimeTrigger (Dtrig) objects are one of several trigger-type objects. The Dtrig object provides a single trigger output that can be configured to fire based on date and time. Configuration allows for a specific day (one time), date range, or other combinations including day of week and daily. Other trigger-type objects include the PeriodicTrigger and Command objects.
Type

All Inputs / Outputs

Inputs
executeTrigger

Outputs
timeTrigger

Property Quick Reference for Comparison Object

(only input and output types, see Table 5-18 for all properties)

Label
exe timeTrig

Property Name
executeTrigger timeTrigger

Data Species
TriggerType BooleanPriorityType

Parent Dependencies: None (any

container).
Resource Count Range: 38 to 50 Trigger Properties

input output

The Dtrig object has the standard input property, executeTrigger, (never used) plus an additional trigger-type output: timeTriggerThe whole purpose of this object. Fires once each day as defined in the objects Config properties. The purpose of this object is to link this output to other objects trigger-type inputs, as needed, to perform a daily function at a particular time.

Commands
For a JDE user with Command, Admin privileges, this menu bar command is available (with the objects property sheet displayed):

Commands > clearThis clears the objects trigger buffer, allowing it to trigger again (on that same day). Typically, this is not necessary unless you are changing the triggerTime after it has already triggered for the day, and you need it to trigger again.

Properties
Table 5-18 DateTimeTrigger properties.

Tab Property Name

objectType, statusFlags, description executionParameters Config foreignAddress membershipGroups Status

Description
See Table 5-3 on page 5-8 for information on these common object properties.

Valid Values

Default

Notes

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: Does not apply to this object. Read-Write: (Future use only.) -1 niagaraR2

normal, processor -1 Leave at default. niagaraR2 Leave at default.

570

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects DateTimeTrigger

Table 5-18

DateTimeTrigger properties. (continued)

Tab Property Name

triggerDay

Description
Read-Write: Defines the day or days the trigger output fires, at the configured trigger time (next property). Three basic selections are:

Valid Values
Any selectable combination.

Default
Date (current)

Notes
For any field or drop-down list in the JDE property sheet, the asterisk (*) functions as a wildcard (matches any and all entries).

Config, cont.

Dateto select a single date. Date Rangeto select a range of

consecutive days.

Week & Dayto select a combination of:

Month, any (or all months) Week, any (or all weeks/last 7 days) Day of week (or all days of week).
triggerTime Read-Write: Defines the time of day the trigger output fires. Read-Write: See position, page 5-9. 12:00 AM to 11:59 PM

Visual

position

Engineering

minExecuteTime, maxExecuteTime, averageExecuteTime, userData lastTrigger securityGroups

Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows the date of the last trigger fire. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

Day Mo Yr General, 7 others

(current) General

DateTimeTrigger Notes
As needed, this object can be used to programatically fire a trigger-type input on any other object. Figure 5-29 shows the object used to clear a Totalizer object total value.
Figure 5-29 DateTimeTrigger object used to reset the Total on the 1st day of each month.

Security

DateTimeTrigger object configured as: triggerDay = 1-***-**** triggerTime = 0:00

On the midnight of the first day of each month, the DateTimeTrigger object fires, which resets the Totalizer objects accumulated total value.

Linked to the resetTotal input of a Totalizer object.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

571

Chapter 5 FunctionGenerator

Control Objects

FunctionGenerator
Quick reference for all properties: Table A-27 Inputs
(none)

Default Object Shape

Outputs
prioritizedOutput statusOutput

abbrev: Func FunctionGenerator (Func) objects are commonly used to test control logic and/or provide simulated values in the station. The object generates a varying analog value that is output on two outputs; a status type and a prioritized type. By linking the outputs to inputs of other control objects, results of a control logic application can be observed in real-time. Configuration provides two basic output modes, sine wave or ramp. Other properties are available to adjust the rate of value change and minimum and maximum values.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs Outputs
presentValue executeTrigger prioritizedOutput statusOutput

Property Quick Reference for FunctionGenerator Object

(only input and output types, see Table 5-19 for all properties)

Type
input output

Label
exe present pOut sOut

Property Name
executeTrigger presentValue prioritizedOutput statusOutput

Data Species
TriggerType float FloatPriorityType FloatStatusType

container).
Resource Count Range: 50 to 72 Trigger Properties

None, apart from the standard input property, executeTrigger (typically not used).

Commands
None.

Properties
Table 5-19 FunctionGenerator (Func) object properties.

Tab Property Name

objectType, statusFlags, description, presentValue executeParameters Status

Description
See Table 5-3 on page 5-8 for information on these common object properties.

Valid Values

Default

Notes
presentValue is always read-only.

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. If needed, you can change the objects execution frequency to change its output cycle rate. When using default settings in the ControlEngineService, these settings are relative to a normal frequency:

Config

freq: never slower normal faster fastest minutely on_trigger order: input processor output -1 niagaraR2

normal, processor

To suspend (freeze) changes to the output, set the execution frequency to never.

fasterTwice the frequency fastestFour times the frequency slowerHalf the frequency
foreignAddress membershipGroups Read-Write: Does not apply to this object. Read-Write: (Future use only.)

-1 niagaraR2

Leave at default. Leave at default.

572

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects FunctionGenerator

Table 5-19

FunctionGenerator (Func) object properties. (continued)

Tab Property Name

minValue maxValue increment

Description
Read-Write: Minimum value that can appear at the object outputs. Read-Write: Maximum value that can appear at the object outputs. Read-Write: Depending on mode, this value functions as follows:

Valid Values
valid float valid float valid float

Default
-10.0 10.0 1.0

Notes
If mode=sinusoidal, internally calculated values are clipped between these two. In sinusoid mode, for an output that varies from 0 to 100, use an increment value of 50 and an offset value of 50. See examples.

Ramp mode: Step value for each output

change, either added (when ramping up) or subtracted (when ramping down). Sinusoid: The output throttling range used above and below the offset value. mode Read-Write: Defines operation as either: ramp, sinusoid sinusoid

RampLinear sawtooth output. SinusoidSine wave output.

offset Config, cont. Read-Write: Applies to sinusoid mode only (ignored in ramp mode). Defines the midpoint of the internally calculated sine wave. degreesPerCycle Read-Write: Applies to sinusoid mode only (ignored in ramp mode). Defines the number of degrees () of the sine waves period covered in each execution cycle (output change). Affects the time base of the output, where: 360/<value> = number of output changes For example, if degreesPerCycle is 3, there are 120 output changes for a complete cycle (period) of the sine wave. If the object executes once every 2 seconds, the sine wave period is 120 x 2 sec. = 240 sec (4 minutes). In this case, if degreesPerCycle is set to 9, the period changes to 80 seconds. priorityForWriting units Read-Write: Defines the priority level used at the prioritizedOutput. Read-Write: Selection of engineering units for display purposes. Choose from a logical grouping, then a specific unit. For selections see About Units, page 5-6. position Visual decimalFormat Read-Write: See position, page 5-9. Read-Write: Sets decimal position from 0 to 6 places, and optionally force (+) sign for positive values. These properties are common to all control objects. For more information, see Table 5-3 on page 5-8. 0 to 6, (+) sign no (+) sign 2, no (+) sign 1 to 16 Select any (BACnet-type unit choices) 16 (Schedule) Other, no_units integer value, typically from 1 to 12 1 valid float 0.0 The increment property value is applied above and below this midpoint. A value of 1 makes the smoothest (and slowest) sine wave. A value of 0 freezes the output at midpoint. See also the the Sinusoid Mode section on page 5-74.

Engineering

minExecuteTime, maxExecuteTime, averageExecuteTime, userData

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

573

Chapter 5 FunctionGenerator

Control Objects

Table 5-19

FunctionGenerator (Func) object properties. (continued)

Tab Property Name

Security Engineering, cont. prioritizedOutput (output pOut) statusOutput (input sIn)

Description
Read Only: The current calculated float value, at the priority level specified in priorityForWriting. Read Only: The current calculated float value and status.

Valid Values
<f. value> @ <pri. level> <f. value> {status flags}

Default
<f. value> @ 16 <value> {ok}

Notes

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

General, 7 others

General

FunctionGenerator Notes
The 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 objects 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: incrementDefines the magnitude above (and below) the midpoint. For example, if you want a total output swing of 8.5, set increment to 4.25. offsetDefines the midpoint output value. degreesPerCycleAn 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:

degreesPerCycle

= =

360 period

1 period 1 min.

x
720 60

1 min. 60 sec.

x exec. cycle =
12

2 sec.

degreesPerCycle

360 x 1 x 1 x 2 1 x 1 x 60 x 1

12 exec. cycle

Note that the objects 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 objects 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. incrementDefines the output step change. This value is added to the output when ramping up and subtracted from the output when ramping down. minValue and maxValueDefines the smallest and largest values for the continuous ramp output. In addition, the objects execution frequency directly affects the output rate.

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

574

Chapter 5

Control Objects FunctionGenerator

Examples
Figure 5-30

Figure 5-30 shows three sinusoid examples and two ramp examples, connected to a GxTimePlot object configured to show values from -10 to 110 in a 2-minute span.

FunctionGenerator examples.

This FunctionGenerator is set up with these values: freq = normal (2 sec) minValue = 0.0 maxValue = 100.0 increment = 50.0 mode = sinusoid offset = 50.0 degreesPerCycle = 6 This FunctionGenerator is set up with these values: freq = normal (2 sec) minValue = 0.0 maxValue = 100.0 increment = 50.0 mode = sinusoid offset = 50.0 degreesPerCycle = 2
The period is now 360 sec (6 minutes). The only change from the first example is a smaller degreesPerCycle.

1 period = 120 sec

This FunctionGenerator is set up with these values: freq = fastest (500 ms) minValue = 20.0 maxValue = 95.0 increment = 50.0 mode = sinusoid offset = 50.0 degreesPerCycle = 6 This FunctionGenerator is set up with these values: freq = normal (2 sec) minValue = 0.0 maxValue = 100.0 increment = 3.0 mode = ramp offset = <dont care> degreesPerCycle = <dont care> This FunctionGenerator is set up with these values: freq = fastest (500 ms) minValue = 20.0 maxValue = 95.0 increment = 3.0 mode = ramp offset = <dont care> degreesPerCycle = <dont care>

95.0

The minValue and maxValue settings were changed, causing the output to be clipped.

20.0

This is equivalent to the first example, but in a ramp mode configuration.

Execution frequency = fastest, minValue and maxValue rescaled.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

575

Chapter 5 IntToFloat

Control Objects

IntToFloat
Quick reference for all properties: Table A-41 Inputs
statusInput

Default Object Shape

Outputs
statusOutput

abbrev: ItoF Integer to Float objects (ItoF) convert an integer value to a floating point status value. This object is used between the output of an object that produces integer values (out) and an input of an object that accepts only floating point values (in). The IntToFloat is the only conversion-type object included in the collection of standard control objects. However, other conversion type objects are included as tridiumx jar file, mainly in subfolders under the lib/programs folder. In addition, a custom conversion object can be easily created using a standard Program object.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs
executeTrigger statusInput

Outputs
statusOutput

Property Quick Reference for IntToFloat Object (only input and output types, see Table 5-20 for all properties)
Type input output Label exe sIn sOut Property Name executeTrigger statusInput statusOutput Data Species TriggerType IntegerStatusType FloatStatusType

container).
Resource Count Range: 35 to 51 Trigger Properties

None, apart from the standard input property, executeTrigger (typically not used).

Commands
None.

Properties
Table 5-20 IntToFloat (ItoF) object properties.

Tab Property Name

objectType, statusFlags, description, executionParameters foreignAddress Config membershipGroups defaultIntValue Status

Description
See Table 5-3 on page 5-8 for information on these common object properties.

Valid Values

Default

Notes

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: Does not apply to this object. Read-Write: (Future use only.) Read-Write: Value used as the input in any of these scenarios: -1 niagaraR2 valid integer value

normal, processor -1 0 Leave at default. niagaraR2 Leave at default.

Input (sIn) is not linked. Input link is removed. Input status is fault or down.
position Visual decimalFormat Read-Write: See position, page 5-9. Read-Write: Sets decimal position of the output from 0 to 6 places, and optionally force (+) sign for positive values. 0 to 6, (+) sign, no (+) sign 2, no (+) sign

576

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects IntToFloat

Table 5-20

IntToFloat (ItoF) object properties. (continued)

Tab Property Name

Description

Valid Values

Default

Notes

Engineering

minExecuteTime, See Table 5-3 on page 5-8 for information maxExecuteTime, on these common object properties. averageExecuteTime,u serData statusInput (input sIn) statusOutput (output sOut) Read Only: Shows the current integer value and status at the statusInput. Read Only: Shows the current float value and status produced on the statusOutput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

<int value> {status flags} <f. value> {status flags} General, 7 others

0 {ok} 0.00 {ok} General

Security

securityGroups

IntToFloat Notes
The IntToF object is one of the simplest objects. It is typically used to convert an IntegerStatusType value from an shadow object or standard control object into the more widely-used FloatStatusType value. Often, properties defaultIntValue and decimalFormat are edited from defaults.

Example

Figure 5-31 shows IntToF objects used to convert the statusElapsedActiveTime output (runtime, in seconds) of two BO objects to float values, in order for these values to be used in a Comparison object.
Figure 5-31 IntToFloat objects used to convert BO elapsed active time (runtime) outputs.

IntoFloat objects FloatStatusType sOut values IntegerStatusType sIn values

Note

To access other conversion objects, open the Niagara Local Library and expand the tridiumx/lib JAR. General conversion objects are under the programs/conversion folder, and Lonworks-related conversion objects are under the programs/lon and programs/lonHoneywell folders. All are pre-engineered Program objects.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

577

Chapter 5 Logic

Control Objects

Logic
Quick reference for all properties: Table A-43 Inputs
statusInputA statusInputB

Default Object Shape

Outputs
prioritizedOutput statusOutput

abbrev: (reflects function, e.g. A_OR_B) A Logic objects acts as a two-input logic gate, producing a boolean result that is available both as a status-type and a prioritized-type output. The level of the prioritizedOutput is configurable to any priority level (1 to 16). A Logic object can be configured to perform one of the following functions: A_AND_ B (AND gate) A_OR_B (OR gate) A_XOR_B (XOR gate) A_NOT_B (NOT gate)

All Inputs / Outputs

Inputs
executeTrigger statusInputA statusInputB

Outputs
presentValue prioritizedOutput statusOutput

Property Quick Reference for Logic Object

(only input and output types, see Table 5-21 for all properties)

Type
input

Label
exe sInA sInB pOut sOut present

Property Name
executeTrigger controlledVariable setpoint prioritizedOutput statusOutput presentValue

Data Species
TriggerType BooleanStatusType BooleanStatusType BooleanPriorityType BooleanStatusType boolean

Parent Dependencies: None (any

container).
Resource Count Range: 67 to 101 Trigger Properties

output

None, apart from the standard input property, executeTrigger (typically not used).

Commands
None.

Properties
Table 5-21 Logic object, important properties.

Tab Property Name

Status objectType, statusFlags, description, presentValue outOfService, reliability executionParameters foreignAddress Config membershipGroups defaultA

Description
See Table 5-3 on page 5-8 for information on these properties common to all control objects. See Table 5-5 on page 5-13 for information on these properties.

Valid Values

Default

Notes
presentValue is always read-only.

normal, processor -1 niagaraR2 False Leave at default. Leave at default.

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: Does not apply to this object. Read-Write: (Future use only.) Read-Write: Acts as a constant state used for statusInputA, when that input is not linked (or if its value has a status fault). Read-Write: Acts as a constant state used for statusInputB, when that input is not linked (or if its value has a status fault). -1 niagaraR2 False, True

defaultB

False, True

False

578

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Logic

Table 5-21

Logic object, important properties. (continued)

Tab Property Name

function

Description
Read-Write: Defines the logic function of the object. The selected function shows in the objects shape. Read-Write: Defines the priority level used at the prioritizedOutput. Read-Write: Defines the prioritizedOutput state produced upon a true logic result. Applies only to the prioritizedOutput. Read-Write: Defines the prioritizedOutput state produced upon a false logic result. Applies only to the prioritizedOutput. Read-Write: See position, page 5-9. Read-Write: Defines the displayed states at the statusInput, statusOutput, and presentValue, and also how they appear on the objects property sheet.

Valid Values
A_AND_B A_OR_B A_XOR_B A_NOT_B 1 to 16 true, false, auto true, false, auto Any desired descriptors for the two states.

Default
A_AND_B

Notes

Config, cont.

priorityForWriting trueCommand

16 (Schedule) true

falseCommand

false

position Visual activeInactiveText active inactive

true <active>, false <inactive> States can display at a linked GxText object.

minExecuteTime, See Table 5-3 on page 5-8 for information maxExecuteTime, on these common object properties. averageExecuteTime,u serData Engineering statusInputA (input sInA) statusInputB (input sInB) prioritizedOutput (output pOut) statusOutput (output sOut) Security securityGroups Read Only: Shows the current boolean state and status at statusInputA. Read Only: Shows the current boolean state and status at the statusInputB. Read Only: Shows the current state and priority level of the prioritizedOutput. Read Only: Shows the current state and status of the statusOutput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

false, true {status flags} false, true @ <pri. level>

false : {ok} false : {ok}

Inactive, Active false : @ 16 Displays state using @ <pri. level> activeInactiveText. Inactive, Active {status flags} General, 7 others false : {ok} General

Logic Notes
Logic objects are 2-input digital gates that can be used to process booleanStatus values in the Niagara station. Each input has a configurable default value (state), which is evaluated whenever the input is not connected or has a fault status. Logic objects are used singly or in combinations to provide whatever boolean logic is needed for an application

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

579

Chapter 5 Logic

Control Objects

Logic Object Truth Tables

Note

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.

Outputs results shown below assume the default property values are assigned for trueCommand (true) and falseCommand (false). Note that these properties are configurable 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.
Table 5-22 Truth tables for Logic object functions.

A_AND_B

A_OR_B

sInA false false true true

sInB false true false true

sOut, pOut false false false true

sInA false false true true

sInB false true false true

sOut, pOut false true true true

A_XOR_B

A_NOT_B

sInA false false true true

sInB false true false true

sOut, pOut false true true false

sInA false false true true

sInB false true false true

sOut, pOut false true true false

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.

580

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Logic

Examples
Figure 5-32

Figure 5-32 shows various boolean operations using Logic objects.

Various Logic object examples.

This Logic object simply inverts the boolean state present on its sInA input. Input sInB is not linked. However, the defaultB property is set to true. The NAND function is done by using two objects. The output of a Logic object configured as A_AND_B (with default Config properties) is inverted to produce a NAND gate. The NOR function is done by using two objects. The output of a Logic object configured as A_OR_B (with default Config properties) is inverted to produce a NOR gate. The EQUIV function is also done by using two objects. The output of a Logic object configured as A_XOR_B (with default Config properties) is inverted to produce an EQUIV gate. When more than 2 inputs are needed in a boolean operation, multiple Logic objects can be cascaded. For example, an 8-input AND gate is made using seven Logic objects, as shown at right. Any of the Logic objects can be configured separately, depending on the boolean operation needed. This cluster could be encapsulated inside a Composite object, so as to expose only the first 8 inputs and final output.

Simple Logic Inversion

Logic Object Configuration (inversion): defaultA: defaultB: function: trueCommand: falseCommand: false (default) true A_NOT_B true (default) false (default)

NAND Gate Operation

sInA false false true true

NAND Logic
sInB false true false true sOut, pOut true true true false

NOR Gate Operation

sInA false false true true

NOR Logic
sInB false true false true sOut, pOut true false false false

EQUIV Gate Operation

sInA false false true true

EQUIV Logic
sInB false true false true sOut, pOut true false false true

Cascaded Logic Objects

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

581

Chapter 5 Loop

Control Objects

Loop
Quick reference for all properties: Table A-44 Inputs
controlledVariable setpoint

Default Object Shape

Outputs
prioritizedOutput statusOutput

abbrev: (none); LOOP Loop objects provide closed-loop PID control (proportional, integral, derivative) at the 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 setpoint deviation.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs
executeTrigger statusInhibit controlledVariable setpoint action resetIntegral

Outputs
eventTrigger presentValue prioritizedOutput statusOutput covTrigger

Property Quick Reference for Loop Object

(only input and output types, see Table 5-23 for all properties)

Type
input

Label
exe sInh sInCtrl sInSet action resetInt eventTr present pOut sOut covTrig

Property Name
executeTrigger statusInhibit controlledVariable setpoint action resetIntegral eventTrigger presentValue prioritizedOutput statusOutput covTrigger

Data Species
TriggerType BooleanStatusType FloatStatusType FloatStatusType ActionEnum TriggerType TriggerType float FloatPriorityType FloatStatusType TriggerType

container).
Resource Count Range: 75 to 137

output

Trigger Properties

The Loop object has the standard input property, executeTrigger, (typically not used) plus an additional trigger-type input:

resetIntegralAny received trigger pulse clears the current integral component of the loops 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 objects configuration properties are correctly defined. Also, note that whenever the Loops input statusInhibit is linked, an integral reset occurs automatically each time a false-to-true transition is received.

In addition, the Loop object also provides two trigger-type outputs: eventTriggerFires upon each event transition (to-offnormal, to-fault, to-normal) that has been specified in the property eventTriggerEnable. covTriggerFires upon each change of value at the statusOutput. As needed, these outputs can be linked to any input using TriggerType data species.

582

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Loop

Commands
For a JDE user with Command, Std privileges, the following right-click commands are available (these commands are not accessible from a Web browser):

enableDebugcauses debug-level data on the Loops operation to be continuously sent to Standard Output. An example of Loop object debug output (continuously repeating):
pGain 0.3000030517578125 iGain: 0.0 dGain0.0 errorSum 0.0 error 0.30000305 pv 0.30000305 deltaSecs 2.003

disableDebugstops debug-level data from being sent to Standard Output.

If the JDE user has Command, Admin privileges, this additional command is available from the JDE menu bar:

Commands > resetAckedTransitionsSets all three flags in the ackedTransitions property (to-offnormal, to-fault, to-normal). Rarely required, see the the JDE Command section on page 5-11 for more information.

Properties
Table 5-23 Loop object properties.

Tab Property Name

objectType, statusFlags, description eventState, reliability, outOfService, ackedTransitions toOffnormal, toFault, toNormal, presentValue executionParameters foreignAddress Config membershipGroups defaultSetpoint Status

Description
See Table 5-3 on page 5-8 for information on these properties common to all control objects. See Table 5-4 on page 5-12 for information on these properties common to all event-type control objects.

Valid Values

Default

Notes

presentValue is always read-only. It displays in the configured output units (outputUnits).

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: Does not apply to this object. Read-Write: (Future use only.) Read-Write: Value used as the loop setpoint in any of these scenarios: -1 niagaraR2 valid float

normal, processor -1 niagaraR2 0.0 Leave at default. Leave at default.

Setpoint input (sInSet) is not linked. Setpoint link is removed. Setpoint input status is fault or down.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

583

Chapter 5 Loop

Control Objects

Table 5-23

Loop object properties. (continued)

Tab Property Name

defaultAction

Description
Read-Write: Selection of loop action as either direct or reverse acting, where:

Valid Values
direct, reverse

Default
direct

Notes
Note: Loop action is defined in a manner opposite to most other control systems.
The action input, if linked, can be used to override this default action (this requires a custom Program object).

directLoop output increases as the

value of the controlled variable becomes less than the setpoint value. In a temperature loop, this is typically considered to be a heating application. reverseLoop output increases as the value of the controlled variable becomes greater than the setpoint value. In a temperature loop, this is typically considered to be a cooling application.

Note: In some applications using statusInhibit and a reverse action loop, different configurations may be desired. See the the Status Inhibit Operation section on page 5-88 for more information.
outputUnits Read-Write: For display purposes, defines the engineering units of the loop output. Choose from a logical grouping, then a specific unit. For selections see About Units, page 5-6. Config, cont. Select any (BACnet-type unit choices) Other, no_units Used in display of presentValue, statusOutput, prioritizedOutput, many property descriptors on the property sheet. Used in display of some property descriptors on the property sheet. Expressed in terms of outputUnits over controlledVariableU nits. Must be a positive value. valid float, positive only 0.0 (no integral) 0.0 (no integral) Integral effect is ignored unless you enter a value here. If set less than the maximumOutput value, control offset may occur.

controlledVariableUnits Read-Write: For display purposes, defines the engineering units of the controlled variable (received at input sInCtrl). Choose from a logical grouping, then a specific unit. proportionalConstant Read-Write: Defines the value of the proportional gain parameter used by the loop algorithm. Used to set the overall gain for the loop. A starting point for this value is found by: output range / throttling range. integralConstant Read-Write: Defines the integral gain parameter, in repeats per minute, used by the loop algorithm. Also called reset rate. Acts on the magnitude of the setpoint error. Read-Write: Defines the largest amount of integral gain allowed, typically required when using PI or PID control.

Select any (BACnet-type unit choices) valid float

Other, no_units

1.0

maxIntegralGain

valid float, positive only

Note: For PI or PID control, this is recommended to be set to the same value as maximumOutput.
derivativeConstant Read-Write: Defines the derivative gain parameter, in seconds, used by the loop algorithm. Acts on the rate of change of the setpoint error. valid float 0.0 (no derivative)

584

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Loop

Table 5-23

Loop object properties. (continued)

Tab Property Name

bias

Description
Read-Write: Defines the amount of output bias added to the output to correct offset error. In other words, the output at setpoint. Expressed in the same units of the outputUnits.

Valid Values
valid float

Default
0.0

Notes
For proportional only control, this is typically set midway between maximum and minimum output. For a loop with an output of 0.0 to 100.0, this is 50.0.

Config, cont.

Note: For proportional-only use only. For PI or PID control, set bias to 0.0 (the default). The integral term can be hampered by a non-zero bias.
maximumOutput minimumOutput priorityForWriting covIncrement Read-Write: Defines the maximum output value that the loop algorithm can produce. Read-Write: Defines the minimum output value that the loop algorithm can produce. Read-Write: Defines the priority level used at the prioritizedOutput. Read-Write: The minimum change for the calculated loop output (since the last output change) before all outputs can update. valid float valid float 1 to 16 valid float 100.0 -100.0 16 (Schedule) 0.0 (no minimum)

maximumOutput must be greater than the minimumOutput.

Execution efficiency (of downstream objects) is typically increased by entering a small value here, say 0.1 * See specific details on inhibitTime, the next property.

timeDelay, notificationClass, eventEnable, notifyType, inhibitTime*, eventTriggerEnable, alarmText inhibitTime

See Table 5-5 on page 5-13 for information on these properties common to all event-type control objects.

Alarm Setup

Read-Write: Duration (Hr:Min:Sec) of the alarm inhibit timer, which applies only if the objects input statusInhibit is linked. The purpose is to prevent nuisance alarms on equipment startup and shutdown, and also to selectively stop Loop output processing. The inhibitTime is triggered by a transition from false-to-true at the statusInhibit input.

any practical value in Hr:Min:Sec

00:00:00 A minimum of 1 (no inhibit) second (00:00:01) is recommended whenever the statusInhibit is linked. Alarm processing compares the controlledVariable input value to the setpoint value (plus or minus the errorLimit).

When statusInhibit becomes true, alarm

processing is delayed for the duration of the inhibit time. The loop output begins recalculating, with the output starting at a value 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 using statusInhibit and a reverse action loop, different configurations may be desired. See the the Status Inhibit Operation section on page 5-88 for more information.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

585

Chapter 5 Loop

Control Objects

Table 5-23

Loop object properties. (continued)

Tab Property Name

Alarm Setup, cont. errorLimit

Description
Read-Write: Defines the maximum deviation value between the controlled variable and the loops setpoint before the object alarms with an off-normal state. Read-Write: Differential value applied to errorLimit before return-to-normal. Read-Write: See position, page 5-9. Read-Write: Sets decimal position of the output from 0 to 6 places, and optionally force (+) sign for positive values. See Table 5-3 on page 5-8 for information on these common object properties.

Valid Values
valid float

Default
100.0

Notes
Applied both above and below the setpoint value.

deadband

valid float

100.0

position Visual decimalFormat

0 to 6, (+) sign, no (+) sign

2, no (+) sign

minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInhibit (input sInh) controlledVariable (input sInCtrl) setpoint (input sInSet) prioritizedOutput (output pOut) statusOutput (output sOut) action (input action)

Read Only: The current boolean state and status of the statusInhibit input. Read Only: The current float value and status of the process input (sInCtrl). Read Only: The current float value and status of the setpoint input (sInSet). Read Only: The current float value and priority level at the prioritized output (pOut). Read Only: The current float value and status at the statusOutput. Read Only: The current action of the loop algorithm, which can be dynamically toggled through a link to the action input. If the action input is not linked, this property displays the current defaultAction setting. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

false, true {status flags} <float value> {status flags} <float value> {status flags} <float value> @ <pri. level> <float value> {status flags} direct, reverse

false : {ok} If linked, the inhibitTime value is used. 00.0 {ok} 00.0 {ok} 0.00 @ 16 00.0 {ok} direct Typically, the action input is not linked. If linked, the source data species must be actionEnum.

Security

Engineering

securityGroups

General, 7 others

General

Loop Notes
The Loop object provides a closed-loop (feedback-based) control signal based upon values received at its setpoint input and its controlled variable input. The loop algorithm may be configured as proportional-only (P), proportional plus integral (PI), or proportional plus integral and derivative (PID). The following main topics apply to Loop objects:

Loop Terms Status Inhibit Operation Proportional Only Control Proportional with Integral (PI) Control Proportional with Integral and Derivative (PID) Control Examples
Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

586

Chapter 5

Control Objects Loop

Loop Terms

The following terms are used ahead to describe the operation of the Loop object.

Process variableThe controlled process, meaning the value at the controlledVariable input. (What youve got.) Abbreviated here as PV. SetpointThe target for the process variable, meaning the value at the setpoint input. (What you want.) Abbreviated here as setpt. Setpoint errorThe difference between the process variable and the setpoint, acted upon by the loop algorithm. Abbreviated as ES. Loop OutputThe correction signal produced by the loop algorithm, available at the object outputs (prioritizedOutput, statusOutput). Referred to as output. The output should be linked (directly or indirectly) to an AnalogOutput object used to position the proportionally-modulated device (such as a valve or damper) that controls the process variable. Proportional gainThe value of the property proportionalConstant. Abbreviated here as KP. Sets the overall gain of the loop, as the following ratio: KP = Output range / effected process range (sometimes called throttling range).

Throttling rangeThe amount of process variable change expected as a result of throttling the system between the minimumOutput and maximumOutput. BiasA value added to the output to correct offset error. It is typically used in proportional-only control as a pivot output value, for when the PV = setpt. ActionDefines the direction of the output relative to setpoint error, where: DirectLoop output increases when PV < setpt. ReverseLoop output increases when PV > setpt.

Note

Action is defined in a manner opposite to most other control systems.

The property defaultAction defines the Loop objects action, which can be overridden by linking to the action input (this requires a Program object with an output using the actionEnum data species).

Integral gainThe value of the property integralConstant. Abbreviated as KI. Sets the integral or reset gain of the loop, expressed in repeats per minute. The KI component of the loop output reacts to the duration of the setpoint error. Derivative gainThe value of the property derivativeConstant. Abbreviated here as KD. Sets the derivative or rate gain of the loop, expressed in seconds. The KD component of the loop output reacts to the rate of change of setpoint error, and provides a dampening effect.

maximumOutputThis property defines the maximum value produced by the loop output. Must be set greater than the minimumOutput value. minimumOutputThis property defines the minimum value produced by the loop output. Must be set less than the maximumOutput value.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

587

Chapter 5 Loop

Control Objects

Status Inhibit Operation

The statusInhibit input, when linked, directly affects two separate functions of a Loop object:

Output processingThe 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, the integral 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 loops value is already at its minOutput value, obviously it will not move any lower. 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 this case, 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.

Note

Alarm processingThe 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 objects 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 the inhibit 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 Only 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 (KP). Control
Output Calculation P-only Configuration Guidelines

Output Calculation: P-only loop output is linear, and is calculated as follows:

Output = or Output = where:

(KP x ES) + bias [(KP x ES) + bias]

(if action = direct) (if action = reverse

ES = [setpt - PV] A characteristic of P-only control is setpoint offset, which occurs unless the process load just happens to be at the (one) ideal level.
Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

588

Chapter 5

Control Objects Loop

P-only Configuration Guidelines

If using proportional-only control, follow these guidelines: Output limitsDefine the maxValue and minValue properties for the loop output, noting that the maximum value must be greater than the minimum. Proportional GainCalculate and enter a proportionalConstant (KP) property value starting with this formula: output range (outputMax - outputMin) throttling range 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 KP is: (100% - 0%) 20 = 100% 20 = 5

When tuning the loop, you can try increasing this value (effectively using only a portion of the throttling range) to eliminate the amount of setpoint error. However, if you increase the KP too much, this typically results in a constant oscillation of the process variable (above and below the setpoint). BiasAssign the bias property an output-midpoint value (for example, 50.0). This allows for equal corrections for a process variable above or below setpoint. Integral and Derivative GainSet the properties integralConstant and derivativeConstant to 0.0 (the defaults). ActionDefine 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.

Proportional with PI configuration is recommended for most control loops, because the integral term eliminates the setpoint offset inherent in P-only loops. PI control uses proportional Integral (PI) gain to adjust the output, and then incrementally continues to add (or subtract, if Control
appropriate) from the output value for as long as a setpoint error continues to exist. The following topics apply to PI Loop control: Output Calculation Repeats Per Minute Integral Overshoot PI Configuration Guidelines

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

589

Chapter 5 Loop

Control Objects

Output Calculation: PI loop output is calculated as follows:

Output = or Output = where:

KP x (ES + KI ) + bias

(if action = direct)

[(KP x (ES + KI ) + bias] (if action = reverse)

ES = [setpt - PV] The integralConstant property specifies the integral gain (KI) in repeats per minute, sometimes called a reset rate. Repeats Per MinuteTo 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 loops 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.
Figure 5-33 Example of Loop integral gain (repeats per minute).
Both Loop outputs change from P-term (first setpoint change). Integral from PI Loop output continues to rise. PI loop output increased about twice the original amount (two resets) in the one minute since the setpoint change.

Compare the output of two Loop objects, both with the same proportional gain. The topmost Loop object has an integralConstant of 2.0, while this property in the other Loop has a value of 0.0 (no integral). The initial setpoint shift causes the equivalent output change from both objects. The output of the Loop_PI object continues to ramp up, however, as the process variable does not respond. After one minute, two resets have occurred.

P-Only Loop output stays fixed.

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).

590

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Loop

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 loops integralConstant is typically kept small, and sized appropriately for the assigned proportionalConstant.

PI Configuration Guidelines
If using PI control, follow these guidelines: Output limitsDefine the maxValue and minValue properties for the loop output, noting that the maximum value must be greater than the minimum. Proportional GainCalculate and enter a proportionalConstant (KP) property value starting with this formula: output range (outputMax - outputMin) throttling range 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 KP is: (100% - 0%) 20 = 100% 20 = 5

When tuning a PI loop, you typically reduce the proportionalConstant value, because the integral effect on the output will correct setpoint error over time. BiasAssign 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 GainSet 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. Make sure to change the maxIntegralGain property from its default (0.0) to a larger valuein most cases, maxIntegralGain should equal the maxOutput value. If maxIntegralGain is left at default, the output will not reflect any integral gain. Derivative GainDisable derivative by setting the derivativeConstant property at 0.0 (the default). ActionDefine 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.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Note

Revised: April 20, 2004

591

Chapter 5 Loop

Control Objects

Proportional with Integral and Derivative (PID) Control

PID loop control can be difficult to tune and (often for this reason) is seldom used. However, in certain cases, PID control may be needed. An example is the control of a process with a long reaction time, such as temperature control of a large mass. For such a lag-oriented system, the derivative component of the PID loop output can help prevent overshoot that might otherwise result from PI control. The derivative gain (KD) exerts an anticipating braking effect on the loop output, based on the rate-of-change of the process. Output Calculation PID Configuration Guidelines

Output Calculation: PID loop output is calculated as follows:

Output = or Output = where:

KP x (ES + KI + KD) + bias

(if action = direct)

[(KP x (ES + KI + KD) + bias] (if action = reverse)

ES = [setpt - PV] In the Loop object, the derivativeConstant property specifies the derivative gain (KD) directly in seconds (note this differs from some systems using derivative in minutes).

PID Configuration Guidelines

If using PID control, follow the the PI Configuration Guidelines section on page 5-91, with the addition of defining a positive value as the derivativeConstant. In general, a derivativeConstant less than 10 seconds should be tried first, and only then increased (if necessary), providing that the loop output remains stable at steady-state conditions.

Examples

Due to the many unique characteristics of any loop-controlled process, the real-life examples in Figure 5-34 are given for background information (not for duplication). Each row gives a separate example with a brief explanation, a screen capture from the JDE, and some of the important Loop configuration properties.

592

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Loop

Figure 5-34

Various Loop Object Examples.

This Loop object monitors the hot-water supply temperature, receives a hot-water supply setpoint that is reset by the outside air temperature, and calculates a 0 to 100% output. The output is rescaled by a Math object to compensate for valve characteristics.

Boiler Control PI Loop

Loop Object Configuration: defaultAction: direct outputUnits: percent controlledVariableUnits: degreesFahrenheit proportionalConstant: 2.00 integralConstant: 0.10 / min. maxIntegralGain: 100.0 % derivativeConstant: 0.0 sec. bias: 0.0 % maximumOutput: 100.0 % minimumOutput: 0.0 %

This Loop object monitors an AHUs discharge air temperature, receives a setpoint 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: direct outputUnits: percent controlledVariableUnits: degreesFahrenheit proportionalConstant: 1.75 integralConstant: 0.50 / min. (other properties as listed in first example)

This Loop object monitors the (minimum) zone head pressure of multiple chilled water supply lines, and receives a constant setpoint of 18 PSI from a Math object. The Loop outputs a 20 to 100% signal used to control a variable frequency drive (VFD) for the chilled water supply pump. A Command object is used (for tuning purposes) to clear the loops integral term.

Chilled Water Supply Pump VFD

Loop Object Configuration: defaultAction: direct outputUnits: percent controlledVariableUnits: pounds_per_sq_inch proportionalConstant: 1.2 integralConstant: 0.8 / min. maxIntegralGain: 100.0 % derivativeConstant: 0.0 sec. bias: 0.0 % maximumOutput: 100.0 % minimumOutput: 20.0 %

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

593

Chapter 5 Math

Control Objects

Math
Quick reference for all properties: Table A-47 Inputs
statusInputA statusInputB statusInputC statusInputD

Default Object Shape

Outputs
statusOutput prioritizedOutput

abbrev: reflects function, e.g. RESET A Math object performs a math operation using float values present at from one to four inputs. The float value result is available on a status-type output and a prioritized-type output. The prioritizedOutput level is configurable to any priority level (1 to 16). The function of the object is configurable as:

All Inputs / Outputs

Inputs
executeTrigger statusInputA statusInputB statusInputC statusInputD prioritizedOutput statusOutput

Outputs

Minimum Maximum Summation Average Difference Absolute Value Square Root Log Natural Log Exponential Sine Cosine Tangent Arcsine Arccosine Arctangent Reset Multiplication Division Power

(MIN) (MAX) (SUM) (AVG) (DIFF) (ABS) (SQRT) (LN) (LOG) (EXP) (SIN) (COS) (TAN) (ASIN) (ACOS) (ATAN) (RESET) (MULT) (DIV) (POW)

Property Quick Reference for FunctionGenerator Object

(only input and output types, see Table 5-24 for all properties)

Type
input

Label
exe sInA sInB sInC sInD sOut pOut

Property Name
executeTrigger statusInputA statusInputB statusInputC statusInputD statusOutput prioritizedOutput

Data Species
TriggerType FloatStatusType FloatStatusType FloatStatusType FloatStatusType FloatStatusType FloatPriorityType

output

Input Usage
Any or all inputs

by Selected Function
average minimum maximum multiplication summation difference (sInA minus sInB) division (sInA divided by sInB) power (sInA to the sInB power) abs (absolute value of sInA) sqrt (square root of sInA) reset (of sInA value according to config properties) All remaining functions, including trigonometric ones which produce an output value in radians.

First two inputs (sInA and sInB) sInA (only)

Parent Dependencies: None (any

container).
Resource Count Range: 67 to 101 Trigger Properties

None, apart from the standard input property, executeTrigger. In certain cases, linking to this input may provide some utility. For example, by configuring a Math object to execute on_trigger, math functions can calculate only under certain conditions, such as another object firing a trigger to indicate an alarm event. None.

Commands

594

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Math

Properties
Table 5-24 Math object properties.

Tab Property Name

Status objectType, statusFlags, description, presentValue, outOfService, reliability executeParameters foreignAddress membershipGroups defaultA

Description
See Table 5-3 on page 5-8 for information on these common object properties.

Valid Values

Default

Notes
For this object, presentValue is always read-only.

See Table 5-5 on page 5-13 for information on these properties.

normal, processor -1 niagaraR2 NaN (null) NaN (null) NaN (null) NaN (null) summation For multiplication, the output is: A X B X C X D, where any NaN values (not linked and no default) are ignored. For division, the output is A / B. If B is 0, the output is NaN. For any of the trigonometric functions, units are in radians. For the power function, inputA is the radix and inputB is the exponent. Leave at default. Leave at default. Can apply to any function selection.

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: Does not apply to this object. Read-Write: (Future use only.) Read-Write: Acts as a constant value used for statusInputA, when that input is not linked (or if its value has a status fault). Read-Write: Acts as a constant value used for statusInputB, when that input is not linked (or if its value has a status fault). Read-Write: Acts as a constant value used for statusInputC, when that input is not linked (or if its value has a status fault). Read-Write: Acts as a constant value used for statusInputD, when that input is not linked (or if its value has a status fault). Read-Write: Defines the math function (operation) used by the object. -1 niagaraR2 valid float

defaultB

valid float

defaultC

valid float

defaultD

valid float

function Config

Certain functions can make use of all (4)

float status inputs, as needed. These function selections are: minimum, maximum, summation, average, and multiplication

Other functions use only the first 2 inputs

(statusInputA and B), namely: difference, division, and power

The remainder of functions use only the

value at statusInputA. Primarily, these are trigonometric functions, and include: abs (absolute value), sqrt (square root), ln (natural log), log, exp, sin, cos, tan, asin, acos, and atan. Also: reset.

The reset function requires defined values

for the properties inputLowLimit, inputHighLimit, outputLowLimit, and outputHighLimit. units Read-Write: Engineering units for the math output, for display purposes. Choose from a logical grouping, then a specific unit. For selections see About Units, page 5-6.

minimum maximum summation average difference abs sqrt ln log exp sin cos tan asin acos atan reset multiplication division power

Select any (BACnet-type unit choices)

Other, no_units

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

595

Chapter 5 Math

Control Objects

Table 5-24

Math object properties. (continued)

Tab Property Name

outputHighLimit

Description
Read-Write: Defines the maximum value produced at the output. All internally calculated values are clamped at this limit. Read-Write: Defines the minimum value produced at the output. All internally calculated values are clamped at this limit. Read-Write: Defines the priority level used at the prioritizedOutput. Read-Write: The minimum change for the calculated loop output (since the last output change) before all outputs can update.

Valid Values
valid float

Default
NaN (none) NaN (none) 16 (Schedule) 0.0 (no minimum)

Notes
A reset application permits the HighLimit to be less than the LowLimit, if a reverse reset output is required.

outputLowLimit

valid float

priorityForWriting covIncrement Config, cont.

1 to 16 valid float

Execution efficiency (of downstream objects) is typically increased by entering a small value here, say 0.1

inputHighLimit

Read-Write: Applies to Reset function only. Defines the maximum input value. An input above this value is evaluated as this value. When the input is at this value, the output is at the outputHighLimit value.

valid float

NaN (none)

inputLowLimit

Read-Write: Applies to Reset function only. Defines the minimum input value. An input below this value is evaluated as this value. When the input is at this value, the output is at the outputLowLimit value.

valid float

NaN (none)

position Visual decimalFormat

Read-Write: See position, page 5-9. Read-Write: Sets decimal position of the output from 0 to 6 places, and optionally force (+) sign for positive values.

0 to 6, (+) sign, no (+) sign

2, no (+) sign

minExecuteTime, These properties are common to all control maxExecuteTime, objects. For more information, see Table 5-3 averageExecuteTime,u on page 5-8. serData statusOutput (output sOut) Engineering prioritizedOutput (output pOut) statusInputA (input sInA) statusInputB (input sInB) statusInputC (input sInC) statusInputD (input sInD) Security securityGroups Read Only: Current calculated float value and status output at the statusOutput. Read Only: Current calculated float value and priority level at the prioritizedOutput. Read Only: Current float value and status at statusInputA. Read Only: Current float value and status at statusInputB. Read Only: Current float value and status at statusInputC. Read Only: Current float value and status at statusInputD. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

<f. value> {status flags} <f. value> @ <pri. level> <f. value> {status flags} <f. value> {status flags} <f. value> {status flags} <f. value> {status flags} General, 7 others

<NaN> {ok} <NaN> @ 16 <NaN> {ok} <NaN> {ok} <NaN> {ok} <NaN> {ok} General

596

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Math

Math Notes
Math 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 inputsmultiplication 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 objects function at the default of summation. The Math objects outputs can be linked to float inputs of other objects that require this constant value. This is the simplest use of a Math object.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

597

Chapter 5 Math

Control Objects

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: outputHighLimitmay (or may not) be greater than the outputLowLimit outputLowLimitmay (or may not) be less than the outputHighLimit inputHighLimitmust be greater than the inputLowLimit inputLowLimitmust 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 upin 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 CompensationA 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.

598

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Math

Cascading Math Objects

Math objects are frequently cascaded to perform a specific calculation. Consider the three Math objects shown in Figure 5-35, used to calculate tonnage of cooling.
Figure 5-35 Cascaded Math objects calculating cooling tonnage.

The first Math object finds the difference between the chilled water return temp. (sInA) and chilled water supply temp. (sInB): the delta T.

The next Math object multiplies the delta T (sInA) and the current chilled water flow rate (sInB), in gallons per minute.

The last Math object divides the result on sInA by the constant of 24 (defaultB property value).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

599

Chapter 5 MultistateInput

Control Objects

MultistateInput
Quick reference for all properties: Table A-48 Inputs
statusInput

Default Object Shape

Outputs
statusOutput

abbrev: MSI MultistateInput (MSI) objects are used to monitor a value with more than two discrete states, for example, a multi-speed fan. The object represents the multistate values in the control engine as integers (with associated text descriptors), where they can be passed to other control logic and/or be monitored for alarm conditions. As with Niagara AI, AO, BI, BO, and MSO objects, you can expose any MSI1 object in the station as a BACnet object.
1

All Inputs / Outputs

Inputs
executeTrigger statusInhibit resetCOSCountTrigger* resetElpActTimeTrigger* statusInput

Outputs
eventTrigger statusCOSCount* statusElpActTime* COSTrigger* COSAlertTrigger* ElpActAlertTrigger* statusOutput

In addition to BACnet-type multistate functions, the MSI object collects runtime (elapsed active time) and counts COS (changes-of-state). Based upon configurable limits, the object can be set to generate alerts for both runtime levels and COS counts. Trigger inputs allow the clearing of the COS count and the runtime value. Trigger outputs are available for each COS, COS alert, runtime alert, and event. Note: Runtime accumulates during any state except Off (first stateText entry). The COS count increments only upon a transition from (or to) the Off state.
Parent Dependencies: None (any

*abbreviations, see chart below

*abbreviations, see chart below

Input / Output Property Reference for MSI Object

(only input and output types, see Table 5-25 for all properties)

Type
input

Label
exe sInh resetCt resetElp sIn eventTr sCnt sCnt cosT cosAlrt elActAlr sOut

Property Name
executeTrigger statusInhibit resetChangeOfStateCountTrigger resetElapsedActiveTimeTrigger statusInput eventTrigger statusChangeOfStateCount statusElapsedActiveTime changeOfStateTrigger changeOfStateAlertTrigger elapsedActiveTimeAlertTrigger statusOutput

Data Species
TriggerType BooleanStatusType TriggerType TriggerType IntegerStatusType TriggerType IntegerStatusType IntegerStatusType TriggerType TriggerType TriggerType IntegerStatusType

output

container).
Resource Count Range: 79 to 141 Trigger Properties

The MSI object has the standard input property, executeTrigger, (typically not used) and also 2 other trigger-type inputs: resetChangeOfStateCountTriggerAny received trigger pulse clears the objects current count of COS (changes of states), resetting it to zero (0). resetElapsedActiveTimeTriggerAny received trigger pulse clears the objects accumulated runtime (elapsed active time), resetting it to zero (0.0). In addition, there are 4 available trigger-type outputs, described as follows:

eventTriggerFires upon each event transition (to-offnormal, to-fault, to-normal) that has been specified in the property eventTriggerEnable.

1. Some state limitations apply. See stateText Considerations, page 5-104.

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

5100

Chapter 5

Control Objects MultistateInput

changeOfStateTriggerFires upon each change-of-state at the statusOutput. changeOfStateAlertTriggerFires 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). elapsedActiveTimeAlertTriggerFires each time a runtime alert is issued (activeTimeAlertLimit value has been reached, or a multiple of this value if periodicAlerts is set to True). As needed, these trigger-type inputs and outputs can be linked to other objects that have properties using TriggerType data species.

Commands
For a JDE user with Command, Admin privileges, the following object commands are available from the menu bar (for example, Command > resetActiveTime):

resetAckedTransitionsSets all three flags in the ackedTransitions property (to-offnormal, to-fault, to-normal). Rarely required, see the JDE Command section on page 5-11 for more information. resetChangeOfStateCountThis sets the changeOfStateCount property value to zero (0), clearing any COS count. resetActiveTimeThis sets the elapsedActiveTime property value to 00:00:00 (Hr:Min:Sec), clearing any accumulated runtime. setChangeOfStateAlertLimitAllows editing of the changeOfStateAlertLimit property value (Alarm Setup property). setRuntimeAlertLimitAllows editing of the activeTimeAlertLimit property value (Alarm Setup property).

Properties
Table 5-25 MultistateInput (MSI) object properties.

Tab Property Name

objectType, statusFlags, description eventState, reliability, outOfService, ackedTransitions toOffnormal, toFault, toNormal, presentValue changeOfStateTime changeOfStateCount

Description
See Table 5-3 on page 5-8 for information on these properties common to all control objects. See Table 5-4 on page 5-12 for information on these properties common to all event-type control objects.

Valid Values

Default

Notes

presentValue can be written to directly whenever the object is set to outOfService.

Status

Read Only: Shows a date/timestamp for the last COS (change of state). Read Only: Shows the total number of changes of state that have occurred since the last COS count reset (clear). Read Only: Shows a date/timestamp for when the COS count was last cleared.

valid timestamp or null (none) integer value

null 0

timeOfStateCountReset

valid timestamp or null (none)

null

Trigger-type inputs can be used to clear COS and runtime values. COS and runtime-related data is not visible from a BACnet exposure.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

5101

Chapter 5 MultistateInput

Control Objects

Table 5-25

MultistateInput (MSI) object properties. (continued)

Tab Property Name

Status, cont. elapsedActiveTime

Description
Read Only: Shows the accumulated runtime (elapsed active time) formatted in Hr:Min:Sec. Read Only: Shows a date/timestamp for when the accumulated runtime (elapsed active time) was last cleared.

Valid Values
Time period up to 9999:99:99 (Hr:Min:Sec) valid timestamp or null (none)

Default
00:00:00

Notes
COS and runtime-related data is not visible from a BACnet exposure.

timeOfActiveReset

null

executeParameters foreignAddress

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: BACnet usage only. Set to a positive integer for this object to appear as a BACnet Multi-state Input object to other BACnet devices. See foreignAddress, page 5-9, and also stateText Considerations, page 5-104. 0 to 4194302 or -1 (not exposed)

normal, processor -1 Must be a unique number among all MultistateInput objects in station.

Config membershipGroups defaultInput

Read-Write: (Future use only.) Read-Write: The input value used by the MSI object if its statusInput link is broken or assumes a status that includes fault. See Table 5-5 on page 5-13 for information on these properties common to all event-type control objects.

niagaraR2 Any one state defined on the Visual tab.

niagaraR2 Leave at default. Off Does not apply if an input value is one of the faultValues. * See specific details on inhibitTime, the next property.

timeDelay, notificationClass, eventEnable, notifyType, inhibitTime*, eventTriggerEnable, alarmText inhibitTime

Read-Write: Duration (Hr:Min:Sec) of the alarm inhibit timer, which applies only if the objects input statusInhibit is linked. The purpose is to prevent nuisance alarms on equipment startup and shutdown. The inhibitTime is triggered by a transition from false-to-true at the statusInhibit input.

any practical value in Hr:Min:Sec

00:00:00 A minimum value (no inhibit) of 1 second (00:00:01) is recommended whenever the statusInhibit input is linked.

Alarm Setup

When statusInhibit becomes true, alarm

processing is delayed for the inhibit time.

Whenever statusInhibit becomes false,

alarm processing remains inhibited. The alarm status of the object cannot change. This applies whether the objects statusFlags show a normal {ok} state or inAlarm and/or unackedAlarm states. changeOfStateAlertLimit Read-Write: Number of COS occurrences that generate a changeOfStateCount alert. activeTimeAlertLimit Read-Write: Amount of runtime (elapsed active time), in Hr:Min:Sec, that generates a runtime alert. Read-Write: The assigned notification class number, used in routing alerts. A NotificationClass object using the same number should exist in the NotificationService objects container. Positive integer Any value up to 9999:59:99 (Hr:Min:Sec) 0 to 8388607 0 00:00:00

alertNotificationClass

5102

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects MultistateInput

Table 5-25

MultistateInput (MSI) object properties. (continued)

Tab Property Name

periodicAlerts

Description
Read-Write: Determines if both COS count alerts and runtime alerts are periodically generated each time the respective limit is reached. Read-Write: Text descriptor included in either a COS count alert or runtime alert. If left at the default hyphen (-), the Station objects alertText is used.

Valid Values
False, True

Default
False

Notes

alertText Alarm Setup, cont.

Any text string, including spaces. Any states as defined on the Visual tab. Any states as defined on the Visual tab. value: unique integer, 0 to n. tag: any text descriptor needed.

(hyphen)

alarmValues

Read-Write: Defines which discrete states correspond to an object alarm condition.

(none of default: Off, On, Fast) (none of defaults): Off, On, Fast 0 = Off 1 = On 2 = Fast default = Error

faultValues

Read-Write: Defines which discrete states correspond to a object fault condition.

If more than 8 stateText entries are defined, only the first 8 may be used as either an alarmValue or faultValue.

position stateText

Read-Write: See position, page 5-9. Read-Write: Defines all possible discrete states by value-name pairs.

Note: For alarm/fault Each state has two fields: operation, only the first 8 stateText are supported. valueUnique integer, 0 to positive n. If BACnet compatibility is needed, states must be contiguous starting at 1. tagText to describe the associated discrete state. State descriptors are used at the statusOutput, presentValue, alarm and fault values.
minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInhibit (input sInh) statusChangeOfState Count (output sCnt) statusElapsedActive Time (output sElpT) statusInput (input sIn) statusOutput (output sOut) Read Only: Current runtime (elapsed active time), totaled in seconds. Available as a IntegerStatusType output. Read Only: Current discrete state and status at the statusInput. Read Only: Current discrete state and status at the statusOutput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10. Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows the current boolean state and status of the statusInhibit input. Read Only: Current COS count. Available as a IntegerStatusType output.

State descriptors are used in linked MultistateLog object collections and also can display at a linked GxText object. The default state signals an invalid input value.

Visual

false, true : {status flags} <count> : {status flags} <seconds> : {status flags} <dis. state> : <status flags> <dis. state> : <status flags> General, 7 others

false : ok 0 : ok

Engineering

0 : ok

Off : ok Off : ok General

Security

securityGroups

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

5103

Chapter 5 MultistateInput

Control Objects

MultistateInput Notes
The MultistateInput (MSI) object is typically used to display a multistate value received from an integration (shadow) object, offering configurable display text for up to 8 discrete states. In addition, the object provides Niagara alarm capability and the option to expose it as a BACnet Mulitstate_Input object. The following main topics are explained on configuring a MSI object: Routinely Configured MSI Properties MSI Alarming Functions MSI Alert Notifications

Routinely Configured MSI Properties

Among all properties on a MSI objects property sheet, the two most typically configured are:

stateText (Visual tab)Defines the objects possible discrete (integer) states and the associated text descriptors. A maximum of 8 states are fully supported (including alarm/fault operation). Text descriptors appear at the objects outputs. They are also seen by users in linked GxText objects and in the accumulated data of a linked MultistateLog. See the next section stateText Considerations for additional details. defaultInput (Config tab)Defines the statusOutput state produced whenever a fault is received on the statusInput. Fault states are defined by the faultValues property on the Alarm Setup tab.

If alarming functions and/or alerts are needed, additional Alarm Setup properties are configured from defaults. If more than 8 stateTexts are defined, only the first 8 can be specified as an alarmState or faultState.

stateText Considerations
When exposing a Niagara MSI 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. A former issue with MSI alarming has been fixed starting in Niagara r2.3.4. Previously, if an MSI was configured without a 0-value stateText entry (such as for BACnet usage), alarm/fault operation would be off by one. This was fixed. Alarm and fault operation could also fail if an MSI was configured with non-contiguous stateText entries (illegal for BACnet export though); this was also fixed. The stateText property is on the Visual tab (Figure 5-36).

Note

5104

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects MultistateInput

Figure 5-36

If exposing as BACnet, the MSI object must have stateText with contiguous values, and with no zero (0).

Default stateText values for a Niagara MSI and MSO object include the non-compliant 0 value.

This MSI object has had its stateText property edited to remove the 0 value. Other values were modified and added as needed, using the StateText Guidelines (below).

StateText GuidelinesIf you follow these guidelines when assigning stateText values, you can then expose an MSI object as BACnet.
1.

Assign numerical states starting at 1 (not 0, as with a standard Niagara MSI). For a two-speed object, for example, this means 1 = Off, 2 = On, and 3 = Fast, vs. the numerical 0, 1, and 2 defaults used in stateText. Assign state numbers contiguously (without skipping a number), as a BACnet restriction. If alarming is needed, note that Niagara limits this to the first 8 stateText entries.

2.

Note

If you already assigned a foreignAddress value to expose the MSI 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). stateText Default FeatureA Niagara MSI 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. There is no default state equivalent for a BACnet Multistate Input object.

Note

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

5105

Chapter 5 MultistateInput

Control Objects

MSI Alarming Functions

An MSI object can be configured for alarm indication, and optionally, event (alarm) notification. The object provides properties to define the alarm state(s), fault state(s), alarm delay, and event notifications, using BACnet-type properties. If more than 8 stateText entries exist, remember that only the first 8 are alarmable. The MSI object can also generate alerts based on configurable limits for runtime (elapsed active time) and change-of-state transitions. Alerts function the same as for the BI object. See BI Alert Notifications on page 5-39 for more information. The following subtopics apply to MSI alarming: MSI Alarm Detection MSI Alarm Notification MSI Alarm Inhibit MSI Alarm Delay

Figure 5-37 MSI objects have alarming functions with BACnet-type properties.

Note

notificationClass, eventEnable, and notifyType apply to alarm notification. inhibitTime and eventTriggerEnable are Niagara-only properties. See MSI Alarm Inhibit.

Alert properties define alert notification, which includes change-of-state alerts and runtime (activeTime) alerts.

The alarmValues and faultValues properties specify which states are offnormal, meaning alarm detection.

MSI Alarm Detection

Several properties on the Alarm Setup tab determine whether an alarm condition is detected by the MSI object. In order of relative importance, these properties include: alarmValuesState(s) in which the MSI is considered offnormal (inAlarm). The object shape and its statusOutput are red during this state. faultValuesState(s) in which the MSI is considered in fault (inAlarm, fault). The object shape and its statusOutput are orange during this state. timeDelayOptional time period that must be met before any alarm state change occurs with the object. See MSI Alarm Delay on page 5-108.

5106

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects MultistateInput

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. 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: notificationClassMust match an existing notificationClass object in the stations notificationServices container. The default class is zero (0). eventEnableFlags 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. notifyTypeEither 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 clients GetAlarmSummary request, the station reports BACnet-exposed objects currently in alarm only if their notifyType properties are set to alarm.

Note

alarmTextText 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. Whenever the statusInhibit input is linked, the objects 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.

Note

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

5107

Chapter 5 MultistateInput

Control Objects

Figure 5-38

Alarm inhibit feature requires linking to the statusInhibit input.

Upon a false-to-true (active) transition, the objects inhibitTime period becomes effective. Until this period expires, the object remains inhibited from any alarm status change. inhibitTime = 00:00:30 (30 seconds)

Whenever a logic false (inactive) is at the statusInhibit (sInh) input, the MSI object cannot change status to (or from) an alarm condition.

After the inhibitTime period expires, the object is capable of changing alarm status to (or from) alarm.

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 objects 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 objects 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 Alert Notifications

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.

5108

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects MultistateInput

MSI object alert subtopics include: Alarm Setup Properties for Both Alert Types Change-of-State (COS) Alerts Runtime (Active Time) Alerts

Alarm Setup Properties for Both Alert Types

Alarm Setup properties that apply to both types of MSI alerts (runtime and COS) are: alertNotificationClassMust match a notificationClass object in the notificationServices container. The default is 0, the same default for alarms. periodicAlertsDetermines 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. alertTextAny 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 to (or from) the Off state (meaning the first stateText entry) increments the objects COS counter by 1. For example, assuming the objects COS counter begins at 0, if the input changes from Off-to-On-to-Fast, then back to On and finally to Off, the COS count will be 2only transitions to or from Off are counted. 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 objects resetChangeOfStateCountTrigger input, if needed. Properties on the Alarm Setup tab that apply to COS alerts include:

changeOfStateAlertLimitInteger 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 MSI object automatically accumulates runtime, that is, elapsed active time. Runtime accumulates for any defined state except the Off state (first stateText entry). 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 integerStatusType data species). Runtime is resettable (to 0) for any JDE user with Admin-level command rights. Runtime can also be reset using a Command object linked to the objects resetElapsedActiveTimeTrigger input, if needed. Properties on the Alarm Setup tab that apply to runtime alerts include:

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

5109

Chapter 5 MultistateInput

Control Objects

activeTimeAlertLimitAmount 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

Figure 5-39 shows two examples of MSI objects in use.

MultistateInput usage examples.

MSI object

This MSI object receives an integer value from a DMS shadow object configured to poll for the COND (condition) element of an AI point. The MSI object equates the integer values to the corresponding condition states. In addition, different states can be defined as alarmValues and faultValues. This can be useful when the output of the MSI object is linked to a Gx object such as a GxText or GxInteger. This permits alarm indication by color (and optionally, if desired, by flashing).
The stateText property of the MSI is configured to match the COND element enumerations possible for DMS analog points. DMS strings were used here, but any descriptors could be entered. On the Alarm Setup tab of the MSI objects property sheet, different states can be defined as alarmValues and faultValues.

stateText values must be contiguous and no higher than 7.

In this example, an MSI object is linked to a Program object written to link to Lon Devices with an NVO implemented with SNVT_lev_disc. The Program object has an input (sIn) using LonLevDiscEnum (data species) and an output of IntegerStatusType. In this case, the output of the MSI is using the defaultInput (off), as the statusInput is receiving the 255 integer value representing a null value.

stateText is defined to represent the SNVT_lev_disc state enumerations.

The defaultInput value is on the MSI objects Config tab.

5110

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects MultistateOutput

MultistateOutput
Quick reference for all properties: Table A-50 Inputs
priorityArray statusInput

Default Object Shape

Outputs
statusOutput prioritizedOutput

abbrev: MSO MultistateOutput (MSO) objects provide a prioritized multistate output signal to other control logic. States are signaled as integers. Typically, MSOs are used to provide control of a multistate device, such as a 3-speed or 4-speed fan. A statusInput is available to use for object alarming, based upon the received multistate feedback signal.
Note: Upon any link change (add or delete

All Inputs / Outputs

Inputs Outputs
eventTrigger statusCOSCount* executeTrigger statusInhibit resetCOSCountTrigger* resetElpActTimeTrigger* priorityArray statusInput statusElpActTime* COSTrigger* COSAlertTrigger* ElpActAlertTrigger* presentValue statusOutput prioritizedOutput *abbreviations, see chart below statusFeedbackOutpu t booleanStatusFbOut* *abbreviations, see chart below

any link) to an MSO object, commands at priority-slots (1-16) that were received from priorityArray links are momentarily cleared. The priorityArray input is now immediately rescanned; any input command found remains effective at the output. As with Niagara AI, AO, BI, BO, and MSI1 objects, you can expose any MSO1 object in the station as a BACnet object. In addition to BACnet-type multistate functions, the MSO object collects runtime (elapsed active time) and counts COS (changes-of-state). Based upon configurable limits, the object can be set to generate alerts for both runtime levels and COS counts. Trigger inputs allow the clearing of the COS count and the runtime value. Trigger outputs are available for each COS, COS alert, runtime alert, and event.
Note: Runtime accumulates during any

Input / Output Property Reference for MSO Object

(only input and output types, see Table 5-26 for all properties)

Type Label
input exe sInh resetCt resetElp pIn sIn eventTr sCnt sCnt cosT cosAlrt elActAlr present sOut pOut sFbOut bsFbOut

Property Name
executeTrigger statusInhibit resetChangeOfStateCountTrigger resetElapsedActiveTimeTrigger priorityArray statusInput eventTrigger statusChangeOfStateCount statusElapsedActiveTime changeOfStateTrigger changeOfStateAlertTrigger elapsedActiveTimeAlertTrigger presentValue statusOutput prioritizedOutput statusFeedbackOutput booleanStatusFeedbackOutput

Data Species
TriggerType BooleanStatusType TriggerType TriggerType IntegerPriorityArrayType IntegerStatusType TriggerType IntegerStatusType IntegerStatusType TriggerType TriggerType TriggerType int IntegerStatusType IntegerPriorityType IntegerStatusType BooleanStatusType

output

state except Off (first stateText entry). The COS count increments only upon a transition from (or to) the Off state.
Parent Dependencies: None (any

container).
Resource Count Range: 93 to 161

1. Some state limitations apply. See stateText Considerations, page 5-116.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

5111

Chapter 5 MultistateOutput

Control Objects

Trigger Properties

The MSO object has the standard input property, executeTrigger, (typically not used) and also 2 other trigger-type inputs: resetChangeOfStateCountTriggerAny received trigger pulse clears the objects current count of COS (changes of states), resetting it to zero (0). resetElapsedActiveTimeTriggerAny received trigger pulse clears the objects accumulated runtime (elapsed active time), resetting it to zero (0.0). In addition, there are 4 available trigger-type outputs, described as follows:

eventTriggerFires upon each event transition (to-offnormal, to-fault, to-normal) that has been specified in the property eventTriggerEnable. changeOfStateTriggerFires upon each change-of-state at the statusOutput. changeOfStateAlertTriggerFires 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). elapsedActiveTimeAlertTriggerFires each time a runtime alert is issued (activeTimeAlertLimit value has been reached, or a multiple of this value if periodicAlerts is set to True). As needed, these trigger-type inputs and outputs can be linked to other objects that have properties using TriggerType data species.

Commands
The MSO object provides a right-click command menu with these commands (default names are shown, these are modifiable using the commandTags property): SetTo set an output state at the Manual level (8). Default choices are Off, On, or Fast. Requires Command, Std privileges. AutoTo clear an output state (e.g. Off, On, Fast) at the Manual level (8). Emergency SetTo set an output state at the Emergency level (1). Default choices are Off, On, or Fast. Requires Command, Emer privileges. Emergency AutoTo clear an output state (e.g. Off, On, Fast) at the Emergency level (1).

For a JDE user with Command, Admin privileges, the following object commands are available from the menu bar (for example, Command > resetActiveTime):

resetAckedTransitionsSets all three flags in the ackedTransitions property (to-offnormal, to-fault, to-normal). Rarely required, see the JDE Command section on page 5-11 for more information. resetChangeOfStateCountSets the changeOfStateCount property value to zero (0), clearing the COS count. resetActiveTimeSets the elapsedActiveTime property value to 00:00:00 (Hr:Min:Sec), clearing the accumulated runtime. setChangeOfStateAlertLimitAllows editing of the changeOfStateAlertLimit property value (Alarm Setup property). setRuntimeAlertLimitAllows editing of the activeTimeAlertLimit property value (Alarm Setup property).

5112

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects MultistateOutput

Properties
Table 5-26 MultistateOutput (MSO) object properties.

Tab Property Name

objectType, statusFlags, description eventState, reliability, outOfService, ackedTransitions toOffnormal, toFault, toNormal, presentValue Status changeOfStateTime changeOfStateCount

Description
See Table 5-3 on page 5-8 for information on these properties common to all control objects. See Table 5-4 on page 5-12 for information on these properties common to all event-type control objects.

Valid Values

Default

Notes

presentValue is always read-only.

Read Only: Shows a date/timestamp for the last COS (change of state). Read Only: Shows the total number of changes of state that have occurred since the last COS count reset (clear). Read Only: Shows a date/timestamp for when the COS count was last cleared. Read Only: Shows accumulated runtime (elapsed active time) in Hr:Min:Sec. Read Only: Shows a date/timestamp for when the accumulated runtime (elapsed active time) was last cleared. Read Only: Shows defined states present on each of the 16 priority level slots for the priorityArray (pIn) input. Read-Write: Defines the output state when all 16 priority level slots have an auto. Read Only: Indicates if an interstart delay is currently active (True) or not (False).

valid timestamp or null (none) integer value

null 0

Trigger-type inputs can be used to clear COS and runtime values. COS and runtime properties have no BACnet visibility if the object is exposed as BACnet (these are not included in standard BACnet multistate object definitions).

timeOfStateCountReset elapsedActiveTime timeOfActiveReset

valid timestamp or null (none) Time period up to 9999:99:99 valid timestamp or null (none)

null 00:00:00 null

priorityArray (input: pIn) Priorities relinquishDefault inInterstartDelay executeParameters foreignAddress

<state n> or auto, levels 1 to 16 <state n> False, True

auto 1 to 16 Off False normal, output -1 Must be a unique number among all MultistateOutput objects in station.

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: BACnet usage only. Set to a positive integer for this object to appear as a BACnet Multi-state Output object to other BACnet devices. See foreignAddress, page 5-9, and also stateText Considerations, page 5-116. 0 to 4194302 or -1 (not exposed)

Config

membershipGroups restartDisable

Read-Write: (Future use only.) Read-Write: Determines whether the output is automatically set to the previous state following a station restart (reboot) or power failure. If set to True, an Off state at manual level (8) is issued following such an occurrence.

niagaraR2 False, True

niagaraR2 False

Leave at default.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

5113

Chapter 5 MultistateOutput

Control Objects

Table 5-26

MultistateOutput (MSO) object properties. (continued)

Tab Property Name

minimumOnTime

Description
Read-Write: Upon a command from the Off state to any other state, results in the state command to be stored at the Minimum On Off priority level (6) for this time (Hr:Min:Sec). Read-Write: Upon a command from any other state to the Off state, results in the Off command to be stored at the Minimum On Off priority level (6) for this duration (Hr:Min:Sec). Read-Write: Specifies whether the minimum On time is applied between all states (True) or only from the Off state (first stateText entry) to any other state (False). Read-Write: Defines the time period (Hr:Min:Sec) that the output is held in the Off state following a command to any other state. Used to prevent multiple simultaneous starts. Applies to commands at all priority levels except Emergency (1). See Table 5-5 on page 5-13 for information on these properties common to all event-type control objects.

Valid Values
Any practical time needed.

Default
00:00:00

Notes

minimumOffTime Config, cont.

Any practical time needed.

00:00:00

perStateMinimum OnTime

False, True

False

interstartDelayTime

Any practical time needed.

00:00:00

timeDelay, notificationClass, eventEnable, notifyType, inhibitTime*, eventTriggerEnable, alarmText inhibitTime

* See specific details on inhibitTime, the next property.

Read-Write: Duration (Hr:Min:Sec) of the alarm inhibit timer, which applies only if the objects input statusInhibit is linked. The purpose is to prevent nuisance alarms on equipment startup and shutdown. The inhibitTime is triggered by a transition at the statusInhibit input.

any practical value in Hr:Min:Sec

00:00:00 (no inhibit)

Alarm Setup

A minimum value of 1 second (00:00:01) is recommended whenever the statusInhibit input is linked. Alarm processing compares the statusInput (feedback) state to priorityArray (command) state.

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. changeOfStateAlertLimit Read-Write: Number of COS occurrences that generate a changeOfStateCount alert. activeTimeAlertLimit Read-Write: Amount of runtime (elapsed active time), in Hr:Min:Sec, that generates a runtime alert. Read-Write: The assigned notification class number, used in routing alerts. A NotificationClass object using the same number should exist in the NotificationService objects container. Positive integer Any value up to 9999:59:99 (Hr:Min:Sec) 0 to 8388607 0 0 00:00:00

alertNotificationClass

5114

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects MultistateOutput

Table 5-26

MultistateOutput (MSO) object properties. (continued)

Tab Property Name

periodicAlerts Alarm Setup, cont.

Description
Read-Write: Determines if both COS count alerts and runtime alerts are periodically generated each time the respective limit is reached. Read-Write: Text descriptor included in either a COS count alert or runtime alert. If left at the default hyphen (-), the Station objects alertText is used.

Valid Values
False, True

Default
False

Notes

alertText

Any text string, including spaces and mixed case characters. Unique integer, 8 or more states are allowed. For BACnet, see the value description.

(hyphen)

position stateText

Read-Write: See position, page 5-9. Read-Write: Defines all possible discrete states by value-name pairs. Each state has two fields:

0 = Off 1 = On 2 = Fast default = Error State descriptors are used in linked MultistateLog object collections and also can display at a linked GxText object. The default state signals an invalid input value.

valueUnique integer. If BACnet

compatibility is needed, states must be contiguous starting at 1. tagText to describe the associated discrete state. State descriptors are used at the statusOutput, presentValue, alarm and fault values. commandTags Read-Write: Defines the labels used to list commands that appear on the right-click command menu. Default values for commandTags are: Set (manualSet) Auto (manualAuto) Emergency Set (emergencySet) Emergency Auto (emergencyAuto) When the user selects a manualSet or emergencySet command, a drop-down selection list of states shows the stateText entries. For example, Off, On, or Fast. minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInhibit (input sInh) Engineering statusChangeOfState Count (output sCnt) statusElapsedActive Time (output sElpT) statusInput (input sIn) statusOutput (output sOut) Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Current boolean state and status of the statusInhibit input. Read Only: Current value and status of the COS count. Available as a IntegerStatusType output. Read Only: Current runtime (elapsed active time), totaled in seconds. Available as a IntegerStatusType output. Read Only: Current discrete state and status received on the statusInput. Read Only: Current discrete state and status of the statusOutput.

Visual

Any desired text string, including spaces and numerals.

See descrip.

If a tag is blank (no characters), the command is not available on the command menu.

false, true : {status flags} <count> : {status flags} <seconds> : {status flags}

false : {ok} 0 : {ok}

0 : {ok}

Status property elapsedActiveTim e shows this value in Hr:Min:Sec.

<dis. state> : {status flags} <dis. state> : {status flags}

Off : ok Off : ok

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

5115

Chapter 5 MultistateOutput

Control Objects

Table 5-26

MultistateOutput (MSO) object properties. (continued)

Tab Property Name

prioritizedOutput Engineering, cont. (output pOut) statusFeedbackOutput (output sFbOut)

Description
Read Only: Current discrete state and priority level of the prioritizedOutput. Read Only: Current discrete state and status of the feedback supplied on the statusInput. If statusInput is not linked, this output always mirrors statusOutput. Read Only: Current command state as a boolean, either false if command is Off or true if any other command. Status follows statusFeedbackOutput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

Valid Values
<dis. state> : @ <pri. level> <dis. state> : {status flags}

Default
Off : @ def Off : {ok}

Notes

booleanStatus FeedbackOutput (output bsFbOut)

false, true : {status flags}

false : {ok}

Security

securityGroups

General, 7 others

General

MultistateOutput Notes
The MSO object is typically used for control of a multistate device or mode of operation. In some cases, a MSO object is used to directly control a physical output of a remote device, represented by a shadow object.

Routinely Configured MSO Properties

The three most typically configured properties for a MSO object are: relinquishDefault (Priorities tab)Defines the MSO objects 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 objects possible discrete (integer) states and the associated text descriptors that appear at the objects 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 objects and 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 objects 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).

5116

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects MultistateOutput

Figure 5-40

If exposing as BACnet, the MSO object must have stateText with contiguous values, and with no zero (0).

Default stateText values for a Niagara MSI and MSO object include the non-compliant 0 value.

This MSO object has had its stateText property edited to remove the 0 value. Other values were modified and added as needed, using the StateText Guidelines (below).

StateText GuidelinesIf you follow these guidelines when assigning stateText values, 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. Assign state numbers contiguously (without skipping a number). This contiguous restriction is from BACnet.

2.

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 FeatureA 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. There is no default state equivalent for a BACnet Multistate Output object. The MSO object includes several Config properties that directly determine the control operation of its main outputs (prioritizedOutput and statusOutput).

Note

Control Related Properties

restartDisableDetermines 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).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

5117

Chapter 5 MultistateOutput

Control Objects

minimumOnTimeDefines the time period in which any non-Off command at the Minimum On Off priority level (6) will exist, as a result of any command transition from Off to that state. This can prevent equipment short-cycling. minimumOffTimeDefines the time period in which an Off command at the Minimum On Off priority level (6) will exist, as a result of any command transition from non-Off to Off. This can prevent equipment short-cycling. perStateMinimumOnTimeSpecifies whether the minimum On time is applied between all states or only from Off (0) to any other state. False (the default), minimum On applies only from Off to any other state. If set to True, minimum On applies to all transitions between states. interstartDelayTimeDefines a delay period, in seconds, before a command from Off to any other state becomes effective. Does not apply with a command to Off. 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 MSO-controlled loads, which might otherwise cause energy (demand) spikes.

MSO Command Tags

Figure 5-41

MSO objects are typically configured with custom command labels, using the commandTags property, on the Visual tab of the property sheet (Figure 5-41).

The commandTags property (Visual tab) determines how (and which) commands are listed.

Editing commandTags allows more meaningful right-click menu labels on the right-click menu than the default values, for example, Change Speed vs. Set. In addition, you can clear any tags to make those commands unavailable (Figure 5-41). This is often done for emergency-level commands, for example.

5118

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects MultistateOutput

MSO Alarming Functions

Alarm detection for a MSO object requires a separate link to a statusFeedback input, which receives the actual integer value of the controlled device. This state is compared against the current controlled/commanded state, and can result in an alarm (if the two integer values are different). See Figure 5-42. The following subtopics apply to MSO alarming: MSO Alarm Inhibit MSO Alarm Delay MSO Alarm Notification Often, another input is linked as well: statusInhibit (sInh), coming from the controlling source. See the MSO Alarm Inhibit section on page 5-120.

Figure 5-42

MultistateOutput alarming.

An MSO alarm condition is when the control command state is different from the feedback state at the statusInput input (feedback).
Feedback signal linked to statusInput (sIn) An alarm occurs upon any mismatch between command and feedback.

Note

The MSO object can also generate alerts based on configurable limits for runtime (elapsed non-Off time) and change-of-state transitions. MSO alerts operate the same as for BinaryInput (BI) objects. See BI Alert Notifications on page 5-39. Figure 5-15 shows the grouping of Alarm Setup properties for a MSO object.
Figure 5-43 MSO objects have alarming functions with BACnet-type properties.

timeDelay specifies an alarm delay period for any sensed alarm condition. notificationClass, eventEnable, and notifyType apply to alarm notification. inhibitTime and eventTriggerEnable are Niagara-only properties. See BO Alarm Inhibit.

Alert properties define alert notification, which includes change-of-state alerts and runtime (non-Off time) alerts.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

5119

Chapter 5 MultistateOutput

Control Objects

MSO 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. Whenever the statusInhibit input is linked, the objects inhibitTime property should hold a defined value (not the default of 00:00:00 in Hr:Min:Sec).

Note

Figure 5-44

MultistateOutput statusInhibit input and inhibitTime property.

statusInhibit (sInh) link (BooleanStatusType data species)

The statusInhibit input is typically linked to the same source that is controlling the MSO. When the MSO is commanded from Off to any other state, any alarm status change is inhibited for the specified inhibitTime, in seconds. When commanded to Off, any alarm status change is inhibited for 3 times the inhibitTime, in seconds.

priorityArray input link for control command Example: inhibitTime = 30 (seconds) Feedback signal linked to statusInput (sIn) When commanded to Off from any other state, the alarm inhibit delay will be 90 seconds.

MSO Alarm Delay

Alarm delay is a BACnet-type property, separate from the alarm inhibit mechanism. It means that the objects 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. 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.
Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Note

5120

Chapter 5

Control Objects MultistateOutput

In the MSO object, properties on the Alarm Setup tab relating to alarm notification are: notificationClassMust match an existing notificationClass object in the stations notificationServices container. The default class is zero (0). eventEnableFlags 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. notifyTypeEither 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 clients GetAlarmSummary request, the station reports BACnet-exposed objects currently in alarm only if their notifyType properties are set to alarm.

alarmTextText descriptor sent as an alarm record field whenever a to-offnormal or to-fault event transition occurs (not a to-normal).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

5121

Chapter 5 MultistateOutput

Control Objects

Examples
Figure 5-45

Figure 5-45 shows two examples of MultistateOutput objects in use.

MultistateOutput examples.

This MSO object provides a command menu for setting the HVAC mode of a LON device. The MSO output is linked to a Program object, which produces an enumerated output. The command menu includes the 13 possible enumerations for SNVT_hvac_mode. The Program object has an input (sIn) using integerStatus (data species) and an output of LonHvacModeEnum. The output of the Program object is linked to an NVI of the LON device that uses SNVT_hvac_mode.

MSO objects right-click command menu

Program object

LON device with NVI using SNVT_hvac_mode

The MSO objects stateText property defines the integer outputs and associated command states.

This MSO object was created in a DMS integration to command a DMS 2S point (2-speed start-stop). When using the PointListManager to create a Cmd:Write, both the DMS shadow object and the MSO are created together, with links between them already established. In this example, an MSI object has been added to display Off, On and Fast for the integer output produced by the DMS shadow object.

MSO object

Shadow object for DMS 2S point

Right-click command for MSO object

5122

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects MultistateOverride

MultistateOverride
Quick reference for all properties: Table A-51 Inputs
(none)

Default Object Shape

Outputs
statusInOverride prioritizedOutput

abbrev: MSOvrd A MultistateOverride (MSOvrd) object provides a prioritized, discrete-level (Off/On/Fast) output signal that is controlled from a right-click command menu. Commands include starting a timed-override for a specified duration, canceling an override, and selecting the override state. The priority level of an override is configurable to any level (from 1 to 16). In addition, text descriptors for the different discrete states are editable. This allows the right-click command menu to show commands as needed, for example, override Occupied and override Standby instead of override Off and override Fast.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs
executeTrigger overrideTrigger

Outputs
inOverride statusInOverride prioritizedOutput

Input / Output Property Reference

(only input and output types, see Table 5-27 for all properties)

Type
input output

Label
exe override inOverr sInOv pOut

Property Name
executeTrigger overrideTrigger inOverride statusInOverride prioritizedOutput

Data Species
TriggerType TriggerType boolean BooleanStatusType IntegerPriorityType

container).
Resource Count Range: 39 to 55 Trigger Properties

The MSOvrd object has the standard input property, executeTrigger, (typically not used) plus an additional trigger-type input: overrideTriggerAny received trigger pulse starts an override, at the configured overrideValue (state), 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 at the configured overrideValue (state), but not any other states. The linked Command object would also not allow a user to cancel an override, or change its duration. An override would be started each time a trigger pulse is received at this input.

Commands
For any user with Command, Std privileges, an MSOvrd object provides a right-click command menu with these commands: overrideTo start an override and specify the duration, in minutes. cancelTo cancel any current override. setOverrideValueTo select the discrete state of the override. A drop-down selection list provides the available discrete states.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

5123

Chapter 5 MultistateOverride

Control Objects

Properties
Table 5-27 MultistateOverride (MSOvrd) object properties.

Tab Property Name

Status objectType, statusFlags, description inOverride (output: inOverr) executeParameters foreignAddress membershipGroups priorityForWriting

Description
See Table 5-3 on page 5-8 for information on these properties common to all control objects. Read-Only: Indicates if an override is currently in effect (True) or not (False). Available as a linkable output.

Valid Values

Default Notes

False, True

False

boolean data species.

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: Does not apply to this object. Read-Write: (Future use only.) Read-Write: Defines the priority level used at the prioritizedOutput during an override. When the override expires or is canceled, this level is autoed. -1 niagaraR2 Any priority level, from 1 to 16 Any positive integer from 1 up to 32-bit limit.

normal, input -1 Manual Operator (8) 60 This override time is displayed (and can be adjusted) each time an override is issued. Leave at default. niagaraR2 Leave at default.

overrideTime (min) Config

Read-Write: Defines the duration of an override, in minutes. When an override is commanded, this time is initialized and begins counting down. If not canceled or re-initiated, the override will last this duration.

overrideValue

Read-Write: Defines the last given override state. This value was issued at the priority level defined in the priorityForWriting property.

(any of the stateText tags)

Off

Note: Any pulse received at the overrideTrigger causes an override at this state (one of the stateText values).
position stateText value, tag Visual Read-Write: See position, page 5-9. Read-Write: Defines all possible discrete commands by value-name pairs. Each command state has two fields: Unique integer, with up to 8 states allowed. For BACnet, see the value description. 0 = Off 1 = On 2 = Fast default = Error

Editing this from the property sheet typically makes no difference (the objects secondary command menu always allows overrides to any specific state). State descriptors are used in the right-click (secondary) popup menu to setOverrideValue. The default state signals an invalid input value.

valueUnique integer. If BACnet

compatibility is needed, states must be contiguous starting at 1 (1 to 8, max.). tagText to describe the associated discrete state. Descriptors are used in the setOverrideValue command menu. minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInOverride (input sInOv) Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows if an override is active and also the status of the object. Available as a default object output.

Engineering

Inactive, Active {status flags}

Inactive : {ok}

booleanStatusType data species

5124

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects MultistateOverride

Table 5-27

MultistateOverride (MSOvrd) object properties. (continued)

Tab Property Name

Security Engineering, cont. prioritizedOutput (input pOut)

Description
Read Only: Shows the state and priority level currently on the prioritizedOutput. Available as a default object output.

Valid Values
Inactive, Active @ <pri. level>

Default Notes
Inactive : @ def IntegerPriorityType data species

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

General, 7 others

General

MultistateOverride Notes
There are two basic ways to use an MultistateOverride object: Available directly to userssee Directly Available. Available through a Command objectsee Used with a Command object.

Directly Available The right-click menu for an MultistateOverride object provides the user a list of
commands, providing the ability to: Initiate an override, specifying the duration in minutes. Cancel an override. Change the state for an override (setOverrideValue).

Note

A setOverrideValue command does not affect an override in progress.

If changed, the duration of override and/or the override value are stored in the objects Config properties. These values become the defaults for the next command, and are seen when the commands popup control appears.

Used with a Command object

In some scenarios, direct access to a MultistateOverride object may provide too much user control for changing override parameters (duration times and override states). In this case, linking a Command object to the objects overrideTrigger may be better. In this configuration, a user can be given access to the Command object (but not directly to the MultistateOverride object). This allows the initiation of an override, but no other control (including canceling an override). The outputTrigger text property of the Command object should be given a descriptive label for the configured override action (Figure 5-8).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

5125

Chapter 5 MultistateOverride

Control Objects

Figure 5-46

Control from a Command object allows override initiation but no other actions.
Command object linked to overrideTrigger input.

outputTriggerText of Command object.

Other Notes
Figure 5-47

The standard set of library (lib) Program objects includes an object used to derive the remaining override time. Two links are required to the MultistateOverride object.

RemainingOverrideTime object in Local Library (tridiumx/lib/programs/hvac).

Local Library opened with lib JAR expanded to reveal programs folders (hvac). Copy the object (sns file) and paste it into your station as needed.

Copied RemainingOverrideTime object.

Remaining override time value. Can be linked to a GxText to display to time to users.

Two links are required between the AnalogOverride object and the Program object (RemainingOverrideTime): overrideTime to overrideTime statusInOverride to statusInOverride

5126

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects PeriodicTrigger

PeriodicTrigger
Quick reference for all properties: Table A-63 Inputs
(none shown)

Default Object Shape

Outputs
(none shown)

(abbrev: Ptrig) PeriodicTrigger objects are one of several trigger-type objects. This object provides a single trigger output that fires each time a continuously repeating interval elapses. A typical use is to perform trigger-initiated functions with a log-type object (do clear, do archive). Other trigger-type objects include the DateTimeTrigger and Command objects.
Parent Dependencies: None (any
Type
input output

All Inputs / Outputs

Inputs
executeTrigger

Outputs
trigger

Property Quick Reference for PeriodicTrigger Object

(only input and output types, see Table 5-28 for all properties)

Label
exe trigger

Property Name
executeTrigger trigger

Data Species
TriggerType BooleanPriorityType

container).

Resource Count Range Trigger Properties

36 to 46 The Ptrig object has the standard input property, executeTrigger, (never used) plus an additional trigger-type output: triggerThe business end of this object. Fires at the continuously repeating interval defined by the Config property triggerPeriod. The purpose of this object is to link this output to other objects trigger-type inputs, as needed, to perform a periodic function.

Commands
For a user with Command, Std privileges, the object provides the following right-click command:

resetRestarts the periodic interval (note this does not fire the trigger output.)

Properties
Table 5-28 PeriodicTrigger object, important properties.

Tab Property Name

Status objectType, statusFlags, description nextTriggerTime executionParameters Config foreignAddress membershipGroups triggerPeriod

Description
See Table 5-3 on page 5-8 for information on these common object properties. Read Only: Shows a date/timestamp for the next calculated trigger pulse. See execution Parameters, page 5-9. Read-Write: Does not apply to this object. Read-Write: (Future use only.) Read-Write: Repeating interval (Hr:Min:Sec) at which the trigger output fires.

Valid Values

Default

Notes

-1 niagaraR2 Interval up to 99999:99:99

normal, processor -1 1:00:00 (hourly) Leave at default. niagaraR2 Leave at default.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

5127

Chapter 5 PeriodicTrigger

Control Objects

Table 5-28

PeriodicTrigger object, important properties. (continued)

Tab Property Name

Security Engineering Visual position

Description
Read-Write: See position, page 5-9.

Valid Values

Default

Notes

minExecuteTime, See Table 5-3 on page 5-8 for information on maxExecuteTime, these common object properties. averageExecuteTime,u serData securityGroups Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

General, 7 others

General

PeriodicTrigger Notes
The PeriodicTrigger can be used whenever a constantly repeating command is needed at one or more objects that have triggerType inputs. Likely candidates include log type objects, and/or log-service objects. For example a PeriodicTrigger can be linked to the doArchiveTrigger input of the AuditLogService, to force an archive at some regular, repeating interval.

5128

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 5

Control Objects Totalizer

Totalizer
Quick reference for all properties: Table A-75 Inputs
statusInput

Default Object Shape

Outputs
statusTotal

abbrev: Total A Totalizer (Total) object totalizes the value received on a single floating-point input. Totalization can be configured to use either a minutely or hourly basis. A Totalizer object is typically linked to a float value that represents a rate, such as electrical power (kW) or material flow (for example, gallons per minute). The Totalizer then accumulates consumption in kWh or gallons.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs
executeTrigger statusInput resetTotalTrigger

Outputs
statusTotal updateOutputTrigger

Property Quick Reference for Totalizer (Total) Object

(only input and output types, see Table 5-29 for all properties)

container).
Resource Count Range: 42 to 62

Type
input

Label
exe sIn resetTr sOut updateTr

Property Name
executeTrigger statusInput resetTotalTrigger statusOutput updateOutputTrigger

Data Species
TriggerType FloatStatusType TriggerType FloatStatusType TriggerType

output

Trigger Properties

The Totalizer object has the standard input property, executeTrigger, (typically never used) plus an additional trigger-type input: resetTotalTriggerAny received trigger pulse clears the objects current statusTotal output, resetting it to zero (0). The object restarts totalizing. In addition, the Totalizer provides a trigger-type output:

updateOutputTriggerFires each time the statusTotal output value changes. This output can be linked to any trigger-type input, as needed.

Commands
For a JDE user with Command, Admin privileges, this menu bar command is available (the objects property sheet must be displayed):

Commands > resetTotalClears the value at the statusTotal output, resetting it to zero (0.0). The object starts totalizing again.

Properties
Table 5-29 Totalizer object properties.

Tab Property Name

objectType, statusFlags, description, presentValue, executeParameters Config foreignAddress membershipGroups Status

Description
See Table 5-3 on page 5-8 for information on these common object properties.

Valid Values

Default

Notes
presentValue can be written.

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: Does not apply to this object. Read-Write: (Future use only.) -1 niagaraR2

normal, input -1 niagaraR2 Leave at default. Leave at default.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

5129

Chapter 5 Totalizer

Control Objects

Table 5-29

Totalizer object properties. (continued)

Tab Property Name

defaultInput

Description
Read-Write: Acts as the statusInput value whenever that input has status flags of either fault or down, or if it is not linked. Read-Write: Engineering units for the totalized output, for display purposes. Choose from a logical grouping, then a specific unit. Read-Write: Defines the interval of totalization. Typically, this relates to the time interval of the rate input. Read-Only: Shows the date/timestamp for when the current totalization period started (time of the last resetTotal command). Read-Write: See position, page 5-9. Read-Write: Sets decimal position of the output from 0 to 6 places, and optionally force (+) sign for positive values.

Valid Values
valid float

Default
0.0

Notes

units Config, cont.

Select any (BACnet-type unit choices) minutely, hourly

Other, no_units

For selections see About Units, page 5-6. For power inputs of kW or MW, choose hourly.

totalizationInterval

minutely

startTime

null

position Visual decimalFormat

0 to 6, (+) sign, no (+) sign

2, no (+) sign

Engineering

minExecuteTime, These properties are common to all control maxExecuteTime, objects. For more information, see Table 5-3 averageExecuteTime, on page 5-8. userData statusInput (input sIn) statusTotal (output sTot) Read Only: Current float value and status at statusInput. Read Only: Current calculated float value and status output at the statusOutput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

<f. value> {status flags} <f. value> {status flags} General, 7 others

0.0 {ok} 0.0 {ok} General

Security

securityGroups

Totalizer Notes
The Totalizer object is typically used for totalizing energy, material consumption, and refrigeration (BTU) tonnage. Figure 5-48 shows an example of a Totalizer object used for totalizing ton-hours.
Figure 5-48 Example Totalizer object for BTU Tons-hours calculation.

This Totalizer object receives a BTU Tons value calculated by a Program object.

The totalizationInterval is set to minutely, and the output (units) are in ton_hours.

5130

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

CHAPTER

Apps Objects
This chapter describes each of the standard Niagara Apps objects, that is, those provided in the apps folder of the tridium JAR file. General information on apps objects is provided first, as follows: About Apps Objects BACnet Heritage Selecting Apps Objects Common Apps Object Things Trigger Properties Common Apps Object Properties Log Objects Logs (Samples) Log Storage Log Object Views Common Log Properties

Individual apps object descriptions follow, arranged alphabetically as follows:

AdminTool AnalogLog BinaryLog Calendar IntegerLog MultistateLog Program Schedule StringLog

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

61

Chapter 6 About Apps Objects

Apps Objects

About Apps Objects

Apps objects provide a variety of system functions that are linkable to a stations control logic, including: Global schedule operation of binary-controlled loads, including holiday and special-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 BACnet server 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). For detailed information on Niagara and BACnet, refer to the Niagara BACnet Integration Reference document.

Refer to

62

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects About Apps Objects

Selecting Apps Objects

Until you become familiar with the different Niagara apps objects, it may not be immediately clear which types provide common functions. The table below crosses some standard system routines to the appropriate object type. Application Routine Needed

Niagara Apps Object Used AnalogLog BinaryLog IntegerLog MultistateLog StringLog

Logging or trending of any:

Floating-point value Boolean state (On/Off, etc.) Integer value Multistate value (Off/On/Fast, etc.) String (alphanumeric text, or text results of most any type output)

Holiday definitions Scheduling control Search and replace routine for property values in the stations database.

Calendar Schedule AdminTool

Any custom application routine or control Program function routine not available by using other apps objects or standard control objects.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

63

Chapter 6 Common Apps Object Things

Apps Objects

Common Apps Object Things

Like control objects, apps objects have properties common to all Niagara object types, such as the status properties objectType and description. Most apps object types also include common properties that affect the objects execution, security (user access), and other common parameters. Also, when using the JDE, each apps object has a dump command for debug purposes. Rather than cover these things in detail for each object type, they are explained in this section. Several apps object types are log objects, and so have common properties. See the following the Log Objects section on page 6-7.

Trigger Properties

In this chapter, the description for each apps object type includes a Trigger Properties section that lists and describes the objects available trigger properties. executeTriggerExcept for the AdminTool and Program object, every apps 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 objects 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 apps 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 apps object (you must have the objects property sheet displayed): Commands > dumpSends data about the object to the Standard Output window, including the objects swid, handle, name, parent, properties and values, and links. 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 apps 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 objects available commands are listed in subsequent descriptions.

Note

64

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects Common Apps Object Things

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 properties for all apps objects.

Tab Property Name

objectType

Description
Read Only: The apps object type. By default, a newly added object uses this string in its name (until renamed). The full string for the object type is shown, for example, AnalogLog or Calendar.

Valid Values
See description

Default

Notes

reflects For most object types, a object type standard abbreviation for that type appears inside the objects shape (near the top). This abbreviation is noted in the individual descriptions for each apps object.

statusFlags

Status

Read Only: Current state of the objects status flags. A normal state (no flags set) is where the status flags value is {ok}, and the objects color is gray. The only status flag that can be set is:

either: {ok} (no flags) or {down}

{ok}

downThe station is down or offline.

The object s shape and outputs are yellow. description Read-Write: Permits a user-defined text descriptor for describing the object. Any printable characters, including spaces and mixed case characters, are allowed. See description

Unlike many control objects, apps objects do not have alarm states, nor do they assume alarm or fault conditions from linked inputs.

Not available for an AdminTool object. For a log object, if description is entered, it appears in the objects LogChart title. Also used to list the log in the stations log index and in the Log Selector.

execution Parameters

Read-Write: Defines the frequency and order for the object as it is executed by the stations control engine.

freq (frequency)Specifies how often the

object is executed. For most apps objects, the default frequency (normal) is acceptable. For Calendar and Schedule objects, frequency is fixed at minutely. orderSpecifies the order of execution in each cycle. On each cycle of the control engine, objects specified as inputs are processed first, then processors next, and lastly the outputs. By default, all apps objects default to the processor order.

freq: never slower normal faster fastest minutely on_trigger order: input processor output

freq: normal order: <see descrip>

This property is not available (nor applies to) an AdminTool object. Usually, default values are recommended. Frequency selections are exclusive. For example, if on_trigger is selected, the object will execute only if the input executeTrigger is linked and a trigger pulse is received on that input. For related details, see ControlEngineService Config property executionFrequency.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Config

Revised: April 20, 2004

65

Chapter 6 Common Apps Object Things

Apps Objects

Table 6-1

Common properties for all apps objects. (continued)

Tab Property Name

foreignAddress

Description
Read-Write: BACnet usage only. Exposes the Niagara object as a BACnet object.

Valid Values
See Description

Default
-1 (not used)

Notes
Not shown for an AdminTool object. Before using, the BACnet service must be installed and configured in the station.

If assigned, this Note: Currently, this property has a number must practical application only for apps object be unique in the types Calendar and Schedule (as well as station within control objects AI, AO, BI, BO, MSI, MSO). an object type (Calendar, For these object types, a valid value is from Schedule, etc.) 0 to 4194302 (BACnet maximum), or -1 if not exposed to BACnet. membershipGroups Read-Write: (Future use only.) position Read-Write: The x-y coordinates for the objects position on the JDE Workspace. Coordinate values are in pixels, and are relative to the upper-left corner of the Workspace and the upper-left corner of the object shape (including its input area). An object with a position of 0,0 is in the top left corner of the Workspace. niagaraR2 Some positive x, y value less than the parent (container) objects size property value. Near the mouse pointer when the object is first created.

Config, cont.

niagaraR2 Leave at default. Typically, you dont manually enter position values, but use the mouse to drag the object as needed on the JDE Workspace. However, if needed, you can enter values directly to tweak an objects position. Providing that the ControlEngineService was set to profileNodes, these properties show the objects execution statistics. Typically, you do not leave the ControlEngineService configured this way except for brief periods to collect these values. This properties are not available (nor apply to) an AdminTool object.

Visual minExecuteTime

Read-Write: Can show the objects minimum execution time, in milliseconds. Shows MAX_VALUE if profileNodes in the ControlEngineService was not previously set (since the last station start).

integer, 0 to n

See descrip.

maxExecuteTime Engineering

Read Only: Can show the objects maximum execution time, in milliseconds. Shows MIN_VALUE if profileNodes in the ControlEngineService was not previously set (since the last station start).

integer, 0 to n

See descrip.

averageExecute Time

Read Only: Can show the objects average execution time, in seconds. Shows 0.0 if profileNodes in the ControlEngineService was not previously set (since the last station start).

valid float

See descrip.

userData

Read-Write: Stores a user entered string. Can be used by servlets and the API for configuration information. Read-Write: Shows the security groups to which the object is assigned. A user must have the appropriate privileges in at least one security group to view and modify properties and issue commands. Refer to the Security Tab section on page 1-20 (Station object UserAdmin topic) for more details on how securityGroups settings apply.

Any desired text string for servlet/API use. Any mix of these types:

<blank>

securityGroups

General

Security

General HVAC Security Life Safety Group 4 Group 5 Group 6 Group 7

Also refer to the About Security section on page 1-21.

66

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects Common Apps Object Things

Log Objects
Five of the apps object types are log-type (log) objects, including the following:

AnalogLog BinaryLog IntegerLog MultistateLog StringLog

These objects are globally managed by the stations LogService. Each log object type has a group of common status and config properties. All log objects except the StringLog also feature graphical views for accessing log data. The following topics apply to all of the log objects:

Logs (Samples) Log Storage Location of Log Objects Log Object Views Common Log Object Properties

Logs (Samples)

Each log (sample) recorded by a log object has three main parts:

timestampWhen the sample was recorded. The format is: <time> <day-mo-year> <time zone>, for example: 12:07:49PM 25-Jun-2001 EDT (see section Timestamp notes)

valueThe value, state, or string at the log objects statusInput. statusThe corresponding input status at the statusInput. (If a StringLog, status is not recordedonly timestamp and value.)

These appear as columns in the objects list of recorded logs, shown in its LogTable view. The LogTable is accessible from both JDE and a Web browser (Figure 6-1).
Figure 6-1 LogTable view (JDE and browser) lists logs with timestamp (tstamp), value, and status.

JDE LogTable view In the case of an AnalogLog (as here), values are formatted using the objects decimalFormat setting. Browser LogTable view AnalogLog values do not use the objects decimalFormat setting, but display the full decimal component.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

67

Chapter 6 Common Apps Object Things

Apps Objects

Timestamp notes
When viewing logs, the timestamps (date, time, and time zone) always reflect the serving Niagara hosts timethat 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:
tstamp 8:00:10 15-Mar-2002 EST value status On {ok} {ok} {ok} {ok}

17:00:12 15-Mar-2002 EST Off 8:00:10 16-Mar-2002 EST On

17:00:14 16-Mar-2002 EST Off

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, the integer offset (for time zone) is -5 (EST is five (5) hours behind GMT).
2002-03-15T08:00:00.78-5 2002-03-15T17:00:12.78-5 2002-03-16T08:00:10.79-5 2002-03-16T17:00:12.78-5 true false true false On Off On Off {ok} {ok} {ok} {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 TimestampsArchives, meaning logs that have archived to a Web Supervisor station (see Archive (SQL) Storage) have a timestamp reflecting the archive hosts 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:
TSTAMP 5:00:10 15-Mar-2002 PST VALUE STATUS true {ok}

14:00:12 15-Mar-2002 PST false {ok} 5:00:10 16-Mar-2002 PST true {ok}

14:00:14 16-Mar-2002 PST false {ok}

68

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects Common Apps Object Things

Order of Logs
The LogTable view for any log object lists logs from top-to-bottom chronologically (Figure 6-2). The oldest logs are at the top; the newest are at the bottom.
Figure 6-2 Oldest logs are at the top and most recent logs at the bottom.
Oldest log

Newer logs

The same ordering occurs when viewing archived log data, that is, logs archived to the supervisor station (Figure 6-3). See Archive (SQL) Storage on page 6-10.
Figure 6-3 Archived log data also shows oldest logs first.
JDE DatabaseBrowser access Browser archive access

Note

A maximum of 2500 archived logs can be viewed. A warning appears on any request where more than 2500 log samples exist, as shown in Figure 6-3.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

69

Chapter 6 Common Apps Object Things

Apps Objects

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 datain fact, as part of the stations runtime database. Whenever a Niagara station is backed up, this includes the contents of all log objects buffers. 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 objects log buffer. All logs in the buffer are included. Archive (SQL) StorageIn 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 stations 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 supervisor station. Log samples in the objects log buffer remain unaffected. Refer also tothe DatabaseService section on page 4-15 and the LogService section on page 4-30. 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.

Note

Note

Buffer Size and Resource Count

The size of any log objects buffer is configurable (property bufferSize). The default buffer size is 60, with an allowable range from 1 to 11,5201. 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 objects 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 station database 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 Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Caution

610

Chapter 6

Apps Objects Common Apps Object Things

Location of Log Objects

In a typical multi-station job, decisions must be made where to locate log objects. Essentially, there are two competing philosophies: Log objects can reside in the Web Supervisor (Web Supervisor Storage). Log objects can reside in the JACE controllers (JACE Controller Log Storage).

Each approach has its advantages and compromises, explained below.

Web Supervisor Storage

The Web Supervisor is typically engineered to provide the browser user interface, serving up GxPages. It also runs the DatabaseService and archives locally, as it contains all log objects. This method requires an external (interstation) link from each Web Supervisor log object to the source control object in JACE controllers. These link types are supported for all log objects (AnalogLog, BinaryLog, IntegerLog, MultistateLog, and StringLog). AdvantagesThe following advantages exist with Web Supervisor log storage: JACE controllers do not require the WebUIService to see logs in chart form, because the buffered log data is being served up by the Web Supervisor. JACE-4/5 controllers, in particular, have more operating RAM and object space without the addition of log objects. Browser users are not required to sign on when accessing log data sourced from a JACE, because the log data resides locally in the Web Supervisor. Exposed (public) IP addresses are not required for each JACE controller to view log data from an Internet connectiononly for the Web Supervisor.

CompromisesThese compromises exist with Web Supervisor log storage:

For a large job with many JACE controllers, the need for a huge amount of log objects in the Web Supervisor may require a server-class PC to operate efficiently. In particular, RAM and CPU resources may be severely tested.

JACE Controller Log Storage

In a distributed log system, typically the Web Supervisor is still engineered to provide the browser user interface, serving up GxPages. It also runs the DatabaseService and is the archive supervisor, typically for all log objects in the system. However, each JACE controller contains its own log objects. Browser user access to log data can be provided, for example, from Web Supervisor GxPages. In the case of an AnalogLog, this can be done with a link between a Gx object and the statusOutput of the log object. For other log object type (which do not have a linkable output), a url can be entered in the Gx objects hyperlinkUrl property. AdvantagesThe following advantages exist with JACE controller log storage:

Logging is not dependent on network connectivity. If, for some reason, connections are lost, logging continues uninterrupted.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

611

Chapter 6 Common Apps Object Things

Apps Objects

CompromisesThese compromises exist with JACE controller log storage:

A browser user will need to sign on to a JACE before viewing its log data, following a link from a Web Supervisor graphic. If user access is needed from the Internet, this means that each JACE must have an exposed IP address, or some other proxy-type mechanism on the JACE LAN must be in place, such as a VPN (virtual private network).

Each JACE with logs that are exposed to users requires the WebUiService, in order for the log data to be displayed in the graphical (LogChart) manner. JACE-4/5 controllers, in particular, will have reduced capacity for other objects due to the RAM requirements of log objects.

Log Object Views

With the exception of the StringLog, all log objects have two special views of objects buffered log data:

LogChartShows a graph with values on the y-axis and time on the x-axis (Figure 6-4). This is the default view in the JDE, when you double-click on the object in the Tree View. If the station has the WebUIService, the chart applet provides a browser-accessible version of the LogChart. The LogChart view is not available for a StringLog object. LogTableA table listing of logs, starting with the oldest (at top) and continuing to the most recent (at bottom), as shown in Figure 6-1. This view is provided by the LogService (WebUIService is not needed for browser access).

Each log object has some number of properties on its Visual tab that control the appearance of its LogChart, for example, the chart type and color. These properties are explained in the sections ahead for each log object type.

LogChart Controls
Areas and controls in the LogChart view are the same in the JDE and Web browser (Figure 6-4 and Figure 6-5).

612

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects Common Apps Object Things

Figure 6-4

LogChart areas and main controls for a log object.

Logs (data) area. To zoom in on an area, click and drag on any x-axis portion. The area becomes highlighted while dragging. When you release the mouse button, the LogChart zooms in on the selected area. Legend area. You must toggle it to visible and click on the object (as shown) to enable most buttons in the Control Bar, at the screens bottom.

Toggles Toolbar visibility.

Toggles Legend visibility.

Toolbar area. This entire line of user controls can be toggled on and off. See Figure 6-5 for button definitions.

Toolbar buttons in the LogChart view are labeled in Figure 6-5. Note that some controls, such as Bring to Front and Save to Server are designed for use after selecting multiple log objects in the browser-accessible Log Selector dialog. The two most commonly-used toolbar buttons are shown labeled in bold (Zoom Out and Toggle Grid).
Figure 6-5 LogChart toolbar buttons and areas.

Line Plot Area Plot Averages Bar Toggle 3D Chart Min/Max Candle Bar Bring to Front Zoom Out Send to Rear Save to Server Time (x-axis) controls, including: Auto, Y (year), M (month), D (day), H (hour), M (minute, S (second) Status line Shows information about current cursor position, both in the logs (data) area and in controls areas.

Cycle Color

Toggle Grid

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

613

Chapter 6 Common Apps Object Things

Apps Objects

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 stations log selector is:
http://<host>/chart/log

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.

You can title a log selector selection. This title appears in the LogChart results. This is also this file name used (in a charts folder under the station folder) if the if the Save to Server button is used. Selection list of available log objects and/or SQL archives. Currently selected logs and/or SQL archives.

Selection buttons for listing logs by object name only, or by swid. Also, options to select archives only, or archives and logs by swid (applies if station has DatabaseService).

Chart button runs the LogChart, showing all selected items.

Text format buttons (HTML, CSV, XML) are available only if a single log or archive is currently selected.

A link to the Log Selector is included among the list of Browser View links in the stations Niagara Help Index. For more details on special browser views that apply to log objects, refer to Chapter 4, Services.

Tip

If you want to provide a link to the log selector from the LogChart view for any 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 stations database. Reference this template file in each log objects property, chartTemplateUrl, as needed.

614

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects Common Apps Object Things

Figure 6-7

Log selector link can be added to a modified chart template HTML file.
After editing and saving the HTML template file, you will need to reference its URL from any log object that needs to use it. (chartTemplateUrl property, on the Visual tab.)

In this example, a single line was added to the defaultChartTemplate.html file (before the server line): <a href=/chart/log> Run Chart Selector </a>

The browser user now has a Log Selector link when viewing the log objects LogChart.

Common Log Object Properties

Log objects have a group of Common Log Properties, similar to many used for the BACnet 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 objects description. As needed, these trigger-type inputs and outputs can be linked to other objects that have properties using TriggerType data species. Trigger InputsAside from the common executeTrigger input (rarely used), each log object has two additional trigger inputs: doArchiveTriggerA received pulse causes the log data currently held in the objects log buffer to be archived (sent to the LogService archive destination). doClearA received pulse causes all log data currently held in the objects log buffer to be cleared.

Trigger OutputsEach log object also has two trigger outputs: recordedTriggerFires upon each recorded log sample. archivedTriggerFires each time the objects log buffer is archived.

Log Object Commands

For any log object, a JDE or Web browser user with Admin-level privileges has the following right-click commands available: clearClears all log data currently held in the objects log buffer. archiveArchives all log data currently held in the objects log buffer.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

615

Chapter 6 Common Apps Object Things

Apps Objects

clearLastArchiveResets 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 was erroneously set ahead, archives made, and then time was corrected.

Common Log Properties

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

Description
Read-Write: Permits a user-defined text descriptor for describing the log. Any printable characters, including spaces and mixed case characters, are allowed. If description is entered, it appears in the objects LogChart title.

Valid Values
See description

Default

Notes
Also used to list the log in the stations log index http://<sta>/log/index and in the Log Selector. As with buffered log data, is saved in the stations config database.

Status

lastArchiveTimestamp

Read Only: Shows a date/timestamp for when the last archive occurred. Shows null if there have been no archives or if the clearLastArchive command was given.

null

executionParameters foreignAddress bufferSize

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 6-5. Read-Write: Does not apply to a log object. Read-Write: Defines the number of log samples for the object that can reside locally (in RAM The necessary allocation of resource counts (RAM) is set aside based upon the entered number. -1 1 to 11520

normal, processor -1 60

Config

stopWhenFull

Read-Write: If set to True, logging stops when the number of unarchived log samples equals the configured bufferSize. If set to False (the default), the log buffer always rotatesthis means that the oldest sample is overwritten as each new log continues to be recorded.

False, True

False

If archiveSetup is set to nearFull, a stopWhenFull of True is overridden (logging continues). If archiveSetup is set to daily but stopWhenFull is True, logging continues after the daily archive, at least until the log buffer is full.

616

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects Common Apps Object Things

Table 6-2

Status and Config properties common to all log objects (AnalogLog, BinaryLog, and others).

Tab Property Name

archiveSetup

Description
Read-Write: Defines the events that cause the objects log data to be archived. Flags can be set in any combination.

Valid Values
selection of any or all: nearFull, daily, polled

Default
(none selected)

Notes

nearFullArchive occurs at 80% of the

log buffer size.

dailyArchive occurs daily, at the time

configured in the LogService.

polledApplies only if another (remote)

Niagara station is configured with the Polled Archive (multisite) service. logEnableDefault Read-Write: Defines if logging occurs with no link (or fault) at the logEnable input. The default is Truelogging occurs. If set to False, a link with an active state is required to enable logging. Config, cont. collectionMode Read-Write: Defines the manner used to record log samples, as follows:
change_of_value See Notes Default differs

False, True

True

interval

according to log type.

intervalLog samples record on a timed

basis using the interval property value.

AnalogLog default
is interval.

change_of_valueLog samples record

upon each change of value that exceeds the changeTolerance property value, if present. daysOfTheWeek Read-Write: Defines days on which logging occurs. Can be set in any combination. Read-Write: Defines the time period in which logging occurs (on valid days of week), using a start time and end time. If you check exclusive, logging occurs only outside of the defined period. interval Read-Write: Defines, in minutes, the period between log sample records when the collectionMode is set to interval. Does not apply if collectionMode is change_of_value. Any positive integer from 1 up to 32-bit limit. Sun, Mon, Tue, Wed, Thu, Fri, Sat 12:00 AM to 12:00 AM (all days selected) (entire range), not exclusive 1

All other log types

have default of change_of_value. daysOfTheWeek and timeRange settings apply to both collection modes (meaning either interval or change_of_value).

timeRange

Log Object Notes

See the following sections for specific details on each log object type:

AnalogLog BinaryLog IntegerLog MultistateLog StringLog

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

617

Chapter 6 AdminTool

Apps Objects

AdminTool
Quick reference for all properties: Table A-1 Inputs
(none)

Default Object Shape

Outputs
(none)

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 (any

All Inputs / Outputs

Inputs
(none)

Outputs
(none)

Input / Output Property Reference for AdminTool Object

(only input and output types, see Table 6-3 for all properties)

Type
input output

Label

Property Name

Data Species

container).
Resource Count Range: 31 to 53 Trigger Properties

None.

Commands
A JDE user with Command, Admin rights has this available right-click command:

searchAndReplaceExecutes the objects 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
Table 6-3 AdminTool object properties.

Tab Property Name

Status objectType, statusFlags rootNode

Description
See Table 6-1 on page 6-5 for information on these properties common to all apps objects. Read-Write: The swid of the starting point (upper hierarchy) of the station database in which the AdminTool function operates. This can range from the stations root (/db/stationName) to any container or primitive object in the stations database. If the recurseChildren property is True, the AdminTool function applies to any and all objects under the rootNode swid.

Valid Values

Default

Notes

valid swid for the station

In Tree View, a right-click copy on any object under the station captures its swid. Use CTRL-V to paste the swid into the rootNode field of the property sheet.

Config

618

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects AdminTool

Table 6-3

AdminTool object properties. (continued)

Tab Property Name

propertyName

Description
Read-Write: The target property name, exactly as shown on the object(s) property sheet(s). The property should be a read-write type. Not all properties can be modified. Read-Write: Not required for most properties that specify a single value of type float, integer, boolean, or string. Example properties of the above types, in order: highLimit, notificationClass, restartDisable, alarmText. However, elementName is required for flag properties shown as check boxes, properties with time in Hr:Min:Sec, and several other properties that have separate fields.

Valid Values
valid property name

Default
-

Notes

elementName

See descrip.

See Table 6-4 on page 6-20 for exact elementName property values required for selected property types.

newValue

Read-Write: The new value assigned to all matching properties in (and under) the specified rootNode.

See descrip.

Config, cont.

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).

No range-checking is performed (illegal values are possible)! For selected property types, exact newValue property values are required. See Table 6-4 on page 6-20.

If a check box property, also use false (to

clear) and true (to set) the specified flag. recurseChildren Read-Write: Defines if the search-and-replace function is extended to all children (and subchildren, etc.) of the specified rootNode. 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, for example, AnalogO* will apply to object types AnalogOutput and AnalogOverride. nodeNameFilter Read-Write: Defines a match filter, meaning only 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 objects named AHU_1_SA and AHU_1_RA. Security Visual Config, cont. propertyValueFilter Read-Write: Defines a match filter, meaning only objects with this exact value are affected. The asterisk (*), when used alone, acts as a wildcard. (A value AND asterisk do not work.) position Read-Write: See position, page 6-6. valid object names in the stations database * False, True False

If set to False, only the rootNode object is affected. See the examples shown in Figure 6-8 and Figure 6-9,

objectTypeFilter

valid Niagara object types

See the example shown in Figure 6-10, and the Wildcard Notes section on page 6-25. See the example shown in Figure 6-8.

existing value of the target property

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 6-6

General, 7 others

General

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

619

Chapter 6 AdminTool

Apps Objects

AdminTool Notes
The 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. The AdminTool object search-and-replace function is performed only by a running stationin 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 stations 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 objects searchAndReplace command directly from its open property sheetaccess 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!

Notes

Element Name Reference

Table 6-4

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.

AdminTool Config properties (elementName, newValue) selected properties.

Property to be Modified
activeInactiveText archiveSetup

JDE Property Sheet Descrip.

active inactive nearFull daily polled

Required elementName
For any: same as JDE description For any: same as JDE description

Required newValue
For any: desired text descriptor For any: false or true

chartTemplateUrl commandTags (AO and MSO objects)

chartTemplateUrl manualSet manualAuto emergencySet emergencyAuto

url For any: same as JDE description

swid to HTML template file For any: desired command text

620

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects AdminTool

Table 6-4

AdminTool Config properties (elementName, newValue) selected properties. (continued)

Property to be Modified
commandTags (BO object)

JDE Property Sheet Descrip.

manualActive manualInactive manualAuto emergencyActive emergencyInactive emergencyAuto

Required elementName
For any: same as JDE description

Required newValue
For any: desired command text

daysOfTheWeek

Sun Mon Tue Wed Thu Fri Sat

sun mon tue wed thu fri sat precision forceSign duration toOffnormal toFault toNormal toOffnormal toFault toNormal frequency

For any: false or true

decimalFormat delayTime eventEnable

Precision Force Sign Hr:Min:Sec (0:00:00) to-offnormal to-fault to-normal

0 to 6 0 to n For any:

(integer) (integer of seconds)

false or true

false or true

eventTriggerEnable

to-offnormal to-fault to-normal

For any: false or true

executionParameters

freq (drop-down selection box: never, slower, normal, faster, fastest, minutely, on_trigger) order (drop-down selection box: input, output, processor)

Either: never, slower, normal, faster, fastest, minutely, on_trigger Either: input, output, processor Either: Courier, TimesRoman, Helvetica, MonoSpaces, SansSerif, Serif, Dialog, DialogInput Either: 8, 10, 12, 14, 16, 18, 20, 24, 32 Either: 0 (Plain), 1 (Bold), 2 (Italic), 3 (Italic-Bold) A hexadecimal (hex) number for each of the three (red, green, blue) rgb values, with a leading "00" prefix. Example, for white (rgb 256, 256, 256 decimal, in that order): newvalue should be 00FFFFFF

order

font

(name) such as: Helvetica

name

(size) such as: 12 (style) such as: Plain

size style

highDeltaColor

highDeltaColor

rgb

Note: This elementName and newValue method works for any color-defined property, for example, backgroundColor.
inhibitTime Hr:Min:Sec (0:00:00) duration

0 to n

(integer of seconds)

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

621

Chapter 6 AdminTool

Apps Objects

Table 6-4

AdminTool Config properties (elementName, newValue) selected properties. (continued)

Property to be Modified
limitEnable lowDeltaColor midDeltaColor priorityForWriting

JDE Property Sheet Descrip.

low-limit high-limit lowDeltaColor midDeltaColor (drop-down selection box, levels 1 through 16) General HVAC Security Life Safety Group 4 Group 5 Group 6 Group 7

Required elementName
lowLimitEnabled highLimitEnabled rgb rgb ControlPriorityEnum

Required newValue
For any: false or true Same method as for highDeltaColor. Same method as for highDeltaColor. level_1 to level_16 A hexadecimal (hex) number for a binary-to-bitmapped mask where a set bit (1) enables that group. From MSB to LSB, the bits mean:
MSB LSB

securityGroups

mask

Group Group Life HVAC 5 7 Safety Group Group Security General 6 4

For example, to set securityGroups to Group 6, Life Safety, and General: 01001001 templateUrl triggerPeriod timeRange templateUrl Hr:Min:Sec (0:00:00) (time) (starting) to (time) (ending) exclusive (check box) url duration startTime endTime exclusive which is 49 hex Therefore newValue = 49 swid to HTML template file 0 to n (integer of seconds) For any: 00:00 to 00:00 (24-hour format) (00:00=12:00AM, 23:59=11:59PM) false or true

Note

Depending on need, Table 6-4 may be expanded in a later document revision.

622

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects AdminTool

Examples

The following examples show different examples of using the AdminTool object. Changing Log Object End Times Stopping FunctionGenerators Changing LimitEnable for AIs

Changing Log Object End Times

The example shown in Figure 6-8 has an AdminTool object configured to change the end time for all log objects in the station that currently have a end time of 5:00PM. The new end time is set to 5:30PM.
Figure 6-8 AdminTool object showing element usage and object type and value filter.

Because it has multiple elements, this property requires an exact string entered in elementName. Setting recurseChildren to True is necessary to modify all child objects. Filter properties are match filters, and can be used in combination (as done here).

The required elementName entry (endTime) for the property timeRange can be found in the Table 6-4. The objectTypeFilter property is set to *Log so that only log-type objects are affected (AnalogLog, BinaryLog, and so forth). Note the wildcard (*) can be used either before (as here) or after other characters, as in other AdminTool examples. In this example, because the timeRange property is also common to notification recipient objects, the *Log objectTypeFilter limits the action to only log objects. Times must be specified using a 24-hour format, so the newValue and propertyValueFilter entries reflect this (17:30 for 5:30PM and 17:00 for 5:00PM). Because the rootNode has been set to the station root level, when the objects searchAndReplace command is given, all log objects in the station NetSup2000 with an end time currently set to 5:00PM will be changed.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

623

Chapter 6 AdminTool

Apps Objects

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.

Because it has multiple elements, this property requires an exact string entered in elementName. Later, this can be set back to normal and the objects command rerun (to restart the FunctionGenerators).

Func* is more than sufficient to affect only FunctionGenerators.

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. Setting recurseChildren to True is necessary to modify all child objects. Filter properties are match filters, and can be used in combination (as done here).

624

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects AdminTool

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 stations 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. objectTypeFilterTo match the Niagara object type. nodeNameFilterTo 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 character string 1s in its name, for example, Ch1sTemp, Ch1sPump, AHU1sFan, and so on. The propertyValueFilter property value can also contain a single wildcard (*), the default. However, a wildcard does not work with any entered value.

Note

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

625

Chapter 6 AnalogLog

Apps Objects

AnalogLog
Quick reference for all properties: Table A-3 Inputs
statusInput

Default Object Shape

Outputs
(none)

abbrev: (none); AnalogLog AnalogLog objects store the analog value received on a float input along with status and a timestamp. Logs are recorded either at regular intervals or upon change-of-values, depending on the objects configuration. This object has the standard config properties that define the size and operation of the log buffer, log archive schemes, and log collection modes. Linkable inputs are available to enable/disable log sampling, trigger log archiving, or trigger the clearing of log samples. Trigger outputs fire upon each log sample and when logs are archived. This object is unique among log objects because it has a statusOutput, producing a value based upon recorded logs. This value is configurable to be the current (last) log value, or the minimum, maximum, average, or sum value of the accumulated logs.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs
executeTrigger doArchiveTrigger doClearTrigger logEnable statusInput recordedTrigger archivedTrigger statusOutput

Outputs

Input / Output Property Reference for AnalogLog object

(only input and output types, see Table 6-5 for all properties)

Type
input

Label
exe doArchi doCleari enable sIn recorde archive sOut

Property Name
executeTrigger doArchiveTrigger doClearTrigger logEnable statusInput recordedTrigger archivedTrigger statusOutput

Data Species
TriggerType TriggerType TriggerType BooleanStatusType FloatStatusType TriggerType TriggerType FloatStatusType

output

container).
Resource Count Range Trigger Properties

115 to 160, assuming bufferSize of 60 (default). Add 1 resource count for each 1-increase in the objects bufferSize. The AnalogLog object has the standard input property, executeTrigger, (typically not used) and also two other trigger-type inputs: doArchiveTriggerA received pulse causes the log data currently held in the objects log buffer to be archived (sent to the LogService archive destination). doClearA received pulse causes all log data currently held in the objects log buffer to be cleared. In addition, there are 2 available trigger-type outputs, described as follows:

recordedTriggerFires upon each recorded log sample. archivedTriggerFires each time the objects log buffer is archived.

Commands
Admin-level users have a right-click command menu, providing these 3 commands: clearClears all log data currently held in the objects log buffer. archiveArchives all log data currently held in the objects log buffer. clearLastArchiveResets 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).

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

626

Chapter 6

Apps Objects AnalogLog

Properties
Table 6-5 AnalogLog object properties.

Tab Property Name

objectType, statusFlags, description Status

Description
See Table 6-1 on page 6-5 for information on these properties common to all apps objects.

Valid Values

Default

Notes
If description is entered, it appears in LogChart title, also to list the log in the stations log index: http://<sta>/log/index

lastArchiveTimestamp executionParameters foreignAddress membershipGroups bufferSize, stopWhenFull, archiveSetup, logEnableDefault, collectionMode, daysOfTheWeek, timeRange, interval outputFunction

See Table 6-2 on page 6-16 for more information on this log object property.

null normal, processor -1 niagaraR2 Leave at default. The collectionMode default is interval.

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 6-5. Read-Write: Does not apply to this object. Read-Write: (Future use only.) See Table 6-2 on page 6-16 for more information on these properties common to all log objects. -1 niagaraR2

Read-Write: Determines the method used to calculate the statusOutput value using recorded logs, where the output is either:

changeTolerance

currentThe last recorded log sample. minimumThe minimum recorded log. maximumThe maximum recorded log. averageThe average of recorded logs. sumThe sum of all recorded logs.

current, minimum, maximum, average, sum

current

When chaining AnalogLog objects, the average selection is often used.

Config

Read-Write: Used only if collectionMode is set to change_of_value. Defines the minimum change required at the statusInput (since the last recorded log sample) before a new sample is recorded. Read-Write: Defines if log samples are recorded as the actual statusInput value, as in the default (False), or the difference (delta) between samples (if True). If set to True, a log sample will have a negative sign when decreasing, or be unsigned when increasing.

Any positive value 0.0000000000 1 (1.0E-11) to MAX_VALUE False, True

0.01

deltaLogging

False

Note: Delta logging is also reflected at the statusOutput.

Typically, when using deltaLogging collectionMode should be set to interval. Otherwise, log samples will show only the changeTolerance value (positive or negative).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

627

Chapter 6 AnalogLog

Apps Objects

Table 6-5

AnalogLog object properties. (continued)

Tab Property Name

units Config, cont.

Description
Read-Write: Selection of engineering units for display purposes. Choose from a logical grouping, then a specific unit. For selections see About Units, page 5-6. Units appear on the LogChart showing the objects log data. Units can also appear on a GxText object linked to the statusOutput.

Valid Values
Select any (BACnet-type unit choices)

Default
Other, no_units

Notes
Units are not used in the objects LogTable view, nor with any access to archived log data.

position chartType

Read-Write: See position, page 6-6. Read-Write: Defines the chart (graph) style used to present log data in the LogChart. The objects LogChart is seen by a JDE user and (if WebUIService is licensed) by a Web browser user.

plot, area, bar, candle, bar_3d, candle_3d Any desired color

plot For an example of each chart type, see Figure 6-14.

chartColor Visual chartTemplateUrl

Read-Write: Defines the color used in the LogChart to represent recorded log data.

Red (255,0,0) See the Tip on page 6-14 for an example of using this property.

Read-Write: Specifies the swid to an HTML Valid swid to an template used to frame the LogChart when appropriate viewing it in a Web browser. HTML template. If left blank, the default HTML template is used (defaultChartTemplate.html). Read-Write: Sets decimal position from 0 to 6 places, optionally forces (+) sign for positive values. Decimal format is used in the y-axis scale values on the objects LogChart, also in displayed values in the JDE LogTable view. Properties common to all apps objects. For more information, see Table 6-1 on page 6-5. Read Only: Shows the current boolean state and status of the logEnable input. Read Only: Shows the current value and status received on the statusInput. Read Only: Shows the current value and status of the statusOutput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 6-6 0 to 6, (+) sign, no (+) sign

decimalFormat

Decimal format is not no (+) sign used in browser access to the objects LogTable view, nor with any access to archived log data.

2,

Engineering

minExecuteTime, maxExecuteTime, averageExecuteTime, userData logEnable (input: enable) statusInput (input: sIn) statusOutput (output: sOut)

false, true : {status flags} <float value> {status flags} <float value> {status flags} General, 7 others

false : {ok} Shows false if logEnable is not linked. 00.0 {ok} 00.0 {ok} General

Security

securityGroups

AnalogLog Notes
The 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

628

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects AnalogLog

statusOutput Notes

The AnalogLog object has a statusOutput and a outputFunction config 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, the output value reflects the math operation on the objects 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.

Source object

1. OATMinuteLog bufferSize = 60 collectionMode = interval interval (min.) =1 outputFunction = average

2. OATHourLog bufferSize = 48 collectionMode = interval interval (min.) = 60 outputFunction = average

3. OATDayLog bufferSize = 35 collectionMode = interval interval (min.) =1440

1. OATMinuteLog, holds the last hours (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.

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. 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).
When linked, an active is required on logEnable during logging.

Delta Logging Notes

AH1_RATlog bufferSize = 60 stopWhenFull = False collectionMode = interval interval (min.) =1 deltaLogging = True

tstamp Example log data portion at system start (cooling cycle). 17:30:00 23-Jul-2001 EDT 8:00:00 24-Jul-2001 EDT 8:01:00 24-Jul-2001 EDT 8:02:00 24-Jul-2001 EDT 8 03 00 24 J l 2001 EDT

value 0.02 7.20 -0.61 -0.73 1 21

status {ok} Values are the differences between current sample {ok} value and previous value. {ok} {ok} { k}

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

629

Chapter 6 AnalogLog

Apps Objects

Figure 6-13 shows a similar example, but with the addition of a DateTimeTrigger object that periodically clears the AnalogLog objects buffer, which is set to stopWhenFull. In this case, only the first hours 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.
DateTimeTrigger (linked to doClearTrigger) triggerDay = Date ** *** **** triggerTime = 3:00 AM AH1_RATlog bufferSize = 60 stopWhenFull = True collectionMode = interval interval (min.) =1 deltaLogging = True

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 stations log data (as defined in the LogService object), which in this case is at 12:01 AM.

Visual Properties Notes

The Visual tab of the log objects property sheet provides several properties that affect the graphical presentation of log data. These properties are: chartTypeDetermines 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. chartColorDetermines the color used to display the objects 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 objects 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).

630

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects AnalogLog

Figure 6-14 shows how the same log data (sine wave, values ranging from 50 to 90) appears in a LogChart using different chartType selections.
Figure 6-14 AnalogLog chartType selections determine how the objects log data appears in the LogChart view.

plot: The plot chartType appears as a continuous line, with the candle: The candle chartType is similar to the bar chart, but
log value on the y-axis against time on the x-axis. bars average changes in log values over repeating periods.

area: An area chartType follows the same plot contour, but fills bar_3d: The bar_3d chartType is like the bar type, but simply in the entire region below recorded log values. adds shadow details for a 3D effect.

bar: The bar chartType shows averages for the log values
over a repeating time period (for each bar).

candle_3d: The candle_3d chartType is like the candle type,

but simply adds shadow details for a 3D effect.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

631

Chapter 6 BinaryLog

Apps Objects

BinaryLog
Quick reference for all properties: Table A-10 Inputs
statusInput

Default Object Shape

Outputs
(none)

abbrev: (none); BinaryLog BinaryLog objects store the boolean value (state) received on a boolean input along with a status and timestamp. Log samples occur at regular intervals or upon change-of-state, depending on the objects configuration. This object has the standard config properties that define the size and operation of the log buffer, log archive schemes, and log collection modes. Linkable inputs are available to enable/disable log sampling, trigger log archiving, or trigger the clearing of log samples. Trigger outputs fire upon each log sample and when logs are archived.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs
executeTrigger doArchiveTrigger doClearTrigger logEnable statusInput recordedTrigger archivedTrigger

Outputs

Input / Output Property Reference for BinaryLog object

(only input and output types, see Table 6-6 for all properties)

Type
input

Label
exe doArchi doCleari enable sIn recorde archive

Property Name
executeTrigger doArchiveTrigger doClearTrigger logEnable statusInput recordedTrigger archivedTrigger

Data Species
TriggerType TriggerType TriggerType BooleanStatusType FloatStatusType TriggerType TriggerType

container).
Resource Count Range: 115 to 160,

assuming bufferSize of 60 (default). Add 1 resource count for each 1-increase in the objects bufferSize.
Trigger Properties

output

The BinaryLog object has the standard input property, executeTrigger, (typically not used) and also two other trigger-type inputs: doArchiveTriggerA received pulse causes the log data currently held in the objects log buffer to be archived (sent to the LogService archive destination). doClearA received pulse causes all log data currently held in the objects log buffer to be cleared. In addition, there are 2 available trigger-type outputs, described as follows:

recordedTriggerFires upon each recorded log sample. archivedTriggerFires each time the objects log buffer is archived.

Commands
For any user with Admin-level privileges, a right-click command menu provides these commands: clearClears all log data currently held in the objects log buffer. archiveArchives all log data currently held in the objects log buffer. clearLastArchiveResets 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).

632

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects BinaryLog

Properties
Table 6-6 BinaryLog object properties.

Tab Property Name

objectType, statusFlags, description Status

Description
See Table 6-1 on page 6-5 for information on these properties common to all apps objects.

Valid Values

Default

Notes
If description is entered, it appears in LogChart title, also to list the log in the stations log index: http://<sta>/log/index

lastArchiveTimestamp executionParameters foreignAddress membershipGroups bufferSize, stopWhenFull, archiveSetup, logEnableDefault, collectionMode, daysOfTheWeek, timeRange, interval position chartType Config

See Table 6-2 on page 6-16 for more information on this log object property.

null normal, processor -1 niagaraR2 Leave at default. The collectionMode default is change_of_value. Typically, this is left at default.

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 6-5. Read-Write: Does not apply to this object. Read-Write: (Future use only.) See Table 6-2 on page 6-16 for more information on these properties common to all log objects. -1 niagaraR2

Read-Write: See position, page 6-6. Read-Only: Defines the chart (graph) style used to present log data in the LogChart. The objects LogChart is seen by a JDE user and (if WebUIServices are licensed) by a Web browser user.

area

area See Figure 6-15 for an example.

chartColor Visual chartTemplateUrl

Read-Write: Defines the color used in the LogChart to represent recorded log data.

Any desired color

Red (255,0,0) See the Tip on page 6-14 for an example of using this property.

Read-Write: Specifies the swid to an HTML Valid swid to an template used to frame the LogChart when appropriate viewing it in a Web browser. HTML template. If left blank, the default HTML template is used (defaultChartTemplate.html). Read-Write: Defines how log samples are stored and described in the LogTable and LogChart. Properties common to all apps objects. For more information, see Table 6-1 on page 6-5. Read Only: Shows the current boolean state and status of the logEnable input. Read Only: Shows the current value and status received on the statusInput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 6-6 Any desired descriptors for the two states.

activeInactiveText

Active, Inactive

Engineering

minExecuteTime, maxExecuteTime, averageExecuteTime, userData logEnable (input: enable) statusInput (input: sIn)

false, true : {status flags} <float value> {status flags} General, 7 others

false : {ok} Shows false if logEnable is not linked. 00.0 {ok} General

Security

securityGroups

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

633

Chapter 6 BinaryLog

Apps Objects

BinaryLog Notes
BinaryLog objects are typically used to track the time of state changes, therefore, the collectionMode property should be left at the default: change_of_value. The default view for a BinaryLog object is its LogChart, which uses a fixed area style plot. This results in bar-type graph (Figure 6-15).
Figure 6-15 LogChart view for a BinaryLog object.
Active time is indicated by the solid color areas, using the objects chartColor setting. Inactive time is indicated by the white (blank) areas.

The two possible states (values) appear using the objects activeInactiveText descriptors.

The LogTable view (Figure 6-16) may also be needed, as each timestamp lists the exact time for each change of state.
Figure 6-16 LogTable view for a BinaryLog object (JDE and Web browser).
As in the LogChart, the two possible states (values) are listed using the objects activeInactiveText descriptors.

LogTable in JDE

LogTable in a browser

Timestamps for each state change.

634

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects Calendar

Calendar
Quick reference for all properties: Table A-14 Inputs
(none)

Default Object Shape

Outputs
statusOutput

abbrev: Cal The Calendar object is an extension of a BACnet Calendar object, and can be exposed directly as such. Calendar objects define a list of dates, which are typically used in the system as holidays. As needed, calendar dates can be single days or span consecutive days. Dates are entered and reviewed graphically, using calendar-based views.
Note:

All Inputs / Outputs

Inputs
executeTrigger statusInput slaveIn

Outputs
presentValue statusOutput covTrigger onActiveTrigger onInactiveTrigger masterOut

The station requires the WebUIService in order for these views to be Web browser-accessible.

By default, the objects statusOutput is active during a calendar date (holiday). Typically, you link this output to the holidayOverride input of one or more Schedule objects, providing holiday control. The object also has 3 trigger outputs that fire, respectively, on any change of value, a change to-active, and a change to-inactive. Calendar objects have slave sync inputs and outputs, used to link multiple Calendar objects in different stations (providing global editing control).
Parent Dependencies: None (any

Input / Output Property Reference for Calendar object

(only input and output types, see Table 6-7 for all properties)

Type
input

Label
exe sIn slaveIn present sOut covTrig onActiv onInact master

Property Name
executeTrigger statusInput slaveIn presentValue statusOutput covTrigger onActiveTrigger onInactiveTrigger masterOut

Data Species
TriggerType BooleanStatusType SlaveSyncType boolean BooleanStatusType TriggerType TriggerType TriggerType SlaveSyncType

output

container).
Resource Count Range: 72 to 132 Trigger Properties

In addition to the standard input property, executeTrigger (typically not used), the Calendar object also has 3 trigger-type outputs: covTriggerFires upon any statusOutput change (to-active and to-inactive). onActiveTriggerFires each time the statusOutput changes to active. onInactiveTriggerFires each time the statusOutput changes to inactive.

As needed, these trigger-type inputs and outputs can be linked to other objects that have properties using TriggerType data species.

Views
For a Calendar object, a JDE user has a right-click Go > <command> menu providing these views (in addition to standard Go commands: Properties and Links).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

635

Chapter 6 Calendar

Apps Objects

CalendarShows 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. CalendarSummaryShows 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 can create and delete calendar dates. EntryListShows 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.

Properties
Table 6-7 Calendar object properties.

Tab Property Name

objectType, statusFlags, description presentValue

Description
See Table 6-1 on page 6-5 for information on these properties common to all apps objects. Read Only: Required for BACnet. Reflects the objects statusOutput state.

Valid Values

Default

Notes

Status

Inactive, Active

Inactive

Displays in the objects configured: activeInactiveText

executionParameters

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 6-5. Read-Write: BACnet usage only. Set to a positive integer for this object to appear as a BACnet Calendar object to other BACnet devices. See foreignAddress, page 6-6, for more information. Read-Write: (Future use only.) Read-Write: Defines how states display at the statusOutput, presentValue, and statusInput, and also how they appear on the objects property sheet. 0 to 4194302 or -1 (not exposed)

fixed_min utely, processor -1 If set, must be a unique number among all other Calendar objects in station. State descriptors can display at a linked GxText object.

foreignAddress Config membershipGroups activeInactiveText

niagaraR2 Any desired descriptors for the two states.

niagaraR2 Leave at default. Active, Inactive

636

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects Calendar

Table 6-7

Calendar object properties. (continued)

Tab Property Name

position templateUrl Visual

Description
Read-Write: See position, page 6-6.

Valid Values

Default

Notes
Does not apply if the Calendar object resides in a station without the WebUIService.

Read-Write: Specifies the swid to an HTML Valid swid to an template used to frame the objects appropriate calendar dates in the calendar applet (when HTML viewing it in a Web browser). template. If left blank, the stations calendar template is used (WebUIServices Config property, calendarTemplateUrl). If that property is blank, the stations defaultTemplateUrl is usedalso a WebUIService property.

minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusOutput (output: sOut) statusInput (input: sIn)

Properties common to all apps objects. For more information, see Table 6-1 on page 6-5. Read Only: Shows the current value and status produced on the statusOutput (the main linkable property of this object). Read Only: Shows the current value and status received on the statusInput.

Inactive, Active

Inactive : {ok} Inactive : {ok}

Inactive, Active

Engineering

An active overrides the statusOutput to

active (at the top of the minute).

Inactive allows normal schedule

operation. statusInputDefault masterOut (output: master) slaveIn (input: slaveIn) Read-Write: Default value for statusInput if it is not linked, or if it has a fault status. Read Only: Always shows SlaveSync. Read Only: Always shows SlaveSync. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 6-6 False, True SlaveSync SlaveSync General, 7 others False Typically seldom (if ever) set to True.

SlaveSync No real-time status (or indication of a master/slave link) is SlaveSync provided on the property sheet. General

Security

securityGroups

Calendar Notes
A 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

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

637

Chapter 6 Calendar

Apps Objects

Figure 6-17

Calendar is typically linked to a one or more Schedule objects.

Calendar object

Calendar Object Processing and Priorities

As with Schedule objects, the ControlEngineService executes Calendar objects once at the top of each minute (fixed). This means that changes in calendar dates and/or a change at the statusInput become effective only once a minute. The objects statusInput, if linked, is given the top priority. This means that: Whenever an active is present at the statusInput, the statusOutput is overridden to active (holiday). When inactive (or if not linked), normal calendar-date operation continues.

Calendar Output Configuration

The Calendar object has a single main output: statusOutput, using the BooleanStatusType data species. Another output, presentValue, is available that reflects the same state, but uses the primitive boolean data species. A collection of three trigger-type outputs provide trigger pulses on any change of state, change to-active, and change to-inactive.

Master / Slave Operation

The Calendar objects output masterOut and input slaveIn allows a single master Calendar object to globally define all holiday-type calendar dates in all of its linked slave Calendar objects. Any calendar date change made in the master Calendar object is immediately copied to its slave objects. This is particularly useful in multi-station jobs. The typical application is as follows: Master Calendar objects reside in the Web Supervisor. Slave Calendar objects reside in JACE controllers. You link the masterOut from a Web Supervisor-resident Calendar object to the masterIn input of one or more JACE-resident Calendar objects.

In case of a communications failure between devices, each JACE retains holiday configurations, as this data is persistently stored in all Calendar objects.

638

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects Calendar

Notes

If a Calendar object is linked as a slave, its calendar setup cannot be directly modified. Its Calendar view still shows the calendar dates as programmed in the master Calendar, but as read-only. Note that the master/slave relationship applies to the objects config property activeInactiveText, as well. A linked slave object receives all of the masters calendar dates only upon an date change in the master object (with communications OK). This applies mostly to a newly-linked slave Calendar object, but can apply if changes are made when device communications are down. Typically, when engineering master/slave Calendar objects in stations, corresponding master/slave Schedule objects are also used.

Calendar View Notes

In the JDE, the Calendar view for a Calendar object provides a graphical calendar to access calendar dates, as shown in Figure 6-25. Controls for editing dates are at the bottom of the view, and become active when a day (or days) are selected.
Figure 6-18 Calendar view in JDE for a Calendar object.
Next year Previous year and month Next month

Outer (double) arrows are to scroll back and forward through years.

Inner (single) arrows are to scroll back and forward through months.

Calendar dates are indicated by shading.

Controls for editing dates become active after clicking on (selecting) one or more dates.

Cancel merely deselects any selected day or days.

When accessing a Calendar object using a browser, the same general view is presented. However, editing controls (new, delete, etc.) are right-click options for any selected day or days (Figure 6-18).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

639

Chapter 6 Calendar

Apps Objects

Figure 6-19

Browser access to Calendar object provides a similar view, but with right-click menu controls for adding and deleting calendar dates.

Previous year Previous month

Scroll controls work in the same fashion as in the JDE.

Click or drag to select day or days.

Right-click for menu options to add, delete, or list calendar dates.

Save button is available after changes are made, but not yet written to persistent storage.

Reload button recalls only those calendar dates currently stored persistently.

Note

There is no browser-accessible equivalent to the JDE CalendarSummary view, where calendar dates for all 12 months of the year can be examined.

Template Priorities
The calendar applet is framed within an HTML template defined by either of these properties, in order of priority:
a. The template referenced by the Calendar objects templateUrl property (on

the objects Visual tab). If this value is blank, then:

b. The template referenced by the WebUIServices calendarTemplateUrl

property (on the WebUIServices Config tab). If this value is blank, then:
c. The defaultTemplateUrl, also on the WebUIServices Config tab.

640

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects IntegerLog

IntegerLog
Quick reference for all properties: Table A-40 Inputs
statusInput

Default Object Shape

Outputs
(none)

abbrev: (none); IntegerLog IntegerLog objects store the integer value and status received on the statusInput along with a timestamp. Log samples occur either at regular intervals or upon change-of-values, depending on the objects configuration. This object has the standard config properties that define the size and operation of the log buffer, log archive schemes, and log collection modes. Linkable inputs are available to enable/disable log sampling, trigger log archiving, or trigger the clearing of log samples. Trigger outputs fire upon each log sample and when logs are archived.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs
executeTrigger doArchiveTrigger doClearTrigger logEnable statusInput recordedTrigger archivedTrigger

Outputs

Input / Output Property Reference for IntegerLog object

(only input and output types, see Table 6-8 for all properties)

Type
input

Label
exe doArchi doCleari enable sIn recorde archive

Property Name
executeTrigger doArchiveTrigger doClearTrigger logEnable statusInput recordedTrigger archivedTrigger

Data Species
TriggerType TriggerType TriggerType BooleanStatusType IntegerStatusType TriggerType TriggerType

container).
Resource Count Range: 115 to 160,

assuming bufferSize of 60 (default). Add 1 resource count for each 1-increase in the objects bufferSize.
Trigger Properties

output

The IntegerLog object has the standard input property, executeTrigger, (typically not used) and also two other trigger-type inputs: doArchiveTriggerA received pulse causes the log data currently held in the objects log buffer to be archived (sent to the LogService archive destination). doClearA received pulse causes all log data currently held in the objects log buffer to be cleared. In addition, there are 2 available trigger-type outputs, described as follows:

recordedTriggerFires upon each recorded log sample. archivedTriggerFires each time the objects log buffer is archived.

Commands
Admin-level users have a right-click command menu, providing these commands: clearClears all log data currently held in the objects log buffer. archiveArchives all log data currently held in the objects log buffer. clearLastArchiveResets 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).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

641

Chapter 6 IntegerLog

Apps Objects

Properties
Table 6-8 IntegerLog object properties.

Tab Property Name

objectType, statusFlags, description Status

Description
See Table 6-1 on page 6-5 for information on these properties common to all apps objects.

Valid Values

Default

Notes
If description is entered, it appears in LogChart title, also to list the log in the stations log index: http://<sta>/log/index

lastArchiveTimestamp

Read Only: Shows a date/timestamp for when the last archive occurred. Shows null if there have been no archives or if the clearLastArchive command was given.

null

executionParameters foreignAddress membershipGroups bufferSize, stopWhenFull, archiveSetup, logEnableDefault, collectionMode, daysOfTheWeek, timeRange, interval deltaLogging

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 6-5. Read-Write: Does not apply to this object. Read-Write: (Future use only.) See Table 6-2 on page 6-16 for more information on these properties common to all log objects. -1 niagaraR2

normal, processor -1 niagaraR2 Leave at default. The collectionMode default is change_of_value. In some cases, interval may be better suited.

Config

Read-Write: Defines if log samples are recorded as the actual statusInput value, as in the default (False), or the difference (delta) between samples (if True). If set to True, a log sample will have a negative sign when decreasing, or be unsigned when increasing.

False, True

False

units

Read-Write: Selection of engineering units for display purposes. Choose from a logical grouping, then a specific unit. For selections see About Units, page 5-6.. Read-Write: See position, page 6-6. Read-Write: Defines the chart (graph) style used to present log data in the LogChart. The objects LogChart is seen by a JDE user and (if WebUIServices are licensed) by a Web browser user.

Select any (BACnet-type unit choices) plot, area, bar, candle, bar_3d, candle_3d Any desired color

Other, no_units

Units appear on the LogChart showing the objects log data.

position chartType

plot

Visual

chartColor chartTemplateUrl

Read-Write: Defines the color used in the LogChart to represent recorded log data.

Red (255,0,0) See the Tip on page 6-14 for an example of using this property.

Read-Write: Specifies the swid to an HTML Valid swid to an template used to frame the LogChart when appropriate viewing it in a Web browser. HTML template. If left blank, the default HTML template is used (defaultChartTemplate.html).

642

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects IntegerLog

Table 6-8

IntegerLog object properties. (continued)

Tab Property Name

minExecuteTime, maxExecuteTime, averageExecuteTime, userData logEnable (input: enable) statusInput (input: sIn) Security securityGroups

Description
Properties common to all apps objects. For more information, see Table 6-1 on page 6-5. Read Only: Shows the current boolean state and status of the logEnable input. Read Only: Shows the current value and status received on the statusInput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 6-6

Valid Values

Default

Notes

Engineering

false, true : {status flags} <int value> {status flags} General, 7 others

false : {ok} Shows false if logEnable is not linked. 0 {ok} General

IntegerLog Notes
The IntegerLog object can be used to trend any integer value in the station. As far as the required data species for linking to the objects statusInput, the IntegerLog object is interchangeable with the MultistateLog objectboth 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 objects LogChart, the objects assigned units descriptor will display along the numbers labeling the y-axis. The MultistateLog object is used to log discrete values (states), which have associated 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 objects LogChart, the assigned stateText descriptors also display along the charts 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.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

643

Chapter 6 MultistateLog

Apps Objects

MultistateLog
Quick reference for all properties: Table A-49 Inputs
statusInput

Default Object Shape

Outputs
(none)

abbrev: (none); MultistateLog MultistateLog objects store the multistate value received on the statusInput along with a status and timestamp. Log samples occur at regular intervals or upon change-of-state, depending on the objects configuration. This object has the standard config properties that define the size and operation of the log buffer, log archive schemes, and log collection modes. Linkable inputs are available to enable/disable log sampling, trigger log archiving, or trigger the clearing of log samples. Trigger outputs fire upon each log sample and when logs are archived.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs
executeTrigger doArchiveTrigger doClearTrigger logEnable statusInput recordedTrigger archivedTrigger

Outputs

Input / Output Property Reference for MultistateLog object

(only input and output types, see Table 6-9 for all properties)

Type
input

Label
exe doArchi doCleari enable sIn recorde archive

Property Name
executeTrigger doArchiveTrigger doClearTrigger logEnable statusInput recordedTrigger archivedTrigger

Data Species
TriggerType TriggerType TriggerType BooleanStatusType IntegerStatusType TriggerType TriggerType

container).
Resource Count Range: 115 to 160,

assuming bufferSize of 60 (default). Add 1 resource count for each 1-increase in the objects bufferSize.
Trigger Properties

output

The BinaryLog object has the standard input property, executeTrigger, (typically not used) and also two other trigger-type inputs: doArchiveTriggerA received pulse causes the log data currently held in the objects log buffer to be archived (sent to the LogService archive destination). doClearA received pulse causes all log data currently held in the objects log buffer to be cleared. In addition, there are 2 available trigger-type outputs, described as follows:

recordedTriggerFires upon each recorded log sample. archivedTriggerFires each time the objects log buffer is archived.

Commands
For any user with Admin-level privileges, a right-click command menu provides these commands: clearClears all log data currently held in the objects log buffer. archiveArchives all log data currently held in the objects log buffer. clearLastArchiveResets 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).

644

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects MultistateLog

Properties
Table 6-9 MultistateLog object properties.

Tab Property Name

objectType, statusFlags, description Status

Description
See Table 6-1 on page 6-5 for information on these properties common to all apps objects.

Valid Values

Default

Notes
If description is entered, it appears in LogChart title, also to list the log in the stations log index: http://<sta>/log/index

lastArchiveTimestamp

Read Only: Shows a date/timestamp for when the last archive occurred. Shows null if there have been no archives or if the clearLastArchive command was given.

null

executionParameters foreignAddress membershipGroups bufferSize, stopWhenFull, archiveSetup, logEnableDefault, collectionMode, daysOfTheWeek, timeRange, interval position chartType Config

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 6-5. Read-Write: Does not apply to this object. Read-Write: (Future use only.) See Table 6-2 on page 6-16 for more information on these properties common to all log objects. -1 niagaraR2

normal, processor -1 niagaraR2 Leave at default. The collectionMode default is change_of_value. Typically, this is left at default.

Read-Write: See position, page 6-6. Read-Write: Defines the chart (graph) style used to present log data in the LogChart. The objects LogChart is seen by a JDE user and (if WebUIServices are licensed) by a Web browser user.

area

area

chartColor chartTemplateUrl Visual

Read-Write: Defines the color used in the LogChart to represent recorded log data.

Any desired color

Red (255,0,0) See the Tip on page 6-14 for an example of using this property. State descriptors can display at a linked GxText object. For log accuracy, verify that stateText configuration matches stateText in the source MSI or MSO object.

Read-Write: Specifies the swid to an HTML Valid swid to an template used to frame the LogChart when appropriate viewing it in a Web browser. HTML template. If left blank, the default HTML template is used (defaultChartTemplate.html). Read-Write: Defines all possible discrete states by value-name pairs. Each state has two fields: Up to 8 states permitted, numerically from 0 to 7.

stateText

valueUnique integer from 0 to 7. tagText to describe the associated

discrete state. State descriptors are used at the statusOutput, presentValue, alarm and fault values, and in both the LogChart and LogTable views.

0 = Off 1 = On 2 = Fast default = Error

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

645

Chapter 6 MultistateLog

Apps Objects

Table 6-9

MultistateLog object properties. (continued)

Tab Property Name

minExecuteTime, maxExecuteTime, averageExecuteTime, userData logEnable (input: enable) statusInput (input: sIn) Security securityGroups

Description
Properties common to all apps objects. For more information, see Table 6-1 on page 6-5. Read Only: Shows the current boolean state and status of the logEnable input. Read Only: Shows the current value and status received on the statusInput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 6-6

Valid Values

Default

Notes

Engineering

false, true : {status flags} <float value> {status flags} General, 7 others

false : {ok} Shows false if logEnable is not linked. 00.0 {ok} General

MultistateLog Notes
The 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 to Basically, the MultistateLog operates like the BinaryLog object, offering similar BinaryLog Object 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. 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 BinaryLogs, 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.

Note

An Error level appears at topan error results when an integer value not included in stateText is received. Different states appear at different levels, using the objects chartColor. The first state is no color (white).

stateText descriptors are used in the LogChart y-axis.

646

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects Program

Program
Quick reference for all properties: Table A-68 Inputs
(none)

Default Object Shape

Outputs
(none)

abbrev: Prog The Program object lets you build a custom application program (control function) as a reusable 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 objects 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 workingshow 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 accomplishedrefer to the standard Niagara tridiumx/lib JAR file of the Local Library for various examples.
Parent Dependencies

All Inputs / Outputs

Inputs
(as defined)

?
Property Name

Outputs
(as defined)

Input / Output Property Reference for Program Object

(only input and output types, see Table 6-10 for all standard properties)

Type
input

Label

Data Species

output

(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. (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 various Niagara data species, plus a basic understanding of programming techniques (keywords, variables, operators, and conditionals).

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 objects 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:

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

647

Chapter 6 Program

Apps Objects

ProgramEditorOpens the objects 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 windows bottom. ProgramDebuggerOpens a two-pane view in the Workspace (Figure 6-22), with the left-side showing the objects 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.

Properties
Table 6-10 Program object properties (standard, not counting those properties added in TRIPL).

Tab Property Name

objectType, statusFlags, description executionParameters foreignAddress membershipGroups typeString Config Status

Description
See Table 6-1 on page 6-5 for information on these properties common to all apps objects.

Valid Values

Default

Notes

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 6-5. Read-Write: Does not apply to this object. Read-Write: (Future use only.) Read-Write: Defines the name of an HTML file used for on context Help when the objects property sheet is open in the JDE. This file must have a tridium\docs file path. -1 niagaraR2 Program

normal, processor -1 niagaraR2 Leave at default. Program

displayTypeString

Read-Write: Defines the text label that Any desired appears inside the top of the objects shape ASCII text when viewed in the JDE Workspace. Also string, including used as the Type field (and filter) for the spaces Status servlet of the WebUiService. The default is Prog (for Program). Examples: Pulse Gen or Num Ramp.

Prog

Short text strings are recommended, because the object shape expands to accommodate long text strings.

position decimalFormat

Read-Write: See position, page 6-6. Read-Write: Sets decimal position from 0 to 6 places, and optionally force (+) sign for positive values. Read-Write: Defines the icon used to represent the object in the JDE Tree View. The default is the standard scroll graphic contained in the coreUI module JAR file: /tridium/images/icons/program.gif

0 to 6, (+) sign, no (+) sign Any .gif file that can be accessed by the station, using a size of 16 x 16 pixels.

2, no (+) sign See descrip.

Visual

icon

Engineering

minExecuteTime, maxExecuteTime, averageExecuteTime, userData inDebugSession

Properties common to all apps objects. For more information, see Table 6-1 on page 6-5. Read-Only: Shows True whenever the object is running in the ProgramDebugger. At all other times, this property is False.

False, True

False

648

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects Program

Table 6-10

Program object properties (standard, not counting those properties added in TRIPL). (continued)

Tab Property Name

Security securityGroups

Description
Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 6-6

Valid Values
General, 7 others

Default
General

Notes

Program Notes
The Program object is typically used whenever a routine is not easily done using standard control objects. Like other apps objects and control objects, program objects are executed by the stations ControlEngineService. However, be aware that Program objects consume more processing (CPU) time than standard objects, and for that reason should not be used indiscriminately. The following Program object subtopics are discussed: Program Editor Program Debugger TRIPL Program Overview Simple Program Example

Program Editor

The Program Editor in the JDE provides a number of controls for creating and modifying the TRIPL program used by a Program object.
Figure 6-21 Program object Program Editor is used to write and compile a TRIPL program.

Tool bar buttons for: Debug Mode, Compile and Save, Cut, Copy, Paste, Find, Replace, and Goto.

Errors when compiling appear in the status line.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

649

Chapter 6 Program

Apps Objects

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).

Program Debugger

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 program shows in this pane. Watch view shows in this pane.

Tool bar buttons for: Edit Mode, Run, Break, and Step.

Line numbers appear as you mouse over the left margin. Right click menus allow setting break points and adding items to the Watch pane.

TRIPL Program Overview

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 (*/).
Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

650

Chapter 6

Apps Objects Program

Comments are not executed by the station but serve as documentation comments and/or labels for sections of the program.

A number of sections, each used to define the objects: Inputs Outputs Properties Variables Processing Program lines (statements) within each section must use the proper rules for variable declarations, expressions, and control flow.

Simple Program Example

A simple example of a Program object is to allow a momentary action switch to trigger a timed override, as defined in a BinaryOverride object. The Program object in this example merely fires a trigger output each time a linked input to a BI object receives an active signalin this case, from a shadow object (not shown) that represents a momentary action switch input.
Figure 6-23 Program triggers a BinaryOverride from a momentary switch/BI output.

In this example, the Program objects property displayTypeString was assigned a value of PushSwitch, which appears inside the objects shape.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

651

Chapter 6 Schedule

Apps Objects

Schedule
Quick reference for all properties: Table A-70 Inputs
holidayOverride

Default Object Shape

Outputs
statusOutput prioritizedOutput

abbrev: Sched The Schedule object is an extension of a BACnet Schedule object, and can be exposed directly as such. Schedule objects provide binary (On/Off) event control using a repeating 7-day schedule. Schedule events are defined by time-of-day and day-of-week. Multiple events can be entered for any and all days, up to 10 events (5 cycles) per day. Aside from regular (repeating) schedule events, the object allows definition of special events, which are assigned as needed to a specific day(s). A special events day replaces all normal time-of-day events. In addition, a holidayOverride input can be linked to a Calendar object, for appropriate holiday action (as configured in the Schedule objects Holiday schedule). All schedule events are entered and reviewed graphically, using schedule-based views.
Note:

All Inputs / Outputs

Inputs Outputs
isActive statusOutput executeTrigger overrideIn holidayOverride slaveIn prioritizedOutput nextEventTime nextEventValue covTrigger onActiveTrigger onInactiveTrigger masterOut

Input / Output Property Reference for Schedule object

(only input and output types, see Table 6-11 for all properties)

Type
input

Label
exe override hday slaveIn isActive sOut pOut nxtTime nxtVal covTrig onActiv onInact master

Property Name
executeTrigger overrideIn holidayOverride slaveIn isActive statusOutput prioritizedOutput nextEventTime nextEventValue covTrigger onActiveTrigger onInactiveTrigger masterOut

Data Species
TriggerType BooleanPriorityType BooleanStatusType SlaveSyncType boolean BooleanStatusType BooleanPriorityType DateTimeType BooleanStatusType TriggerType TriggerType TriggerType SlaveSyncType

The station requires the WebUIService in order for these views to be Web browser-accessible.

output

If the Schedule object is linked to a Calendar object, access to its calendar configuration is automatically included. A Schedule objects current event action is available at both the statusOutput and prioritizedOutput. Other outputs provide data on the next scheduled event, and trigger pulses on event changes. Schedule objects have slave sync inputs and outputs, used to link multiple Schedule objects in different stations (providing global editing control).
Parent Dependencies:

None (any container).

Resource Count Range: 72 to 132 Trigger Properties

In addition to the standard input property, executeTrigger (typically not used), the Calendar object also has 3 trigger-type outputs:

covTriggerFires upon any statusOutput change (to-active and to-inactive).

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

652

Chapter 6

Apps Objects Schedule

onActiveTriggerFires each time the statusOutput changes to active. onInactiveTriggerFires each time the statusOutput changes to inactive.

Commands
For any user with Command, Admin privileges, a right-click command menu provides this command:

cleanupSpecialsRemoves any previously-executed special events (providing they are older than the number of days defined by the config property specialCleanup).

Views
For a Schedule object, a JDE user has a right-click Go > <command> menu providing these views (in addition to standard Go commands: Properties and Links).

ScheduleEditorProvides a two-paned graphical view (Figure 6-25) with four different tabs, including: Weekly: The primary tab, showing days of the week (Sun through Sat) where daily events are graphically reviewed and modified. Holiday: Defines the schedule events (if any) that are executed during a holiday (when an active is present at the holidayOverride input). Special Events: Using the right-side calendar pane and the ScheduleEditor menu bar pull-down, special events can be added and configured. Special events are typically one-time events occurring on one or more days. Links: Shows a list of objects, by complete swid, that are under control of the Schedule object (linked to an output). EventCalendarShows the entire calendar year (all 12 months), with special events (or holidays from a linked Calendar object) indicated by shading. Arrow controls allow you to scroll backwards and forwards through the years. The ScheduleEditor view is the default view for a Schedule object in the JDE (double-click in Tree View) and from a linked Gx object in a Web browser (providing that the station with Schedule object also has the WebUiService).

Notes

However, the browser view differs slightly by offering a Schedule Summary, instead of tabs for selecting event-time editors (Figure 6-26). The list of objects controlled by the Schedule (Links) is not available to a Web browser user. Admin-level-write privileges are required for any user to create, delete, and modify schedule events. If you provide access to a browser user to a Schedule through a linked Gx object, be aware of this. Unlike commands through a linked Gx object, which are checked against the users privileges for the Gx object, Schedule events are considered config properties of the target object.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

653

Chapter 6 Schedule

Apps Objects

Properties
Table 6-11 Schedule object properties.

Tab Property Name

objectType, statusFlags, description isActive

Description
See Table 6-1 on page 6-5 for information on these properties common to all apps objects. Read Only: Required for BACnet. Reflects whether the object is capable of providing event-time scheduling control (is operating within its effectivePeriod).

Valid Values

Default

Notes

Status

False, True

True

See the Config property effectivePeriod.

executionParameters

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 6-5. Read-Write: BACnet usage only. Set to a positive integer for this object to appear as a BACnet Schedule object to other BACnet devices. See foreignAddress, page 6-6, for more information. Read-Write: (Future use only.) Read-Write: Defines the priority level used at the prioritizedOutput. Read-Write: Defines a to and from date range, in which the objects outputs are allowed to be made active from scheduled active event-times. The date format is <day <mo> <year>, with wildcards set by asterisks (*). Typically left at default (year-round). 0 to 4194302 or -1 (not exposed)

fixed_min utely, processor -1 If set, must be a unique number among all other Schedule objects in station.

foreignAddress

membershipGroups priorityForWriting

niagaraR2 Any priority level, from 1 to 16 See descrip.

niagaraR2 Leave at default. Schedule (16) 1 Jan **** to 31 Dec **** If a slave object, this range is read-only (set in master). The effectivePeriod does not apply to active values received at the overrideIn input. State descriptors can display at a linked GxText object.

effectivePeriod

Config

activeInactiveText

Read-Write: Defines how states display at the statusOutput and prioritizedOutput. Read-Write: Defines the number of days that must transpire before any expired special events are removed from the objects EventCalendar (when using the objects command cleanupSpecials). Read-Write: Defines how an active schedule event-time or overrideIn input appears at the objects outputs. Read-Write: Defines how an inactive schedule event-time or overrideIn input appears at the objects outputs. Read-Write: See position, page 6-6. Read-Write: Defines the color used in the event-time columns of the ScheduleEditor to denote active (On) event times. Read-Write: Defines the color used in the event-time columns of the ScheduleEditor to denote inactive (Off) event times.

Any desired descriptors for the two states.

Active, Inactive

specialCleanup (d)

positive integer 14 0 is up to previous number of days (2 weeks) day. Negative numbers can be used to remove up to the current days (-1) or beyond (future). true, false, auto true Selection of auto applies to the prioritizedOutput onlythis is equivalent to a false for the statusOutput.

trueCommand

falseCommand

true, false, auto

false

position activeColor Visual

Any color selectable in the Edit dialog. Any color selectable in the Edit dialog.

green

inactiveColor

dark gray

654

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects Schedule

Table 6-11

Schedule object properties. (continued)

Tab Property Name

templateUrl Visual, cont.

Description

Valid Values

Default

Notes
Does not apply if the Schedule object resides in a station without the WebUIService.

Read-Write: Specifies the swid to an HTML Valid swid to an template used to frame the objects appropriate schedule in the schedule applet (when HTML viewing it in a Web browser). template. If left blank, the stations schedule template is used (WebUIServices Config property, scheduleTemplateUrl). If that property is blank, the stations defaultTemplateUrl is usedalso a WebUIService property.

minExecuteTime, maxExecuteTime, averageExecuteTime, userData holidayOverride Default Engineering statusOutput (output: sOut) prioritizedOutput (output: pOut) masterOut (output: master) slaveIn (input: slaveIn) Security securityGroups

Properties common to all apps objects. For more information, see Table 6-1 on page 6-5. Read-Write: Default value for the holidayOverride input, used if it is not linked, or if it has a fault status. Read Only: Shows the current state and status of the statusOutput, one of the two main linkable outputs. Read Only: Shows the current state and priority level of the prioritizedOutput, the other of the two main linkable outputs. Read Only: Always shows SlaveSync. Read Only: Always shows SlaveSync. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 6-6

False, True

False

Typically seldom (if ever) set to True.

Inactive, Active

Inactive : {ok} Inactive : @ 16 SlaveSync No real-time status (or indication of a master/slave link) is SlaveSync provided on the property sheet. General

Inactive, Active @ <pri. level> SlaveSync SlaveSync General, 7 others

Schedule Notes
The 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. 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

Note

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

655

Chapter 6 Schedule

Apps Objects

Figure 6-24

Schedule is typically linked to a Calendar object and one or more BO objects.

Schedule object

Schedule Object Processing and Priorities

As with Calendar objects, the ControlEngineService executes Schedule objects once at the top of each minute (fixed). This means that changes in schedule times and input changes (overrideIn, holidayOverride) become effective only once a minute. How the outputs respond to the objects configured schedule event-times and override inputs is done in a prioritized fashion on each execution cycle. From highest to lowest, the priorities of evaluation can be summarized as follows:
1. 2. 3. 4.

overrideIn input (if linked) Special Events, as configuredreplace holiday and weekly events holidayOverride input (if linked)replace weekly events weekly schedulenormal time-of-day (weekly) events

Table 6-12 provides a matrix showing output action, beginning with the normal weekly schedule control.
Table 6-12 Schedule object priority evaluations (at the top of each minute).

Weekly schedule action

active inactive whatever whatever whatever whatever whatever

overrideIn Input
none or auto none or auto active inactive none or auto none or auto none or auto

Special Event action (if any)

none none whatever whatever active inactive none

holidayOverride Input
none or inactive none or inactive whatever whatever whatever whatever active

statusOutput, (prioritizedOutput)
trueCommand(@priorityForWriting) falseCommand(@priorityForWriting) active1(@priorityForWriting) inactive1(@priorityForWriting) trueCommand(@priorityForWriting) falseCommand(@priorityForWriting) (Follows the holiday schedule, either): falseCommand(@priorityForWriting),or trueCommand(@priorityForWriting) A holiday schedule should not be left blank (no events), assuming inactive. Otherwise, an output that is active upon transition to the holiday day will remain active. See Figure 6-25 on page 6-58.

1.

Note an active or inactive at the overrideIn input bypasses the trueCommand or falseCommand property configurations.

656

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects Schedule

Output Configuration

The Schedule object has two main outputs: statusOutput and prioritizedOutput. Three config properties directly affect how these outputs operate, as follows: priorityForWritingDefines the priority level (from 1 to 16) that is always used at the prioritizedOutput. By default, this is 16 (Schedule level). trueCommandDefines the output state (true, false, or auto) produced during an active schedule event-time, where true = active, false = inactive. By default, this is true. (Note: auto is equivalent to true for the statusOutput). falseCommandDefines the output state (true, false, or auto) produced during an inactive schedule event-time, where true = active, false = inactive. By default, this is false. (Note: auto is equivalent to false for the statusOutput).

All three of these properties are typically left at default values. However, in the situation where the output of one (overriding) Schedule object feeds the overrideIn of another Schedule object, either the trueCommand or falseCommand of the overriding Schedule object should be set to auto. Otherwise, both objects will operate strictly from the overriding Schedule objects action.

Master / Slave Operation

The Schedule objects output masterOut and input slaveIn allows a single master Schedule object to globally define all scheduling event-times, including special events, in all of its linked slave Schedule objects. Any event-time change made in the master Schedule object is immediately copied to its slave objects. This is particularly useful in multi-station jobs. The typical application is as follows: Master Schedule objects reside in the Web Supervisor. Slave Schedule objects reside in JACE controllers. You link the masterOut from a Web Supervisor-resident Schedule object to the masterIn input of one or more JACE-resident Schedule objects.

In case of a communications failure between devices, each JACE retains schedule configurations, as this data is persistently stored in all Schedule objects. If a Schedule object is linked as a slave, its schedule setup cannot be directly modified. Its ScheduleEditor view still shows the weekly, holiday, and special event times as programmed in the master Schedule, but as read-only. However, note that most properties on its property sheet are independent, for example, priorityForWriting, trueCommand, falseCommand, and others. Exceptions to this include the effectivePeriod and activeInactiveText properties, which do have a master/slave relationship. A linked slave object receives all of the masters schedule event-times only upon an event-time change in the master object (with communications OK). This applies mostly to a newly-linked slave Schedule object, but can apply if changes are made when device communications are down. Typically, when engineering master/slave Schedule objects in stations, corresponding master/slave Calendar objects are also used.

Notes

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

657

Chapter 6 Schedule

Apps Objects

ScheduleEditor Notes

In the JDE, the ScheduleEditor view for a Schedule object provides three separate tabs to enter event-times, as shown in Figure 6-25. WeeklyProvides 7 columns, one for each day of the week. HolidayProvides a single column, which describes the schedule events (if any) that occur for any day designated as a holiday. SpecialEventsProvides 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.

Weekly schedule has 7 columns for all the days of the week.

In the JDE, the right side of the ScheduleEditor shows calendar with any special event days or holidays indicated by shading. The Holiday tab is a single column that defines the schedule action whenever the holidayOverride input is active. It is recommended that you do not leave this blank (no event times), but instead enter an eventeven if just Inactive starting at 12am midnight and continuing for the rest of the day (as shown here). Otherwise, loads may unexpectedly continue operation over a holiday. The Special Events tab works with the currently selected day (or days) on the right-side calendar view to define special event actions. In this case, the day selected is not a Special Event day. When a Special Event day is active, events replace all normal time-of-day events.

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.

658

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 6

Apps Objects Schedule

When accessing a Schedule object using a browser, the weekly, holiday, and special events views are on separate links of a Schedule Summary page (Figure 6-26).
Figure 6-26 Browser access to Schedule object starts with a Schedule Summary, providing a row of links.

The Schedule Summary page provides separate links to the weekly, holiday, and special events views. If the object is linked to a Calendar object, a link to its Calendar view also appears. Links to the weekly, holiday and special events run the schedule applet within the designated HTML template. This is defined in the Schedule objects Visual property templateUrl (or if not designated there) in the WebUIServices property scheduleTemplateUrl. The weekly and holiday schedule operate like the tab equivalents when using the JDE ScheduleEditor.

The Special Events link provides a listing of all special events for object. You can select one to either review (Display) or delete, but you cannot modify one. You can, however, add a new special event.

Notes

The Special Events link provides a list of all special events for the Schedule object (unlike the graphical day indication on a calendar when using the JDE). You can select a listed special event to display or delete, if needed (but not to modify). Or, choose New to add a new special event. Time-of-day events are added in the same graphical manner as in the JDE. However, date selections for special events use a text dialog vs. a calendar.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

659

Chapter 6 StringLog

Apps Objects

StringLog
Quick reference for all properties: Table A-73 Inputs
statusInput

Default Object Shape

Outputs
(none)

abbrev: (none); StringLog StringLog objects store the value received on the statusInput as an ASCII string, adding a timestamp. The FlexBindingType input allows you to link it to most object outputs (excepting TriggerTypes). As with other log objects, log samples occur at regular intervals or upon change-of-value, depending on the objects configuration. This object has the standard config properties that define the size and operation of the log buffer, log archive schemes, and log collection modes. Linkable inputs are available to enable/disable log sampling, trigger log archiving, or trigger the clearing of log samples. Trigger outputs fire upon each log sample and when logs are archived.
Parent Dependencies: None (any

All Inputs / Outputs

Inputs
executeTrigger doArchiveTrigger doClearTrigger logEnable statusInput recordedTrigger archivedTrigger

Outputs

Input / Output Property Reference for BinaryLog object

(only input and output types, see Table 6-13 for all properties)

Type
input

Label
exe doArchi doCleari enable in recorde archive

Property Name
executeTrigger doArchiveTrigger doClearTrigger logEnable input recordedTrigger archivedTrigger

Data Species
TriggerType TriggerType TriggerType BooleanStatusType FlexBindingType TriggerType TriggerType

container).
Resource Count Range: 115 to 160, assuming bufferSize of 60 (default). Add 1 resource count for each 1-increase in the objects bufferSize. Trigger Properties

output

The StringLog object has the standard input property, executeTrigger, (typically not used) and also two other trigger-type inputs: doArchiveTriggerA received pulse causes the log data currently held in the objects log buffer to be archived (sent to the LogService archive destination). doClearA received pulse causes all log data currently held in the objects log buffer to be cleared. In addition, there are 2 available trigger-type outputs, described as follows:

recordedTriggerFires upon each recorded log sample. archivedTriggerFires each time the objects log buffer is archived.

Commands
For any user with Admin-level privileges, a right-click command menu provides these commands: clearClears all log data currently held in the objects log buffer. archiveArchives all log data currently held in the objects log buffer. clearLastArchiveResets 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).

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

660

Chapter 6

Apps Objects StringLog

Properties
Table 6-13 StringLog object properties.

Tab Property Name

objectType, statusFlags, description Status

Description
See Table 6-1 on page 6-5 for information on these properties common to all apps objects.

Valid Values

Default

Notes
If description is entered, it is used to list the log in the stations log index: http://<sta>/log/index

lastArchiveTimestamp

Read Only: Shows a date/timestamp for when the last archive occurred. Shows null if there have been no archives or if the clearLastArchive command was given.

null

executionParameters foreignAddress membershipGroups bufferSize, stopWhenFull, archiveSetup, logEnableDefault, collectionMode, daysOfTheWeek, timeRange, interval position Config

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 6-5. Read-Write: Does not apply to this object. Read-Write: (Future use only.) See Table 6-2 on page 6-16 for more information on these properties common to all log objects. -1 niagaraR2

normal, processor -1 niagaraR2 Leave at default. The collectionMode default is change_of_value. Typically, this is left at default.

Visual

Read-Write: See position, page 6-6.

Engineering

minExecuteTime, maxExecuteTime, averageExecuteTime, userData logEnable (input: enable) input (input: in)

Properties common to all apps objects. For more information, see Table 6-1 on page 6-5. Read Only: Shows the current boolean state and status of the logEnable input. Read Only: Shows the current string value received on the input. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 6-6

false, true : {status flags} Any ASCII string General, 7 others

false : {ok} Shows false if logEnable is not linked. Unbound General

Security

securityGroups

StringLog Notes
Recorded logs differ from other log objects in that only two fields are present:

timestampWhen the log was recorded. The format is: <time> <day-mo-year> <time zone>, for example: 12:07:49 25-Jun-2001 EDT valueThe ASCII string at the log objects statusInput.

Also, there is no LogChart view for a StringLog object. The default view is the LogTable view.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

661

Chapter 6 StringLog

Apps Objects

FlexBinding Input The statusInput of a StringLog object uses a FlexBindingType data speciesthis
means it is link-compatible with almost any object output (not just String types). For example, if linked to the prioritizedOutput of a BO object (Figure 6-27), the StringLog logs a string value of either true @<level> or false @<level>, where <level> is a number from 1 to 16, or def (for default).
Figure 6-27 Example StringLog object linked to a BO prioritizedOutput.

StringLog object, linked to a prioritizedOutput of a BO.

Example recorded logs of the StringLog, shown in its LogTable view.

Note that if the objects collectionMode is configured for change_of_value, in this example it will capture any command change from the source BO. This is true even if the objects state does not change (as opposed to the operation of a BinaryLog). Of course you can link a StringLog object to a string-type output as well, as shown in Figure 6-28. This log records the runtime (in Hr:Min:Sec) of a chilled water pump.
Figure 6-28 Example StringLog object linked to a String type output.
StringLog object, linked to a String type output of a conversion Program object. In this case, the StringLog collectionMode is set to interval, with its interval set to 60 (minutes).

Example recorded logs of the StringLog, shown in its LogTable view.

662

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

CHAPTER

Container Objects
This chapter describes each of the standard Niagara container-type objects, that is, those provided in the containers folder of the tridium JAR file. General information on container-type objects is provided first, as follows: About Container Objects Tree View Controls Container Functions Inputs and Outputs Layers in Containers Browser Views Common Container Object Things Security Groups and Containers Alarm and Alert Text Common Container Object Properties Containers That Composite To Composite Or Not to Composite

Note

For the remaining sections, the term container object is used generically for any container-type object (any type listed below). Whenever a specific type of container is described, including the Container object, it is capitalized. Individual container object descriptions follow, arranged alphabetically as follows:

Bundle Composite Container GxPage PollAlways PollOnDemand ServiceContainer

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

71

Chapter 7 About Container Objects

Container Objects

About Container Objects

Container objects provide the means to organize standard primitive objects (control, apps, and Gx), plus other container objects, in a hierarchical manner. In use, they contain child objects, meaning other objects reside in their Workspace. In fact, the Workspace view is the primary view for any container object1double-click the object in the JDE Tree View, and its Workspace appears. The ultimate container object (although not categorized as such) is the Station object, as all other objects in the station can be considered its child objects.

Note

Tree View Controls

Container icons in the JDE Tree View differ among the different container types. Default container icons are shown in Figure 7-1, left.
Figure 7-1 Default container icons seen in the Tree View.

Bundle or Composite GxPage Container Expand means child objects exist.

Child objects

PollAlways PollOnDemand

The Tree View has special navigational functions that work with container objects. A containers parental status is indicated by an expand control to the left of its icon. Expand the control and its child objects are revealed (Figure 7-1, right). As most containers allow multiple levels, additional containers may exist as child objects, each with their own child objects. Right-click commands allow you to cut, copy, and paste objects, including containers, as needed in the station database. This is especially useful when replicating an application that consists of one or additional (nested) containers, or when saving applications to your local library. In summary, a container object is defined mainly by its collection of child objects. Often, the properties of the container object itself are of minor importance.

1. The one exception is the stations ServiceContainer, which has no Workspace. The primary view for a ServiceContainer is the ServiceManager view.
Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

72

Chapter 7

Container Objects About Container Objects

Container Functions
For selection purposes, the functions provided by container objectsby object type, include:

Simple folder organizationContainer and PollAlways. Encapsulation of child objects into a simpler objectBundle and Composite. Browser-accessible graphic with real-time valuesGxPage. Demand-based polling of child integration objectsPollOnDemand. Folder for all station servicesServiceContainer.

Some container objects are executed in the station by the control engine (managed by the ControlEngineService), along with control and apps objects. These include the more complex Bundle, Composite, and GxPage objects.

Inputs and Outputs

The simplest container objects (Container, PollAlways, PollOnDemand, and ServiceContainer) act mainly as folders. These containers provide no inputs or outputs, meaning links cannot be made directly to themonly to child objects. However, the remaining container types (Bundle, Composite, and GxPage) have an available composite mechanism. This allows contained child objects, on a configurable basis, to have their outputs and/or inputs exposed through the parent containermeaning that the container object acquires outputs and inputs. This mechanism can be thought of as encapsulation, where only the most likely linkable properties are exposed. Those needed only internally are left inside the containers Workspace. See the Containers That Composite section on page 7-8 for more information.

Layers in Containers
Containers have independent layer controls for both the Workspace and the WorkspaceEditor views. Typically, layers are important only in GxPage containers, as each Gx object has an associated layer property, used for overlap control. For more information on GxPage layers, see the Layer Control section on page 7-26. However, in any container holding control logic, you may want to add GxText objects, say, for annotations. This may be useful when in the WorkspaceEditor, but undesirable when observing real-time values in the Workspace (monitor mode).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

73

Chapter 7 Common Container Object Things

Container Objects

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).
Figure 7-2 Layer control can be used in any type of container, but applies mainly to Gx objects.

GxText objects (layer_3) are visible in the WorkspaceEditor.

In the containers Workspace, layer_3 (used by GxTexts) has been made not visible.

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 (if the 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 Things

Container 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

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

74

Chapter 7

Container Objects Common Container Object Things

Security Groups and Containers

Like Niagara primitive objects, container objects have a securityGroups property. This property is available on the objects 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 itincluding 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 of the objects 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 objects (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 Up Process

If both the containers alarmText or alertText and a child objects alarmText or alertText is at the default hyphen (-), the next (higher) parent containers alarmText or alertText value is used. This pass up process continues, potentially all the way to 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.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

75

Chapter 7 Common Container Object Things

Container Objects

Commands
Container objects have no right-click commands. However, for a JDE user with Command, Admin privileges, the dump command is available for any of the simpler container objects (Container, PollAlways, PollOnDemand): Commands > dumpSends 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 properties for all container objects.

Tab Property Name

objectType

Description
Read Only: The container object type. By default, a newly added object uses this string in its name (until renamed).This text appears inside the objects shape in JDE. The full string for the object type is shown, for example, Composite or GxPage.

Valid Values
See description

Default

Notes

reflects For any of the complex object type containers (Bundle, Composite, GxPage), you can edit this using the displayTypeString property. {ok} Unlike many control objects, containers do not have alarm states. In the case of composited containers, they do not assume alarm or fault conditions from linked inputs. For a GxPage container, this is sometimes linked to a GxText object in that container (or another GxPage). Not available for any of the simpler container types, namely the Container, PollAlways, and PollOnDemand. Usually, default values are recommended. The selection on_trigger is not valid for containers. For related details, see ControlEngineService Config property executionFrequency.

statusFlags Status

Read Only: Current state of the objects status flags. A normal state (no flags set) is where the status flags value is {ok}, and the objects color is gray. The only status flag that can be set is:

either: {ok} (no flags) or {down}

downThe station is down or offline.

The object s shape and outputs are yellow. description Read-Write: Permits a user-defined text descriptor for describing the container. Any printable characters, including spaces and mixed case characters, are allowed. Read-Write: Applies to a Bundle, Composite, or GxPage only. Defines the frequency and order for the object as it is executed by the stations control engine. See description

execution Parameters

freq (frequency)Specifies how often the

object is executed. For most containers, the default frequency (normal) is acceptable. orderSpecifies the order of execution in each cycle. On each cycle of the control engine, objects specified as inputs are processed first, then processors next, and lastly the outputs. By default, the Bundle, Composite, and GxPage containers default to the processor order. Config

freq: never slower normal faster fastest minutely on_trigger order: input processor output

freq: normal order: <see descrip>

76

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 7

Container Objects Common Container Object Things

Table 7-1

Common properties for all container objects. (continued)

Tab Property Name

foreignAddress Config, cont.

Description
Read-Write: BACnet usage only. Exposes the Niagara object as a BACnet object.

Valid Values
-1 (not used)

Default
-1 (not used)

Notes
These properties are not shown for the simpler containers. Leave at default settings.

Note: Currently, this property does not apply to any container object.
membershipGroups Read-Write: (Future use only.) position Read-Write: The x-y coordinates for the objects position on the JDE Workspace. Coordinate values are in pixels, and are relative to the upper-left corner of the Workspace and the upper-left corner of the object shape (including its input area). An object with a position of 0,0 is in the top left corner of the Workspace. niagaraR2 Some positive x, y value less than the parent (container) objects size property value. niagaraR2 Near the mouse pointer when the object is first created. Typically, you dont manually enter position values, but use the mouse to drag the object as needed on the JDE Workspace. However, if needed, you can enter values directly to tweak an objects position. Providing that the ControlEngineService was set to profileNodes, these properties show the objects execution statistics. Typically, you do not leave the ControlEngineService configured this way except for brief periods to collect these values. This properties are not available (nor apply to) any of the simpler containers.

Visual minExecuteTime

Read-Write: Can show the objects minimum execution time, in milliseconds. Shows MAX_VALUE if profileNodes in the ControlEngineService was not previously set (since the last station start).

integer, 0 to n

See descrip.

maxExecuteTime Engineering

Read Only: Can show the objects maximum execution time, in milliseconds. Shows MIN_VALUE if profileNodes in the ControlEngineService was not previously set (since the last station start).

integer, 0 to n

See descrip.

averageExecute Time

Read Only: Can show the objects average execution time, in seconds. Shows 0.0 if profileNodes in the ControlEngineService was not previously set (since the last station start).

valid float

See descrip.

userData

Read-Write: Stores a user entered string. Can be used by servlets and the API for configuration information. Read-Write: Shows the security groups to which the container is assigned. A user must have the appropriate privileges in at least one security group to view and modify properties and issue commands. Refer to the Security Tab section on page 1-20 (Station object UserAdmin topic) for more details on how securityGroups settings apply.

Any desired text string for servlet/API usage. Any mix of these types:

<blank>

securityGroups

General

General HVAC Security Life Safety Group 4 Group 5 Group 6 Group 7

For more information, see the Security Groups and Containers section on page 7-5. Also refer to the About Security section on page 1-21.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Security

Revised: April 20, 2004

77

Chapter 7 Containers That Composite

Container Objects

Containers That Composite

Three types of container objects have composite capability. This means that you can selectively expose inputs and outputs of their child objects at the container-level. Essentially, this encapsulates the inner workings of the object, and highlights important inputs and outputs for linkage to other objects (Figure 7-3). These container types are: Bundle Composite (surprise) GxPage

Figure 7-3 Example Bundle and GxPage objects with exposed (composite) properties.
Bundle objects GxPage object

Note

Composited containers shown above are from one of the standard tridiumx/lib applications, available in the Local Library (tridumx/lib JAR, applications folder). In general, these applications are excellent examples of using composited containers.

78

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 7

Container Objects Containers That Composite

To Composite
When working inside the WorkspaceEditor for any of these objects, a Composite command is available (Figure 7-4). This command is present on the right-click menu for any child object, and even when no child object (only background) is selected.
Figure 7-4 Composite command available on Bundle, Composite, or GxPage Workspace.

Composite command opens the Composite Editor for that container object.

The following composite-related topics follow: Composite Editor About Composite Property Names Adding Properties Deleting Properties Inputs and Default Values

Caution

There are known limitations of composited containers, particularly for use with control logic. See the Or Not to Composite section on page 7-13 and the Bundle Issues section on page 7-16 for more details.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

79

Chapter 7 Containers That Composite

Container Objects

Composite Editor

As shown in Figure 7-5, the composite editor is where you choose properties (inputs and outputs) of the containers child objects to expose at the container levelan 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.
Figure 7-5 Composite editor has a Properties side and an Exposed side.

The Properties side lists all inputs and outputs for one child object. Select any child object using the drop-down list, which refreshes the list on the Properties side. The Exposed side lists all inputs and outputs that are currently exposed. This includes inputs and outputs from all child objects. This figure shows the composite editor for a Bundle before any inputs or outputs have been exposedthe Exposed side is blank. Also, no property is currently selected on the Properties sidethe Selected Property is blank and its action buttons are grayed (unavailable).

Properties side

Exposed side

Drop-down list to select a child object, by object name. Selected Property field and associated action buttons.

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 sOutAirFlowfor the statusOutput of AirFlow. eventTriggerAirFlowfor the eventTrigger output of AirFlow.

When adding a property, you can accept the default name or simply retype it. 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.

Notes

710

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 7

Container Objects Containers That Composite

Adding Properties

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. 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.

Note

Step 1

In the composite editor, click the drop-down list of child objects and select an object. Click a property to select it. The default name appears in the Selected Property field. Edit the default name, as needed (or optionally accept it). Click Add. The property appears on the exposed side. It will be exposed when you click OK to close the composite editor (as well as any other changes done while in the editor). 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 containers 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 ( ). Any composite property must be unlinked before you can delete it. Furthermore, you cannot delete a property if another composite property is listed 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).
Deleting a composite (exposed) property.

Step 2

Step 3 Step 4

Deleting Properties

Notes

Procedure 7-2

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. Click Delete.
a.

Step 2

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 you click OK to close the composite editor. 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).

b.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

711

Chapter 7 Containers That Composite

Container Objects

Figure 7-6

Error popup dialog when attempting to delete a composite property.

This attempt to delete OccStatus (second property from the bottom), produced an Error popup. Possible reasons for this error: 1. OccStatus is linked, and/or 2. ZoneTemp (property below it) is linked.

In this particular case, the OccStatus property was already unlinkedhowever, the ZoneTemp property (below it) was linked. Here, ZoneTemp must be unlinked before the property above it can be removed. If needed, ZoneTemp can be re-linked afterwards.

Inputs and Default Values

When exposing inputs of child objects that use status type data species (FloatStatusType, BooleanStatusType, IntegerStatusType), note that each exposed input has an available default property value at the Composite (parent) level. As shown in Figure 7-7, you can access and modify default values on the Config tab of the Composite objects property sheet.
Figure 7-7 Default Input properties are for status-type inputs of a Bundle or Composite.

The default value is used by the child object whenever the composite input is not linked, or if a fault or down status is received on that input.

Note: Composite-level default input settings override any corresponding default input settings that exist at the child-object level.
Default properties appear for each status-type input exposed among the Composites child objects.

712

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 7

Container Objects Containers That Composite

Or Not to Composite
In general, all of the following statements are thought to be true. Please draw your own conclusions about using the composite feature.

There are known drawbacks when using Bundle or Composite objects to encapsulate control logic, including: Control response time is affected. The container now needs to execute during the object execution cycle, in addition to all of its child objects. Values coming in and out of a Bundle or Composite are not as fresh as when links are made directly between child objects.
Note

This is why you should not nest composited containersit is recommended that a maximum of one level of encapsulation is used.

Properties using certain data species do not work correctly when exposed through a Bundle or Composite. See the Bundle Issues section on page 7-16 for more details. Control logic using Bundle-to-Bundle and/or Composite-to-Composite links has proven particularly problematic. Make control logic links directly between control and apps objects, whenever possible.

Note

If the control logic in a composited container needs to be modified, some of the composites properties may first require unlinking, even if they appear unrelated to modifications. See the Deleting Properties section on page 7-11. GxPages are often (and quite successfully) not composited. In this case, links need to be made directly from control and apps objects to the contained Gx objectsindividually, and one-at-a-time. For unique applications, existing only once or twice, this is fine. In the case of an application that is replicated many times, yet wholly contained within the same station, this is typically not an issue. This assumes, of course, that the application is built such that a parent container contains the complete applicationincluding the GxPage container(s), containers with control objects, apps objects, and all links among them. In the case of an application that is replicated many times, but parted out between stations (think Web Supervisor for GxPages and possibly logs, JACE-4/5 for control logic), a significant linking effort may be needed. Each Gx object on each GxPage of each application will require to be individually linked. In this case, composites of GxPages in the Web Supervisor (along with Bundled control logic in the JACE-4/5) can save much engineering time as a result of the linking match feature. Bundle and Composite objects exist to be composited. If child properties are not exposed, either type functions like the simpler Container. However, the Bundle or Composite is still processed by the control engine. For this purpose, a Container object uses less overhead and is a better choice.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

713

Chapter 7 Bundle

Container Objects

Bundle
Quick reference for all properties: Table A-13 Inputs
(none)

Default Object Shape

Outputs
(none)

abbrev: (none); Bundle The Bundle object is the successor to the Composite object, offering a method to encapsulate child objects. However, the Bundle provides moreuser access to commands and views of exposed child objects (if linked to a GxPage composite). A Bundle is useful for linking exposed control logic (outputs) to a composited GxPage (inputs). However, to avoid possible problems, do not make logic-to-logic links that pass through a Bundle or Composite. Instead, make these links directly between the primitive child objects. As with Composite and GxPages objects, a Match (by-name) feature is available when linking exposed inputs and outputs.
Parent Dependencies: None (any
Type
input1 output

Example Inputs / Outputs

Inputs
(as exposed from child objects)

Outputs
(as exposed from child objects)

Note:

Input / Output Property Reference for Bundle Object

(only input and output types, see Table 7-2 for all properties)

Label / Property Name

(as exposed in Composite Editor) (as exposed in Composite Editor)

Data Species
(as in the exposed child object) (as in the exposed child object)

1.

For a variety of reasons, inputs to contained control objects should generally not be exposed.

container).
Resource Count Range: 48 to 74, plus the sum of all resource counts of child objects.

Caution

Bundles have known issues associated with some link types. In addition, performance can degrade if control logic passes through Bundle links. See the Bundle Issues section on page 7-16.

Commands
None from the Workspace containing the Bundle object. For a JDE user with Admin-level write privileges, the WorkspaceEditor for a Container provides these right-click menu commands: LayersProduces the Layer Options editor for the Workspace. Not typically used for a Bundle, as numbered layer settings apply only to Gx objects. ArrangeProduces the Arrange Glyphs editor, which allows you to globally position child objects within the containers Workspace, using display order, name, or type. Typically used before links between objects are made. ReorderProduces the Reorder editor. Allows you to change the order that child objects are listed under the Bundle in the Tree View. It does not affect placement of child objects on the Workspace. CompositeProduces the composite editor (see page 7-10).

714

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 7

Container Objects Bundle

Properties
Table 7-2 Bundle object properties.

Tab Property Name

objectType, statusFlags, description Status

Description
See Table 7-1 on page 7-6 for information on these properties common to all control objects.

Valid Values

Default

Notes

executionParameters Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 7-6. foreignAddress membershipGroups typeString Config Read-Write: Does not apply to this object. Read-Write: (Future use only.) Read-Write: (Future Use) Defines the name of an HTML file used for on context Help when the objects property sheet is open in the JDE. This file must have a tridium\docs file path. -1 niagaraR2 Bundle

normal, processor -1 niagaraR2 Leave at default. Bundle Not currently implemented.

displayTypeString

Any desired Read-Write: Defines the text label that appears inside the top of the objects shape when ASCII text string, including viewed in the JDE Workspace. spaces The default is Bundle. Examples: VAV1 Logic or AHU Logs. Read-Write: The message text used in the Any desired alarm record for a child object alarm, providing ASCII text that object has a default hyphen (-) alarmText. string, including spaces Read-Write: The message text used in the alert record for a child object alert, providing that object has a default hyphen (-) alertText.

Bundle

Short text strings are recommended, to keep the object shape from unduly expanding. For either, if left at default hyphen (-), the alarmText or alertText of the next (up) parent container is used.

Alarm Setup

alarmText

alertText

position decimalFormat

Read-Write: See position, page 7-7. Read-Write: Sets decimal precision for float values of exposed inputs and output as seen on the objects shape in the JDE. Read-Write: Defines the icon used to represent the object in the JDE Tree View. The default is the standard jigsaw graphic contained in the coreUI module JAR file: /tridium/images/icons/composite.gif

0 to 6, (+) sign, no (+) sign Any .gif file accessible by the station, using a size of 16 x 16 pixels. x: 10 to 1500 y: 10 to 1500 Any color, as set in the Color Editor

2, Has little practical no (+) sign usedoes not affect links to outputs. See Descrip.

icon

Visual

size

Read-Write: Defines (in pixels) the overall size of the containers Workspace. Dimensions are specified by x (width) and y (height). Read-Write: Specifies the background color of the containers Workspace. Read-Write: (Future Use) Specifies the URL to display on alarm.

x:800 y:550

backgroundColor

(white) r255, g255 b255 Not currently implemented.

alarmPageUrl Security Engineering

minExecuteTime, Properties common to Bundle, Composite, and maxExecuteTime, GxPage container objects. For more averageExecuteTime information, see Table 7-1 on page 7-6. userData securityGroups Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 7-7

General, 7 others

General

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

715

Chapter 7 Bundle

Container Objects

Bundle Notes
The 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. 2.

An application with GxPages is replicated many times. 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. 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 stationsbundled 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.

Notes

Bundle Issues
Table 7-3

Bundle (and Composite) objects have several known limitations and issues. Please review Table 7-3 carefully to avoid incorrect use when exposing child objects. General Guidelines
Avoid exposing inputs (of any type) to any contained control objects and apps objects (Calendar, Schedule, and Program). If an input is exposed, then any link to it must pass through the Bundle. 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 to inputs of other control objects. Control response does not suffer, because additional Bundle object execution time is not a factor.

Bundle (and Composite) object limitations, general guidelines.

Known Limitations
Exposed inputs and outputs that use the following data species 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

Note: Inputs to log objects (AnalogLog, BinaryLog, etc.) can be successfully exposed in a Bundle.
Never nest a Bundle or Composite object within another Bundle or Composite object.

A Bundle within a Bundle does not operate correctly.

716

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 7

Container Objects Bundle

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 objectsone with control logic, the other with logs.
Figure 7-8 Dividing a bundled application between two Niagara stations.

At right, the sns file for the application has been copied from the Local Library and pasted into the station for the Web Supervisor (MyStation). Also, the container FunctionGenerators was moved under the Bundle object named Control (using the Tree View and dragging the container to the Control container, selecting Move after dropping). This was done because the Control Bundle will be cut and pasted next, and the FunctionGenerator links are wanted intact. At right, the Tree View is used to cut the Control Bundle from the Web Supervisor station. This leaves the Bundle for logs (Logs) and the composited GxPage in the Web Supervisor.

At right, the Tree View is used to paste the Control Bundle into a JACE controller station (CntrlEngSvcTest). In this case, the Bundle is pasted inside a Container named Logic. Because this application was built using Bundles, the necessary external links between the GxPage (graphics), logs, and control logic can be done quickly using the Match feature (Figure 7-9).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

717

Chapter 7 Bundle

Container Objects

This example continues as the interstation (external) links are made.

Figure 7-9 Using the Match feature when linking a Bundle object.

Linking between objects in different stations is done using the Tree View and right-click commands Link From, Link To <obj>. At right, the composited GxPage (Graphics) is selected as From, and the Bundle Control (in the JACE station) is selected as To. (This order can be reversed with the same results.)

The Link Editor appears, showing the exposed inputs in the GxPage and the exposed outputs of the Bundle. Because exposed properties of the GxPage and the Bundle were named carefully, a single Match command arranges for 7 links to be made. Selecting OK results in all 7 external links to be made from the Bundle to the GxPage.

Note: In this specific app, the input ZoneTempText should also be linked to the output ZoneTemp.
At right, the external publications are shown in the Bundle outputs, and the external subscriptions are shown in the composited GxPage. The same type of Match link can also be made between the Logs Bundle (in the Web Supervisor) and the Control Bundle in the JACE station.

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.

718

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 7

Container Objects Composite

Composite
Quick reference for all properties: Table A-17 Inputs
(none)

Default Object Shape

Outputs
(none)

abbrev: (none); Composite The Composite object is mostly for legacy supportit 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.

Example Inputs / Outputs

Inputs
(as exposed from child objects)

Outputs
(as exposed from child objects)

As with Bundle and GxPages objects, a Match (by-name) feature is available when linking exposed inputs and outputs.
Parent Dependencies: None (any

Input / Output Property Reference for Bundle Object

(only input and output types, see Table 7-4 for all properties)

Type
input output

Label / Property Name

(as exposed in Composite Editor) (as exposed in Composite Editor)

Data Species
(as in the exposed child object) (as in the exposed child object)

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: LayersProduces the Layer Options editor for the Workspace. Not typically used for a Bundle, as numbered layer settings apply only to Gx objects. ArrangeProduces the Arrange Glyphs editor, which allows you to globally position child objects within the containers Workspace, using display order, name, or type. Typically used before links between objects are made. ReorderProduces the Reorder editor. Allows you to change the order that child objects are listed under the Bundle when expanded in the Tree View. It does not affect placement of child objects on the Workspace. CompositeProduces the composite editor (see page 7-10).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

719

Chapter 7 Composite

Container Objects

Properties
Table 7-4 Composite object properties.

Tab Property Name

objectType, statusFlags, description Status

Description
See Table 7-1 on page 7-6 for information on these properties common to all control objects.

Valid Values

Default

Notes

executionParameters Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 7-6. foreignAddress membershipGroups typeString Config Read-Write: Does not apply to this object. Read-Write: (Future use only.) Read-Write: (Future Use) Defines the name of an HTML file used for on context Help when the objects property sheet is open in the JDE. This file must have a tridium\docs file path. displayTypeString Any desired Read-Write: Defines the text label that appears inside the top of the objects shape when ASCII text string, including viewed in the JDE Workspace. spaces The default is Composite. Examples: 8-AND or RTU Logic. alarmText Alarm Setup Read-Write: The message text used in the Any desired alarm record for a child object alarm, providing ASCII text that object has a default hyphen (-) alarmText. string, including spaces Read-Write: The message text used in the alert record for a child object alert, providing that object has a default hyphen (-) alertText. -1 niagaraR2 Composite

normal, processor -1 niagaraR2 Leave at default. Composite Not currently implemented.

Composite Short text strings are recommended, to keep the object shape from unduly expanding. For either, if left at default hyphen (-), the alarmText or alertText of the next (up) parent container is used. See Alarm and Alert Text, page 7-5.

alertText

position decimalFormat

Read-Write: See position, page 7-7. Read-Write: Sets decimal precision for float values of exposed inputs and output as seen on the objects shape in the JDE Workspace. Read-Write: Defines the icon used to represent the object in the JDE Tree View. The default is the standard jigsaw graphic contained in the coreUI module JAR file: /tridium/images/icons/composite.gif

0 to 6, (+) sign, no (+) sign Any .gif file that can be accessed by the station, using a size of 16 x 16 pixels. x: 10 to 1500 y: 10 to 1500 Any color, as set in the Color Editor

2, Has little practical no (+) sign usedoes not affect links to outputs. See descrip.

icon

Visual

size

Read-Write: Defines (in pixels) the overall size of the containers Workspace. Dimensions are specified by x (width) and y (height). Read-Write: Specifies the background color of the containers Workspace. Read-Write: (Future Use) Specifies the URL to display on alarm.

x:800 y:550

backgroundColor

(white) r255, g255 b255 Not currently implemented.

alarmPageUrl Engineering

minExecuteTime, Properties common to Bundle, Composite, and maxExecuteTime, GxPage container objects. For more averageExecuteTime information, see Table 7-1 on page 7-6. userData

720

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 7

Container Objects Composite

Table 7-4

Composite object properties. (continued)

Tab Property Name

Security securityGroups

Description
Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 7-7

Valid Values
General, 7 others

Default
General

Notes

Composite Notes
Composite 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. 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. The Composite shown in Figure 7-10 is used to simplify an 8-input AND logic operation. This example Composite contains only cascaded Logic objects. Likely, this Composite application will be reused in the station.
Example Composite object representing 8-input logic gate.
The IOBar view in the WorkspaceEditor for a Composites child objects lists the exposed inputs and outputs. How the Composite appears on its Workspace.

Note

Example

Figure 7-10

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

721

Chapter 7 Container

Container Objects

Container
Quick reference for all properties: Table A-18 Inputs
(none)

Default Object Shape

Outputs
(none)

abbrev: (none); Container Container objects are simple holders of other objectsboth primitive types and/or other containers. They are the most frequently used container type in a station database. You can nest multiple levels of Containers in a station database, as needed. Like the PollAlways and PollOnDemand containers, Containers are not executed by the stations control engine.
Note: Use a LonContainer in place of a

Example Inputs / Outputs

Inputs
(none

Outputs
(none)

Input / Output Property Reference for Container Object

(only input and output types, see Table 7-5 for all properties)

Type
input output

Label

Property Name

Data Species

Container when engineering a Honeywell XL15C application. A LonContainer appears identical to a Container, however, it provides additional validation routines. The LonContainer is in the Local Library, tridiumx/lonworks/containers folder.
Parent Dependencies: None (any

container).
Resource Count Range: 30 to 42, plus the sum of all resource counts of all child objects.

Commands
None from the Workspace containing the Container container. However, for a JDE user with Admin-level write privileges, the WorkspaceEditor for a Container provides these right-click menu commands: LayersProduces the Layer Options editor for the Workspace. Not typically used for a Container, as numbered layer settings apply only to Gx objects. ArrangeProduces the Arrange Glyphs editor, which allows you to globally position child objects within the containers Workspace, using display order, name, or type. Typically used before links between objects are made. ReorderProduces the Reorder editor. Allows you to change the order that child objects are listed under the Container, when expanded in the Tree View. It does not affect placement of child objects on the Workspace.

722

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 7

Container Objects Container

Properties
Table 7-5 Container object properties.

Tab Property Name

Status objectType, statusFlags description

Description
See Table 7-1 on page 7-6 for information on these properties common to all containers.

Valid Values

Default

Notes

Config

(For each) Any desired ASCII text string, including spaces

container

alarmText Alarm Setup

Read-Write: The message text used in the alarm record for a child object alarm, providing that object has a default hyphen (-) alarmText. Read-Write: The message text used in the alert record for a child object alert, providing that object has a default hyphen (-) alertText. Read-Write: See position, page 7-7. Read-Write: Defines the icon used to represent the object in the JDE Tree View. The default is the standard folder graphic contained in the coreUI module JAR file: /tridium/images/icons/folder.gif

alertText

For either, if left at default hyphen (-), the alarmText or alertText of the next (up) parent container is used. See Alarm and Alert Text, page 7-5.

position icon

Any .gif file that can be accessed by the station, using a size of 16 x 16 pixels. x: 10 to 1500 y: 10 to 1500 Any color, as set in the Color Editor General, 7 others

See descrip.

Visual

size

Read-Write: Defines (in pixels) the overall size of the containers Workspace. Dimensions are specified by x (width) and y (height).

x:800 y:550 (white) r255, g255 b255 General Not currently implemented.

backgroundColor Read-Write: Specifies the background color of the containers Workspace. alarmPageUrl Security securityGroups Read-Write: (Future Use) Specifies the URL to display on alarm. Read-Write: Shows the security groups to which the object is assigned. For more details, see Security Groups and Containers, page 7-5.

Container Notes
Containers are often the most commonly used container type in a station database. Functionally, the Container is identical to the PollAlways objectthe difference is in name (objectType) and the Tree View appearance (icon) only. You can use the two container types interchangeably, as needed. However, under a device integration, use of PollAlways container is recommended, especially if also using PollOnDemand containers.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

723

Chapter 7 GxPage

Container Objects

GxPage
Quick reference for all properties: Table A-36 Inputs
(none)

Default Object Shape

Outputs
(none)

abbrev: (none); GxPage The GxPage object provides a graphical window into the system. It can contain only Gx objects, the components for making a graphical user interface. Gx objects have inputs for linkage to outputs of control and apps objects in stations. Real-time updates are displayed while the graphic is being viewed in the JDE, and command and view access is provided for commandable objects. If the station is running the WebUIService, GxPages can be accessed in an identical manner using a Web browser. A GxPage maintains an open connection back to the station serving the information. This allows the display to continue updating in real-time as values change. A GxPage can be used as a simple container or have inputs exposed in a composite form. Typically, a composite is made only if also engineering composited Bundles. When composited, a Match (by-name) feature is available when linking exposed inputs.
Parent Dependencies: None (any container). Child Dependencies: Only Gx objects. Resource Count Range

Example Inputs / Outputs

Inputs
(as exposed from child objects)

Outputs
(none possible)

Input / Output Property Reference for GxPage Object

(only input and output types, see Table 7-6 for all properties)

Type
input output

Label / Property Name

(as exposed in Composite Editor) (none possible)

Data Species
(as in the exposed child object)

54 to 77, plus the sum of all resource counts of child Gx objects.

Commands
None from the Workspace containing the GxPage container. For a JDE user with Admin-level write privileges, the WorkspaceEditor for a GxPage provides these right-click menu commands: LayersProduces the Layer Options editor for the GxPages Workspace. This is a useful command, as numbered-layer settings apply only to Gx objects. ArrangeProduces the Arrange Glyphs editor, which allows you to globally position child objects within the containers Workspace, using display order, name, or type. Typically not used in a GxPage Workspace. ReorderProduces the Reorder editor. Allows you to change the order that child objects are listed under the GxPage, when expanded in the Tree View. It does not affect placement of child objects on the Workspace. CompositeProduces the composite editor (see page 7-10).

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

724

Chapter 7

Container Objects GxPage

Properties
Table 7-6 GxPage properties.

Tab Property Name

objectType, statusFlags, description Status

Description
See Table 7-1 on page 7-6 for information on these properties common to all control objects.

Valid Values

Default

Notes

executionParameters Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 7-6. foreignAddress membershipGroups typeString Config Read-Write: Does not apply to this object. Read-Write: (Future use only.) Read-Write: (Future Use) Defines the name of an HTML file used for on context Help when the objects property sheet is open in the JDE. This file must have a tridium\docs file path. displayTypeString Any desired Read-Write: Defines the text label that appears inside the top of the objects shape when ASCII text string, including viewed in the JDE Workspace. spaces The default is GxPage. Examples: GxP1 or AHU1 Gx. Alarm Setup alarmText alertText Read-Write: Does not apply to this object. Read-Write: Does not apply to this object. -1 niagaraR2 GxPage

normal, processor -1 niagaraR2 Leave at default. GxPage Not currently implemented.

GxPage

Short text strings are recommended, to keep the object shape from unduly expanding. Child objects (Gx types) are not alarmable.

position decimalFormat

Read-Write: See position, page 7-7. Read-Write: Sets decimal precision for float values displayed at exposed inputs (as seen on the objects shape in the JDE). Read-Write: Defines the icon used to represent the object in the JDE Tree View. The default is the standard 3 Blocks graphic contained in the coreUI module JAR file: /tridium/images/icons/gxPage.gif

0 to 6, (+) sign, no (+) sign Any .gif file that can be accessed by the station, using a size of 16 x 16 pixels. x: 10 to 1500 y: 10 to 1500 Any color, as set in the Color Editor

2, No real usedoes no (+) sign not affect GxPage display of analogs. See descrip.

icon

Visual

size

Read-Write: Defines (in pixels) the overall size of the containers Workspace. Dimensions are specified by x (width) and y (height). Read-Write: Specifies the background color of the containers Workspace.

x:800 y:550

backgroundColor

(white) Often set to a r255, g255 color, especially if b255 background layer image is not used. Not currently implemented.

alarmPageUrl templateUrl

Read-Write: (Future Use) Specifies the URL to display on alarm.

Read-Write: Specifies the swid to an HTML Valid swid to an template used to frame the GxPage graphic (by appropriate the Gx servlet). If left blank, the global HTML HTML template referenced in the WebUIService template. (config property gxPageTemplateUrl) is used.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

725

Chapter 7 GxPage

Container Objects

Table 7-6

GxPage properties. (continued)

Tab Property Name

Security Engineering

Description

Valid Values

Default

Notes

minExecuteTime, Properties common to Bundle, Composite, and maxExecuteTime, GxPage container objects. For more averageExecuteTime information, see Table 7-1 on page 7-6. userData securityGroups Read-Write: Shows the security groups to which the GxPage is assigned. See Security Groups and Containers, page 7-5.

General, 7 others

General

GxPage Notes
GxPage 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 larger systems, GxPages are typically the primary function of the Web Supervisor station. GxPages, Gx objects, and related topics are explained in detail in the document Niagara Web Solutions Guide. Please refer to it for specific examples. 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.

Refer to

Layer Control

726

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 7

Container Objects GxPage

Figure 7-11

Layer Options dialog to set GxPage layer control.

These are the default layer settings for a GxPage.

There are 8 layers of primary importance in a GxPage, namely:

top layer_1 layer_2 layer_3 layer_4 layer_5 layer_6 background

Layer assignments of contained Gx objects determines overlap behavior of the objects when viewed in the GxPage. Layers above are listed from highest to lowest overlap priority (layer top overlaps layer_1, which overlaps layer_2, and so on). The lowest layer is background. By default, newly-added Gx objects are assigned to layer_3. Overlap control is initially determined by the order of creation (newer objects appear on top). You should assign overlapping Gx objects to separate layers, and not rely on creation order. Otherwise, problems may develop when the station database is exported and imported, for example, during a Niagara release upgrade.

Note

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

727

Chapter 7 GxPage

Container Objects

By default, all 8 of these layers in a GxPage are visible and enabled, except the lowest (background) layer, which is visible but not enabled (Figure 7-11). In general, you should keep all layers visible. If a layer is not enabled, you cannot select (more importantly, move) objects assigned to it. This is particularly useful after adding and sizing a GxImage, say, and then assigning it to the background layer. Layers assigned as not visible disappear only when using the JDE. If a GxPage is viewed in a browser, all 8 layers are visible (regardless of layer settings). Layer settings are independent for WorkspaceEditor and Workspace views. Usually, however, only WorkspaceEditor layer settings are used in GxPages.

Notes

GxPage composites

Using the composite editor, any GxPage can be composited, meaning selected inputs can be exposed at the container-level. This is typically done only when also engineering control logic in Bundles, for use in widely-replicated applications. Using this scheme can save considerable linking time, particularly if a GxPage and the source control and apps objects reside in different stations. Composited GxPages are used in the collection of standard Niagara applications (tridiumx/lib JAR, applications folder), along with Bundle objects for control logic and logs. In general, the lib applications demonstrate good techniques for using composited container objects. See the To Composite section on page 7-9 for more information.

Notes

728

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 7

Container Objects PollAlways

PollAlways
Quick reference for all properties: Table A-64 Inputs
(none)

Default Object Shape

Outputs
(none)

abbrev: (none); PollAlways PollAlways objects are actually the same as Container objects, merely simple holders of other objectsboth primitive types and/or other containers. Like the Container and PollOnDemand containers, PollAlways objects are not executed by the stations control engine. PollAlways containers are recommended in place of Containers whenever engineering under a specific device integration (BACnet, Modbus, DMS, GCM, etc.), and the continuous polling of contained shadow objects is needed. Their use makes it clearer in the Tree View, especially when PollOnDemand containers are also used.
Parent Dependencies: None (any

Example Inputs / Outputs

Inputs
(none

Outputs
(none)

Input / Output Property Reference for PollAlways Object

(only input and output types, see Table 7-7 for all properties)

Type
input output

Label

Property Name

Data Species

container).
Resource Count Range: 30 to 42, plus the sum of all resource counts of all child objects.

Commands
In its JDE Workspace, a PollAlways object has no commands. However, for a JDE user with Admin-level write privileges, the WorkspaceEditor for a Container provides these right-click menu commands: LayersProduces the Layer Options editor for the Workspace. Not typically used for a Container, as numbered-layer settings apply only to Gx objects. ArrangeProduces the Arrange Glyphs editor, which allows you to globally position child objects within the containers Workspace, using display order, name, or type. Typically used before links between objects are made. ReorderProduces the Reorder editor. Allows you to change the order that child objects are listed under the PollAlways container in the Tree View.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

729

Chapter 7 PollAlways

Container Objects

Properties
Table 7-7 PollAlways object properties.

Tab Property Name

Status objectType, statusFlags description

Description
See Table 7-1 on page 7-6 for information on these properties common to all containers.

Valid Values

Default

Notes

Config

(For each) Any desired ASCII text string, including spaces

Poll Always For either, if left at default hyphen (-), the alarmText or alertText of the next (up) parent container is used. See Alarm and Alert Text, page 7-5.

alarmText Alarm Setup

Read-Write: The message text used in the alarm record for a child object alarm, providing that object has a default hyphen (-) alarmText. Read-Write: The message text used in the alert record for a child object alert, providing that object has a default hyphen (-) alertText. Read-Write: See position, page 7-7. Read-Write: Defines the icon used to represent the object in the JDE Tree View. The default is the double handset graphic contained in the coreUI module JAR file: /tridium/images/icons/pollAlways.gif

alertText

position icon

Any .gif file that can be accessed by the station, using a size of 16 x 16 pixels. x: 10 to 1500 y: 10 to 1500 Any color, as set in the Color Editor General, 7 others

See descrip.

Visual

size

Read-Write: Defines (in pixels) the overall size of the containers Workspace. Dimensions are specified by x (width) and y (height).

x:800 y:550 (white) r255, g255 b255 General Not currently implemented.

backgroundColor Read-Write: Specifies the background color of the containers Workspace. alarmPageUrl Security securityGroups Read-Write: (Future Use) Specifies the URL to display on alarm. Read-Write: Shows the security groups to which the object is assigned. For more details, see Security Groups and Containers, page 7-5.

PollAlways Notes
PollAlways containers are functionally the same as Container containers. Note that icons for the two types of poll containers appear slightly different in JDE Tree View. The PollOnDemand container shows a diagonal line through it: The PollAlways container shows no diagonal line:

730

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 7

Container Objects PollOnDemand

PollOnDemand
Quick reference for all properties: Table A-66 Inputs
(none)

Default Object Shape

Outputs
(none)

abbrev: (none); PollOnDemand PollOnDemand objects are simple containers like Container and PollAlways objects, but with one important difference: the polling of child integration (shadow) objects occurs only when linked Gx objects (graphics) are being viewed. This on-demand polling scheme helps overall polling efficiency for many Niagara integrations. This feature (and object) is supported for most Niagara integrations using a polling method, including BACnet, DMS, GCM, Johnson N2, and others. It does not apply, however, to LonWorks shadow objects. Note: PollOnDemand containers are recommended to hold shadow objects used only for system monitoring and user interface. However, you should use PollAlways containers to hold shadow objects used in control logic or for data logging. See the Caution on page 7-33.
Parent Dependencies: None (any
Type
input output

Example Inputs / Outputs

Inputs
(none

Outputs
(none)

Input / Output Property Reference for PollOnDemand Object

(only input and output types, see Table 7-8 for all properties)

Label

Property Name

Data Species

container).
Resource Count Range: 30 to 42, plus the sum of all resource counts of all child objects.

Commands
In its JDE Workspace, a PollAlways object has no commands. However, for a JDE user with Admin-level write privileges, the WorkspaceEditor for a Container provides these right-click menu commands: LayersProduces the Layer Options editor for the Workspace. Not typically used for a Container, as numbered-layer settings apply only to Gx objects. ArrangeProduces the Arrange Glyphs editor, which allows you to globally position child objects within the containers Workspace, using display order, name, or type. Typically used before links between objects are made. ReorderProduces the Reorder editor. Allows you to change the order that child objects are listed under the PollAlways container in the Tree View.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

731

Chapter 7 PollOnDemand

Container Objects

Properties
Table 7-8 PollOnDemand object properties.

Tab Property Name

Status objectType, statusFlags description

Description
See Table 7-1 on page 7-6 for information on these properties common to all containers.

Valid Values

Default

Notes

Config

(For each) Any desired ASCII text string, including spaces

Poll On Demand Container For either, if left at default hyphen (-), the alarmText or alertText of the next (up) parent container is used. See Alarm and Alert Text, page 7-5.

alarmText Alarm Setup

Read-Write: The message text used in the alarm record for a child object alarm, providing that object has a default hyphen (-) alarmText. Read-Write: The message text used in the alert record for a child object alert, providing that object has a default hyphen (-) alertText. Read-Write: See position, page 7-7. Read-Write: Defines the icon used to represent the object in the JDE Tree View. The default is a double handset, lined graphic contained in the coreUI module JAR file: /tridium/images/icons/pollOnDemand.gif

alertText

position icon

Any .gif file that can be accessed by the station, using a size of 16 x 16 pixels. x: 10 to 1500 y: 10 to 1500 Any color, as set in the Color Editor General, 7 others

See descrip.

Visual

size

Read-Write: Defines (in pixels) the overall size of the containers Workspace. Dimensions are specified by x (width) and y (height).

x:800 y:550 (white) r255, g255 b255 General Not currently implemented.

backgroundColor Read-Write: Specifies the background color of the containers Workspace. alarmPageUrl Security securityGroups Read-Write: (Future Use) Specifies the URL to display on alarm. Read-Write: Shows the security groups to which the object is assigned. For more details, see Security Groups and Containers, page 7-5.

PollOnDemand Notes
A shadow object in a PollOnDemand container polls only while a linked Gx object is viewed (typically in a GxPage graphic). This dynamic polling is automatic, and applies whether the Gx object is being viewed in the JDE or in a Web browser connection. Icons for the two types of containers appear slightly different in JDE Tree View. The PollOnDemand container shows a diagonal line through it: The PollAlways container shows no diagonal line:

Figure 7-12 shows a PollOnDemand object used in a BACnet integration.

732

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 7

Container Objects PollOnDemand

Figure 7-12

PollOnDemand containers for BACnet shadow objects linked to Gx objects.

BACnetDevice object operates like a PollAlways container for any directly contained shadow objects. You can create other PollOnDemand and/or PollAlways containers under the BACnetDevice and move (or cut and paste) shadow objects to them.

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 objects 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 for the 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.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: September 30, 2006 (Notes this page only)

733

Chapter 7 ServiceContainer

Container Objects

ServiceContainer
Quick reference for all properties: Table A-71 Inputs
(none)

Default Object Shape

Outputs
(none)

abbrev: services A station has a single ServiceContainer object, which is automatically created by the New Station wizard. The ServiceContainer resides in the station root. The ServiceContainer holds all standard and optional Niagara services used by the station. The object itself has few configuration properties, and no inputs or outputs. It is unique in that it also has no Workspace view. The default view for the ServiceContainer is the ServiceManager view, available only for JDE users with Admin privileges. The ServiceManager provides a table listing all station services, with quick access to available commands for each service.
Parent Dependencies: Station root.

Example Inputs / Outputs

Inputs
(none

Outputs
(none)

Input / Output Property Reference for ServiceContainer Object

(only input and output types, see Table 7-9 for all properties)

Type
input output

Label

Property Name

Data Species

Only one ServiceContainer per station.

Child Dependencies: Only service objects. Resource Count Range: 600 and upwards, depending on number of optional services.

Commands
The ServiceContainer offers a single (but significant) right-click command from its JDE Workspace: Restart Station. Command, Admin privileges are required.

Properties
Table 7-9 ServiceContainer object properties.

Tab Property Name

Visual Config Status objectType, statusFlags, description

Description
See Table 7-1 on page 7-6 for information on these common container properties.

Valid Values
ServiceContainer {ok} Any desired text string

Default

Notes

Station Services

position

Read-Write: See position, page 7-7.

Security

securityGroups

Read-Write: The security groups to which the container is assigned. See Security Groups and Containers, page 7-5.

General, 7 others

General

Admin command rights are needed for the Restart Station command.

734

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 7

Container Objects ServiceContainer

ServiceContainer Notes
Double-click on the ServiceContainer in the JDE Tree View to open its ServiceManager view (Figure 7-13). This view shows all currently installed Niagara services in the station, and has two main areas: Serviceslists each service by the objects name, type, and description. Click on the row of any service to select it. Commandsprovides a list of commands available for the selected service. To issue a command, click it and then the Invoke button at the bottom.

Figure 7-13 ServiceManager is the default view for the stations single ServiceContainer.

Services

Commands

ServiceContainer

Invoke Command

Go menu commands are also available for any selected service, by using the right-click popup menu.
Figure 7-14 ServiceManager provides right-click access to properties and views of different services.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

735

Chapter 7 ServiceContainer

Container Objects

Linking to Child Services

The ServiceContainer can contain only Niagara service objects, a few of which have triggerType inputs and outputs. These include the LogService, AuditLogService, and ErrorLogService. Although their parent ServiceContainer has no Workspace, you can still link to these particular objects using the Tree View and the right-click Link From or Link To menu commands.
Figure 7-15 Link to service objects using Tree View commands.

736

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

CHAPTER

Gx Objects
This chapter describes each of the standard Niagara Gx objects, that is, those provided in the gx folder of the tridium JAR file. General information on Gx objects is provided first, as follows: About Gx Objects Execution of Gx Objects Gx Object Categories Common Gx Object Things Common Gx Object Properties General Gx Object Notes

Individual Gx object descriptions follow, arranged alphabetically as follows:

GxBarGraph GxBoolean GxDamper GxFan GxFloat GxImage GxInteger GxPipe GxSpectrum GxText GxTimePlot

Refer to

For more information on building GxPage graphics, including other examples of using Gx objects, refer to the Niagara Web Solutions Guide.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

81

Chapter 8 About Gx Objects

Gx Objects

About Gx Objects
Gx 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 objectsjust 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 two categories are by shape appearance, and are: Pre-Designed Shapes Graphic File / Color-Based Shapes

Pre-Designed Shapes

Gx objects in this category have a known form, meaning that they do not reference a graphics (.gif) file. However, you can change the objects shape, including color, size, aspect ratio, and sometimes direction. Gx objects that fit this category are:

GxBarGraph GxDamper GxFan GxPipe GxSpectrum GxText GxTimePlot

82

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects Common Gx Object Things

Note that when linked, most of these objects change appearance in real-time. For example, the GxFan provides animation of a running fan, the GxDamper changes blade positions, and so on. The GxText object, by far, is the most commonly used.

Graphic File / Color-Based Shapes

Gx objects in this category have one or more properties that reference an image, that is, a graphics (.gif) file. Graphics include those standard images in the Local Library (tridiumx/images JAR), as well as custom-made graphics. Alternately, most of these objects can be set to display simply as a color-filled rectangle or ellipse, and not reference a .gif file. However, .gif usage is more typical. Gx objects that fit this category are: GxBoolean GxFloat GxImage GxInteger

In general, use of the objects above provides a method for highly customized GxPages.

Common Gx Object Things

Like other objects, Gx objects have common properties and characteristics. Rather than cover these things in detail for each object, they are explained in this section. The following main topics apply to most, if not all, Gx objects: Common Gx Object Properties General Gx Object Notes

Notes

In this chapter (vs. other object chapters), the description for each Gx object has no Trigger Properties section. Gx objects have no trigger properties. Likewise, the Commands section is absent for each Gx object description. Gx objects have no direct runtime commands. However, if a Gx object is linked, and the linked object is commandable (has right-click commands), those commands may be available through the Gx object. This is determined by the users security privileges and the securityGroups setting for the Gx object. See Providing Command Access, page 8-6.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

83

Chapter 8 Common Gx Object Things

Gx Objects

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 properties for Gx objects.

Tab Property Name

objectType

Description

Valid Values

Default

Notes

Read Only: The Gx object type. By default, See description reflects It is recommended that a newly added Gx object uses this string in object type you rename any Gx its name (until renamed). object that is to be linked, and not use default The full string for the object type is shown, names (GxText_2, etc.). for example, GxBoolean or GxFan. Read Only: Current state of the objects status flags. A normal state (no flags set) is where the status flags value is {ok}, and the object appears normally. The only status flag that can be set is: either: {ok} (no flags) or {down} {ok} Unlike other some objects, Gx objects do not directly have alarm states. However, some Gx objects are capable of indicating the offnormal condition of a linked (source) object.

statusFlags

Status

downThe station is down or offline.

In the JDE, the text Down appears wherever real-time values would be. No BUI access to a down station is possible. isVisible Read Only: Reflects the boolean state currently at the object input isVisible. If this input not linked, the default state is true. Linking to the isVisible input offers a method to toggle the visibility of the object. If this input is linked, the object is visible only while a true (active) is present. Likewise, the object becomes invisible while a false (inactive) is present. font name size style Read-Write: Specifies the font used for text elements within selected Gx objects. Has three separate elements, as follows: Any combination Helvetica, 10, Plain false, true : {status flags} true: {ok}

The input isVisible uses a BooleanStatusType data species. See Input isVisible on page 8-7.

The font property applies only to these Gx object types:

nameSelections list with font types:

Courier TimesRoman Helvetica MonoSpaces SansSerif Dialog DialogInput ZapfDingbats sizeSelection list with (from smallest to largest): 8, 10, 12, 14, 16, 18, 20, 24, 32 styleSelection list with: Plain Italic Bold Italic-Bold

GxBarGraph (labels) GxSpectrum (input

value)

GxText (text)

Config

84

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects Common Gx Object Things

Table 8-1

Common properties for Gx objects. (continued)

Tab Property Name

position

Description
Read-Write: The x-y coordinates for the objects position on the JDE Workspace. Coordinate values are in pixels, and are relative to the upper-left corner of the Workspace and the upper-left corner of the object shape. An object with a position of 0,0 is in the top left corner of the Workspace.

Valid Values
Some positive x, y value less than the parent (container) objects size property value.

Default
Near the mouse pointer when the object is first created.

Notes
Typically, you dont manually enter position values, but use the mouse to drag the object as needed on the JDE Workspace. You can also use the nudge key shortcuts (ALT-<arrow>) to make 1-pixel position changes. See Keyboard Shortcuts, page 8-9. For Gx objects that reference image file(s), the right-click option Gx > Size to Image, is the best method. Be aware that if you overlap Gx objects, you should assign them to different layers. Otherwise, things may look OK based on order of creation (last on top), but after a station export (upgrade) and reinstall, Gx objects will not overlap as intended.

size

Read-Write: Defines (in pixels) the overall size of the object: x (width) and y (height). When working in the WorkspaceEditor, you typically use the mouse to drag shape handles, as needed, to resize Gx objects. Also see Keyboard Shortcuts, page 8-9.

x:, y: as needed for appropriate display

varies by Gx object

layer

Read-Write: The layer of the parent container to which the object is assigned. Although layers apply to most container objects, it is the GxPage where most layer usage is typically used. See the Layer Control section on page 7-26 for more information.

Visual

top, layer_1, layer_2, layer_3, layer_4, layer_5, layer_6, background

layer_3

hyperlinkOnClick

Read-Write: Specifies if the cursor changes to a pointing hand when a user mouses over, providing a hyperlink on mouse click. Choices are one of the following:

disabled, binding, url

disabled

disabledno hyperlink (or pointing

hand).

The hyperlinkOnClick and hyperlinkUrl properties apply to all Gx object types except GxPipe and GxTimePlot. If selection is url, a valid URL is required in the hyperlinkUrl property.

bindingprovides a hyperlink to the

source objects default view (typically its properties). If linked to a Schedule, Calendar, or log-type object, this selection is often used. The default view for these objects types are not properties, but special purpose views like ScheduleEditor, CalendarEditor, and ChartLog.

urlprovides a hyperlink to the URL

specified in the hyperlinkUrl property. hyperlinkUrl Read-Write: URL of the target to display upon a mouse click, providing that hyperlinkOnClick is set to url. Typically, this is a station URL (swid), but can be any URL accessible by a user. For example, http://www.tridium.com. valid URL The hyperlinkOnClick property must be set to url to use this entry. Applies to all Gx object types except GxPipe and GxTimePlot.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

85

Chapter 8 Common Gx Object Things

Gx Objects

Table 8-1

Common properties for Gx objects. (continued)

Tab Property Name

Visual, cont.

Description

Valid Values
False, True

Default
True

Notes
If False, this does not prevent any available right-click commands. It just doesnt advertise that any are available.

highlightCommand Read-Write: Specifies if the objects outline able becomes highlighted in a mouse over to indicate right-click commands are available. Works only if the linked object is commandable. If set to True, when a user mouses over the Gx object, a thin red outline appears around the objects border. securityGroups

Read-Write: Shows the security groups to Any mix of these types: which the Gx object is assigned. A user must have the appropriate privileges in at General least one security group to view and modify HVAC properties. Security Note: securityGroup properties are Life Safety important for any Gx object linked to another Group 4 commandable object. It is the Gx object Group 5 securityGroup settings that are checked Group 6 against the users privileges, and determine Group 7 what (if any) right-click command menu is made available. This is the only check on commands through a Gx object. See Providing Command Access.

General

If the user has rights to the parent GxPage, all Gx objects will be accessible. If a Gx object is linked to a commandable object, the securityGroups settings of the commandable object are not checked (at least for any commands through the Gx object).

General Gx Object Notes

The following general topics apply to all Gx object types: Providing Command Access Input isVisible Gx Object Shortcuts

Providing Command Access

Note

Security

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).

The importance and use of Gx objects securityGroup properties was incorrectly described in older (r2.1 and r2.2) versions of this document.

86

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects Common Gx Object Things

Figure 8-1

Command access depends on Gx object securityGroup settings.

This Gx object has its securityGroups property set to HVAC only. This user has command access because the security mask provides Std and Emer Command access to the HVAC group.

Right-click command menu of the linked object. Note: The securityGroup settings for the commandable object make no difference (at least for command access through any Gx object).

If this Gx objects securityGroups property was left at default (General only), this user would not have command access through this object, as Command rights for the General group are cleared.

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 objects isVisible input is not linked, it is always evaluated as True. By default, this means a Gx object is always visible. If a Gx objects 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 objects property highlightCommandable is True, a user still sees the objects 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.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

87

Chapter 8 Common Gx Object Things

Gx Objects

Gx Object Shortcuts

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 objects property sheet. Available commands (Gx > <command>) for any selected Gx object are: LayerApplies to all Gx objects. It allows you to quickly to review (and if needed), change the layer in which the object resides. Set StringOnly for GxText (text) and GxTimePlot (displayNameA to D). Set ColorApplies 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 ImageApplies 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 the Gx > 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.

88

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects Common Gx Object Things

Procedure 8-1

Changing current selected color.

Step 1 Step 2 Step 3

In the WorkspaceEditor of the GxPage, click on the background (no object selected). Move your mouse pointer over the desired color. Press C on the keyboard. The current selected color is set to match the current active color. You can now use the Gx > Set Color command to change any color-based property to match this color.

Keyboard Shortcuts
Positioning or resizing Gx objects occasionally requires precision that is hard to achieve by just dragging with the mouse. Table 8-2 lists keyboard shortcuts that are available for any selected Gx object.
Table 8-2 Keyboard combinations for moving and resizing Gx objects.

Name
Nudge Keys

Keyboard Combinations
ALT ALT ALT ALT
+ + + + +

Action performed on the Gx Object

(each is 1-pixel per arrow key press) Nudges object towards the right, size is unchanged. Nudges object towards the left, size is unchanged. Nudges object towards the top, size is unchanged. Nudges object towards the bottom, size is unchanged. Decreases horizontal size, keeps left edge anchored. Decreases horizontal size, keeps right edge anchored. Decreases vertical size, keeps bottom edge anchored. Decreases vertical size, keeps top edge anchored. Increases horizontal size, keeps left edge anchored. Increases horizontal size, keeps right edge anchored. Increases vertical size, keeps bottom edge anchored. Increase vertical size, keeps top edge anchored.

Shrink Keys

CTRL

CTRL + CTRL + CTRL + Grow Keys SHIFT + SHIFT + SHIFT + SHIFT +

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

89

Chapter 8 GxBarGraph

Gx Objects

GxBarGraph
Quick reference for all properties: Table A-28 Inputs
isVisible binding

Default Object Shape

Outputs
(none)

abbrev: (none); GxBarGraph The GxBarGraph is a rectangular (bar) shaped object for linking to a single analog value. It displays as a proportionally expanding bar, moving in real-time to show magnitude changes. In the WorkspaceEditor, the object can be resized and rescaled by dragging, and its orientation can be set as either horizontal or vertical. Object configuration properties include an upper and lower value range, whether these values should display as labels, and the different colors for the value (bar), bar background, and label text. Visual properties allow color changes upon offnormal conditions, also for the display of the source objects engineering units. Additional properties specify hyperlink related actions.
Parent Dependencies: None (any

Display Examples

container).
Resource Count Range: 45 to 82
input output

Input / Output Property Reference for GxBarGraph Object

(only input and output types, see Table 8-3 for all properties)

Type

Label

Property Name
isVisible binding

Data Species
BooleanStatusType FloatFlexBindingType

Properties
Table 8-3 GxBarGraph object properties.

Tab Property Name

objectType, statusFlags, isVisible foregroundColor backgroundColor Config Status

Description
See Table 8-1 on page 8-4 for information on these properties common to all Gx objects. Read-Write: Color of the value (bar) that expands and contracts in real-time. Read-Write: Color of the background behind the value (bar). Read-Write: Color of the text labels, including lower and upper range (outside of bar area) and current real-time value (inside bar area). Read-Write: See Table 8-1 on page 8-4 for more information on font settings.

Valid Values

Default

Notes

Any color, set in (green) the Color Editor r0, g255, b0 Any color, set in the Color Editor Any color, set in the Color Editor Any combination (gray) r127, g127, b127 (black) r0, g0, b0 Helvetica, 12, Plain Also, the color of the outline around the bar area.

labelsColor

font name, size, style

810

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects GxBarGraph

Table 8-3

GxBarGraph object properties. (continued)

Tab Property Name

orientation

Description
Read-Write: Specifies how the bar moves within the objects shape. If auto (default), the bar moves in the direction of the longest side.

Valid Values
auto, horizontal, vertical

Default
auto

Notes

horizontal causes the value bar to always

move sideways (left-to-right).

vertical causes the value bar to always

move up and down. Config, cont. minValue Read-Write: Minimum value range for the bar area. This value shows (in text) at the lower end of the bar area, if showLabels = True. Values received that are less than minValue display as minValue (no bar). maxValue Read-Write: Maximum value range for the bar area. This value shows (in text) at the upper end of the bar area, if showLabels = True. Values received that are greater than maxValue display as maxValue (full bar). showLabels Read-Write: Specifies whether the minValue and maxValue values display near the ends of the bar area, and if the current real-time value displays inside the bar area. Read-Write: See position, page 8-5. Read-Write: See size, page 8-5. If showLabels = True, this includes the min/max label area outside of the bar area. layer hyperlinkOnClick hyperlinkUrl Read-Write: See layer, page 8-5. Read-Write: See hyperlinkOnClick, page 8-5. Read-Write: See hyperlinkUrl, page 8-5. False, True layer_3 disabled True Must be linked to a statusOutput for color changes. False, True True <valid float> 100.0 <valid float> 0.0 maxValue must be greater than minValue. Otherwise, the display is always minValue (no bar).

position size

x:100 y:120

statusColorEnabled Read-Write: Specifies if bar and background colors change during offnormal status of the source (linked) object. Visual

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.
flashingEnabled Read-Write: Specifies if a statusOutput flashing of the source object (unacknowledged alarm) should be reflected by periodically flashing the entire GxBarGraph shape. The entire shape flashes between visible (red) and invisible at a 1 Hz frequency, during an alarm (until alarm acknowledgment). displayUnits Read-Write: Specifies if (and how) engineering units of the source object display in the inner bar label (current real-time value). Read-Write: See highlightCommandable, page 8-6. none, abbreviated, full False, True abbreviated Refer also to About Units, page 5-6. False, True False If used, the object must be set for statusColorEnabled

highlight Commandable

True

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

811

Chapter 8 GxBarGraph

Gx Objects

Table 8-3

GxBarGraph object properties. (continued)

Tab Property Name

binding Engineering boundHandle boundUrl debugOn Security securityGroups

Description
Read Only: Shows the analog value received on the binding link. Read Only: The handle of the linked to object. Read Only: Shows the complete station URL of the linked object.property. Read-Write: Allows debug on processing. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 8-6

Valid Values
<float value> valid ID valid swid False, True General, 7 others

Default
Unbound False General

Notes

GxBarGraph Notes
The GxBarGraph object has no built-in provision for a graduated scale. However, you can create an graphic file for a properly-sized scale, and use it in a GxImage file that you align next to the GxBarGraph. This technique is used in the demoR2 station, for example, as shown in Figure 8-2.
Figure 8-2 Graduated scale GxImage object aligned next to GxBarGraph object.

GxImage object that references a .gif graphic showing a graduated scale. This object is usually 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 than the graduated scale GxImage object, and then sized and aligned as needed.

812

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects GxBoolean

GxBoolean
Quick reference for all properties: Table A-29 Inputs
isVisible binding

Default Object Shape

Outputs
(none)

abbrev: (none); GxBoolean The GxBoolean object displays one of two images (or colors) for the boolean state of a linked 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 objects 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

Display Examples

Both objects shown selected here are GxBooleans. Each uses two different image (.gif) files to show different states. The fans active state is an animated .gif, showing spinning fan blades. See related Note. The active state for the heating coil GxBoolean is a .gif with brighter red color (to indicate that it is On).

This status lamp is made with overlapping Gx objectsa GxText on top, and a GxBoolean (defined with colors) on a lower layer. An active cycle is indicated by green.

Input / Output Property Reference for GxBoolean Object

(only input and output types, see Table 8-4 for all properties)

container).
Resource Count Range: 47 to 82

Type
input output

Label

Property Name
isVisible binding

Data Species
BooleanStatusType BooleanFlexBindingType

Properties
Table 8-4 GxBoolean object properties.

Tab Property Name

objectType, statusFlags, isVisible activeImage Status

Description
See Table 8-1 on page 8-4 for information on these properties common to all Gx objects. Read-Write: Swid of the image to display during an active state of the linked boolean output. An animated .gif is sometimes used. Read-Write: Swid of the image to display during an inactive state of the linked boolean output.

Valid Values

Default

Notes

valid station swid to .gif file valid station swid to .gif file

See preceding Note about limiting use of animated .gif files.

Config

inactiveImage activeColor inactiveColor

(transparent) (for each) Read-Write: Color to represent the active state of the linked boolean output. Any color, set in the Color Editor (transparent) Read-Write: Color to represent the inactive state of the linked boolean output.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

813

Chapter 8 GxBoolean

Gx Objects

Table 8-4

GxBoolean object properties. (continued)

Tab Property Name

shape

Description
Read-Write: Specifies whether the shape boundaries (inside the border area) are rectangular or elliptical. This is the area occupied by the active and inactive colors, and bound by the border color. Read-Write: Specifies what type of boolean status causes the object to change state. The default, value, is typically used to show the active or inactive status of the linked output. Other selections show the active image/color only upon (one) the following conditions: in_alarm, fault, overridden, out_of_service, unacked_alarm, down.

Valid Values
rectangle, ellipse

Default
rectangle

Notes
If set to ellipse, the objects footprint is still rectangular (does not crop any assigned image file). The value selection works with a binding to any boolean type property, including statusOutput. Other selections require statusOutput binding, exclusively.

booleanKey Config, cont.

value in_alarm fault overridden out_of_service unacked_alarm down

value

borderColor borderWidth position size layer hyperlinkOnClick hyperlinkUrl Visual flashingEnabled

Read-Write: Color of the outline around the shape (rectangle or ellipse). Read-Write: Width, in pixels, of the outline around the shape (rectangle or ellipse). Read-Write: See position, page 8-5. Read-Write: See size, page 8-5. If referencing image files, use Size to Image. Read-Write: See layer, page 8-5. Read-Write: See hyperlinkOnClick, page 8-5. Read-Write: See hyperlinkUrl, page 8-5. Read-Write: Specifies if the statusOutput flashing of the source object (unacknowledged alarm) should be reflected by periodically flashing the entire GxBoolean shape. The entire shape flashes between visible and invisible at a 1 Hz frequency, during an alarm (until alarm acknowledgment).

Any color, set in (transparent) the Color Editor 0 to 100 False, True False, True 2 (pixels) x:32 y:32 layer_3 disabled True False If True, the Gx object must be linked to a statusOutput for flashing.

statusColorEnabled Read-Write: Does not apply to this object.

highlight Commandable binding Engineering boundHandle boundUrl debugOn Security securityGroups

Read-Write: See highlightCommandable, page 8-6. Read Only: Shows the boolean value received on the binding link. Read Only: The handle of the linked to object. Read Only: Shows the complete station swid of the linked object.property. Read-Write: Allows debug on processing. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 8-6

False, True Inactive, Active valid ID valid swid False, True General, 7 others

True Unbound False General Internal use only.

GxBoolean Notes
The 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.

814

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects GxBoolean

Animated .gif Notes

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 effectthe 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 stations WebUIService serving of Gx objects. The delay is typically not perceptable to a usera 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:
gifDelay=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)
gifDelay=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:
disposeImages=false

If not in the hosts 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 Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

815

Chapter 8 GxDamper

Gx Objects

GxDamper
Quick reference for all properties: Table A-30 Inputs
isVisible binding

Default Object Shape

Outputs
(none)

abbrev: (none); GxDamper The GxDamper object provides a scalable side-view graphic of a parallel-blade type damper, 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

Display Examples

container).
Resource Count Range: 44 to 73
input output

Input / Output Property Reference for GxDamper Object

(only input and output types, see Table 8-5 for all properties)

Type

Label

Property Name
isVisible binding

Data Species
BooleanStatusType FloatFlexBindingType

Properties
Table 8-5 GxDamper object properties.

Tab Property Name

objectType, statusFlags, isVisible foregroundColor Status

Description
See Table 8-1 on page 8-4 for information on these properties common to all Gx objects. Read-Write: Color of damper blades (interior lines) that can change angle in real-time. Read-Write: Color of the background color in the rectangular damper shape. Read-Write: Specifies how the interior blades (lines) are oriented within the objects shape. If auto (default), when full open, blades are perpendicular to the longest side.

Valid Values

Default

Notes

Any color, set in the Color Editor

(green) r0, g255, b0

backgroundColor

Any color, set in (gray) the Color Editor r127, g127, b127 auto, horizontal, vertical auto Typically, auto is recommended. This provides a typical schematic for a parallel-blade damper.

Config

orientation

vertical shows blade(s) as vertical when full

open (regardless of shape aspect).

horizontal shows blade(s) as horizontal

when full open (regardless of shape aspect).

816

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects GxDamper

Table 8-5

GxDamper object properties. (continued)

Tab Property Name

closeValue

Description
Read-Write: The minimum value range, where damper vanes are shown fully closed. Values received that are less than closeValue display as closeValue (fully closed).

Valid Values
valid float

Default
0.0

Notes
If the received value is between these two values, the angle of the vanes proportionally adjusts. If you set closeValue to be greater than openValue, the min/max operation is reversed.

Config, cont.

openValue

Read-Write: The maximum value range, where damper vanes are shown fully opened. Values received that are greater than openValue display as openValue (fully open).

valid float

100.0

position size layer hyperlinkOnClick hyperlinkUrl

Read-Write: See position, page 8-5. Read-Write: See size, page 8-5. Read-Write: See layer, page 8-5. Read-Write: See hyperlinkOnClick, page 8-5. Read-Write: See hyperlinkUrl, page 8-5.

False, True

x:25 y:100 layer_3 disabled True If True, the Gx object must be linked to a statusOutput for color changes.

statusColorEnabled Read-Write: Specifies if foreground and background colors change during offnormal status of the source (linked) object. Visual

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.
flashingEnabled Read-Write: Specifies if a statusOutput flashing of the source object (unacknowledged alarm) will be reflected by periodically flashing the entire GxDamper shape. The entire shape flashes between visible (red) and invisible at a 1 Hz frequency, during an alarm (until alarm acknowledgment). highlight Commandable binding Read-Write: See highlightCommandable, page 8-6. Read Only: Shows the analog value received on the binding link. Read Only: The handle of the linked to object. Read Only: Shows the complete station URL of the linked object.property. Read-Write: Allows debug on processing. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 8-6 False, True <float value> valid ID valid swid False, True General, 7 others True Unbound False General False, True False

If used, statusColorEnabled must be set to True.

Engineering Security

boundHandle boundUrl debugOn securityGroups

GxDamper Notes
The 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.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

817

Chapter 8 GxFan

Gx Objects

GxFan
Quick reference for all properties: Table A-31 Inputs
isVisible binding

Default Object Shape

Outputs
(none)

abbrev: (none); GxFan The GxFan provides an animated fan graphic for linking to a single boolean output. Blades inside the fan rotate during an active (On) state, and stop during an inactive (Off) state. In the WorkspaceEditor, the object is scaled and resized by dragging. Configuration properties specify the fan direction (left, right, up, down), and the different colors used for the fan blades, fan body, and center area. Visual properties allow color changes upon offnormal conditions. Additional properties specify hyperlink-related actions.
Parent Dependencies: None (any

Display Examples

This GxFan has been aligned over a GxImage that provides a 3D illusion.

container).
Resource Count Range: 43 to 70
Type
input output

Input / Output Property Reference for GxFan Object

(only input and output types, see Table 8-6 for all properties)

Label

Property Name
isVisible binding

Data Species
BooleanStatusType BooleanFlexBindingType

Properties
Table 8-6 GxFan object properties.

Tab Property Name

objectType, statusFlags, isVisible foregroundColor backgroundColor Status

Description
See Table 8-1 on page 8-4 for information on these properties common to all Gx objects. Read-Write: Color of the rotating fan blades (spokes), including the center axle. Read-Write: Color of the outer fan housing (which has an assigned direction).

Valid Values

Default

Notes

Any color, set in (black), the Color Editor r:0, g:0, b:0 Any color, set in (med. gray) the Color Editor r:127, g:127, b:127

centerColor Config

(lt. gray) Read-Write: Color of the center area (between Any color, set in the fan spokes). the Color Editor r:189, g:189, b:189 Read-Write: Orientation of the outer fan shape and output direction which affects fan blade rotation. Selections include: east, west, north, south
east

direction

north (up)Blades rotate counterclockwise. south (down)Blades rotate clockwise. east (right)Blades rotate clockwise. west (left)Blades rotate counterclockwise.

818

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects GxFan

Table 8-6

GxFan object properties. (continued)

Tab Property Name

position size layer hyperlinkOnClick hyperlinkUrl

Description
Read-Write: See position, page 8-5. Read-Write: See size, page 8-5. Read-Write: See layer, page 8-5. Read-Write: See hyperlinkOnClick, page 8-5. Read-Write: See hyperlinkUrl, page 8-5.

Valid Values
False, True

Default
x:110 y:80 layer_3 disabled True

Notes

statusColorEnabled Read-Write: Specifies if the fan colors change during offnormal status of the source object. Visual

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.
flashingEnabled Read-Write: Specifies if the statusOutput flashing of the source object (unacknowledged alarm) should be reflected by periodically flashing the entire GxFan shape. The entire shape flashes between visible and invisible at a 1 Hz frequency, during an alarm (until alarm acknowledgment). highlight Commandable binding Read-Write: See highlightCommandable, page 8-6. Read Only: Shows the boolean value received on the binding link. Read Only: The handle of the linked to object. Read Only: Shows the complete station swid of the linked object.property. Read-Write: Allows debug on processing. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 8-6 False, True Inactive, Active valid ID valid swid False, True General, 7 others True Unbound False General False, True False

If True, the Gx object must be linked to a statusOutput for color changes.

If used, the object must be set for statusColorEnabled.

Engineering

boundHandle boundUrl debugOn

Internal use only.

Security

securityGroups

GxFan Notes
The 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.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

819

Chapter 8 GxFloat

Gx Objects

GxFloat
Quick reference for all properties: Table A-32 Inputs
isVisible binding

Default Object Shape

Outputs
(none)

abbrev: (none); GxFloat A GxFloat object is similar to a GxBoolean object, but is for linkage to an analog (float) value. It displays one of multiple images (or colors) depending on the received value. Each different image (or color) is assigned to a specific analog range. In this manner, display change is incremental (discrete). Like the GxBoolean, a GxFloat can be configured to displays as either a square or elliptical shape. 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. Visual properties allow for various hyperlink related actions.
Parent Dependencies: None (any

Display Example
10 to 30

The object shown selected is a GxFloat, linked to an AO object. The GxFloat has 5 separate analog ranges,each references an image (.gif) file showing a damper in some position of open.

30 to 50

70 to 100

Input / Output Property Reference for GxFloat Object

(only input and output types, see Table 8-7 for all properties)

container).
Resource Count Range: 43 to 80

Type
input output

Label

Property Name
isVisible binding

Data Species
BooleanStatusType FloatFlexBindingType

Properties
Table 8-7 GxFloat object properties.

Tab Property Name

objectType, statusFlags, isVisible ranges Low, High Color Image Status

Description
See Table 8-1 on page 8-4 for information on these properties common to all Gx objects. Read-Write: Specifies the different analog ranges (each from low to high), and the associated shape color or image for each. Ranges cannot overlap. For example ranges of 0.0 to 5.5, and 5.5 to 12.2 are OK, but ranges 0.0 to 5.5, and 5.2 to 12.2 are not. Read-Write: Specifies whether the shape boundaries (inside the border area) are rectangular or elliptical. This is the area occupied by the assigned range colors, and bound by the border color. Read-Write: Color of the outline around the shape (rectangle or ellipse). Read-Write: Width, in pixels, of the outline around the shape (rectangle or ellipse).

Valid Values

Default

Notes

If using animated .gif files, please see Any color, set in transparent, Animated .gif the Color Editor (no image) Notes, page 8-15. valid station swid to gif file rectangle, ellipse rectangle If set to ellipse, the objects footprint is still rectangular (does not crop any assigned image file).

Low, High: <valid float>

Low:NaN, High:NaN,

Config

shape

borderColor borderWidth

Any color, set in (transparent) the Color Editor 0 to 100 2 (pixels)

820

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects GxFloat

Table 8-7

GxFloat object properties. (continued)

Tab Property Name

position size Visual layer hyperlinkOnClick hyperlinkUrl highlight Commandable binding Engineering boundHandle boundUrl debugOn Security securityGroups

Description
Read-Write: See position, page 8-5. Read-Write: See size, page 8-5. If referencing image files, use Size to Image. Read-Write: See layer, page 8-5. Read-Write: See hyperlinkOnClick, page 8-5. Read-Write: See hyperlinkUrl, page 8-5. Read-Write: See highlightCommandable, page 8-6. Read Only: Shows the float value received on the binding link. Read Only: The handle of the linked to object. Read Only: Shows the complete station swid of the linked object.property. Read-Write: Allows debug on processing. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 8-6

Valid Values
False, True <valid float> valid ID valid swid False, True General, 7 others

Default
x:32 y:32 layer_3 disabled True Unbound False General

Notes

Internal use only.

GxFloat Notes
The GxFloat object allows you to visually associate images (or colors) with specific ranges of analog (float) values. In most cases, .gif files are referenced. If using with animated .gif files, see Animated .gif Notes, page 8-15.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

821

Chapter 8 GxImage

Gx Objects

GxImage
Quick reference for all properties: Table A-29

Default Object Shape

Inputs
isVisible binding

abbrev: (none); GxImage The GxImage object can display a single image, as referenced by its image property. It is commonly used as a background image in a graphic (in this case, it is typically assigned to the background layer). 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 Visual properties provide various hyperlink related actions. Using these functions, GxImage objects are sometimes used as navigational buttons, such as to object views (for example, Schedule or log objects), or other GxPages. A popular variation is to use transparent GxImage objects (no referenced image file), sized as needed to provide appropriate hotspot hyperlinks to other views. When used as a button or hotspot, a GxImage is typically linked to the target object.
Parent Dependencies: None (any

Outputs
(none)

Display Examples

This entire background is from a GxImage object. It is assigned to the GxPages background layer.

Each GxImage object shown selected is transparent (no referenced image file).

Input / Output Property Reference for GxImage Object

(only input and output types, see Table 8-8 for all properties)

Type
input output

Label

Property Name
isVisible binding

Data Species
BooleanStatusType FlexBindingType

container).
Resource Count Range: 42 to 64

Properties
Table 8-8 GxImage object properties.

Tab Property Name

objectType, statusFlags, isVisible image Config borderColor borderWidth position size Status

Description
See Table 8-1 on page 8-4 for information on these properties common to all Gx objects. Read-Write: Swid of the image to display. Read-Write: Color of the outline around the rectangular image. Read-Write: Width, in pixels, of the outline around the image Read-Write: See position, page 8-5. Read-Write: See size, page 8-5. If referencing image file, use Size to Image.

Valid Values

Default

Notes

valid station swid to gif file

Any color, set in (transparent) the Color Editor 0 to 100 2 (pixels) x:32 y:32

Visual

822

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects GxImage

Table 8-8

GxImage object properties. (continued)

Tab Property Name

Visual, cont. layer hyperlinkOnClick hyperlinkUrl highlight Commandable binding Engineering boundHandle boundUrl debugOn Security securityGroups

Description
Read-Write: See layer, page 8-5. Read-Write: See hyperlinkOnClick, page 8-5. Read-Write: See hyperlinkUrl, page 8-5. Read-Write: See highlightCommandable, page 8-6. Read Only: Shows the value received on the binding link (if any). Read Only: The handle of the linked to object. Read Only: Shows the complete station swid of the linked object.property. Read-Write: Allows debug on processing. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 8-6

Valid Values
False, True value of linked property valid ID valid swid False, True General, 7 others

Default
layer_3 disabled True Unbound False General

Notes

Internal use only.

GxImage Notes
A GxImage object, complete with referenced image property, is automatically created whenever you use the Tree View to copy a .gif file from the Local or Remote Library and paste it into your GxPage Workspace. However, you will still need to use the Gx > Size to Image option for this (or typically any other) GxImage object.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

823

Chapter 8 GxInteger

Gx Objects

GxInteger
Quick reference for all properties: Table A-34 Inputs
isVisible binding

Default Object Shape

Outputs
(none)

abbrev: (none); GxInteger A GxInteger object is very similar to a GxFloat, but is for linkage to an integer value. 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 as either a square or elliptical shape. Visual properties allow color changes upon offnormal conditions, as well as various hyperlink related actions.
Parent Dependencies: None (any

Display Example
The selected object is a GxInteger that receives a LonWorks occupancy value as an integer (from 0 to 3). A different image (.gif) is mapped to each possible integer state, as shown here.

Input / Output Property Reference for GxInteger Object

(only input and output types, see Table 8-9 for all properties)

Type
input output

Label

Property Name
isVisible binding

Data Species
BooleanStatusType IntegerFlexBindingType

container).
Resource Count Range: 43 to 80

Properties
Table 8-9 GxInteger object properties.

Tab Property Name

objectType, statusFlags, isVisible mapping Value Color Image Status

Description
See Table 8-1 on page 8-4 for information on these properties common to all Gx objects.

Valid Values

Default

Notes

Read-Write: Specifies the different possible Value: 0, If using animated .gif integer values, and the associated shape color <valid integer> transparent, files, please see or image for each. Any color, set in (no image) Animated .gif Notes, page 8-15. the Color Editor valid station swid to gif file Read-Write: Specifies whether the shape boundaries (inside the border area) are rectangular or elliptical. This is the area occupied by the assigned value colors, and bound by the border color. Read-Write: Color of the outline around the shape (rectangle or ellipse). Read-Write: Width, in pixels, of the outline around the shape (rectangle or ellipse). rectangle, ellipse rectangle If set to ellipse, the objects footprint is still rectangular (does not crop any assigned image file).

Config

shape

borderColor borderWidth

Any color, set in (transparent) the Color Editor 0 to 100 2 (pixels)

824

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects GxInteger

Table 8-9

GxInteger object properties. (continued)

Tab Property Name

position size layer hyperlinkOnClick hyperlinkUrl flashingEnabled highlight Commandable binding Engineering boundHandle boundUrl debugOn Security securityGroups

Description
Read-Write: See position, page 8-5. Read-Write: See size, page 8-5. If referencing image files, use Size to Image. Read-Write: See layer, page 8-5. Read-Write: See hyperlinkOnClick, page 8-5. Read-Write: See hyperlinkUrl, page 8-5. Read-Write: Does not apply to this object. Read-Write: See highlightCommandable, page 8-6. Read Only: Shows the float value received on the binding link. Read Only: The handle of the linked to object. Read Only: Shows the complete station swid of the linked object.property. Read-Write: Allows debug on processing. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 8-6

Valid Values
False, True False, True <valid float> valid ID valid swid False, True General, 7 others

Default
x:32 y:32 layer_3 disabled False True Unbound False General

Notes

Visual

Internal use only.

GxInteger Notes
The GxInteger object is similar to the GxFloat, but is binding-compatible with integer (vs. float) properties. Also, unlike the GxFloat (where different ranges are associated with each .gif or color), the GxInteger associates individual integers with each .gif or color. If using with animated .gif files, see Animated .gif Notes, page 8-15.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

825

Chapter 8 GxPipe

Gx Objects

GxPipe
Quick reference for all properties: Table A-36 Inputs
isVisible

Default Object Shape

Outputs
(none)

abbrev: (none); GxPipe GxPipe objects are simple graphics elements for showing piping. Each GxPipe depicts a single pipe section, using 3D-type shading. In the WorkspaceEditor, the object can be resized and rescaled by dragging, and can be oriented either horizontally or vertically. Configuration properties specify pipe color and various options for the two endpoints. Note: It may be easier to specify the width and height of a GxPipe directly in its property sheet (size property, Visual tab) rather than by dragging. GxPipe objects are unique among Gx object because they are drawing-only objects, without a binding input or hyperlink-related properties. They are typically assigned to a lower layer, for example, layer 6.
Parent Dependencies: None (any

Display Examples
Each section of pipe is one GxPipe object.

Fittings and pump shown here are GxImage objects, using images copied from Local Library.

Input / Output Property Reference for GxPipe Object

(only input and output types, see Table 8-10 for all properties)

Type
input output

Label

Property Name
isVisible

Data Species
BooleanStatusType

container).
Resource Count Range: 18 to 33

Properties
Table 8-10 GxPipe object properties.

Tab Property Name

objectType, statusFlags, isVisible orientation Status

Description
See Table 8-1 on page 8-4 for information on these properties common to all Gx objects. Read-Write: Specifies how 3D-effect shading appears on the pipe section. Selections are:

Valid Values

Default

Notes

Config

autodarker shading along longer sides. horizontaldarker shading top and bottom. verticaldarker shading left and right sides.
color Read-Write: Color of the pipe section.

auto, horizontal, vertical

auto

Typically, auto is recommended. This provides logical shading control.

Any color, set in the Color Editor

(blue) r0, g0, b255

826

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects GxPipe

Table 8-10

GxPipe object properties. (continued)

Tab Property Name

endpoint1

Description
Read-Write: Sets the graphical look of the left end (horizontal pipe) or top end (vertical pipe). The default is open. A selection list provides a variety of elbows, tees, and a cross. Affects mostly shading.

Valid Values
(for each) open l_north_east l_north_west l_south_east l_south_west t_north t_south t_east t_west cross

Default
open

Notes

Config, cont.

endpoint2

Read-Write: Sets the graphical look of the right end (horizontal pipe) or bottom end (vertical pipe). The default is open. A selection list provides a variety of elbows, tees, and a cross. Affects mostly shading.

open

position Visual size

Read-Write: See position, page 8-5. Read-Write: See size, page 8-5. GxPipe size is often best controlled by entering x and y values directly in the property sheet.

x:100 y:8

layer Security securityGroups

Read-Write: See layer, page 8-5. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 8-6

General, 7 others

layer_3 General

GxPipe Notes
The default diameter of GxPipe object is 8 pixels. This dimension works well with the various .gif image files that depict pipe-flange fittings (elbows and tees). These image files can be found in the Local Library, tridiumx folder, images JAR: tridiumx/images/piping Included are a number of fittings in colors blue, light blue, orange, and red.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

827

Chapter 8 GxSpectrum

Gx Objects

GxSpectrum
Quick reference for all properties: Table A-37 Inputs
isVisible binding midPointInput

Default Object Shape

Outputs
(none)

abbrev: (none); GxSpectrum A GxSpectrum provides a rectangular-shaped color gradient. Change in the gradient occurs in proportion to a delta magnitude between two analog values. These analog (float) values are usually sourced on separate inputs. The value of the primary input can be set to display, in text, in the center of the shape. The secondary (midpoint) input value can be sourced from another link, or simply stored as a configuration property. Additional properties define the high, low, and mid-delta colors, as well as analog values for the midpoint default and gradient range. A popular use for a GxSpectrum object is to visually show the temperature setpoint deviation for a specific area on a floor plan.
Parent Dependencies: None (any

Display Examples

Each room in this floor plan is overlaid with a GxSpectrum object. These objects are configured to show room temp deviation from setpoint. They also provide the room temperature value (in center).

container).
Resource Count Range: 48 to 81
Input / Output Property Reference for GxSpectrum Object
(only input and output types, see Table 8-11 for all properties)

Type
input

Label

Property Name
isVisible binding midPointInput

Data Species
BooleanStatusType FloatFlexBindingType FloatFlexBindingType

Properties
Table 8-11 GxSpectrum object properties.

output

Tab Property Name

objectType, statusFlags, isVisible lowDeltaColor Status

Description
See Table 8-1 on page 8-4 for information on these properties common to all Gx objects. Read-Write: Gradient low endpoint color, which occurs when the primary value is lower than the current midpoint by the valueDelta.

Valid Values

Default

Notes

Any color, set in the Color Editor

(blue), r:0, g:0, b:255

midDeltaColor Config

(gray), Read-Write: Gradient midpoint color, which Any color, set in occurs when the primary value equals the the Color Editor r:127, g:127, current midpoint (the delta between them is 0). b:127 Any color, set in Read-Write: Gradient high endpoint color, which occurs when the primary value is higher the Color Editor than the current midpoint by the valueDelta. Read Only: Shows an example gradient, low-to-high (from left-to-right), using the currently configured low, mid, and high colors. (red), r:255, g:0, b:0

highDeltaColor

sample

828

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects GxSpectrum

Table 8-11

GxSpectrum object properties. (continued)

Tab Property Name

midPointDefault

Description
Read-Write: Specifies a midpoint value used if the midPointInput is not linked, or if it is linked but has a current status of fault or down. Read-Write: Specifies the gradient value range used, from the midpoint to a gradient endpoint. The total value range, from one gradient endpoint to another, is twice this amount.

Valid Values
<valid float>

Default
50.0

Notes

valueDelta Config, cont.

<valid float>

25.0

font name, size, style

Read-Write: Applies to the displayed text for the binding value (if displayText = True). See Table 8-1 on page 8-4 for more information on font settings. Read-Write: Specifies if the primary value (binding input) displays in the center of the gradient rectangle, using the selected font. Read-Write: See position, page 8-5. Read-Write: See size, page 8-5. Read-Write: See layer, page 8-5. Read-Write: See hyperlinkOnClick, page 8-5. Read-Write: See hyperlinkUrl, page 8-5. Read-Write: Specifies if (and how) engineering units of the source object display in the inner bar label (current real-time value). Read-Write: See highlightCommandable, page 8-6. Read Only: Shows the analog (float) value received on the binding link. Read Only: The handle of the linked to object. Read Only: Shows the complete station swid of the linked object.property. Read-Write: Allows debug on processing. Read Only: Shows the analog (float) value received on the midPointInput link.

Any combination

Helvetica, 12, Plain

displayText

False, True

True

position size layer Visual hyperlinkOnClick hyperlinkUrl displayUnits

none, abbreviated, full False, True <valid float> valid ID valid swid False, True <valid float>

x:110 y:80 layer_3 disabled abbreviated Refer also to About Units, page 5-6.

highlight Commandable binding boundHandle Engineering boundUrl debugOn midPointInput

True Unbound False Internal use only. If midPointInput is not linked, the midPointDefault value is seen.

Security

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

GxSpectrum Notes
The 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 objects engineering units are available, depending on the setting of the displayUnits property of the GxSpectrum.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

829

Chapter 8 GxText

Gx Objects

GxText
Quick reference for all properties: Table A-38 Inputs
isVisible binding

Default Object Shape

Outputs
(none)

abbrev: (none); GxText The GxText object provides a single line of text, with configuration properties for font type, size, color, and background color. It is widely- used in these two basic applications: To display a real-time value or status, when linked to a control or apps object. Engineering units of the source output are automatically available. Additional static text can be added before and/or after the real-time value, if needed. To display just static text (annotation), from a single word to an entire line of text. Typically, in this scenario, the GxText object is not linked. However, hyperlink property settings allow it to be used as a button, for example.

Display Examples

This GxPage (from the demoR2 database) includes various GxText objects, shown here selected. They are used mainly for button labels and text annotation.

When displaying a real-time statusOutput type value, properties allow color changes upon offnormal conditions. Additional properties specify hyperlink-related actions. Almost all text that appears in a GxPage graphic must be done using GxText objects. For this reason, it is among the most commonly used type of Gx objects.
Resource Count Range: 49 to 86

Four GxText objects are shown selected here. Three of them are linked to control objects to display current values. One is used only as a static label.

Input / Output Property Reference for GxText Object

(only input and output types, see Table 8-12 for all properties)

Type
input output

Label

Property Name
isVisible binding

Data Species
BooleanStatusType FlexBindingType

Properties
Table 8-12 GxText object properties.

Tab Property Name

objectType, statusFlags, isVisible foregroundColor backgroundColor font name, size, style Status

Description
See Table 8-1 on page 8-4 for information on these properties common to all Gx objects. Read-Write: Color of the text itself, which appears in the selected font. Read-Write: Color of the rectangular background behind the text. Read-Write: See Table 8-1 on page 8-4 for more information on font settings.

Valid Values

Default

Notes

Any color, set in the Color Editor

(black) r0, g0, b0

Config

Any color, set in (transparent) the Color Editor Any combination of name, size, style Helvetica, 12, Plain

830

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects GxText

Table 8-12

GxText object properties. (continued)

Tab Property Name

text

Description
Read-Write: Static text to display, if any. This is optional if linking to another object for real-time value display. In this case, the value of that objects property will automatically be used as the text, providing that the displayBindingText property is True (default). If needed, additional text can be entered before and/or after the property value text, using this entry method: optional text <value> optional text where <value> is the literal string.

Valid Values
any characters from keyboard

Default

Notes

Config, cont.

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.) displayBindingText Read-Write: If the GxText object is linked to another objects property, this determines if that propertys value is used as the text. Read-Write: Specifies how the displayed text is aligned (left/right), within the GxText rectangle. Read-Write: Color of the outline around the rectangular GxText shape. Read-Write: Width, in pixels, of the outline around the rectangular GxText shape. Read-Write: See position, page 8-5. Read-Write: See size, page 8-5. Read-Write: See layer, page 8-5. Read-Write: See hyperlinkOnClick, page 8-5. Read-Write: See hyperlinkUrl, page 8-5. False, True True True (default) is typical. If False, only the text (property) value is seen.

justification borderColor borderWidth position size layer hyperlinkOnClick hyperlinkUrl

center, left, right

left

Any color, set in (transparent) the Color Editor 0 to 100 False, True 2 (pixels) x:100 y:120 layer_3 disabled True If used, the object must be linked to a statusOutput.

statusColorEnabled Read-Write: Specifies if text and background colors change during offnormal status of the source (linked) object. Visual

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.
flashingEnabled Read-Write: Specifies if a statusOutput flashing of the source object (unacknowledged alarm) should be reflected by periodically flashing the entire GxText shape. The entire shape flashes between visible (red) and invisible at a 1 Hz frequency, during an alarm (until alarm acknowledgment). displayUnits Read-Write: Specifies if (and how) engineering units of the source object display with the value. none, abbreviated, full abbreviated Refer also to About Units, page 5-6. False, True False If used, the object must be set for statusColorEnabled.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

831

Chapter 8 GxText

Gx Objects

Table 8-12

GxText object properties. (continued)

Tab Property Name

Visual, cont. highlight Commandable

Description
Read-Write: See highlightCommandable, page 8-6.

Valid Values
False, True

Default
True

Notes

binding Engineering boundHandle boundUrl debugOn Security securityGroups

Read Only: Shows the property value received on the binding link. Read Only: The handle of the linked to object. Read Only: Shows the complete station URL of the linked object.property. Read-Write: Allows debug on processing. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 8-6

<value> valid ID valid swid False, True General, 7 others

Unbound False General

GxText Notes
GxText objects are the backbone of many GxPage solutions, providing real-time updates, descriptive hyperlink buttons, and general text annotations.

Linking Flexibility The binding input of a GxText uses a FlexBindingType data species. This means
that you can link a GxText object to: Almost any output of another object (except a trigger type), or An internal property of another object. Typical examples include status properties, such as description or timeOfActiveReset. The value of the linked property automatically becomes the displayed text.

This type of link flexibility is unique to the GxText object.

832

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 8

Gx Objects GxTimePlot

GxTimePlot
Quick reference for all properties: Table A-39 Inputs
isVisible bindingA bindingB bindingC bindingD

Default Object Shape

Outputs
(none)

abbrev: (none); GxTimePlot The GxTimePlot object provides a resizeable x-y type time plot, showing a real-time line graph of up to four possible analog (float) values. Configuration properties include color settings for the different plotted values, the background, and the grid lines. Additional properties set the plot-time window (x-axis), minimum and maximum values (y-axis), and a unit descriptor for the y-axis. A legend area is available, which (if enabled) occupies an area below the time plot graph. The legend lists an assigned label for each of the plot values, beside its assigned color. A GxTimePlot starts graphing when its container is being viewed, with current real-time values appearing on its right side. Graphing continues while the connection to the graphic remains open, with a right-to-left scroll of the time plot as it progresses.

Display Example

Input / Output Property Reference for GxTimePlot Object

(only input and output types, see Table 8-13 for all properties)

Parent Dependencies: None (any

Type
input

Label

Property Name
isVisible bindingA bindingB bindingC bindingD

Data Species
BooleanStatusType FloatFlexBindingType FloatFlexBindingType FloatFlexBindingType FloatFlexBindingType

container).
Resource Count Range: 58 to 94

output

Properties
Table 8-13 GxTimePlot object properties.

Tab Property Name

objectType, statusFlags, isVisible colorA colorB Config colorC colorD colorBackground Status

Description
See Table 8-1 on page 8-4 for information on these properties common to all Gx objects. Read-Write: Color of the first plotted value (received on bindingA input).

Valid Values

Default

Notes

In the legend area (if enabled), the Any color, set in displayed legend the Color Editor (magenta) Read-Write: Color of the second plotted value (received on bindingB input). r255, g0, b255 names and colors is arranged as (green) Read-Write: Color of the third plotted value follows: (received on bindingC input). r0, g255, b0 input A input B (red) Read-Write: Color of the fourth plotted value input C input D (received on bindingD input). r255, g0, b0 Read-Write: Color of the plot areas background. Any color, set in the Color Editor (white) r255, g255, b255

(for each)

(blue) r0, g0, b255

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

833

Chapter 8 GxTimePlot

Gx Objects

Table 8-13

GxTimePlot object properties. (continued)

Tab Property Name

colorGrid

Description
Read-Write: Color of grid lines in the plot area. Read-Write: Specifies the lowest value that can be plotted (y-axis bottom, or origin). Appears at the bottom of the y-axis. Read-Write: Specifies the largest value that can be plotted (y-axis top, or upper limit). Appears at the top of the y-axis. Read-Write: Specifies, in minutes, the time window that can be shown (x-axis length). Used as the delta between the two x-axis labels (current time - visibleDuration, and current time).

Valid Values
Any color, set in the Color Editor <valid float>

Default
(gray) r191, g191, b191 0.0

Notes

minValue

maxValue

<valid float>

100.0

Values outside the min and maxValue range plot as min and maxValue.

visibleDuration Config, cont.

1 to n, (integer)

2 (minutes)

A viewed GxTimePlot continues to scroll, and x-axis time labels increment.

displayLegend displayNameA displayNameB displayNameC displayNameD units

Read-Write: Specifies whether the legend area should appear. Read-Write: Legend text for bindingA value.

False, True (for each)

True If blank but input is linked, the linked objects name shows. If blank and unlinked, shows Unbound. Best left at no units if inputs use different unit types.

Read-Write: Legend text for bindingB value. any desired text string Read-Write: Legend text for bindingC value. Read-Write: Legend text for bindingD value. Read-Write: Specifies the y-axis unit labels that display next to the minValue and maxValue. For selections, see About Units, page 5-6. Read-Write: See position, page 8-5. Read-Write: See size, page 8-5. If displayLegend = True, size includes the legend area at the bottom of the shape. any units selectable from drop-down list

no_units (none show)

position Visual size

x:100 y:120

layer Engineering boundNameA boundNameB boundNameC boundNameD securityGroups

Read-Write: See layer, page 8-5. Read Only: (for each) Shows the name of the object linked to input bindingA, B, C, or D.

(for each) valid object name, or Unbound if not linked. General, 7 others

layer_3 Unbound Unbound Unbound Unbound General

Security

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 8-6

GxTimePlot Notes
Besides use in GxPages, GxTimePlots are often used in other containers holding control objects as well, so as to directly monitor outputs. An example of the latter might include a time plot showing Loop-related values, such as its output, setpoint, process variable, and so on.

834

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

CHAPTER

Notification Objects
This chapter describes the standard Niagara Notification objects, including those provided in the tridium JAR file of the local library. About Notification Objects Classes Recipients Notification Schemes Linking Notes Common Notification Object Properties

Individual notification object descriptions follow, arranged as follows:

NotificationClass ApiRecipient MailRecipient1 PrinterRecipient RemotePrinterRecipient SnmpRecipient2 VasRecipient3

Note

A BACnetRecipient object also exists, in the tridiumx, bacnet JAR. Its use requires the BACnetService to be installed and configured in the station. For detailed information on the BACnetRecipient, see the Generating BACnet Alarms section of the Niagara BACnet Integration Reference. For details on the SnmpRecipient, see the Getting Started with the Niagara SNMP Service document. For more details on the Vykon Alarm Service (including VasRecipient), see the Vykon Alarm Service Installation and Configuration Instructions.

Refer to

1. Prior to r2.2, equivalent was the ExtMailRecipient object (tridiumx, recipients JAR). 2. Requires optional snmp feature with SnmpService (tridiumx, snmp JAR). 3. Requires vas feature (Vykon Alarm Service), applies to Web Supervisor station only.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

91

Chapter 9 About Notification Objects

Notification Objects

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, larger numbers 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 configuration change 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 Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

92

Chapter 9

Notification Objects Notification Schemes

Notification Schemes
A stations 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 appropriate notification 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 notifications received from multiple notification classes (Figure 9-1).
Figure 9-1 Notification links to a recipient object support multiple notification classes.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

93

Chapter 9 Notification Schemes

Notification Objects

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 properties for all notification objects.

Tab Property Name

objectType

Description
Read Only: The notification object type. By default, a newly added object uses this string in its name (unless renamed). The full string for the object type is shown, for example, RemotePrinterRecipient.

Valid Values
See description

Default
reflects object type

Notes

Status

statusFlags

Read Only: Current state of the objects status flags. A normal state (no flags set) is where the status flags value is {ok}. The only status flag that can be set is:

either: {ok} (no flags) or {down}

{ok}

Unlike some other object types, notification objects do not have alarm states.

downThe station is down or offline.

Visual position Read-Write: Specifies the x-y coordinates (in pixels) for the objects position in the NotificationService container (JDE Workspace). Read-Write: Shows the security groups to which the object is assigned. A user must have the appropriate privileges in at least one security group to view and modify properties and issue commands.

securityGroups

Any mix of these types:

General

General HVAC Security Life Safety Group 4 Group 5 Group 6 Group 7

More notes on securityGroup settings will go here.

Security

94

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 9

Notification Objects NotificationClass

NotificationClass
Quick reference for all properties: Table A-61 Inputs
(none shown)

Default Object Shape

Outputs
(none shown)

abbrev: Notif Class n

(where n = class number)

NotificationClass objects provide alarm and event-routing to the Niagara alarm subsystem, as well as to linked recipients (also in the NotificationService container). Station-wide, a NotificationClass associates with various alarm/event-generating objects via its notificationClass number. This is a property of the NotificationClass object itself, plus a property of all objects capable of generating an alarm or event. A station may have as many notification classes as needed (full range is from 0 to 8388607). By default, the New Station wizard creates a single NotificationClass (0). Apart from notification class number, there are two important configuration properties for each NotificationClass object: eventPrioritiesHow notifications in that class are prioritized, according to event types to-offnormal (alarm), to-fault, and (return) to-normal. Priorities range from 0 to 255; a lower number indicates a higher priority. Priorities are individually specified. ackRequiredWhich event types (as above) require an acknowledgment. These are separately flagged.

All Inputs / Outputs

Inputs
slaveIn

Outputs
notificationOutput masterOut

Input / Output Property Reference for NotificationClass Object

(only input and output types, see Table 9-2 for all properties)

Type
input output

Label
slaveIn notifica master

Property Name
slaveIn notificationOutput masterOut

Data Species
SlaveSyncType NotificationTriggerType SlaveSyncType

NotificationClass objects have slave sync inputs and outputs, used to link multiple NotificationClass objects in different stations. This provides global editing control.
Parent Dependencies

NotificationService. NotificationClass objects and recipient objects can be placed in containers under the NotificationService, not just directly in the NotificationService.

Resource Count Range: 22 to 34 Trigger Properties

The primary notificationOutput output uses data species NotificationTriggerType. It can be linked to one or more notification recipient objects.

Commands
(none)

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

95

Chapter 9 NotificationClass

Notification Objects

Properties
Table 9-2 NotificationClass object properties.

Tab Property Name

objectType, statusFlags Status description

Description
See Table 9-1 on page 9-4 for information on these common properties. Read-Write: Permits a user-defined text descriptor for describing the notification class. Any printable characters, including spaces and mixed case characters, are allowed. Read-Write: The assigned notification class number, reflected inside the objects shape. Must be a unique number among all NotificationClass objects in the station.

Valid Values
See description

Default
no description

Notes

notificationClass

0 to 8388607 0 to 255 typical

-1 Numbers can be (not skipped, e.g. 100, functional) 200, 300, ... 900, 1000 and so on are a valid collection. (all selected) Selection to-offnormal applies to any alarm state, e.g. high-limit or low-limit for an AI, AO, or Loop object, or offnormal for a BI, BO, MSI, or MSO object.

ackRequired

Read-Write: (BACnet application) Flags that specify the types of event transitions, as they occur, that require acknowledgment. Events still appear in the alarm console even for objects using a notification class where ackRequired is cleared (not set). Also, they are stored in the EVENT.UNACKEDALARMS table (SQL db) until acknowledgment, regardless of this setting. In their alarm record, however, the ackRequired field will always show false. In addition, objects that are assigned to a class where ackRequired is cleared (for one or more transitions), have associated flags permanently set in their ackedTransitions property. On the other hand, an event transaction type requiring acknowledgment causes the alarmable object to send receipt of an acknowledgment back to the supervisors NotificationService (upon receipt). This confirms acknowledgment. The alarm/event is not removed from the alarm console until this receipt of acknowledgment is received.

selection of any or all: to-offnormal to-fault to-normal

Config

eventPriorities toOffnormal toFault toNormal

Read-Write: The priority assigned to each type of event transition, namely:

(for each) 0 to 255

(for each) 255

to-offnormal to-fault to-normal

Lower numbers indicate higher priority, where 0 is the highest priority and 255 the lowest. Often, higher priorities (lower numbers) are assigned to to-offnormal or to-fault types.

In the alarm console (or alarm URL from a browser), higher priority alarms and events are listed first (above) lower priority ones, even if they are older.

Visual

position

Read-Write: See position, page 9-4.

Engineering

masterOut slaveIn

Read Only: Always shows SlaveSync. Read Only: Always shows SlaveSync.

SlaveSync SlaveSync

SlaveSync No real-time status (or indication of a master/slave link) SlaveSync is provided on the property sheet.

96

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 9

Notification Objects NotificationClass

Table 9-2

NotificationClass object properties. (continued)

Tab Property Name

Security securityGroups

Description
Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 9-4

Valid Values
General, 7 others

Default
General

Notes

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 alarms and 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 http:\\<WebSupHost>\alarm).

Standalone JACE-4/5 Operation

A standalone JACE-4/5 with WebUiService offers a reduced alarming subsystem, which requires only the NotificationService (set to archive_local_no_sql) and whatever 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 http:\\<JACE-4/5host>\alarm). 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 NotificationClass object 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.

Master/Slave Usage

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

97

Chapter 9 ApiRecipient

Notification Objects

ApiRecipient
Quick reference for all properties: Table A-6 Inputs
(none shown)

Default Object Shape

Outputs
(none)

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

All Inputs / Outputs

Inputs
notificationInput

Outputs
(none)

Input / Output Property Reference for ApiRecipient Object

(only input and output types, see Table 9-3 for all properties)

Type
input output

Label

Property Name
notificationInput

Data Species
NotificationTriggerType

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
Table 9-3 ApiRecipient object properties.

Tab Property Name

Status objectType, statusFlags validDays

Description
See Table 9-1 on page 9-4 for information on these common properties. Read-Write: Defines the days of the week in which event notifications can be sent to the node API. Can be set in any combination. Read-Write: Defines the time period in which event notifications can be sent to the node API (on valid days of week), using a start time and end time. If you check exclusive, event notifications are sent only outside of the defined period.

Valid Values

Default

Notes

Sun, Mon, Tue, Wed, Thu, Fri, Sat 12:00 AM to 12:00 AM

(all days selected) (entire range), not exclusive

Security Visual

Config

timeRange

position

Read-Write: See position, page 9-4.

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 9-4

General, 7 others

General

98

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 9

Notification Objects MailRecipient

MailRecipient
Quick reference for all properties: Table A-45 Inputs
(none shown)

Default Object Shape

Outputs
(none)

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

All Inputs / Outputs

Inputs
notificationInput

Outputs
(none)

Input / Output Property Reference for ApiRecipient Object

(only input and output types, see Table 9-4 for all properties)

Type
input output

Label

Property Name
notificationInput

Data Species
NotificationTriggerType

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
Table 9-4 MailRecipient object properties.

Tab Property Name

Status objectType, statusFlags validDays

Description
See Table 9-1 on page 9-4 for information on these common properties. Read-Write: Defines the days of the week in which routed event notifications can be sent as e-mails. Can be set in any combination. Read-Write: Defines the time period in which routed event notifications can be sent as e-mails (on valid days of week), using a start time and end time. If you check exclusive, event notifications are sent only outside of the defined period.

Valid Values

Default

Notes

Sun, Mon, Tue, Wed, Thu, Fri, Sat 12:00 AM to 12:00 AM

(all days selected) (entire range), not exclusive

timeRange

Config

address To Cc Bcc

Read-Write: (For each) specifies the e-mail address(es) to which the notification is sent. A primary (To) address is required; other addresses are optional. If multiple addresses are needed in an entry, use a semicolon (;) between addresses, e.g: hsmith@aol.com;bjones@msn.com

Valid e-mail address, including domain

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

99

Chapter 9 MailRecipient

Notification Objects

Table 9-4

MailRecipient object properties. (continued)

Tab Property Name

subject

Description
Read-Write: Specifies the subject line of the e-mail sent for any routed notification. For example: Notification from Central Plant Used in all alarms, alerts, and (if enabled) acknowledgments.

Valid Values
Any desired subject line.

Default
Niagara Alarm

Notes
Typically, a subject line under 40 characters is used.

routeAcks

Read-Write: Specifies if each acknowledgment of a routed alarm or alert also generates an e-mail notification. Read-Write: Defines the alarm record fields to be included in an e-mailed notification. Any entries checked are selected. Each selected field appears as a separate line in the e-mails body text. Selections include:

False, True

False

alarmFields

See descrip.

(All selected)

For an alarm notification, the first body line in the e-mail sent is: Alarm received from <station>. Following this, each field is an additional line. Note that line descriptors vary from property sheet selections. For example, instead of tstamp, that line in the e-mail begins with Time:

Config, cont.

eventSwidObjects station swid. nameObjects name. tstampTimestamp when alarm occurred. notificationClassObjects class number. priorityPriority of the alarm (0 to 255). eventTypeAlarm type, such as Out of range or Change of state. messageTextObjects alarmText. ackRequiredShows if acknowledgment is required. fromStateObjects previous state condition (normal, offnormal, etc.). toStateObjects state condition at the time of the notification (offnormal, normal, etc.). statusObjects current statusFlags. newValueObjects value (if analog) or state (if binary). setpointValueObjects setpoint (Loop only). errorLimitObjects high or lowLimit (analog objects only). deadbandObjects alarm deadband (analog objects only).

910

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 9

Notification Objects MailRecipient

Table 9-4

MailRecipient object properties. (continued)

Tab Property Name

ackFields

Description
Read-Write: Defines the acknowledgment (ack) record fields to be included in an e-mailed ack notification. Any checked are selected. Each selected field appears as a separate line in the e-mails body text. Selections include:

Valid Values
See descrip.

Default
(All selected)

Notes
For an acknowledgment notification, the first body line in the e-mail sent is: Alarm acknowledged. Following this, each field is an additional line. Note that line descriptors vary from property sheet selections. For example, instead of ackSource, that line in the e-mail begins with Acked by:

alertFields

Config, cont.

eventSwidObjects station swid. nameObjects name. tstampTimestamp when alarm occurred. notificationClassObjects class number. priorityPriority of the alarm (0 to 255). eventTypeAlarm type, such as Out of range or Change of state. toStateObjects state condition at the time of the notification (offnormal, normal, etc.). statusObjects current statusFlags. ackSourceUser name that acknowledged. timeOfAckAcknowledgment timestamp.

Read-Write: Defines the alert record fields to be included in an e-mailed notification. Any checked are selected. Each selected field appears as a separate line in the e-mails body text. Selections include:

See descrip.

(All selected)

For an alert notification, the first body line in the e-mail sent is: Alert received from <station>. Following this, each field is an additional line. Note that line descriptors vary from property sheet selections. For example, instead of alertType, that line in the e-mail begins with Type:

alertSwidObjects station swid. nameObjects name. tstampTimestamp when alert occurred. notificationClassObjects class number. priorityPriority of the alert (0 to 255). alertTypeAlert type, either Runtime limit or Change of state count. messageTextObjects alertText. alertLimitEither elapsed active time (runtime) limit or change of state count limit.

Security Visual

position

Read-Write: See position, page 9-4.

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 9-4

General, 7 others

General

MailRecipient Notes
Use of MailRecipient objects requires the MailService to be installed and correctly configured, that is, referencing a working SMTP host. If the SMTP host is incorrectly identified, notifications routed to MailRecipient objects are stored as e-mails in the MailServices outbox. See Outbox Notes on page 4-37.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

911

Chapter 9 MailRecipient

Notification Objects

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
Alarm received from MyStation. Time: 10:28 3-Oct-2001 EDT Swid: /MyStation/Temp/VAV_Type_1/Control/ZoneTemp Name: ZoneTemp Message: Zone Temp is out of range Status: {inAlarm} Type: Out of range Old state:normal New state:low_limit Exceeding Value:65.5 Deadband: 5.0 Exceeded Limit:66.0 Class ID: 0 Priority: 5 Ack required:false

Acknowledgment Example
Alarm acknowledged. Swid: /MyStation/Temp/VAV_Type_1/Control/ZoneTemp Name: ZoneTemp Alarm Time:10:38 3-Oct-2001 EDT Type: Out of range Acked state:low_limit Status: {ok} Class ID: 0 Priority: 5 Acked by: Administrator (admin) Ack Time: 10:39 3-Oct-2001 EDT

Alert Example
Alert received from MyStation. Time: Swid: Name: Message: Class ID: Priority: Type: Limit: 10:47 3-Oct-2001 EDT /MyStation/AHU_Type_1/Control/SFan SFan Maintenance check on AHU_1 recommended 0 255 Change of state count 100

912

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 9

Notification Objects PrinterRecipient

PrinterRecipient
Quick reference for all properties: Table A-67 Inputs
(none shown)

Default Object Shape

Outputs
(none)

abbrev: (none); PrinterRecipient The PrinterRecipient object is used to route alarms and alerts to a local printer. It applies primarily to a Web Supervisor station, but can be used in a JACE-NP station as well. It has no application in a JACE-4/5 station. The printer used must be working as the host operating systems (Windows NT or 2000) default printer, and is recommended to be a continuous feed type printer (typically, a dot-matrix). Otherwise, if a form type printer is used (most laser-type or ink-jet printers), each notification printed will consume a separate piece of paper.
Parent Dependencies: NotificationService. Resource Count Range: 22 to 34. Trigger Properties

All Inputs / Outputs

Inputs
notificationInput

Outputs
(none)

Input / Output Property Reference for PrinterRecipient Object

(only input and output types, see Table 9-5 for all properties)

Type
input output

Label

Property Name
notificationInput

Data Species
NotificationTriggerType

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
Table 9-5 PrinterRecipient object properties.

Tab Property Name

Status objectType, statusFlags validDays

Description
See Table 9-1 on page 9-4 for information on these common properties. Read-Write: Defines the days of the week in which routed notifications can be printed. Can be set in any combination. Read-Write: Defines the time period in which routed notifications can be printed (on valid days of week), using a start time and end time. If you check exclusive, notifications are printed only outside of the defined period.

Valid Values

Default

Notes

Sun, Mon, Tue, Wed, Thu, Fri, Sat 12:00 AM to 12:00 AM

(all days selected) (entire range), not exclusive False

timeRange Config

routeAcks

Read-Write: Specifies if each acknowledgment of a routed alarm or alert also generates a printed notification. Read-Write: Defines the local printer. Currently, the only valid selection is DEFAULT printer. Read-Write: See position, page 9-4.

False, True

printerName Visual position

DEFAULT

DEFAULT

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

913

Chapter 9 PrinterRecipient

Notification Objects

Table 9-5

PrinterRecipient object properties. (continued)

Tab Property Name

Alarm Setup alertNotificationClass

Description
Read-Write: The notification class number used in routing an alert when a problem occurs with this PrinterRecipient. Likely scenarios would include out of paper conditions, printer offline, or printer turned off.

Valid Values
0 to 8388607 (for BACnet compatibility)

Default
0

Notes

Security

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 9-4

General, 7 others

General

PrinterRecipient Notes
The PrinterRecipient can be used if: A local printer exists (attached directly to the host, that is, the Web Supervisor PC or JACE-NP). This printer is installed and configured as the Windows default printer.

The recommended printer type is a dot-matrix style, using continuous feed paper. 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 (out-of-paper, offline, powered off, etc.), the PrinterRecipient sends an alert to the named alertNotificationClass. For such an alert, the alertType is equipmentFailure and the messageText is Printer failure.

914

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 9

Notification Objects RemotePrinterRecipient

RemotePrinterRecipient
Quick reference for all properties: Table A-69 Inputs
(none shown)

Default Object Shape

Outputs
(none)

abbrev: (none); RemotePrinterRecipient The RemotePrinterRecipient object is used to route alarms and alerts to a networked printer. It applies primarily to a Web Supervisor station, but can be used in a JACE-NP station as well. It has no application in a JACE-4/5. The printer used must be known to the hosts operating system (Windows NT or 2000) as an available networked printer. This means the printer can be found on the local LAN using the Windows browse feature (for example, within the Add Printer function). In addition, the printer is recommended to be a continuous feed type printer (typically, a dot-matrix). Otherwise, if a form type printer is used (most laser-type or ink-jet printers), each notification printed will consume a separate piece of paper.
Parent Dependencies: NotificationService. Resource Count Range: 27 to 39 Trigger Properties

All Inputs / Outputs

Inputs
notificationInput

Outputs
(none)

Input / Output Property Reference for RemotePrinterRecipient

(only input and output types, see Table 9-6 for all properties)

Type
input output

Label

Property Name
notificationInput

Data Species
NotificationTriggerType

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
Table 9-6 RemotePrinterRecipient object properties.

Tab Property Name

Status objectType, statusFlags validDays

Description
See Table 9-1 on page 9-4 for information on these common properties. Read-Write: Defines the days of the week in which routed notifications can be printed. Can be set in any combination. Read-Write: Defines the time period in which routed notifications can be printed (on valid days of week), using a start time and end time. If you check exclusive, notifications are printed only outside of the defined period.

Valid Values

Default

Notes

Sun, Mon, Tue, Wed, Thu, Fri, Sat 12:00 AM to 12:00 AM

(all days selected) (entire range), not exclusive False

timeRange Config

routeAcks

Read-Write: Specifies if each acknowledgment of a routed alarm or alert also generates a printed notification.

False, True

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

915

Chapter 9 RemotePrinterRecipient

Notification Objects

Table 9-6

RemotePrinterRecipient object properties. (continued)

Tab Property Name

printerName Config, cont.

Description

Valid Values

Default
no selection

Notes
Recommended printers are dot-matrix types.

Read-Write: Defines the networked printer, by Any printer name known to the Windows operating system. that appears in the drop-down A list of available networked printers automatically appears in a drop-down selection selection list. list. Printers typically appear listed as:

\\<printerHost>\DIRECT
or

\\<PChost>\<PrinterName>
(if a shared printer). Alarm Setup alertNotificationClass Read-Write: The notification class number used in routing an alert when a problem occurs with this RemotePrinterRecipient. Likely scenarios would include network offline conditions, out of paper printer conditions, printer offline, or printer turned off. position Read-Write: See position, page 9-4. 0 to 8388607 0

Security Visual

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 9-4

General, 7 others

General

RemotePrinterRecipient Notes
The RemotePrinterRecipient can be used to route alarms and alerts to any networked (LAN) printer available to the hosts 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.

916

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 9

Notification Objects SnmpRecipient

SnmpRecipient
abbrev: (none); SnmpRecipient The SnmpRecipient object is used to route Niagara alarms and alerts to an SNMP (Simple Network Management Protocol) manager. It requires the SnmpService to be installed and configured in the station (tridiumx, snmp JAR). Note: The SNMP module is an optional, separately-licensed feature. Notifications are sent to the SNMP manager defined in the SnmpService. The SnmpRecipient object has few properties, specifying valid days and times of operation.
Parent Dependencies: NotificationService. Resource Count Range: 27 to 39. Trigger Properties
Inputs
(none shown)

Default Object Shape

Outputs
(none)

All Inputs / Outputs

Inputs
notificationInput

Outputs
(none)

Input / Output Property Reference for RemotePrinterRecipient

(only input and output types, see Table 9-7 for all properties)

Type
input output

Label

Property Name
notificationInput

Data Species
NotificationTriggerType

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
Table 9-7 SnmpRecipient object properties.

Tab Property Name

Status objectType, statusFlags validDays

Description
See Table 9-1 on page 9-4 for information on these common properties. Read-Write: Defines the days of the week in which routed notifications can be sent. Can be set in any combination. Read-Write: Defines the time period in which routed notifications can be sent (on valid days of week), using a start time and end time. If you check exclusive, notifications are sent only outside of the defined period.

Valid Values

Default

Notes

Sun, Mon, Tue, Wed, Thu, Fri, Sat 12:00 AM to 12:00 AM

Config

(all days selected) (entire range), not exclusive

timeRange

Security Visual

position

Read-Write: See position, page 9-4.

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 9-4

General, 7 others

General

SnmpRecipient Notes
For more details on the SnmpService, see the Getting Started with the Niagara SNMP Driver document.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

917

Chapter 9 VasRecipient

Notification Objects

VasRecipient
abbrev: (none); VasRecipient The VasRecipient object applies to a Web Supervisor station licensed for (and running) the VykonAlarmService. This recipient and service are found in the tridiumx, vas JAR. Note: Currently, VAS can only be licensed for a Web Supervisor. Notifications linked to the VasRecipient are sent to remote Vykon Alarm Client workstations (PCs running the VAS Client software). Currently, only one VasRecipient is supported under the Web Supervisors NotificationService container. The VasRecipient only has a few properties, specifying valid days and times of operation.
Inputs
(none shown)

Default Object Shape

Outputs
(none)

All Inputs / Outputs

Inputs
notificationInput

Outputs
(none)

Input / Output Property Reference for RemotePrinterRecipient

(only input and output types, see Table 9-8 for all properties)

Type
input output

Label

Property Name
notificationInput

Data Species
NotificationTriggerType

Parent Dependencies: NotificationService. (Only for a Web Supervisor station with VykonAlarmService). Resource Count Range: 27 to 39. 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
Table 9-8 VasRecipient object properties.

Tab Property Name

Status objectType, statusFlags validDays

Description
See Table 9-1 on page 9-4 for information on these common properties. Read-Write: Defines the days of the week in which routed notifications can be sent. Can be set in any combination. Read-Write: Defines the time period in which routed notifications can be sent (on valid days of week), using a start time and end time. If you check exclusive, notifications are sent only outside of the defined period.

Valid Values

Default

Notes

Sun, Mon, Tue, Wed, Thu, Fri, Sat 12:00 AM to 12:00 AM

(all days selected) (entire range), not exclusive

Config Security Visual

timeRange

position

Read-Write: See position, page 9-4.

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 9-4

General, 7 others

General

918

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 9

Notification Objects VasRecipient

VasRecipient Notes
For more details on VAS (Vykon Alarm Service), see the following related documents: Vykon Alarm Service Installation and Configuration Instructions Vykon Alarm Client Users Guide Release Notes for VAS

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

919

Chapter 9 VasRecipient

Notification Objects

920

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

CHAPTER

10

Ndio Objects
This chapter describes components of the Ndio (Niagara direct input/output) module, the station interface to the physical I/O points on certain JACE controllers and/or JACE I/O expansion boards. This module is available as the ndio JAR under the tridiumx folder. Currently, Ndio applies only to a station engineered for a JACE-41 (with or without a JACE-IO-XX expansion module), and not to any other Niagara host platform. General information on the Ndio module is provided first, as follows: About Ndio Objects Ndio Containers Ndio Primitives Common Ndio Object Things

Individual Ndio object descriptions follow, arranged alphabetically as follows: Containers: NdioContainer NdioProcessor Primitives: Ndio0to10VInput Ndio0to10VOutput2 NdioBinaryInput NdioBinaryOutput NdioHighSpeedCounterInput NdioResistiveInput NdioThermistorType3Input

Note

At the time of this document, the ndio JAR contains an primitive object of type Ndio0to20MAOutput, for future use. It is not covered in this document.

1. Some JACE-4XX models have no integral I/O, but can accept an I/O expansion module. 2. Currently applies only to the JACE-IO-XX expansion modules.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

101

Chapter 10 About Ndio Objects

Ndio Objects

About Ndio Objects

Ndio objects represent the onboard I/O points on certain JACE controllers (some of the JACE-4 series) and on JACE I/O expansion modules. Ndio objects are executed in the station by the control engine managed by the ControlEngineService, along with all control and apps objectsthere is no special Ndio service. An ndio JAR resides in tridiumx. Currently, this module has two containers and eight different primitive objects (Figure 10-1). When engineering, you copy these objects from the Local Library (or Remote Library of the JACE-4) into the station database.
Figure 10-1 The ndio JAR is in the tridiumx folder and contains all Ndio objects.

Ndio Containers
In a JACE-4 station, all Ndio objects must be hierarchically organized as follows:
NdioContainer: The parent container for all other Ndio objectsit must reside in the root of the station. Only one per station. NdioProcessor: Resides in the workspace of the NdioContainer, it is the parent of

primitive (control) Ndio objects. Depending on the configuration of the JACE, there may be one or more NdioProcessors.

JACE-401 or JACE-403 (with onboard I/O) has only one NdioProcessor, configured to be onboard_proc_A Currently, a JACE-401 or 403 cannot accept an I/O expansion module. Any other JACE-4 series with an installed expansion module will have either one or two NdioProcessors, as follows: If a JACE-IO-20 (20 point) module, only one NdioProcessor, configured as slot_1_proc_A. If a JACE-IO-32 (32 point) module, two NdioProcessors, configured as slot_1_proc_A and slot_1_proc_B, respectively. Each is a container for certain inputs and outputs. See Processor Responsibilities, page 10-4.

102

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects Ndio Primitives

Figure 10-2

Ndio object hierarchy in a JACE-4 station database.

Note

This two-tier container scheme is used to support JACE controller and expansion board models that have multiple I/O processors (each with an indexed set of I/O points). For example, the current JACE-IO-32 expansion module has two (2) I/O processors. At some future point, additional JACE controller models may also have multiple onboard I/O processors.

Ndio Primitives
Each Ndio primitive represents a physical I/O point on the JACE controller. You can copy them directly in the second-tier NdioProcessor container, or in some other child container under it. Ndio primitives show a fault status (Figure 10-3) until you assign them a valid ioIndex numberby default this ioIndex number is 0 (unconfigured).
Figure 10-3 Ndio objects show fault status until an unused ioIndex number is assigned.

The following subtopics apply to Ndio primitives: Processor Responsibilities Ndio UI objects Ndio outputs

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

103

Chapter 10 Ndio Primitives

Ndio Objects

Processor Responsibilities
Responsibilities of the I/O processors on the various JACE-4 controllers and I/O expansion modules are shown in Table 10-1, including numbers and types of Ndio objects you will need in the JACE-4 station database.
Table 10-1 I/O processor responsibilities and Ndio objects for JACE-4 controllers, I/O expansion modules.

JACE-401, 403
(4 DOs, 8 UIs)

Ndio Object Types

NdioBinaryOutput Ndio UI objects (various types)

NdioProcessor (onboard_proc_A)
No. Physical Point 4 8 Digital Outputs 14 Universal Inputs 18 ioIndex 14 18

Ndio Object Types JACE-IO-20 I/O Expansion Module

(8 DOs, 8 UIs, 4 AOs) NdioBinaryOutput Ndio0to10VOutput Ndio UI objects (various types)

NdioProcessor (slot_1_proc_A)
No. Physical Point 8 4 8 Digital Outputs 18 Analog Outputs 14 Universal Inputs 18 ioIndex 18 14 18

Ndio Object Types JACE-IO-32 I/O Expansion Module

Ndio0to10VOutput Total of 8 DOs, 16 UIs, Ndio UI objects and 8 AOs (various types) (2 I/O Processors) NdioBinaryOutput

NdioProcessor A (slot_1_proc_A)
No. Physical Point 4 4 8 Digital Outputs 14 Analog Outputs 14 Universal Inputs 18 ioIndex 14 14 18

NdioProcessor B (slot_1_proc_B)
No. 4 4 8 Physical Point Digital Outputs 58 Analog Outputs 58 ioIndex 14 14

Universal Inputs 916 18

For the single I/O processor JACE-401 and 403, you copy and paste all Ndio primitives in (or under) the only NdioProcessor container, configured as procNum onboard_proc_A. For a JACE-4 with the JACE-IO-20 (20 point) expansion module, you copy and paste all Ndio primitives in (or under) the NdioProcessor container configured as procNum slot_1_proc_A . For a JACE-4 with the JACE-IO-32 (32 point) expansion module, you copy and paste two NdioProcessor containers under the NdioContainer, and configure one as procNum slot_1_proc_A and the other as procNum slot_1_proc_B. Physical DOs 14, AOs 14, and UIs 18 are configured with Ndio primitive objects in the slot_1_proc_A NdioProcessor container. Physical DOs 58, AOs 58, and UIs 916 are configured with Ndio primitive objects in the slot_1_proc_B NdioProcessor container. Note that Ndio primitives in this second B NdioProcessor use ioIndex assignments starting at 1 (do not match hardware terminal assignments).

104

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects Ndio Primitives

Ndio UI objects
Among the seven different types of Ndio objects, all but two represents a JACE universal input (UI). Collectively, these objects are called Ndio UI objects. The five types of Ndio UI objects are:

Ndio0to10VInput NdioBinaryInput NdioHighSpeedCounterInput NdioResistiveInput NdioThermistorType3Input

When engineering a JACE station, you can select any combination of these objects for as many physical UI points that exist on the hardware. Unlike other controllers where universal inputs are physically configured using hardware jumpers or DIP switches, all configuration is done one-to-one with Ndio UI objects in the station. For example, for a JACE-403 having six (6) UIs, two possible station setups are: (6) HighSpeedCounterInput objects or (2) 0to10VInputs, (1) BinaryInput, (1) HighSpeedCounterInput, and (2) ResistiveInputs When the station is starting or running, the collection of objects configures the I/O processor according to the ioIndex numbers you assigned them. For a JACE-401 or 403 with integral (onboard) I/O, these numbers correspond directly to the UI terminal numbers on the JACE controller (Figure 10-4).

Figure 10-4 The ioIndex property (Config tab) in Ndio UI objects determines how the I/O processor is configured.
I/O End of JACE-403 Board

JACE-403 UI terminals UI1 through UI6.

This NdioThermistorType3 object has been assigned to ioIndex 5 (UI terminal 5). G UI5

Wired to a Type 3 Thermistor Temperature Sensor

For a JACE-4 with a JACE-IO-20 (20 point) expansion module, the ioIndex numbers in the Ndio UI objects also correspond directly to hardware UI terminals 18.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

105

Chapter 10 Ndio Primitives

Ndio Objects

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. 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.

Notes

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 (14) 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 14 under each of the two NdioProcessors. See Table 10-1 on page 10-4.
Figure 10-5 The index property (Config tab) in a NdioBinaryOutput determines the digital output (1 to 4) used.
I/O End of JACE-4 Board

JACE-403 has four Form-C relay outputs, 1 through 4. This NdioBinaryOutput object has been assigned to ioIndex 4 (digital output 4).

Normally open (N.O.) contacts of output 4 wired to control equipment load.

C4 N04

106

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects Ndio Primitives

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 18).

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 Override Switches

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: 0AutoHand, 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 unknownhowever, there is override indication. Each AO has a 3-position switch: 0AutoHand, 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 unknownhowever, 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 Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

107

Chapter 10 Common Ndio Object Things

Ndio Objects

Note

While the output is locally overridden, the Ndio object will continue to respond input changes as if it was still under Niagara control, output changes included. However, please understand that the output value is actually unknown the entire duration the output is physically overridden.
Figure 10-6 Overridden output on JACE-IO-32 is indicated by object color (status) change.
This NdioBO object is for a DO that is currently overridden on the JACE-IO-32. The output currently shows Inactive, but the actual state is unknown.

This 0to10VOut object is for an AO that is currently overridden on the JACE-IO-32. The output currently shows 10.00, but the actual value is unknown.

Also, please be aware that for any DO that is overridden on a JACE-IO-32, the associated NdioBinaryOutput object will continue to update historical properties such as elapsedActiveTime (runtime) and changeOfStateCount in response to priorityArray input changeshowever, again there is no connection to reality. In the case of DO-controlled equipment, if current state, elapsed active time and/or changes of state are critical though manual overrides, use of a UI input (and a NdioBinaryInput object) is recommended. The UI should be wired to status contacts on the controlled equipment. In the case of an AO, if output value monitoring is critical during manual overrides, use of a UI input (and a Ndio0to10VInput object) may be used. The UI must be wired to the AO output to be monitored.

Common Ndio Object Things

Ndio primitive objects closely resemble standard Niagara control objects in linkable properties, Config properties, commands, and behavior. Table 10-2 lists the four control objects (Chapter 5, Control Objects) that are most similar.
Table 10-2 Standard control objects most like the various Ndio objects.

Standard Niagara Control Object

AnalogInput AnalogOutput

Ndio Object Counterparts

Ndio0to10VInput, NdioHighSpeedCounterInput1, NdioResistiveInput, NdioThermistorType3Input Ndio0to10VOutput

108

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects Common Ndio Object Things

Table 10-2

Standard control objects most like the various Ndio objects. (continued)

Standard Niagara Control Object

BinaryInput BinaryOutput
1.

Ndio Object Counterparts

NdioBinaryInput NdioBinaryOutput

The HighSpeedCounterInput is the only Ndio object without alarming (Event-type) properties.

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 equivalent standard 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 absentthe onboard physical input (JACE I/O processor) supplies the raw data.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

109

Chapter 10 NdioContainer

Ndio Objects

NdioContainer
Quick reference for all properties: Table A-56 Inputs
(none)

Default Object Shape

Outputs
(none)

abbrev: (none) A NdioContainer object is the parent object for all Ndio objects in the station. Immediate child objects are one or more NdioProcessor. Only one NdioContainer object is supported. Apart from a few debug-related properties, it functions mostly as a simple container. The example Workspace here shows a JACE-403, which has a single I/O processor (supports only a single NdioProcessor).

Example Workspace for NdioContainer

Resource Count

30 to 53, plus the sum of all child object resource counts. (none).

Commands Properties
Table 10-3 lists important properties for the NdioContainer object.
Table 10-3 NdioContainer object, important properties.

Tab Property Name

Engineering debug

Description
Read/Write: Specifies if Ndio-related debug messages appear in any Standard Output window opened for the station. Read/Write: Specifies if debug messages written to Standard Output are verbose.

Valid Values
False, True

Default Notes
False

verbose

False, True

False

NdioContainer Notes
When adding a NdioContainer object, you must place it in the stations root. You can then copy and paste an NdioProcessor object into its Workspace. If desired, you can enable debug (Engineering tab) to observe Ndio messages when setting ioIndex properties in Ndio objects. To improve station performance, it is recommended that you leave debug disabled unless troubleshooting Ndio issues.

1010

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects NdioProcessor

NdioProcessor
Quick reference for all properties: Table A-59 Inputs
(none)

Default Object Shape

Outputs
(none)

abbrev: (none) The NdioProcessor object is the container for Ndio primitives (Ndio objects) for a specific I/O processor on either a JACE controller or JACE I/O expansion board. For a JACE-401 or 403, (with only one I/O processor), it is set to onboard_proc_A. Note this is equivalent to the previous first_onboard_processor in Niagara 2.3. Note: The objects config property procNum must be set to the proper enumerated value, which varies by platform. See Table 10-1 on page 10-4. Otherwise, if left at default (undefined) or a different setting, I/O communications will stop, the NdioProcessor is marked down, and all child Ndio objects will have a fault (orange) status. Child Ndio objects can be placed directly in the NdioProcessors Workspace or put in other subordinate containers. Device status (ping) is included for any NdioProcessor, which by default generates an alarm in a I/O processor fault scenario.
Resource Count

Example Workspace for NdioProcessor

53 to 84, plus the sum of all child object resource counts. (none).

Commands Properties
Table 10-4 lists important properties for the NdioProcessor object.
Table 10-4 NdioProcessor object, important properties.

Tab Property Name

objectType statusFlags General, Status

Description
Read Only: The Ndio object type. Read Only: Current Niagara state of the JACE I/O processor, as one of these:

Valid Values
NdioProcessor (appears in braces { }) ok, down

Default Notes
Always NdioProcessor see Notes The status for a new NdioProcessor object (copied from Local Library) is down until the procNum property is correctly set.

okCommunications to I/O processor OK. faultCommunications to I/O processor

cannot be established (and the device status mechanism has been disabled). downThe Device status mechanism cannot detect the I/O processor (or the station is opened offline).

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

1011

Chapter 10 NdioProcessor

Ndio Objects

Table 10-4

NdioProcessor object, important properties. (continued)

Tab Property Name

procEnable

Description
Read/Write: Enables or disables station communications to the I/O processor. Typically left at the default True (enabled). While False, disables all related I/O. The NdioProcessor is marked down and child objects have a fault status

Valid Values
False, True

Default Notes
True If DeviceStatus is enabled (default), False also generates a Device Down change_of_state alarm.

General, Config.

procNum

Read/Write: Specifies the I/O processor represented by this object. A JACE-401 or 403 has one valid selection: onboard_proc_A (previously: first_onboard_processor) Currently, other selections are: slot_1_proc_A for JACE-IO-20 or first half of I/O on a JACE-IO-32. slot_1_proc_B for second half of I/O on a JACE-IO-32.

See Descrip.

undefined After copying object from Local Library, set this to a valid value.

deviceStatusPing Delay DeviceStatus, Config deviceStatusDisplay Dots

Read/Write: Specifies the delay period, in milliseconds, between device status pings to the JACE I/O processor. Read/Write: Specifies whether a | character is posted in Standard Output window for each device status ping. Characters appear when any Ndio-related message is posted to Standard Output.

500 to n

1000

Typically left at default.

False, True

False

Typically left at default.

deviceStatus Disabled notificationClass

Read/Write: Specifies whether the device status (ping) mechanism is disabled. Default is False (device status enabled). Read/Write: The destination notification class for change_of_state alarms triggered by I/O processor communications events. Example events are Device down or Device up.

False, True

False

Typically left at default.

DeviceStatus, Alarm Setup

0 to 8388607

Note: Device status must be enabled (deviceStatusDisabled=False) for I/O processor events to be sent to this notification class.

NdioProcessor Notes
The NdioProcessor functions mainly as a container for Ndio (primitive) objects such as Ndio UI objects, NdioBinaryOutput, and Ndio0to10VOutput objects.

1012

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects Ndio0to10VInput

Ndio0to10VInput
Quick reference for all properties: Table A-52 Inputs
statusInput

Default Object Shape

Outputs
statusOutput

abbrev: 0to10VIn The Ndio0to10VInput object configures a JACE universal input (UI) to read a Vdc signal within a 010 V range and produce a scaled output. Like the NdioResistiveInput and NdioThermistorType3Input objects, this object is similar to a standard AnalogInput (AI) object, including all alarm capabilities. The output value follows the objects configurable voltage-to-value lookup table. This table can contain up to 20 different points, or 19 segments. Values are linearly interpolated between points. The default table is 2 points (linear response), spanning the full 010 V input-range of the JACEs UI. An offset property allows sensor-to-system calibration. Besides reading a 010 Vdc sensor, this object is also used for a 420 mA sensor, where an external 499 resistor (supplied with JACE hardware) is wired across the UI. This object can be exposed directly as a BACnet Analog_Input object1.
Parent Dependencies: NdioProcessor. Resource Count Range: 70 to 126 Trigger Properties

All Inputs / Outputs

Inputs
executeTrigger statusInhibit

Outputs
eventTrigger covTrigger statusOutput

Input / Output Properties for Ndio0to10VInput Object

(only input and output types, see Table 10-5 for all properties)

Type
input output

Label
exe sInh eventTr covTrig sOut

Property Name
executeTrigger statusInhibit eventTrigger covTrigger statusOutput

Data Species
TriggerType BooleanStatusType TriggerType TriggerType FloatStatusType

This object has the standard input property, executeTrigger, (typically not used) and also two trigger-type outputs: eventTriggerFires upon each event transition (to-offnormal, to-fault, to-normal) that has been specified in the property eventTriggerEnable. covTriggerFires upon each change of value at the statusOutput. As needed, these outputs can be linked to any input using TriggerType data species.

Commands
A JDE user with Command, Admin rights has this available menu bar command:

Commands > resetAckedTransitionsSets all three flags in the ackedTransitions property (to-offnormal, to-fault, to-normal). Rarely required, see the the JDE Command section on page 5-11 for more information.

1. For direct exposure as a BACnet object, the JACE-4 requires both the BACnetService and the BACxNdioService.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

1013

Chapter 10 Ndio0to10VInput

Ndio Objects

Properties
Table 10-5 Ndio0to10VInput object properties.

Tab Property Name

objectType, statusFlags, description eventState, reliability, outOfService, ackedTransitions, toOffnormal, toFault, toNormal presentValue syncFlag

Description
See Table 5-3 on page 5-8 for information on these properties common to all control and Ndio objects. See Table 5-4 on page 5-12 for information on these properties common to all event-type objects.

Valid Values

Default

Notes
default description is Ndio 0 to 10 V Input presentValue can be written to directly whenever the object is set to outOfService.

Status

Read Only: Shows whether the object successfully updated the configuration of the JACEs dedicated I/O processor.

False, True

False

False until ioIndex value is assigned to non-zero value.

executeParameters foreignAddress

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: BACnet usage only. Set to a positive integer for this object to appear as a BACnet Analog_Input object to other BACnet devices. See foreignAddress, page 5-9, for more information. Read-Write: (Future use only.) Read-Write: Selection of engineering units for display purposes. Choose from a logical grouping, then a specific unit. Read-Write: The minimum required input change (since the last output change) before outputs and presentValue update. Affects the outputs statusOutput and covTrigger (fires at change of value). Read-Write: I/O processor-to-terminal number for the UI configured by this object. See Table 10-1 on page 10-4 for more details by hardware platform. 0 to 4194302 or -1 (not exposed)

normal, input -1 If set, must be a unique number among all other AI objects in station.

membershipGroups units

niagaraR2 Select any (BACnet-type unit choices) valid float

niagaraR2 Leave at default. Other, no_units 0.0 (no minimum) For selections see About Units, page 5-6. covIncrement value is expressed in same units as scaled output value (not in voltage). Must be unique number among all Ndio UI objects for the I/O processor.

covIncrement

Config

ioIndex

0 (unconfigured) 16 (401, 403) 18 (IO-XX) Points, 2 to 20 Voltage, 0.0 to 10.0 <float> Value, <valid float>

linearization Points Voltage Value

Read-Write: The physical input signal (voltage) to output (value) response curve. A linear response can be achieved with only two (2) points, the default. Up to 20 points can 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), and Values are as defined by the sensor. offset Read-Write: Value added to the internally calculated value before it passes to the objects statusOutput. Allows for wiring or sensor-to-system compensation. valid float

Points 2 Output values are Volts Value linearly interpolated 0.0 0.0 between points. 10.0 10.0 There is no extrapolation of output values when the input signal is outside the defined Voltage range.

0.0

Can be positive or negative, as needed.

1014

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects Ndio0to10VInput

Table 10-5

Ndio0to10VInput object properties. (continued)

Tab Property Name

timeDelay, notificationClass, eventEnable, notifyType, eventTriggerEnable, alarmText inhibitTime

Description
See Table 5-5 on page 5-13 for information on these properties common to all event-type control objects.

Valid Values

Default

Notes
* See specific details on inhibitTime, the next property.

Read-Write: Duration (Hr:Min:Sec) of the alarm inhibit timer, which applies only if the objects input statusInhibit is linked. Refer to AI Alarm Inhibit, page 5-19, for more information. Read-Write: Valid processing low range for the received input value. Below this value, the object and its output have a fault status. Read-Write: Valid processing high range for the received input value. Above this value, the object and its output have a fault status. Read-Write: Value above which the object is evaluated in high-limit alarm. Above this value (if not in fault), the object and output have inAlarm status. Read-Write: Value below which the object is considered in low-limit alarm. Below this value (if not in fault), the object and output have inAlarm status. Read-Write: Differential value applied to high and low limits before return-to-normal. Deadband is subtracted from highLimit and added to lowLimit. Read-Write: Flags that enable low-limit and high-limit alarms, as needed. Read-Write: See position, page 5-9. Read-Write: Sets decimal position from 0 to 6 places, and optionally force (+) sign for positive values. Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows the current boolean state and status of the statusInhibit input. Read Only: Shows the current value and status of the statusOutput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10.

any practical value in Hr:Min:Sec

00:00:00 A minimum of 1 (no inhibit) second (00:00:01) is recommended whenever the statusInput is linked. MIN_VALUE is default, meaning no effective minimum. MAX_VALUE is default, meaning no effective maximum. 0.0 The limitEnable flag (for high-limit) must also be set. The limitEnable flag (for low-limit) must also be set. Deadband does not apply to fault conditions.

minPresentValue

valid float

Alarm Setup

maxPresentValue

valid float

highLimit

valid float

lowLimit

valid float

0.0

deadband

valid float

0.0

limitEnable

(select) low-limit, high-limit 0 to 6, (+) sign no (+) sign

(none)

position Visual decimalFormat

Effects display value no (+) sign only (no effect on precision). 2,

Engineering

minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInhibit (input sInh) statusOutput (output sOut)

false, true : {status flags} <float value> {status flags} General, 7 others

false : {ok} 00.0 {ok} General

Security

securityGroups

0to10VInput Notes
The 0to10VInput object is used for either a 010 Vdc or 420 mA sensor.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

1015

Chapter 10 Ndio0to10VOutput

Ndio Objects

Ndio0to10VOutput
Quick reference for all properties: Table A-53 abbrev: 0to10VOut Each Ndio0to10VOutput (0to10VOut) object provides the interface to one analog output (AO) on a JACE expansion I/O controller. AOs are used for proportional control of dampers, valves, and other devices. Apart from a few additional config properties (including ioIndex number), this object is otherwise very similar to a standard AnalogOutput (AO) object. It includes the same command prioritization scheme and all alarm and event capabilities. You can expose an Ndio0to10VOutput object directly as a BACnet Analog_Output object1.
Parent Dependencies: NdioProcessor. Resource Count Range: 93 to 160
output

Default Object Shape

Inputs
priorityArray statusInput

Outputs
statusOutput prioritizedOutput

All Inputs / Outputs

Inputs
executeTrigger statusInhibit priorityArray statusInput

Outputs
eventTrigger covTrigger statusOutput prioritizedOutut statusFeedbackOutput

Input / Output Property Reference for 0to10VOut Object

(only input and output types, see Table 10-6 for all properties)

Type
input

Label
exe sInh pIn sIn eventTr covTrig sOut pOut sFbOut

Property Name
executeTrigger statusInhibit priorityArray statusInput eventTrigger covTrigger statusOutput prioritizedOutput statusFeedbackOutput

Data Species
TriggerType BooleanStatusType FloatPriorityArrayType FloatStatusType TriggerType TriggerType FloatStatusType FloatPriorityType FloatStatusType

Trigger Properties

The 0to10VOut object has the standard input property, executeTrigger, (typically not used) and also two trigger-type outputs: eventTriggerFires upon each event transition (to-offnormal, to-fault, to-normal) that has been specified in the property eventTriggerEnable. covTriggerFires upon each change of value at the statusOutput. As needed, these outputs can be linked to any input using TriggerType data species.

Commands
A right-click command menu provides these commands (note that default command names are shown, these are modifiable using the objects commandTags property): SetTo set an output value at the Manual level (8). Requires Command, Std privileges. AutoTo clear an output value set at the Manual level (8). Requires Command, Std privileges. EmergencySetTo set an output value at the Emergency level (1). Requires Command, Emer privileges.

1. For direct exposure as a BACnet object, the JACE-4 requires both the BACnetService and the BACxNdioService.
Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

1016

Chapter 10

Ndio Objects Ndio0to10VOutput

EmergencyAutoTo clear an output value set at the Emergency level (1). Requires Command, Emer privileges.

For a JDE user with Command, Admin privileges, the following object command is available from the menu bar:

Commands > resetAckedTransitionsSets all three flags in the ackedTransitions property (to-offnormal, to-fault, to-normal). Rarely required, refer to the JDE Command section on page 5-11 for more information.

Properties
Table 10-6 Ndio0to10VOutput (0to10VOut) object properties.

Tab Property Name

objectType, statusFlags, description eventState, reliability, outOfService, ackedTransitions toOffnormal, toFault, toNormal, presentValue priorityArray (input: pIn) relinquishDefault executeParameters foreignAddress Status

Description
See Table 5-3 on page 5-8 for information on these properties common to all control objects. See Table 5-4 on page 5-12 for information on these properties common to all event-type control objects.

Valid Values

Default

Notes

presentValue is always read-only.

Priorities

Read Only: Shows values present on each of the 16 priority level slots for the priorityArray (pIn) input. Read-Write: Defines the output value when all 16 priority level slots have an auto.

<valid float> or auto, levels 1 to 16 valid float

auto 1 to 16 0.0 normal, output -1 Must be a unique among all BACnet-exposed AnalogOutput objects in station.

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: BACnet usage only. Set to a positive integer for this object to appear as a BACnet Analog_Output object to other BACnet devices. See foreignAddress, page 5-9, for more information. Read-Write: (Future use only.) Read-Only: Fixed at volts (Electrical). Read-Write: The minimum required change-of-value at the priorityArray input (since the last output change) before the outputs and presentValue update. Affects these outputs: 0 to 4194302 or -1 (not exposed)

membershipGroups units Config covIncrement

niagaraR2 Electrical, volts valid float

niagaraR2 Leave at default. Electrical, volts A small value, say 0.1, may be desired (no minimum) to prevent undue movement of controlled device from input fluctuations. 0.0

prioritizedOutput statusOutput covTrigger (fires at change of value)

ioIndex 0 Read-Write: I/O processor-to-terminal number for the AO configured by this object. (unconfigured) JACE-IO-32 has two I/O processors, each with 4 AOs. (Physical AOs 5, 6, 7, 8 also use ioIndex 1, 2, 3, and 4 respectively). 1, 2, 3, 4

Must be unique number among all Analog Outputs for that I/O processor. See Table 10-1.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

1017

Chapter 10 Ndio0to10VOutput

Ndio Objects

Table 10-6

Ndio0to10VOutput (0to10VOut) object properties. (continued)

Tab Property Name

offset

Description
Read-Write: Value that is internally added to the currently active value at the priorityArray input, before being compared to the linearization table (Input side). Read-Write: Input (priorityArray + offset) to physical output (volts) response curve. A linear response can be achieved with only two (2) points. The default (11 points) also provides a linear response. Up to 20 points can be specified. Volts rules are:

Valid Values
valid float

Default
0.0

Notes
Can be positive or negative, as needed.

linearization Input Volts Config, cont.

Points, 2 to 20 Input, <valid float> Volts, 0.0 to 10.0

Volts value range is from 0.0 to 10.0. Volts must increase in each new point
(must be greater than preceding point). An example linear setup for 0100% input for full range to a 210V actuator: Input 0.0 100.0 timeDelay, notificationClass, eventEnable, notifyType, inhibitTime*, eventTriggerEnable, alarmText inhibitTime Volts 2.0 10.0

Output values are Input, Volts linearly interpolated 0.0 0.0 between points. 1.0 1.0 There is no 2.0 2.0 extrapolation of 3.0 3.0 volts values when the 4.0 4.0 input signal is outside 5.0 5.0 the defined Input 6.0 6.0 range. 7.0 7.0 8.0 8.0 9.0 9.0 10.0 10.0

Points 11

See Table 5-5 on page 5-13 for information on these properties common to all event-type control objects.

* See specific details on inhibitTime, the next property.

Read-Write: Duration (Hr:Min:Sec) of the alarm inhibit timer, which applies only if the objects input statusInhibit is linked. The purpose is to prevent nuisance alarms on equipment startup and shutdown.

any practical value in Hr:Min:Sec

00:00:00 A minimum of 1 (no inhibit) second (00:00:01) is recommended whenever the statusInhibit is linked.

Alarm Setup

Note: Alarming is based solely on the value at the priorityArray input.

The inhibit timer is triggered by a transition at the statusInhibit input.

When statusInhibit becomes true, alarm

processing is delayed for the inhibit time. When statusInhibit becomes false, alarm processing remains inhibited. minPresentValue Read-Write: Valid processing low range. Below this value, the object and its statusOutput have a fault status (orange). The minimum value that can be set for the object using its right-click command menu. maxPresentValue Read-Write: Valid processing high range. Above this value, the object and its statusOutput have a fault status (orange). The maximum value that can be set for the object using its right-click command menu. Greater than min setting (above). Less than max See Notes Defaults are MIN and setting (below) MAX_VALUE. A non-default value is required for both of these properties in See Notes order to provide a slider adjustment from the JDE.

1018

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects Ndio0to10VOutput

Table 10-6

Ndio0to10VOutput (0to10VOut) object properties. (continued)

Tab Property Name

highLimit Alarm Setup, cont. lowLimit deadband limitEnable position decimalFormat

Description
Read-Write: Value above which the object is considered in high-limit alarm. Read-Write: Value below which the object is considered in low-limit alarm. Read-Write: Differential value applied to off-normal limits before return-to-normal. Read-Write: Flags that enable low-limit and high-limit alarms. Read-Write: See position, page 5-9. Read-Write: Sets decimal position from 0 to 6 places, and optionally force (+) sign for positive values. Read-Write: Defines the command labels that show on the right-click command menu for the object. Default tags are:

Valid Values
valid float valid float valid float valid float 0 to 6, (+) sign, no (+) sign Any desired text string, including spaces and numerals.

Default
0.0 0.0 0.0 0.0 2, no (+) sign See descrip.

Notes

Visual

commandTags

minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInhibit (input: sInh) statusInput (input: sIn)

Set (manualSet level) Auto (manualAuto level) Emergency Set (emergencySet level) Emergency Auto (emergencyAuto level)

If a tag is blank (no characters), the command is not available on the command menu.

Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows the current boolean state and status of the statusInhibit input. Read Only: Shows the current value and status received on the statusInput.

false, true : {status flags} <float value> {status flags}

false : {ok} 00.0 {ok} If statusInput is not linked, reflects value at priorityArray.

Engineering

Note: This input value is not used in the 0to10VOut objects alarm processing .
statusOutput (output: sOut) prioritizedOutput (output: pOut) statusFeedbackOutput (output: sFbOut) Read Only: Shows the current value and status of the statusOutput. Read Only: Shows the current value and status of the statusOutput. Read Only: Shows the current value and status at the statusFeedbackOutput. <float value> {status flags} 00.0 {ok}

<float value> @ 0.00 @ 16 <pri. level> <float value> {status flags} 00.0 {ok} Reflects statusInput value (if linked), otherwise shows the statusOutput value.

Security

securityGroups

Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10

General, 7 others

General

Ndio0to10VOutput Notes
The 0to10VOutput object configures an AO on a JACE-IO-32 or JACE-IO-20. In the case of a JACE-IO-32, each AO can be physically overridden at the I/O expansion module. For more details, see to Output Override Switches, page 10-7.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

1019

Chapter 10 NdioBinaryInput

Ndio Objects

NdioBinaryInput
Quick reference for all properties: Table A-54

Default Object Shape

Inputs
(none)

abbrev: ndioBI The NdioBinaryInput (ndioBI) object configures a JACE universal input (UI) to read 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
output

Outputs
statusOutput

All Inputs / Outputs

Inputs Outputs
eventTrigger statusCOSCount* executeTrigger statusInhibit resetCOSCountTrigger* resetElpActTimeTrigger* statusElpActTime* COSTrigger* COSAlertTrigger* ElpActAlertTrigger* statusOutput *abbreviations, see chart below *abbreviations, see chart below

Input / Output Property Reference for NdioBinaryInput Object

(only input and output types, see Table 10-7 for all properties) Type input Label exe sInh resetCt resetElp eventTr sCnt sCnt cosT cosAlrt elActAlr sOut Property Name executeTrigger statusInhibit resetChangeOfStateCountTrigger resetElapsedActiveTimeTrigger eventTrigger statusChangeOfStateCount statusElapsedActiveTime changeOfStateTrigger changeOfStateAlertTrigger elapsedActiveTimeAlertTrigger statusOutput Data Species TriggerType BooleanStatusType TriggerType TriggerType TriggerType IntegerStatusType IntegerStatusType TriggerType TriggerType TriggerType BooleanStatusType

Trigger Properties

This object has the standard input property, executeTrigger, (typically not used) and also 2 other trigger-type inputs: resetChangeOfStateCountTriggerAny received trigger pulse clears the objects current count of COS (changes of states), resetting it to zero (0). resetElapsedActiveTimeTriggerAny received trigger pulse clears the objects accumulated runtime (elapsed active time), resetting it to zero (0.0). In addition, there are 4 available trigger-type outputs, described as follows:

eventTriggerFires upon each event transition (to-offnormal, to-fault, to-normal) that has been specified in the property eventTriggerEnable. changeOfStateTriggerFires upon each change-of-state at the statusOutput. changeOfStateAlertTriggerFires 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.
Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

1020

Chapter 10

Ndio Objects NdioBinaryInput

elapsedActiveTimeAlertTriggerFires each time a runtime alert is issued (activeTimeAlertLimit value has been reached), or when a multiple of this value occurs (if periodicAlerts is set to True). As needed, these trigger-type inputs and outputs can be linked to other objects.

Commands
For a JDE user with Command, Admin privileges, the following object commands are available from the menu bar (for example, Command > resetActiveTime):

resetAckedTransitionsSets all three flags in the ackedTransitions property (to-offnormal, to-fault, to-normal). Rarely required, see the the JDE Command section on page 5-11 for more information. resetChangeOfStateCountThis sets the changeOfStateCount property value to zero (0), clearing any COS count. resetActiveTimeThis sets the elapsedActiveTime property value to 00:00:00 (Hr:Min:Sec), clearing any accumulated runtime. setChangeOfStateAlertLimitAllows editing of the changeOfStateAlertLimit property value (Alarm Setup property). setRuntimeAlertLimitAllows editing of the activeTimeAlertLimit property value (Alarm Setup property).

Properties
Table 10-7 NdioBinaryInput (NdioBI) object properties.

Tab Property Name

objectType, statusFlags, description eventState, reliability, outOfService, ackedTransitions, toOffnormal, toFault, toNormal presentValue changeOfStateTime Status changeOfStateCount

Description
See Table 5-3 on page 5-8 for information on these properties common to all control and Ndio objects. See Table 5-4 on page 5-12 for information on these properties common to all event-type objects.

Valid Values

Default

Notes
default description is Ndio Universal Binary Input presentValue can be written to directly whenever the object is set to outOfService.

Read Only: Shows a date/timestamp for the last COS (change of state). Read Only: Shows the total number of changes of state that have occurred since the last COS count reset (clear). Read Only: Shows a date/timestamp for when the COS count was last cleared. Read Only: Shows accumulated runtime (elapsed active time) formatted in Hr:Min:Sec. Read Only: Shows a date/timestamp for when the accumulated runtime (elapsed active time) was last cleared. Read-Write: Shows whether the object successfully updated the configuration of the JACEs dedicated I/O processor.

valid timestamp or null (none) integer value

null 0

timeOfStateCountReset elapsedActiveTime

valid timestamp or null (none) Time period up to 9999:99:99 (Hr:Min:Sec) valid timestamp or null (none) False, True

null 00:00:00

timeOfActiveReset

null

syncFlag

False

False until ioIndex value is assigned to non-zero value.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

1021

Chapter 10 NdioBinaryInput

Ndio Objects

Table 10-7

NdioBinaryInput (NdioBI) object properties. (continued)

Tab Property Name

executeParameters foreignAddress

Description

Valid Values

Default
normal, input -1

Notes

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: BACnet usage only. Set to a positive integer for this object to appear as a BACnet Binary_Input object to other BACnet devices. See foreignAddress, page 5-9, for more information. Read-Write: (Future use only.) 0 to 4194302 or -1 (not exposed)

Must be a unique number among all BI objects in station.

membershipGroups Config ioIndex

niagaraR2

niagaraR2 Leave at default. 0 Must be unique number among all Ndio UI objects for the I/O processor. If normal, UI input closure=Active, open=Inactive. If reverse, UI input closure=Inactive, open=Active.

Read-Write: I/O processor-to-terminal 0 (unconfigured) number for the UI configured by this object. 16 (401, 403) See Table 10-1 on page 10-4 for more 18 (IO-XX) details by hardware platform. Read-Write: Determines whether the output value directly reflects the binary input state (normal) or reverses the binary state. Typically, normally open (N.O.) equipment contacts are monitored using normal logic. normal, reverse

polarity

normal

timeDelay, notificationClass, eventEnable, notifyType, inhibitTime*, eventTriggerEnable, alarmText inhibitTime

See Table 5-5 on page 5-13 for information on these properties common to all event-type control objects.

* See specific details on inhibitTime, the next property.

Read-Write: Duration (Hr:Min:Sec) of the alarm inhibit timer, which applies only if the objects input statusInhibit is linked. The purpose is to prevent nuisance alarms on equipment startup and shutdown. The inhibitTime is triggered by a transition at the statusInhibit input.

any practical value in Hr:Min:Sec

00:00:00 A minimum value (no inhibit) of 1 second (00:00:01) is recommended whenever the statusInhibit input is linked. Alarm processing compares the statusInput value to the defined alarmValue.

Alarm Setup

When statusInhibit becomes true, alarm

processing is delayed for the inhibit time.

When statusInhibit becomes false, alarm

processing is delayed for three times the inhibit time. changeOfStateAlertLimit activeTimeAlertLimit Read-Write: Number of COS occurrences that generate a changeOfStateCount alert. Read-Write: Amount of runtime (elapsed active time), in Hr:Min:Sec, that generates a runtime alert. Read-Write: The assigned notification class number, used in routing alerts. A NotificationClass object using the same number should exist in the NotificationService objects container. periodicAlerts Read-Write: Determines if both COS count alerts and runtime alerts are periodically generated each time the respective limit is reached. False, True False Positive integer Value up to 99999:59:59 (Hr:Min:Sec) 0 to 8388607 0 00:00:00

alertNotificationClass

1022

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects NdioBinaryInput

Table 10-7

NdioBinaryInput (NdioBI) object properties. (continued)

Tab Property Name

alertText Alarm Setup, cont.

Description
Read-Write: Text descriptor included in either a COS count alert or runtime alert. If left at the default hyphen (-), the Station objects alertText is used.

Valid Values
Any text string, including spaces and mixed case characters. Active, Inactive False, True Any desired descriptors for the two states.

Default
(hyphen)

Notes
255 characters maximum.

alarmValue alarmValueEnabled position

Read-Write: Defines the digital state that is evaluated as an alarm. Read-Write: Determines if the BI object is configured for alarming. Read-Write: See position, page 5-9. Read-Write: Defines how states display at the statusInput, statusOutput, and presentValue, also how they appear on the objects property sheet. Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows the current boolean state and status of the statusInhibit input. Read Only: Shows the current COS count. Available as a IntegerStatusType output. Read Only: Shows the current runtime (elapsed active time), totaled in seconds. Available as a IntegerStatusType output. Read Only: Shows the current state and status of the statusOutput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10.

Active False Active, Inactive State descriptors can display at a linked GxText object.

Visual

activeInactiveText active, inactive minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInhibit (input sInh)

false, true : {status flags} <count> : {status flags} <seconds> : {status flags} Inactive, Active

false : {ok} 0 : {ok}

Engineering

statusChangeOfState Count (output sCnt) statusElapsedActive Time (output sElpT) statusOutput (output sOut)

0 : {ok}

Inactive : {ok} General

Security

securityGroups

General, 7 others

NdioBinaryInput Notes
The NdioBI object is used to read the binary (digital) state of dry contacts on a JACE UI (universal input). Typical use is for equipment status monitoring. Please to the following BinaryInput (BI) object topics for related information on alarming: BI Alarm Detection, page 5-37. BI Alarm Notification, page 5-37. BI Alarm Inhibit, page 5-38. BI Alarm Delay, page 5-38.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

1023

Chapter 10 NdioBinaryOutput

Ndio Objects

NdioBinaryOutput
Quick reference for all properties: Table A-55 Inputs
priorityArray statusInput

Default Object Shape

Outputs
statusOutput prioritizedOutput

abbrev: NdioBO Each NdioBinaryOutput (NdioBO) object provides the interface to an onboard digital output (DO) on a JACE-4 controller or I/O expansion board. Depending on the hardware platform, the DO may be a form-C SPDT relay or a triac output. In either case, the DO (and this object) is used for direct On/Off control of equipment. Apart from an ioIndex property for its physical output address, this object is otherwise identical to a standard BinaryOutput (BO) object. It includes the same command prioritization scheme and all alarm and event capabilities. You can expose an NdioBinaryOutput object directly as a BACnet Binary_Output object1.
Parent Dependencies: NdioProcessor. Resource Count Range: 104 to 168 Note: Upon any link change (add or delete

All Inputs / Outputs

Inputs Outputs
eventTrigger statusCOSCount* executeTrigger statusInhibit resetCOSCountTrigger* resetElpActTimeTrigger* priorityArray statusInput statusElpActTime* COSTrigger* COSAlertTrigger* ElpActAlertTrigger* presentValue statusOutput prioritizedOutput *abbreviations, see chart below statusFeedbackOutput *abbreviations, see chart below

Input / Output Property Reference for NdioBinaryOutput Object

(only input and output types, see Table 10-8 for all properties)

Type Label
input exe sInh resetCt resetElp pIn sIn eventTr sCnt sCnt cosT cosAlrt elActAlr present sOut pOut sFbOut

Property Name
executeTrigger statusInhibit resetChangeOfStateCountTrigger resetElapsedActiveTimeTrigger priorityArray statusInput eventTrigger statusChangeOfStateCount statusElapsedActiveTime changeOfStateTrigger changeOfStateAlertTrigger elapsedActiveTimeAlertTrigger presentValue statusOutput prioritizedOutput statusFeedbackOutput

Data Species
TriggerType BooleanStatusType TriggerType TriggerType BooleanPriorityArrayType FloatStatusType TriggerType IntegerStatusType IntegerStatusType TriggerType TriggerType TriggerType boolean BooleanStatusType BooleanPriorityType BooleanStatusType

any link) to a NdioBO object, commands at priority-slots (1-16) that were received from priorityArray links are momentarily cleared. The priorityArray input is now immediately rescanned; any input command found remains effective at the output. This is an improvement over previous releases, where a link change might produce an output cycle until a linked Schedule output updated.
Trigger Properties

output

This object has the standard input property, executeTrigger, (typically not used) and also 2 other trigger-type inputs: resetChangeOfStateCountTriggerAny received trigger pulse clears the objects current count of COS (changes of states), resetting it to zero (0). resetElapsedActiveTimeTriggerAny received trigger pulse clears the objects accumulated runtime (elapsed active time), resetting it to zero (0.0). In addition, there are 4 available trigger-type outputs, described as follows:

1. For direct exposure as a BACnet object, the JACE-4 requires both the bacnet module and the bacnetx ndio module.
Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

1024

Chapter 10

Ndio Objects NdioBinaryOutput

eventTriggerFires upon each event transition (to-offnormal, to-fault, to-normal) that has been specified in the property eventTriggerEnable. changeOfStateTriggerFires upon each change-of-state at the statusOutput. changeOfStateAlertTriggerFires 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). elapsedActiveTimeAlertTriggerFires each time a runtime alert is issued (activeTimeAlertLimit value has been reached, or a multiple of this value if periodicAlerts is set to True).

Commands
The NdioBO object provides a right-click command menu with these commands (default command names shownmodifiable using the commandTags property):

ActiveTo set an active output at the Manual level (8). Requires Command, Std privileges. InactiveTo set an inactive value at the Manual level (8). Requires Command, Std privileges. AutoTo clear any active or inactive output at the Manual level (8). EmergencyActiveTo set an active output at the Emergency level (1). Requires Command, Emer privileges. EmergencyInactiveTo set an inactive output at the Emergency level (1). Requires Command, Emer privileges. EmergencyAutoTo clear any active or inactive output at the Emergency level (1). Requires Command, Emer privileges.

For a JDE user with Command, Admin privileges, the following object commands are available from the menu bar (for example, Command > resetActiveTime):

resetAckedTransitionsSets all three flags in the ackedTransitions property (to-offnormal, to-fault, to-normal). Rarely required, see the the JDE Command section on page 5-11 for more information. resetChangeOfStateCountThis sets the changeOfStateCount property value to zero (0), clearing the COS count. resetActiveTimeThis sets the elapsedActiveTime property value to 00:00:00 (Hr:Min:Sec), clearing the accumulated runtime. setChangeOfStateAlertLimitAllows editing of the changeOfStateAlertLimit property value (Alarm Setup property). setRuntimeAlertLimitAllows editing of the activeTimeAlertLimit property value (Alarm Setup property).

Properties
Table 10-8 NdioBinaryOutput (NdioBO) object properties.

Tab Property Name

objectType, statusFlags, description Status

Description
See Table 5-3 on page 5-8 for information on these properties common to all control and Ndio objects.

Valid Values

Default Notes

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

1025

Chapter 10 NdioBinaryOutput

Ndio Objects

Table 10-8

NdioBinaryOutput (NdioBO) object properties. (continued)

Tab Property Name

eventState, reliability, outOfService, ackedTransitions toOffnormal, toFault, toNormal, presentValue Status, cont. changeOfStateTime changeOfStateCount

Description
See Table 5-4 on page 5-12 for information on these properties common to all event-type objects.

Valid Values
<cmd state> or auto, levels 1 to 16

Default Notes
auto 1 to 16 presentValue is always read-only.

Read Only: Shows a date/timestamp for the last COS (change of state). Read Only: Shows the total number of changes of state that have occurred since the last COS count reset (clear). Read Only: Shows a date/timestamp for when the COS count was last cleared. Read Only: Shows accumulated runtime (elapsed active time) in Hr:Min:Sec. Read Only: Shows a date/timestamp for when the accumulated runtime (elapsed active time) was last cleared. Read Only: Shows commands present on each of the 16 priority level slots for the priorityArray (pIn) input. Read-Write: Defines the output state when all 16 priority level slots have an auto. Read Only: Indicates if an interstart delay is currently active (True) or not (False).

valid timestamp or null (none) integer value

null 0

timeOfStateCountReset elapsedActiveTime timeOfActiveReset

valid timestamp or null (none) Time period up to 9999:99:99 valid timestamp or null (none) Active, Inactive, or auto, levels 1 to 16 Active, Inactive False, True

null 00:00:00 null

Be aware that a locally overridden DO (JACE-IO-32) does not stop historical properties such as elapsedActiveTime and changeOfStateCount from incrementing due to changes at the priorityArray input.

priorityArray (input: pIn) Priorities relinquishDefault inInterstartDelay executeParameters foreignAddress

auto 1 to 16 Inactive False normal, output -1 Must be a unique number among all BO objects in station. Must be unique number among all DO outputs for that I/O processor.

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. 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. Read-Write: (Future use only.) Read-Write: I/O processor-to-terminal number for DO configured by this object. See Table 10-1 on page 10-4 for more details by hardware platform. Read-Write: Determines if the same boolean state at the statusInput is reflected at the statusOutput (normal), or if the output remains opposite from the input (reverse). Read-Write: Upon a command from inactive to active, results in an active command stored at the Minimum On Off priority level (6) for this time (Hr:Min:Sec). Read-Write: Upon a command from active to inactive, results in an inactive command stored at the Minimum On Off priority level (6) for this duration (Hr:Min:Sec). 0 to 4194302 or -1 (not exposed) niagaraR2 0 (unconfigured) 14 (401, 403, IO-32) 18 (IO-20) normal, reverse

membershipGroups ioIndex

niagaraR2 Leave at default. 0

Config

polarity

normal

minimumOnTime

Any practical time needed.

00:00:00

minimumOffTime

Any practical time needed.

00:00:00

1026

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects NdioBinaryOutput

Table 10-8

NdioBinaryOutput (NdioBO) object properties. (continued)

Tab Property Name

restartDisable Config, cont.

Description
Read-Write: Determines whether the output is automatically restarted following a station restart (reboot) or power failure. If set to True, an inactive at manual level (8) is issued following such an occurrence. Read-Write: Defines the time period the output is held inactive following an active command. Used to prevent multiple simultaneous starts. Applies to commands at all priority levels except Emergency (1). See Table 5-5 on page 5-13 for information on these properties common to all event-type control objects.

Valid Values
False, True

Default Notes
False

interstartDelayTime

Any practical time needed.

00:00:00

Applied also following a station restart.

timeDelay, notificationClass, eventEnable, notifyType, inhibitTime*, eventTriggerEnable, alarmText inhibitTime

* See specific details on inhibitTime, the next property.

Read-Write: Duration (Hr:Min:Sec) of the alarm inhibit timer, which applies only if the objects input statusInhibit is linked. The purpose is to prevent nuisance alarms on equipment startup and shutdown. The inhibitTime is triggered by a transition at the statusInhibit input.

any practical value in Hr:Min:Sec

00:00:00 A minimum value of (no inhibit) 1 second (00:00:01) is recommended if the statusInhibit input is linked. Alarm processing compares the statusInput (feedback) value to the priorityArray (command) value.

When statusInhibit goes false-to-true,

alarm processing is delayed for this time. Alarm Setup

When statusInhibit goes true-to-false,

alarm processing is delayed for three times the inhibit time. changeOfStateAlertLimit activeTimeAlertLimit Read-Write: Number of COS occurrences that generate a changeOfStateCount alert. Read-Write: Amount of runtime (elapsed active time), in Hr:Min:Sec, that generates a runtime alert. Read-Write: The assigned notification class number, used in routing alerts. A NotificationClass object using the same number should exist in the NotificationService objects container. Read-Write: Determines if both COS count alerts and runtime alerts are generated each time a respective limit occurs. Read-Write: Text descriptor included in either a COS count alert or runtime alert. If left at the default hyphen (-), the parent container objects alertText is used. position Read-Write: See position, page 5-9. Read-Write: Defines the displayed states at the statusInput, statusOutput, and presentValue, and also how they appear on the objects property sheet. Positive integer Any value up to 9999:59:99 (Hr:Min:Sec) 0 to 8388607 0 0 00:00:00

alertNotificationClass

periodicAlerts

False, True

False

alertText

Any text string, including spaces and mixed case characters. Any desired descriptors for the two states.

(hyphen)

255 characters maximum.

Active, Inactive States can display at a linked GxText object.

Visual

activeInactiveText active, inactive

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

1027

Chapter 10 NdioBinaryOutput

Ndio Objects

Table 10-8

NdioBinaryOutput (NdioBO) object properties. (continued)

Tab Property Name

commandTags

Description
Read-Write: Defines the labels used to list commands that appear on the right-click command menu. Default text values for commandTags are:

Valid Values
Any desired text string, including spaces and numerals.

Default Notes
See descrip. If a tag is blank (no characters), the command is not available on the command menu.

Visual, cont.

minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInhibit (input sInh) statusChangeOfState Count (output sCnt)

Active (manualActive) Inactive (manualInactive) Auto (manualAuto) EmergencyActive (emergencyActive) EmergencyInactive (emergencyInactive) EmergencyAuto (emergencyAuto)

Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows the current boolean state and status of the statusInhibit input. Read Only: Shows the current value and status of the COS count. Available as a IntegerStatusType output. Read Only: Shows the current runtime (elapsed active time), totaled in seconds. Available as a IntegerStatusType output. Read Only: Shows the current state and status received on the statusInput. Read Only: Shows the current state and status of the statusOutput. Read Only: Shows the current state and priority level of the prioritizedOutput. Read Only: Shows the current state and status of the feedback value being supplied on the statusInput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10.

false, true : {status flags} <count> : {status flags} <seconds> : {status flags} Inactive, Active {status flags} Inactive, Active {status flags} Inactive, Active @ <pri. level> Inactive, Active {status flags} General, 7 others

false : {ok} 0 : {ok}

Engineering

statusElapsedActive Time (output sElpT) statusInput (input sIn) statusOutput (output sOut) prioritizedOutput (output pOut) statusFeedbackOutput (output sFbOut)

0 : {ok}

Inactive : {ok} Inactive : {ok} Inactive : @ def Inactive : {ok} General

Security

securityGroups

NdioBinaryOutput Notes
The Ndio object configures an DO on a JACE-4 series controller or JACE-IO-XX I/O expansion module. Please refer to the following BinaryOutput (BO) object topics for more details: BO Alarm Inhibit, page 5-50. BO Alarm Delay, page 5-50. BO Alarm Notification, page 5-50.

In the case of a JACE-IO-32, each AO can be physically overridden at the I/O expansion module. For more details, see to Output Override Switches, page 10-7.

1028

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects NdioHighSpeedCounterInput

NdioHighSpeedCounterInput
Quick reference for all properties: Table A-57 Inputs
statusInput

Default Object Shape

Outputs
totalOutput

abbrev: NdioCounterIn The NdioHighSpeedCounterInput object configures a JACE universal input (UI) to monitor dry contacts for pulses, where a total count is maintained, plus a calculated rate. Contact pulses are detected on the falling edge (closed-to-open). When indexed by this object, a JACE hardware UI input supports a pulse input frequency up to 20 Hz. Typical use is for a metering application, such as an electric demand meter or a fuel meter. Each recorded input change represents some quantity of energy or material (kilowatt-hours, fuel gallon, etc.). Config properties provide scaling for both total and rate values, as well as display units and other rate parameters. Total and rate values are available as linkable outputs. The JACEs I/O processor accumulates the total independently of the main JACE processor. In this way, the total is preserved over a soft restart (reboot) of a JACE-4. This object can be exposed directly as a BACnet Analog_Input object1.
Parent Dependencies: NdioProcessor. Resource Count Range: 54 to 84 Trigger Properties

All Inputs / Outputs

Inputs Outputs
rawOutput countOutput executeTrigger totalOutput rateOutput

Input / Output Properties for NdioHighSpeedCounter Object

(only input and output types, see Table 10-9 for all properties)

Type
input output

Label
exe raw count total rate

Property Name
executeTrigger rawOutput countOutput totalOutput rateOutput

Data Species
TriggerType String String FloatStatusType FloatStatusType

This object has the standard input property, executeTrigger, (typically not used). A user with Command, Std rights has this available right-click command:

Commands
resetCounterResets the accumulated total at the totalOutput and countOutput outputs to zero (0.0 and 0, respectively). Be aware that only Std command rights are necessary for this command, especially when assigning securityGroups properties and user privileges.

Note

1. For direct exposure as a BACnet object, the JACE-4 requires both the BACnetService and the BACxNdioService.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

1029

Chapter 10 NdioHighSpeedCounterInput

Ndio Objects

Properties
Table 10-9 NdioHighSpeedCounterInput object properties.

Tab Property Name

objectType, statusFlags, description reliability, outOfService Status presentValue

Description
See Table 5-3 on page 5-8 for information on these properties common to all control and Ndio objects. See Table 5-4 on page 5-12 for information on these two properties. Read Only: Shows the current accumulated total value (as on the totalOutput). presentValue can be written to directly whenever the object is set to outOfService.

Valid Values

Default

Notes

valid float (positive)

0.0

syncFlag

Read-Write: Shows whether the object successfully updated the configuration of the JACEs dedicated I/O processor.

False, True

False

Remains False until the ioIndex value is assigned.

executeParameters foreignAddress

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: BACnet usage only. Set to a positive integer for this object to appear as a BACnet Analog_Input object to other BACnet devices. See foreignAddress, page 5-9, for more information. Read-Write: (Future use only.) Read-Write: Selection of engineering units for display of the total value. Choose from a logical grouping, then a specific unit. For example, in a typical electric meter application, units is set to: Energy, kilowatt_hours 0 to 4194302 or -1 (not exposed)

normal, input -1

membershipGroups units

niagaraR2 Select any (BACnet-type unit choices)

niagaraR2 Leave at default. Other, no_units units can be displayed by a linked GxText object. For selections see About Units, page 5-6.

Config

ioIndex

Read-Write: I/O processor-to-terminal number for the UI configured by this object. See Table 10-1 on page 10-4 for more details by hardware platform.

0 (unconfigured) 16 (401, 403) 18 (IO-XX) valid float

Must be unique number among all Ndio UI objects for the I/O processor.

countScale

Read-Write: The scale (multiplier) for the count total, where: totalOutput = count x countScale Read-Write: Number of rate interval samples stored and used for calculating the rateOutput. The higher the number, the more normalized the rate calculation will be. Read-Write: Time period (in seconds) between samples from which each new rateOutput calculation is performed. The higher the number, the more normalized the rate calculation will be. Read-Write: The scale (multiplier) for the rate value, where: rateValue = pulses/sec x rateScale

1.0

rateHistory

1 to 100, integer

See Figure 10-7 on page 10-32 for more details. See Figure 10-7 on page 10-32 for more details.

rateInterval

1 to n, integer

10

rateScale

<valid float> (positive)

1.0

1030

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects NdioHighSpeedCounterInput

Table 10-9

NdioHighSpeedCounterInput object properties. (continued)

Tab Property Name

rateUnits Config, cont.

Description
Read-Write: Selection of engineering units for display of the rate value. Choose from a logical grouping, then a specific unit. For example, in a typical electric meter application, rateUnits is set to: Power, kilowatts

Valid Values
Select any (BACnet-type unit choices)

Default
Other, no_units

Notes
rateUnits can be displayed by a linked GxText object.

position Visual decimalFormat

Read-Write: See position, page 5-9. Read-Write: Sets decimal position from 0 to 6 places, and optionally force (+) sign for positive values. Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: The number of counted pulses reported by the JACE I/O processor. Read Only: The number of counted pulses since the last resetCount command. Equals the rawOutput + bootAdjust. A resetCount command zeroes this value. Read Only: A calculated value used to account for differences to due to station restart, hard reset, counter rollover, etc. Read Only: Shows the current float value and status of the totalOutput, which equals count x countScale. Read Only: Shows the current float value and status of the rateOutput, which equals pulses/sec. x rateScale. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10.

0 to 6, (+) sign no (+) sign

2, Effects display value no (+) sign only (no effect on precision).

minExecuteTime, maxExecuteTime, averageExecuteTime, userData rawOutput (output raw) countOutput (output count)

0 to n (positive integer) 0 to n (positive integer) 0 to n

Not cleared by the resetCount command. Stored across a station restart (JACE-4 reboot).

Engineering

bootAdjust

totalOutput (output total) rateOutput (output rate) securityGroups Security

<float value> {status flags} <float value> {status flags} General, 7 others

00.0 {ok}

The scaled count value. The scaled rate value. This objects resetCount command requires only Std command privleges.

00.0 {ok}

General

HighSpeedCounterInput Notes
The 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 which a 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.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

1031

Chapter 10 NdioHighSpeedCounterInput

Ndio Objects

Figure 10-7

Sample graph of raw rate versus normalized rate.

Raw rate Normalized rate

This graph shows the smoothing effect of a rate value when normalized. In both cases, the rateInterval = 10 (seconds). When rateHistory = 1, (default), the rate reflects an instantaneous rate at each rate interval, shown by the Raw rate. When rateHistory = 5, the rate becomes normalized, meaning the rateOutput lags, but is noticeably smoother. See Figure 10-8 for the data used in this graph.
Rate

4.000

3.500

3.000

2.500

2.000

1.500

1.000 50 100 Time (seconds) 150 200

Figure 10-8

Example of time, pulse count and rate - raw and normalized.

Actual Time sec.

This figure shows the data for the Figure 10-7 graph. The bolded rectangles represent a sliding window that marches down the rows, showing how the normalized rate is calculated. Note that for simplicity, this example uses default rateScale (1), where the rate is the same as the pulses per second. More typically, the rateScale property is set to another value. 10 20 30 40 50 60 70 80 90 100 110 120 130 140 150 160 170 180 190 200

Delta Time sec.

10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10 10

Raw Count pulses

100 120 140 165 190 220 250 285 320 350 380 410 435 460 480 500 520 540 560 580

Delta Count pulses

20 20 25 25 30 30 35 35 30 30 30 25 25 20 20 20 20 20 20

Instant. Rate Normal. Rate pulse/sec. pulse/sec.

2.000 2.000 2.500 2.500 3.000 3.000 3.500 3.500 3.000 3.000 3.000 2.500 2.500 2.000 2.000 2.000 2.000 2.000 2.000 2.250 2.500 2.750 3.000 3.250 3.250 3.250 3.125 2.875 2.750 2.500 2.250 2.125 2.000 2.000 2.000

1032

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects NdioResistiveInput

NdioResistiveInput
Quick reference for all properties: Table A-58 Inputs
statusInput

Default Object Shape

Outputs
statusOutput

abbrev: ResIn An NdioResistiveInput object configures a JACE universal input (UI) to read a resistive value within a 0100 K range and produce a scaled output. Like the Ndio0to10VInput and NdioThermistorType3Input objects, this object is similar to a standard AnalogInput (AI) object, including all alarm capabilities. The output value follows the objects configurable resistance-to-value lookup table. This table can contain up to 20 different points, or 19 segments. Values are linearly interpolated between points. The default table is 11 points or 10 segments, spanning the full 0100 K range of the JACE universal input. This object can be exposed directly as a BACnet Analog_Input object1.
Parent Dependencies: NdioProcessor. Resource Count Range: 70 to 126 Trigger Properties

All Inputs / Outputs

Inputs
executeTrigger statusInhibit

Outputs
eventTrigger covTrigger statusOutput

Input / Output Properties for NdioResistiveInput Object

(only input and output types, see Table 10-10 for all properties)

Type
input output

Label
exe sInh eventTr covTrig sOut

Property Name
executeTrigger statusInhibit eventTrigger covTrigger statusOutput

Data Species
TriggerType BooleanStatusType TriggerType TriggerType FloatStatusType

This object has the standard input property, executeTrigger, (typically not used) and also two trigger-type outputs: eventTriggerFires upon each event transition (to-offnormal, to-fault, to-normal) that has been specified in the property eventTriggerEnable. covTriggerFires upon each change of value at the statusOutput. As needed, these outputs can be linked to any input using TriggerType data species.

Commands
A JDE user with Command, Admin rights has this available menu bar command:

Commands > resetAckedTransitionsSets all three flags in the ackedTransitions property (to-offnormal, to-fault, to-normal). Rarely required, see the the JDE Command section on page 5-11 for more information.

Properties
Table 10-10 NdioResistiveInput object properties.

Tab Property Name

objectType, statusFlags, description Status

Description
See Table 5-3 on page 5-8 for information on these properties common to all control and Ndio objects.

Valid Values

Default

Notes
default description is Ndio Resistive Input

1. For direct exposure as a BACnet object, the JACE-4 requires both the BACnetService and the BACxNdioService.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

1033

Chapter 10 NdioResistiveInput

Ndio Objects

Table 10-10 NdioResistiveInput object properties. (continued)

Tab Property Name

eventState, reliability, outOfService, ackedTransitions, toOffnormal, toFault, toNormal presentValue syncFlag

Description
See Table 5-4 on page 5-12 for information on these properties common to all event-type objects.

Valid Values

Default

Notes
presentValue can be written to directly whenever the object is set to outOfService.

Status, cont.

Read Only: Shows whether the object successfully updated the configuration of the JACEs dedicated I/O processor.

False, True

False

False until ioIndex value is assigned to non-zero value.

executeParameters foreignAddress

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: BACnet usage only. Set to a positive integer for this object to appear as a BACnet Analog_Input object to other BACnet devices. See foreignAddress, page 5-9, for more information. Read-Write: (Future use only.) Read-Write: Selection of engineering units for display purposes. Choose from a logical grouping, then a specific unit. Read-Write: The minimum required input change (since the last output change) before outputs and presentValue update. Affects the statusOutput and covTrigger (fires at change of value). Read-Write: I/O processor-to-terminal number for the UI configured by this object. See Table 10-1 on page 10-4 for more details by hardware platform. 0 to 4194302 or -1 (not exposed)

normal, input -1 If set, must be a unique number among all other AI objects in station.

membershipGroups units

niagaraR2 Select any (BACnet-type unit choices) valid float

niagaraR2 Leave at default. Other, no_units 0.0 (no minimum) For selections see About Units, page 5-6. covIncrement value is expressed in same units as scaled output value (not in resistance). Must be unique number among all Ndio UI objects for the I/O processor. Output values are linearly interpolated between points. When resistance at the UI input is outside the entered resistance range (lowest resistance and highest resistance), the output value is clamped at the corresponding end valuein other words, there is no extrapolation of output values.

covIncrement

ioIndex

0 (unconfigured) 16 (401, 403) 18 (IO-XX) Points, 2 to 20

Config

linearization Points Resistance Value

Read-Write: Physical input signal (resistance, ohms) to output (value). Up to 20 points can be specified. Default setup provides 11 points (10 segments): Resistance 0.0 1000.0 2000.0 4000.0 8000.0 20000.0 30000.0 50000.0 65000.0 90000.0 100000.0 Value 0.0 1000.0 2000.0 4000.0 8000.0 20000.0 30000.0 50000.0 65000.0 90000.0 100000.0

11 Points

Resistance, 0.0 See to 100000.0 Descrip. for <float> default Resistance Value, and Values <valid float>

Rules for Resistance values are:

Resistance value range is 0.0 to 100000. Resistance must increase in each new
point (be greater than preceding point). Values may be float, positive or negative.

1034

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects NdioResistiveInput

Table 10-10 NdioResistiveInput object properties. (continued)

Tab Property Name

Config, cont. offset

Description
Read-Write: Value added to the internally calculated value before it passes to the objects statusOutput. Allows for wiring or sensor-to-system compensation. See Table 5-5 on page 5-13 for information on these properties common to all event-type control objects.

Valid Values
valid float

Default
0.0

Notes
Can be positive or negative, as needed.

timeDelay, notificationClass, eventEnable, notifyType, inhibitTime*, eventTriggerEnable, alarmText inhibitTime

* See specific details on inhibitTime, the next property.

Read-Write: Duration (Hr:Min:Sec) of the alarm inhibit timer, which applies only if the objects input statusInhibit is linked. Refer to AI Alarm Inhibit, page 5-19, for more information. Read-Write: Valid processing low range for the received input value. Below this value, the object and its output have a fault status. Read-Write: Valid processing high range for the received input value. Above this value, the object and its output have a fault status. Read-Write: Value above which the object is evaluated in high-limit alarm. Above this value (if not in fault), the object and output have inAlarm status. Read-Write: Value below which the object is considered in low-limit alarm. Below this value (if not in fault), the object and output have inAlarm status. Read-Write: Differential value applied to high and low limits before return-to-normal. Deadband is subtracted from highLimit and added to lowLimit. Read-Write: Flags that enable low-limit and high-limit alarms, as needed. Read-Write: See position, page 5-9. Read-Write: Sets decimal position from 0 to 6 places, and optionally force (+) sign for positive values. Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows the current boolean state and status of the statusInhibit input. Read Only: Shows the current value and status of the statusOutput.

any practical value in Hr:Min:Sec

00:00:00 A minimum of 1 (no inhibit) second (00:00:01) is recommended whenever the statusInput is linked. MIN_VALUE is default, meaning no effective minimum. MAX_VALUE is default, meaning no effective maximum. 0.0 The limitEnable flag (for high-limit) must also be set. The limitEnable flag (for low-limit) must also be set. Deadband does not apply to fault conditions.

minPresentValue Alarm Setup

valid float

maxPresentValue

valid float

highLimit

valid float

lowLimit

valid float

0.0

deadband

valid float

0.0

limitEnable

(select) low-limit, high-limit 0 to 6, (+) sign no (+) sign

(none)

position Visual decimalFormat

2, Effects display value no (+) sign only (no effect on precision).

Engineering

minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInhibit (input sInh) statusOutput (output sOut)

false, true : {status flags} <float value> {status flags}

false : {ok} 00.0 {ok}

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

1035

Chapter 10 NdioResistiveInput

Ndio Objects

Table 10-10 NdioResistiveInput object properties. (continued)

Tab Property Name

Security securityGroups

Description
Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10.

Valid Values
General, 7 others

Default
General

Notes

ResistiveInput Notes
Typically, you enter values in the linearization table from a sensors documentation. If the sensor has more than 20 data points, enter those within the range of expected measurement. Use the offset property to compensate for (linear) error that may be introduced by wiring to the sensor. Example 10-1 shows possible linearization table entries that could be used for a 10K3A1 type thermistor sensor, used to display degrees Celsius.
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
-50 -40 -30 -20 -15 -10 -5 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22

Ohms
667828 335671 176683 96974 72895 55298 42314 32650 31030 29500 28054 26688 25396 24173 23016 21921 20885 19904 18974 18092 17257 16465 15714 15001 14325 13623 13053 12494 11943 11420

Deg. C
23 24 25 26 27 28 29 30 35 40 45 50 55 60 65 70 75 80 85 90 95 100 105 110 115 120 125 130 140 150

Ohms
10923 10450 10000 9572 9165 8777 8408 8056 6530 5325 4367 3601 2985 2487 2082 1751 1480 1256 1070 916.1 787.0 678.6 587.3 510.1 444.5 386.6 340.8 300.0 234.1 184.8

Resistance
3601 5325 6530 8056 8777 9165 9572 10000 10450 10923 11420 12494 13623 15001 17257 19904 25396 32650 55298 96974

Value
50 40 35 30 28 27 26 25 24 23 22 20 18 16 13 10 5 0 -10 -20

Note that Resistance entries in the points (linearization table) must be entered in an increasing manner, as shown here. Also, the UI input is optimized to provide the best resolution around the 10K ohm range. For any sensor with a range far from 10K ohms (such as a 100-ohm or 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 a transmitter to produce a Vdc or mA output, and used instead with a UI input configured by a Ndio0to10VInput object.

1036

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects NdioThermistorType3Input

NdioThermistorType3Input
Quick reference for all properties: Table A-60

Default Object Shape

Inputs
statusInput

abbrev: Type3In The NdioThermistorType3Input object configures a JACE universal input to read a Type 3 Thermistor temperature sensor. Like the Ndio0to10VInput and NdioResistiveInput objects, this object is similar to a standard AnalogInput (AI) object, including all alarm capabilities. A selectable tempUnits property specifies the displayed output value, either in degrees Celsius, Fahrenheit, or Kelvin. An offset property allows sensor-to-system calibration. This object can be exposed directly as a BACnet Analog_Input object1.
Parent Dependencies: NdioProcessor. Resource Count Range: 70 to 126 Trigger Properties

Outputs
statusOutput

All Inputs / Outputs

Inputs
executeTrigger statusInhibit

Outputs
eventTrigger covTrigger statusOutput

Input / Output Properties for NdioThermistorType3Input Object

(only input and output types, see Table 10-11 for all properties)

Type
input output

Label
exe sInh eventTr covTrig sOut

Property Name
executeTrigger statusInhibit eventTrigger covTrigger statusOutput

Data Species
TriggerType BooleanStatusType TriggerType TriggerType FloatStatusType

This object has the standard input property, executeTrigger, (typically not used) and also two trigger-type outputs: eventTriggerFires upon each event transition (to-offnormal, to-fault, to-normal) that has been specified in the property eventTriggerEnable. covTriggerFires upon each change of value at the statusOutput. As needed, these outputs can be linked to any input using TriggerType data species.

Commands
A JDE user with Command, Admin rights has this available menu bar command:

Commands > resetAckedTransitionsSets all three flags in the ackedTransitions property (to-offnormal, to-fault, to-normal). Rarely required, see the the JDE Command section on page 5-11 for more information.

Properties
Table 10-11 NdioThermistorType3Input object properties.

Tab Property Name

objectType, statusFlags, description Status

Description
See Table 5-3 on page 5-8 for information on these properties common to all control and Ndio objects.

Valid Values

Default

Notes
default description is Ndio Thermistor Type 3 Input

1. For direct exposure as a BACnet object, the JACE-4 requires both the BACnetService and the BACxNdioService.
Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

1037

Chapter 10 NdioThermistorType3Input

Ndio Objects

Table 10-11

NdioThermistorType3Input object properties. (continued)

Tab Property Name

eventState, reliability, outOfService, ackedTransitions, toOffnormal, toFault, toNormal presentValue syncFlag

Description
See Table 5-4 on page 5-12 for information on these properties common to all event-type objects.

Valid Values

Default

Notes
presentValue can be written to directly whenever the object is set to outOfService.

Status, cont.

Read Only: Shows whether the object successfully updated the configuration of the JACEs dedicated I/O processor.

False, True

False

Remains False until the ioIndex value is successfully assigned.

executeParameters foreignAddress

Read-Write: The objects execution frequency and order. For more details, see execution Parameters, page 5-9. Read-Write: BACnet usage only. Set to a positive integer for this object to appear as a BACnet Analog_Input object to other BACnet devices. See foreignAddress, page 5-9, for more information. Read-Write: (Future use only.) Read-Write: The minimum required input change (since the last output change) before outputs and presentValue update. Affects the outputs statusOutput and covTrigger (fires at change of value). Read-Write: I/O processor-to-terminal number for the UI configured by this object. See Table 10-1 on page 10-4 for more details by hardware platform. 0 to 4194302 or -1 (not exposed)

normal, input -1 If set, must be a unique number among all other AI objects in station.

membershipGroups covIncrement

niagaraR2 valid float

niagaraR2 Leave at default. 0.0 (no minimum) covIncrement value is expressed in same terms as scaled output value (tempUnits). Must be unique number among all Ndio UI objects for the I/O processor. Can be positive or negative, as needed. See Note in Table 10-12 on page 10-40.

ioIndex Config

0 (unconfigured) 16 (401, 403) 18 (IO-XX) valid float

offset

Read-Write: Value added to the internally calculated temperature value before it appears at the objects statusOutput. Allows for sensor-to-system compensation for factors such as sensor wiring, etc. Read-Write: Specifies the internal calculation used on the raw input value to format it in the correct numeric range. Also specifies the displayed unit descriptor. For example, a linked GxText object can display either the abbreviated or full versions as follows: C F K degrees_Celsius, degrees_Fahrenheit, degrees_Kelvin

0.0

tempUnits

degrees_ celsius, fahrenheit, kelvin

degrees_ celsius

timeDelay, notificationClass, eventEnable, notifyType, inhibitTime*, eventTriggerEnable, alarmText

Alarm Setup

See Table 5-5 on page 5-13 for information on these properties common to all event-type control objects.

* See specific details on inhibitTime, the next property.

1038

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Chapter 10

Ndio Objects NdioThermistorType3Input

Table 10-11

NdioThermistorType3Input object properties. (continued)

Tab Property Name

inhibitTime

Description
Read-Write: Duration (Hr:Min:Sec) of the alarm inhibit timer, which applies only if the objects input statusInhibit is linked. Refer to AI Alarm Inhibit, page 5-19, for more information.

Valid Values
any practical value in Hr:Min:Sec

Default

Notes

00:00:00 A minimum of 1 (no inhibit) second (00:00:01) is recommended whenever the statusInput is linked. MIN_VALUE is default, meaning no effective minimum. MAX_VALUE is default, meaning no effective maximum. 0.0 The limitEnable flag (for high-limit) must also be set. The limitEnable flag (for low-limit) must also be set. Deadband does not apply to fault conditions.

minPresentValue

Read-Write: Valid processing low range for the received input value. Below this value, the object and its output have a fault status. Read-Write: Valid processing high range for the received input value. Above this value, the object and its output have a fault status. Read-Write: Value above which the object is evaluated in high-limit alarm. Above this value (if not in fault), the object and output have inAlarm status. Read-Write: Value below which the object is considered in low-limit alarm. Below this value (if not in fault), the object and output have inAlarm status. Read-Write: Differential value applied to high and low limits before return-to-normal. Deadband is subtracted from highLimit and added to lowLimit. Read-Write: Flags that enable low-limit and high-limit alarms, as needed. Read-Write: See position, page 5-9. Read-Write: Sets decimal position from 0 to 6 places, and optionally force (+) sign for positive values. Properties common to all control objects. For more information, see Table 5-3 on page 5-8. Read Only: Shows the current boolean state and status of the statusInhibit input. Read Only: Shows the current value and status of the statusOutput. Read-Write: Shows the security groups to which the object is assigned. For more details, see securityGroups, page 5-10.

valid float

maxPresentValue Alarm Setup, cont.

valid float

highLimit

valid float

lowLimit

valid float

0.0

deadband

valid float

0.0

limitEnable

(select) low-limit, high-limit 0 to 6, (+) sign no (+) sign

(none)

position Visual decimalFormat

2, Effects display value no (+) sign only (no effect on precision).

Engineering

minExecuteTime, maxExecuteTime, averageExecuteTime, userData statusInhibit (input sInh) statusOutput (output sOut)

false, true : {status flags} <float value> {status flags} General, 7 others

false : {ok} 00.0 {ok} General

Security

securityGroups

ThermistorType3Input Notes
The ThermistorType3Input object is used for any Type 3 thermistor temperature sensor. The offset property allows for calibration/compensation, typically for wiring resistance.

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

1039

Chapter 10 NdioThermistorType3Input

Ndio Objects

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
-22 -13 5 14 23 32 41 50 59 68 77 86 95 104 113 122 131 140 149 158 167 176 185 194 203 212 221 230 239 248

Ohms
135200.0 102863.0 61012.0 47554.0 37304.0 29481.0 23456.0 18782.0 15134.0 12267.0 10000.0 8197.0 6755.0 5595.0 4657.0 3895.0 3272.0 2761.0 2340.0 1991.0 1700.0 1458.0 1255.0 1084.0 939.0 817.0 712.0 623.0 548.0 483.0

Deg. C
-30 -25 -15 -10 -5 0 5 10 15 20 25 30 35 40 45 50 55 60 65 70 75 80 85 90 95 100 105 110 115 120 125 130 135 140 145 150

Ohms
125233.0 102890.0 61030.0 47549.0 37316.0 29490.0 23462.0 18787.0 15136.0 12268.0 10000.0 8197.0 6754.0 5594.0 4656.0 3893.0 3271.0 2760.0 2339.0 1990.0 1700.0 1458.0 1255.0 1084.0 939.6 817.2 713.0 624.1 547.9 482.5 426.0 377.2 334.9 298.1 266.0 238.0

Notes
Outside the NDIO software upper-limit of 100K ohms. Any input above 100K (for example, open circuit) displays a set value. See note below.

JACE input circuitry is optimized to provide best resolution around the room 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 internal response curve for a ThermistorType3 input object such that temperature accuracy above 55C (131F) was greatly improved. Boiler applications 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, which when reading an open-circuit UI, displays -11.92F.

Note: If upgrading a JACE with NDIO that is currently running r2.301.428e (or earlier) to r2.3.5, please note that existing NdioThermistorType3 objects will likely need sensor calibration (offset change), 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 or later to r2.3.5, existing NdioThermistorType3 objects used in room temperature applications should not require any change to offset.

250

469

1040

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

APPENDIX

Object Property Quick Reference

This appendix provides a complete listing of all properties for all standard Niagara objects found in the tridium JAR. The following main sections are included:

Attributes Property Quick References Variable Types Enumerations Resource Count Ranges

Attributes
Attributes for each object property describe its usage. This includes how the property is accessed, how its value is stored, and what user (access) level is required. Attribute Notation Attribute Notation Examples

Attribute Notation
In the quick reference table for each object type, the various attributes for each property are listed inside brackets { }, using a format similar to: {<access><storage><input/output>:<access level>} where the following attribute notations are used:
r w P T -dem i o ~ Op Ad readable writeable persistent transient on demand transient input linkable output linkable always display operator level administrator level Can be viewed (by user with proper level). Can be modified (by user with proper level). Property value is persistently stored (disk or flash). Property value is stored only in RAM. Value from RAM in a foreign device (fetched vs. polled). Linkable input of the object. Linkable output of the object. Linkable and always shown on object shape. Requires operator-level access for read or write. Requires administrator-level access for read or write.

for example, {rwP:Ad}

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A1

Appendix A Attributes

Object Property Quick Reference

Note

The attribute of -dem (on demand transient) applies to many properties of Niagara shadow objects, used in integrations (BACnet, LonWorks, others). However, for standard Niagara objects, the -dem property attribute does not apply.

Attribute Notation Examples

Some common attribute combinations found among object properties: Attribute
{rT:Op}

Definition

Description, Example Property

readable, transient, operator level Typical for many status properties, which are read-only. Common example: statusFlags

{rwP:Ad}

readable, writeable, persistent, administrator level

Typical for most config properties, which are read-write (for administrator level users only). Common example: executionParameters

{rTi~:Op}

readable, transient, input, always shown, operator level

Typical for many object inputs (that are shown on the object shape by default). Common example: statusInput

{rTo~:Op}

readable, transient, output, always shown, operator level

Typical for many object outputs (that are shown on the object shape by default). Common example: statusOutput

{rwP:Op}

readable, writeable, persistent, operator level transient, input, administrator level

Used for property description.

{Ti:Ad}

Used for input property executeTrigger.

A2

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference Property Quick References

Property Quick References

A quick reference table is provided for each object type, listing all properties grouped by type. Included are property names, data species used, and property attributes. Object types are listed alphabetically as follows:
AdminTool AnalogInput AnalogLog AnalogOutput AnalogOverride ApiRecipient AuditLogService BackupService BinaryInput BinaryLog BinaryOutput BinaryOverride Bundle Calendar Command Comparison Composite Container ControlEngineService CpAnalogNode CpBinaryNode CpIntegerNode CpStringNode DatabaseService DateTimeTrigger ErrorLogService FunctionGenerator GxBarGraph GxBoolean GxDamper GxFan GxFloat GxImage GxInteger GxPage GxPipe GxSpectrum GxText GxTimePlot
Niagara Release 2.3.5 Niagara Standard Programming Reference

IntegerLog IntToFloat LogService Logic Loop MailRecipient MailService Math MultistateInput MultistateLog MultistateOutput MultistateOverride Ndio0to10VInput Ndio0to10VOutput NdioBinaryInput NdioBinaryOutput NdioContainer NdioHighSpeedCounterInput NdioResistiveInput NdioProcessor NdioThermistorType3Input NotificationClass NotificationService PeriodicTrigger PollAlways PollArchiveService PollOnDemand PrinterRecipient Program RemotePrinterRecipient Schedule ServiceContainer Station StringLog TimeSyncService Totalizer UiEngineService VasRecipient WebUiService

Revised: April 20, 2004

A3

Appendix A AdminTool

Object Property Quick Reference

AdminTool
Table A-1 Tab
Status Config

AdminTool object properties, quick reference. Name

objectType statusFlags rootNode propertyName elementName newValue recurseChildren objectTypeFilter nodeNameFilter propertyValueFilter position securityGroups

Data Species
String StatusFlagsType UrlType String String String boolean String String String PointType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Visual Security

AnalogInput
Table A-2 Tab
Status

AnalogInput object properties, quick reference. Name

objectType statusFlags description eventState reliability outOfService ackedTransitions toOffnormal toFault toNormal presentValue executionParameters foreignAddress membershipGroups units covIncrement defaultInput timeDelay notificationClass eventEnable notifyType inhibitTime eventTriggerEnable alarmText minPresentValue maxPresentValue highLimit lowLimit deadband limitEnable position decimalFormat

Data Species
String StatusFlagsType String EventStateEnum ReliabilityEnum boolean EventTransitionBitsType EventTimestampsType EventTimestampsType EventTimestampsType float ExecutionParametersType int String EngUnitsEnum float float DurationType int EventTransitionBitsType NotifyTypeEnum DurationType EventTransitionBitsType String float float float float float LimitEnableBitsType PointType DecimalFormatType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Op} {rwT:Op} {rwP:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rwT:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

Alarm Setup

Visual

A4

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference AnalogLog

Table A-2 Tab

Engineering

AnalogInput object properties, quick reference. (continued) Name

executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInhibit eventTrigger covTrigger statusInput statusOutput securityGroups

Data Species
TriggerType int int float String BooleanStatusType TriggerType TriggerType FloatStatusType FloatStatusType SecurityGroupBitsType

Attributes
{Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi:Op} {To:Ad} {To:Ad} {rTi~:Op} {rTo~:Op} {rwP:Ad}

Security

AnalogLog
Table A-3 Tab
Status

AnalogLog object properties, quick reference. Name

objectType statusFlags description lastArchiveTimestamp executionParameters foreignAddress membershipGroups bufferSize stopWhenFull archiveSetup logEnableDefault collectionMode daysOfTheWeek timeRange interval outputFunction changeTolerance deltaLogging units position chartType chartColor chartTemplateUrl decimalFormat holeValue executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData buffer doArchiveTrigger doClearTrigger recordedTrigger archivedTrigger logEnable statusInput statusOutput lastValue securityGroups

Data Species
String StatusFlagsType String TimestampType ExecutionParametersType int String int boolean LogArchiveSetupType boolean LogControlNodeCollectionModeEnum DaysOfWeekBitsType TimeRangeType int AnalogLogNodeOutputFunctionEnum float boolean EngUnitsEnum PointType LogControlNodeChartTypeEnum ColorType UrlType DecimalFormatType float TriggerType int int float String LogRecordBufferType TriggerType TriggerType TriggerType TriggerType BooleanStatusType FloatStatusType FloatStatusType float SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {wP:Ad} {Ti:Ad} {Ti:Ad} {To:Ad} To:Ad} {rTi:Op} {rTi~:Op} {rTo:Op} {wP:Ad} {rwP:Ad}

Config

Visual

Engineering

Security

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A5

Appendix A AnalogOutput

Object Property Quick Reference

AnalogOutput
Table A-4 Tab
Status

AnalogOutput object properties quick reference. Name Data Species

String StatusFlagsType String EventStateEnum ReliabilityEnum boolean EventTransitionBitsType EventTimestampsType EventTimestampsType EventTimestampsType float FloatPriorityArrayType float ExecutionParametersType int String EngUnitsEnum float DurationType int EventTransitionBitsType NotifyTypeEnum DurationType EventTransitionBitsType String float float float float float LimitEnableBitsType PointType DecimalFormatType FloatCommandTagsType TriggerType int int float String BooleanStatusType TriggerType TriggerType FloatStatusType FloatStatusType FloatStatusType FloatPriorityType FloatPriorityType FloatPriorityType FloatStatusType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Op} {rwT:Op} {rwP:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rTo:Op} {rTi~:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi:Op} {To:Ad} {To:Ad} {rTi~:Op} {rTo~:Op} {rTo~:Op} {wP:Ad} {wP:Ad} {rTo~:Op} {rTo:Op} {rwP:Ad}

objectType statusFlags description eventState reliability outOfService ackedTransitions toOffnormal toFault toNormal presentValue Priorities priorityArray relinquishDefault Config executionParameters foreignAddress membershipGroups units covIncrement Alarm Setup timeDelay notificationClas eventEnable notifyType inhibitTime eventTriggerEnable alarmText minPresentValue maxPresentValue highLimit lowLimit deadband limitEnable Visual position decimalFormat commandTags Engineering executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInhibit eventTrigger covTrigger statusInput statusOutput statusOutput manualSetpoint emergencylSetpoint prioritizedOutput statusFeedbackOutput Security securityGroups

A6

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference AnalogOverride

AnalogOverride
Table A-5 Tab
Status

AnalogOverride object properties quick reference. Name

objectType statusFlags description inOverride executionParameters foreignAddress membershipGroups priorityForWriting overrideTime overrideValue position decimalFormat minExecuteTime maxExecuteTime averageExecuteTime userData statusInOverride prioritizedOutput securityGroups

Data Species
String StatusFlagsType String boolean ExecutionParametersType int String ControlPriorityEnum int float PointType DecimalFormatType int int float String BooleanStatusType FloatPriorityType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rTo:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTo~:Op} {rTo~:Op} {rwP:Ad}

Config

Visual Engineering

Security

ApiRecipient
Table A-6 Tab
Status

ApiRecipient object properties quick reference. Name

objectType statusFlags notificationInput validDays timeRange position securityGroups

Data Species
String StatusFlagsType NotificationTriggerType DaysOfWeekBitsType TimeRangeType PointType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {Ti:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config Visual Security

AuditLogService
Table A-7 Tab
Status

AuditLogService object properties quick reference. Name

objectType statusFlags description lastArchiveTimestamp bufferSize stopWhenFull archiveSetup position buffer doArchiveTrigger doClearTrigger recordedTrigger archivedTrigger securityGroups

Data Species
String StatusFlagsType String TimestampType int boolean LogArchiveSetupType PointType LogRecordBufferType TriggerType TriggerType TriggerType TriggerType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {Ti:Ad} {Ti:Ad} {To:Ad} {To:Ad} {rwP:Ad}

Config

Visual Engineering

Security

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A7

Appendix A BackupService

Object Property Quick Reference

BackupService
Table A-8 Tab
Status

BackupService object properties quick reference. Name

objectType statusFlags description lastBackupTime backupEnabled scheduledBackupTime position securityGroups

Data Species
String StatusFlagsType String TimestampType boolean TimeType PointType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config Visual Security

BinaryInput
Table A-9 Tab
Status

BinaryInput object properties quick reference. Name

objectType statusFlags description eventState reliability outOfService ackedTransitions toOffnormal toFault toNormal changeOfStateTime changeOfStateCount timeOfStateCountReset elapsedActiveTime timeOfActiveTimeReset changeOfStateAlertFlag activeTimeAlertFlag presentValue executionParameters foreignAddress membershipGroups polarity defaultInput timeDelay notificationClass eventEnable notifyType inhibitTime eventTriggerEnable alarmText changeOfStateAlertLimit activeTimeAlertLimit lastCosCountAlert lastActiveTimeAlert alertNotificationClass periodicAlerts alertText alarmValue alarmValueEnabled position activeInactiveText

Data Species
String StatusFlagsType String EventStateEnum ReliabilityEnum boolean EventTransitionBitsType EventTimestampsType EventTimestampsType EventTimestampsType TimestampType int TimestampType DurationType TimestampType boolean boolean boolean ExecutionParametersType int String PolarityEnum boolean DurationType int EventTransitionBitsType NotifyTypeEnum DurationType EventTransitionBitsType String int DurationType int DurationType int boolean String boolean boolean PointType BooleanEnumTagsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Op} {rwT:Op} {rwP:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rP:Op} {rP:Op} {rP:Op} {rP:Op} {rP:Op} {wP:Ad} {wP:Ad} {rwT:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {wP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

Alarm Setup

Visual

A8

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference BinaryLog

Table A-9 Tab

Engineering

BinaryInput object properties quick reference. (continued) Name

executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInhibit eventTrigger statusChangeOfStateCount statusElapsedActiveTime resetChangeOfStateCountTrigger resetElapsedActiveTimeTrigger changeOfStateTrigger changeOfStateAlertTrigger elapsedActiveTimeAlertTrigger statusInput statusOutput securityGroups

Data Species
TriggerType int int float String BooleanStatusType TriggerType IntegerStatusType IntegerStatusType TriggerType TriggerType TriggerType TriggerType TriggerType BooleanStatusType BooleanStatusType SecurityGroupBitsType

Attributes
{Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi:Op} {To:Ad} {rTo:Op} {rTo:Op} {Ti:Ad} {Ti:Ad} {To:Ad} {To:Ad} {To:Ad} {rTi~:Op} {rTo~:Op} {rwP:Ad}

Security

BinaryLog
Table A-10 Tab
Status

BinaryLog object properties quick reference. Name

objectType statusFlags description lastArchiveTimestamp executionParameters foreignAddress membershipGroups bufferSize stopWhenFull archiveSetup logEnableDefault collectionMode daysOfTheWeek timeRange interval position chartType chartColor chartTemplateUrl activeInactiveText executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData buffer doArchiveTrigger doClearTrigger recordedTrigger archivedTrigger logEnable statusInput securityGroups

Data Species
String StatusFlagsType String TimestampType ExecutionParametersType int String int boolean LogArchiveSetupType boolean LogControlNodeCollectionModeEnum DaysOfWeekBitsType TimeRangeType int PointType LogControlNodeChartTypeEnum ColorType UrlType BooleanEnumTagsType TriggerType int int float String LogRecordBufferType TriggerType TriggerType TriggerType TriggerType BooleanStatusType BooleanStatusType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {wP:Ad} {Ti:Ad} {Ti:Ad} {To:Ad} {To:Ad} {rTi:Op} {rTi~:Op} {rwP:Ad}

Config

Visual

Engineering

Security

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A9

Appendix A BinaryOutput

Object Property Quick Reference

BinaryOutput
Table A-11 Tab
Status

BinaryOutput object properties quick reference. Name

objectType statusFlags description eventState reliability outOfService ackedTransitions toOffnormal toFault toNormal changeOfStateTime changeOfStateCount timeOfStateCountReset elapsedActiveTime timeOfActiveTimeReset presentValue priorityArray relinquishDefault inInterstartDelay executionParameters foreignAddress membershipGroups polarity minimumOnTime minimumOffTime restartDisable interstartDelayTime timeDelay notificationClass eventEnable notifyType inhibitTime eventTriggerEnable alarmText changeOfStateAlertLimit activeTimeAlertLimit alertNotificationClass periodicAlerts alertText position activeInactiveText commandTags

Data Species
String StatusFlagsType String EventStateEnum ReliabilityEnum boolean EventTransitionBitsType EventTimestampsType EventTimestampsType EventTimestampsType TimestampType int TimestampType DurationType TimestampType boolean BooleanPriorityArrayType boolean boolean ExecutionParametersType int String PolarityEnum DurationType DurationType boolean DurationType DurationType int EventTransitionBitsType NotifyTypeEnum DurationType EventTransitionBitsType String int DurationType int boolean String PointType BooleanEnumTagsType BooleanCommandTagsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Op} {rwT:Op} {rwP:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rP:Op} {rP:Op} {rP:Op} {rP:Op} {rP:Op} {rwT:Op} {rTi~:Op} {rwP:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Priorities

Config

Alarm Setup

Visual

A10

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference BinaryOverride

Table A-11 Tab

Engineering

BinaryOutput object properties quick reference. (continued) Name

executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInhibit eventTrigger statusChangeOfStateCount statusElapsedActiveTime resetChangeOfStateCountTrigger resetElapsedActiveTimeTrigger changeOfStateTrigger changeOfStateAlertTrigger elapsedActiveTimeAlertTrigger statusInput statusOutput prioritizedOutput statusFeedbackOutput securityGroups

Data Species
TriggerType int int float String BooleanStatusType TriggerType IntegerStatusType IntegerStatusType TriggerType TriggerType TriggerType TriggerType TriggerType BooleanStatusType BooleanStatusType BooleanPriorityType BooleanStatusType SecurityGroupBitsType

Attributes
{Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi:Op} {To:Ad} {rTo:Op} {rTo:Op} {Ti:Ad} {Ti:Ad} {To:Ad} {To:Ad} {To:Ad} {rTi~:Op} {rTo~:Op} {rTo~:Op} {rTo:Op} {rwP:Ad}

Security

BinaryOverride
Table A-12 Tab
Status

BinaryOverride object properties quick reference. Name

objectType statusFlags description inOverride executionParameters foreignAddress membershipGroups priorityForWriting overrideTime overrideValue position activeInactiveText minExecuteTime maxExecuteTime averageExecuteTime userData statusInOverride prioritizedOutput securityGroups

Data Species
String StatusFlagsType String boolean ExecutionParametersType int String ControlPriorityEnum int float PointType DecimalFormatType int int float String BooleanStatusType BooleanPriorityType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rTo:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTo~:Op} {rTo~:Op} {rwP:Ad}

Config

Visual Engineering

Security

Bundle
Table A-13 Tab
Status

Bundle object properties quick reference. Name

objectType statusFlags description executionParameters foreignAddress membershipGroups typeString displayTypeString alarmText alertText

Data Species
String StatusFlagsType String ExecutionParametersType int String String String String String

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

AlarmSetup

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A11

Appendix A Calendar

Object Property Quick Reference

Table A-13 Tab

Visual

Bundle object properties quick reference. (continued) Name

position decimalFormat icon size backgroundColor alarmPageUrl executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData securityGroups

Data Species
PointType DecimalFormatType UrlType DimensionType ColorType UrlType TriggerType int int float String SecurityGroupBitsType

Attributes
{rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad}

Engineering

Security

Calendar
Table A-14 Tab
Status

Calendar object properties quick reference. Name

objectType statusFlags description presentValue executionParameters foreignAddress membershipGroups activeInactiveText entryList position templateUrl executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusOutput statusInput statusInputDefault covTrigger onActiveTrigger onInactiveTrigger masterOut slaveIn securityGroups

Data Species
String StatusFlagsType String boolean ExecutionParametersType int String BooleanEnumTagsType CalendarEntryListType PointType UrlType TriggerType int int float String BooleanStatusType BooleanStatusType boolean TriggerType TriggerType TriggerType SlaveSyncType SlaveSyncType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rTo:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTo~:Op} {rTi:Op} {rwP:Ad} {To:Ad} {To:Ad} {To:Ad} {rTo:Ad} {rTi:Ad} {rwP:Ad}

Config

Visual Engineering

Security

Command
Table A-15 Tab
Status Visual

Command object properties quick reference. Name

objectType statusFlags position outputTriggerTextA outputTriggerTextB outputTriggerTextC outputTriggerTextD

Data Species
String StatusFlagsType PointType String String String String

Attributes
{rT:Op} {rT:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

A12

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference Comparison

Table A-15 Tab

Engineering

Command object properties quick reference. (continued) Name

outputTriggerA outputTriggerB outputTriggerC outputTriggerD securityGroups

Data Species
TriggerType TriggerType TriggerType TriggerType SecurityGroupBitsType

Attributes
{To:Ad} {To:Ad} {To:Ad} {To:Ad} {rwP:Ad}

Security

Comparison
Table A-16 Tab
Status

Comparison object properties quick reference. Name

objectType statusFlags description presentValue outOfService reliability executionParameters foreignAddress membershipGroups defaultA defaultB function priorityForWriting trueCommand falseCommand position decimalFormat activeInactiveText executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInputA statusInputB prioritizedOutput statusOutput securityGroups

Data Species
String StatusFlagsType String boolean boolean ReliabilityEnum ExecutionParametersType int String float float ComparisonNodeFunctionEnum ControlPriorityEnum BooleanCmdEnum BooleanCmdEnum PointType DecimalFormatType BooleanEnumTagsType TriggerType int int float String FloatStatusType FloatStatusType BooleanPriorityType BooleanStatusType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rTo:Op} {rwP:Op} {rwT:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi~:Op} {rTi~:Op} {rTo~:Op} {rTo~:Op} {rwP:Ad}

Config

Visual

Engineering

Security

Composite
Table A-17 Tab
Status

Composite object properties quick reference. Name

objectType statusFlags description executionParameters foreignAddress membershipGroups typeString displayTypeString alarmText alertText

Data Species
String StatusFlagsType String ExecutionParametersType int String String String String String

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

AlarmSetup

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A13

Appendix A Container

Object Property Quick Reference

Table A-17 Tab

Visual

Composite object properties quick reference. (continued) Name

position decimalFormat icon size backgroundColor alarmPageUrl executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData securityGroups

Data Species
PointType DecimalFormatType UrlType DimensionType ColorType UrlType TriggerType int int float String SecurityGroupBitsType

Attributes
{rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad}

Engineering

Security

Container
Table A-18 Tab
Status Config AlarmSetup Visual

Container object properties quick reference. Name

objectType statusFlags description alarmText alertText position icon size backgroundColor alarmPageUrl securityGroups

Data Species
String StatusFlagsType String String String PointType UrlType DimensionType ColorType UrlType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Security

A14

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference ControlEngineService

ControlEngineService
Table A-19 Tab
Status

ControlEngineService object properties quick reference. Name

objectType statusFlags description startTime totalObjectCount fastestObjectCount fasterObjectCount normalObjectCount slowerObjectCount onTriggerObjectCount minutelyObjectCount fastestCycles fasterCycles normalCycles slowerCycles minutelyCycles totalOverruns fastestOverruns fasterOverruns normalOverruns slowerOverruns fastestAverageExecuteTime fasterAverageExecuteTime normalAverageExecuteTime slowerAverageExecuteTime minutelyAverageExecuteTime lateStarts executionFrequencies profileNodes displayDots position securityGroups

Data Species
String StatusFlagsType String String int int int int int int int int int int int int int int int int int float float float float float int ExecutionFrequenciesType boolean boolean PointType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

Visual Security

CpAnalogNode
Table A-20 Tab
Status

CpAnalogNode object properties quick reference. Name

objectType statusFlags description cmdLink value executionParameters foreignAddress membershipGroups maxValue minValue position commandText decimalFormat executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData securityGroups

Data Species
String StatusFlagsType String float float ExecutionParametersType int String float float PointType String DecimalFormatType TriggerType int int float String SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rTi~:Op} {rTo~:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad}

Config

Visual

Engineering

Security

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A15

Appendix A CpBinaryNode

Object Property Quick Reference

CpBinaryNode
Table A-21 Tab
Status

CpBinaryNode object properties quick reference. Name

objectType statusFlags description cmdLink value executionParameters foreignAddress membershipGroups position commandText activeInactiveText executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData securityGroups

Data Species
String StatusFlagsType String boolean boolean ExecutionParametersType int String PointType String BooleanEnumTagsType TriggerType int int float String SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rTi~:Op} {rTo~:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad}

Config

Visual

Engineering

Security

CpIntegerNode
Table A-22 Tab
Status

CpIntegerNode object properties quick reference. Name

objectType statusFlags description cmdLink value executionParameters foreignAddress membershipGroups maxValue minValue position commandText decimalFormat executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData securityGroups

Data Species
String StatusFlagsType String int int ExecutionParametersType int String int int PointType String DecimalFormatType TriggerType int int float String SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rTi~:Op} {rTo~:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad}

Config

Visual

Engineering

Security

CpStringNode
Table A-23 Tab
Status

CpStringNode object properties quick reference. Name

objectType statusFlags description cmdLink value executionParameters foreignAddress membershipGroups

Data Species
String StatusFlagsType String String String ExecutionParametersType int String

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rTi~:Op} {rTo~:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

A16

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference DatabaseService

Table A-23 Tab

Visual Engineering

CpStringNode object properties quick reference. (continued) Name

position commandText executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData securityGroups

Data Species
PointType String TriggerType int int float String SecurityGroupBitsType

Attributes
{rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad}

Security

DatabaseService
Table A-24 Tab
Status

DatabaseService object properties quick reference. Name

objectType statusFlags description isConnected databaseProductName databaseProductVersion driverName driverVersion urlPrefix databaseType orderByTimestampDecsending position securityGroups jdbcDriverClassName jdbcConnectionUrl databaseUser databasePassword msJdbcDriverClassName msJdbcConnectionUrl msDatabaseUser msDatabasePassword msCreateNewDatabase msDatabaseName msDatabaseDataFilename msDatabaseLogFilename orJdbcDriverClassName orJdbcConnectionUrl orDatabaseUser orDatabasePassword

Data Species
String StatusFlagsType String boolean String String String String String DatabaseTypeEnum boolean PointType SecurityGroupBitsType String String String String String String String String String String String String String String String String

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

Visual Security Cloudscape, Config

MS SQL Server, Config

Oracle, Config

DateTimeTrigger
Table A-25 Tab
Status

DateTimeTrigger object properties quick reference. Name

objectType statusFlags description executionParameters foreignAddress membershipGroups triggerDay triggerTime position

Data Species
String StatusFlagsType String ExecutionParametersType int String ConcreteCalendarEntryType TimeType PointType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

Visual

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A17

Appendix A ErrorLogService

Object Property Quick Reference

Table A-25 Tab

Engineering

DateTimeTrigger object properties quick reference. (continued) Name

executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData timeTrigger lastTrigger securityGroups

Data Species
TriggerType int int float String TriggerType DateType SecurityGroupBitsType

Attributes
{Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {To:Ad} {rP:Ad} {rwP:Ad}

Security

ErrorLogService
Table A-26 Tab
Status

ErrorLogService object properties quick reference. Name

objectType statusFlags description lastArchiveTimestamp bufferSize stopWhenFull archiveSetup position buffer doArchiveTrigger doClearTrigger recordedTrigger archivedTrigger securityGroups

Data Species
String StatusFlagsType String TimestampType int boolean LogArchiveSetupType PointType LogRecordBufferType TriggerType TriggerType TriggerType TriggerType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {Ti:Ad} {Ti:Ad} {To:Ad} {To:Ad} {rwP:Ad}

Config

Visual Engineering

Security

FunctionGenerator
Table A-27 Tab
Status

FunctionGenerator object properties quick reference. Name

objectType statusFlags description presentValue executionParameter foreignAddress membershipGroups minValue maxValue increment mode offset degreesPerCycle priorityForWriting rampDirection units position decimalFormat executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData prioritizedOutput statusOutput securityGroups

Data Species
String StatusFlagsType String float ExecutionParametersType int String float float float FunctionGeneratorNodeModeEnum float int ControlPriorityEnum int EngUnitsEnum PointType DecimalFormatType TriggerType int int float String FloatPriorityType FloatStatusType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rTo:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wT:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTo~:Op} {rTo~:Op} {rwP:Ad}

Config

Visual Engineering

Security

A18

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference GxBarGraph

GxBarGraph
Table A-28 Tab
Status

GxBarGraph object properties quick reference. Name

objectType statusFlags isVisible foregroundColor backgroundColor labelsColor font orientation minValue maxValue showLabels position size layer hyperlinkOnClick hyperlinkUrl statusColorEnabled flashingEnabled displayUnits highlightCommandable binding boundHandle boundUrl proxyCommands facetValues debugOn securityGroups

Data Species
String StatusFlagsType BooleanStatusType ColorType ColorType ColorType FontType GxOrientationEnum float float boolean PointType DimensionType GxLayerEnum GxHyperlinkEnum UrlType boolean boolean GxDisplayUnitsEnum boolean FloatFlexBindingType int UrlType GxProxyCommandsType GxFacetValuesType boolean SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rTi:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rTi:Ad} {rT:Ad} {rT:Ad} {wT:Ad} {wT:Ad} {rwT:Ad} {rwP:Ad}

Config

Visual

Engineering

Security

GxBoolean
Table A-29 Tab
Status

GxBoolean object properties quick reference. Name

objectType statusFlags isVisible activeImage inactiveImage activeColor inactiveColor shape booleanKey borderColor borderWidth position size layer hyperlinkOnClick hyperlinkUrl statusColorEnabled flashingEnabled displayUnits highlightCommandable

Data Species
String StatusFlagsType BooleanStatusType UrlType UrlType ColorType ColorType GxShapeEnum GxBooleanKeyEnum ColorType int PointType DimensionType GxLayerEnum GxHyperlinkEnum UrlType boolean boolean GxDisplayUnitsEnum boolean

Attributes
{rT:Op} {rT:Op} {rTi:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {rwP:Ad}

Config

Visual

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A19

Appendix A GxDamper

Object Property Quick Reference

Table A-29 Tab

Engineering

GxBoolean object properties quick reference. (continued) Name

binding boundHandle boundUrl proxyCommands facetValues debugOn securityGroups

Data Species
FlexBindingType int UrlType GxProxyCommandsType GxFacetValuesType boolean SecurityGroupBitsType

Attributes
{rTi:Ad} {rT:Ad} {rT:Ad} {wT:Ad} {wT:Ad} {rwT:Ad} {rwP:Ad}

Security

GxDamper
Table A-30 Tab
Status

GxDamper object properties quick reference. Name

objectType statusFlags isVisible foregroundColor backgroundColor orientation closeValue openValue position size layer hyperlinkOnClick hyperlinkUrl statusColorEnabled flashingEnabled displayUnits highlightCommandable binding boundHandle boundUrl proxyCommands facetValues debugOn securityGroups

Data Species
String StatusFlagsType BooleanStatusType ColorType ColorType GxOrientationEnum float float PointType DimensionType GxLayerEnum GxHyperlinkEnum UrlType boolean boolean GxDisplayUnitsEnum boolean FloatFlexBindingType int UrlType GxProxyCommandsType GxFacetValuesType boolean SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rTi:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {rwP:Ad} {rTi:Ad} {rT:Ad} {rT:Ad} {wT:Ad} {wT:Ad} {rwT:Ad} {rwP:Ad}

Config

Visual

Engineering

Security

GxFan
Table A-31 Tab
Status

GxFan object properties quick reference. Name

objectType statusFlags isVisible foregroundColor backgroundColor centerColor direction position size layer hyperlinkOnClick hyperlinkUrl statusColorEnabled flashingEnabled displayUnits highlightCommandable

Data Species
String StatusFlagsType BooleanStatusType ColorType ColorType ColorType GxDirectionEnum PointType DimensionType GxLayerEnum GxHyperlinkEnum UrlType boolean boolean GxDisplayUnitsEnum boolean

Attributes
{rT:Op} {rT:Op} {rTi:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {rwP:Ad}

Config

Visual

A20

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference GxFloat

Table A-31 Tab

Engineering

GxFan object properties quick reference. (continued) Name

binding boundHandle boundUrl proxyCommands facetValues debugOn securityGroups

Data Species
BooleanFlexBindingType int UrlType GxProxyCommandsType GxFacetValuesType boolean SecurityGroupBitsType

Attributes
{rTi:Ad} {rT:Ad} {rT:Ad} {wT:Ad} {wT:Ad} {rwT:Ad} {rwP:Ad}

Security

GxFloat
Table A-32 Tab
Status

GxFloat object properties quick reference. Name

objectType statusFlags isVisible ranges shape borderColor borderWidth position size layer hyperlinkOnClick hyperlinkUrl statusColorEnabled flashingEnabled displayUnits highlightCommandable binding boundHandle boundUrl proxyCommands facetValues debugOn securityGroups

Data Species
String StatusFlagsType BooleanStatusType GxRangeSetType GxShapeEnum ColorType int PointType DimensionType GxLayerEnum GxHyperlinkEnum UrlType boolean boolean GxDisplayUnitsEnum boolean FloatFlexBindingType int UrlType GxProxyCommandsType GxFacetValuesType boolean SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rTi:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {wP:Ad} {wP:Ad} {rwP:Ad} {rTi:Ad} {rT:Ad} {rT:Ad} {wT:Ad} {wT:Ad} {rwT:Ad} {rwP:Ad}

Config

Visual

Engineering

Security

GxImage
Table A-33 Tab
Status

GxImage object properties quick reference. Name

objectType statusFlags isVisible image borderColor borderWidth position size layer hyperlinkOnClick hyperlinkUrl statusColorEnabled flashingEnabled displayUnits highlightCommandable

Data Species
String StatusFlagsType BooleanStatusType UrlType ColorType int PointType DimensionType GxLayerEnum GxHyperlinkEnum UrlType boolean boolean GxDisplayUnitsEnum boolean

Attributes
{rT:Op} {rT:Op} {rTi:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {wP:Ad} {wP:Ad} {rwP:Ad}

Config

Visual

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A21

Appendix A GxInteger

Object Property Quick Reference

Table A-33 Tab

Engineering

GxImage object properties quick reference. (continued) Name

binding boundHandle boundUrl proxyCommands facetValues debugOn securityGroups

Data Species
FlexBindingType int UrlType GxProxyCommandsType GxFacetValuesType boolean SecurityGroupBitsType

Attributes
{rTi:Ad} {rT:Ad} {rT:Ad} {wT:Ad} {wT:Ad} {rwT:Ad} {rwP:Ad}

Security

GxInteger
Table A-34 Tab
Status

GxInteger object properties quick reference. Name

objectType statusFlags isVisible image borderColor borderWidth position size layer hyperlinkOnClick hyperlinkUrl statusColorEnabled flashingEnabled displayUnits highlightCommandable binding boundHandle boundUrl proxyCommands facetValues debugOn securityGroups

Data Species
String StatusFlagsType BooleanStatusType UrlType ColorType int PointType DimensionType GxLayerEnum GxHyperlinkEnum UrlType boolean boolean GxDisplayUnitsEnum boolean FlexBindingType int UrlType GxProxyCommandsType GxFacetValuesType boolean SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rTi:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {wP:Ad} {wP:Ad} {rwP:Ad} {rTi:Ad} {rT:Ad} {rT:Ad} {wT:Ad} {wT:Ad} {rwT:Ad} {rwP:Ad}

Config

Visual

Engineering

Security

GxPage
Table A-35 Tab
Status

GxPage object properties quick reference. Name

objectType statusFlags description executionParameters foreignAddress membershipGroups typeString displayTypeString alarmText alertText position decimalFormat icon size backgroundColor alarmPageUrl templateUrl

Data Species
String StatusFlagsType String ExecutionParametersType int String String String String String PointType DecimalFormatType UrlType DimensionType ColorType UrlType UrlType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

AlarmSetup Visual

A22

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference GxPipe

Table A-35 Tab

Engineering

GxPage object properties quick reference. (continued) Name

executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData securityGroups

Data Species
TriggerType int int float String SecurityGroupBitsType

Attributes
{Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad}

Security

GxPipe
Table A-36 Tab
Status

GxPipe object properties quick reference. Name

objectType statusFlags isVisible image borderColor borderWidth position size layer hyperlinkOnClick hyperlinkUrl statusColorEnabled flashingEnabled displayUnits highlightCommandable binding boundHandle boundUrl proxyCommands facetValues debugOn securityGroups

Data Species
String StatusFlagsType BooleanStatusType UrlType ColorType int PointType DimensionType GxLayerEnum GxHyperlinkEnum UrlType boolean boolean GxDisplayUnitsEnum boolean FlexBindingType int UrlType GxProxyCommandsType GxFacetValuesType boolean SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rTi:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {wP:Ad} {wP:Ad} {rwP:Ad} {rTi:Ad} {rT:Ad} {rT:Ad} {wT:Ad} {wT:Ad} {rwT:Ad} {rwP:Ad}

Config

Visual

Engineering

Security

GxSpectrum
Table A-37 Tab
Status

GxSpectrum object properties quick reference. Name

objectType statusFlags isVisible lowDeltaColor midDeltaColor highDeltaColor sample midPointDefault valueDelta font displayText position size layer hyperlinkOnClick hyperlinkUrl statusColorEnabled flashingEnabled displayUnits highlightCommandable

Data Species
String StatusFlagsType BooleanStatusType ColorType ColorType ColorType GxSpectrumSampleType float float FontType boolean PointType DimensionType GxLayerEnum GxHyperlinkEnum UrlType boolean boolean GxDisplayUnitsEnum boolean

Attributes
{rT:Op} {rT:Op} {rTi:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {wP:Ad} {rwP:Ad} {rwP:Ad}

Config

Visual

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A23

Appendix A GxText

Object Property Quick Reference

Table A-37 Tab

Engineering

GxSpectrum object properties quick reference. (continued) Name

binding boundHandle boundUrl proxyCommands facetValues debugOn midPointInput securityGroups

Data Species
FloatFlexBindingType int UrlType GxProxyCommandsType GxFacetValuesType boolean FloatFlexBindingType SecurityGroupBitsType

Attributes
{rTi:Ad} {rT:Ad} {rT:Ad} {wT:Ad} {wT:Ad} {rwT:Ad} {rTi:Ad} {rwP:Ad}

Security

GxText
Table A-38 Tab
Status

GxText object properties, quick reference. Name

objectType statusFlags isVisible foregroundColor backgroundColor font text displayBindingText justification borderColor borderWidth position size layer hyperlinkOnClick hyperlinkUrl statusColorEnabled flashingEnabled displayUnits highlightCommandable binding boundHandle boundUrl proxyCommands facetValues debugOn securityGroups

Data Species
String StatusFlagsType BooleanStatusType ColorType ColorType FontType String boolean GxJustificationEnum ColorType int PointType DimensionType GxLayerEnum GxHyperlinkEnum UrlType boolean boolean GxDisplayUnitsEnum boolean FlexBindingType int UrlType GxProxyCommandsType GxFacetValuesType boolean SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rTi:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rTi:Ad} {rT:Ad} {rT:Ad} {wT:Ad} {wT:Ad} {rwT:Ad} {rwP:Ad}

Config

Visual

Engineering

Security

GxTimePlot
Table A-39 Tab
Status

GxTimePlot object properties, quick reference. Name

objectType statusFlags isVisible

Data Species
String StatusFlagsType BooleanStatusType

Attributes
{rT:Op} {rT:Op} {rTi:Ad}

A24

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference IntegerLog

Table A-39 Tab

Config

GxTimePlot object properties, quick reference. (continued) Name

colorA colorB colorC colorD colorBackground colorGrid minValue maxValue visibleDuration displayLegend displayNameA displayNameB displayNameC displayNameD units position size layer bindingA bindingB bindingC bindingD boundNameA boundNameB boundNameC boundNameD securityGroups

Data Species
ColorType ColorType ColorType ColorType ColorType ColorType float float int boolean String String String String EngUnitsEnum PointType DimensionType GxLayerEnum FloatFlexBindingType FloatFlexBindingType FloatFlexBindingType FloatFlexBindingType String String String String SecurityGroupBitsType

Attributes
{rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {Ti:Ad} {Ti:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad}

Visual

Engineering

Security

IntegerLog
Table A-40 Tab
Status

IntegerLog object properties quick reference. Name

objectType statusFlags description lastArchiveTimestamp executionParameters foreignAddress membershipGroups bufferSize stopWhenFull archiveSetup logEnableDefault collectionMode daysOfTheWeek timeRange interval deltaLogging units position chartType chartColor chartTemplateUrl

Data Species
String StatusFlagsType String TimestampType ExecutionParametersType int String int boolean LogArchiveSetupType boolean LogControlNodeCollectionModeEnum DaysOfWeekBitsType TimeRangeType int boolean EngUnitsEnum PointType LogControlNodeChartTypeEnum ColorType UrlType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

Visual

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A25

Appendix A IntToFloat

Object Property Quick Reference

Table A-40 Tab

Engineering

IntegerLog object properties quick reference. (continued) Name

executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData buffer doArchiveTrigger doClearTrigger recordedTrigger archivedTrigger logEnable statusInput lastValue securityGroups

Data Species
TriggerType int int float String LogRecordBufferType TriggerType TriggerType TriggerType TriggerType BooleanStatusType IntegerStatusType int SecurityGroupBitsType

Attributes
{Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {wP:Ad} {Ti:Ad} {Ti:Ad} {To:Ad} {To:Ad} {rTi:Op} {rTi~:Op} {wP:Ad} {rwP:Ad}

Security

IntToFloat
Table A-41 Tab
Status

IntToFloat object properties quick reference. Name

objectType statusFlags description executionParameters foreignAddress membershipGroups defaultIntValue position decimalFormat executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInput statusOutput securityGroups

Data Species
String StatusFlagsType String ExecutionParametersType int String int PointType DecimalFormatType TriggerType int int float String IntegerStatusType FloatStatusType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi~:Op} {rTo~:Op} {rwP:Ad}

Config

Visual Engineering

Security

LogService
Table A-42 Tab
Status

LogService object properties quick reference. Name

objectType statusFlags description logUrlPrefix archiveUrlPrefix archiveMode archiveAddress archiveTime lastDailyArchive minRetryTime maxRetryTime position doArchiveAllTrigger doClearLastDailyArchiveTrigger securityGroups

Data Species
String StatusFlagsType String String String ArchiveModeEnum AddressesType TimeType TimestampType int int PointType TriggerType TriggerType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rP:Ad} {rP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {Ti:Ad} {rwP:Ad}

Config

Visual Engineering Security

A26

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference Logic

Logic
Table A-43 Tab
Status

Logic object properties quick reference. Name

objectType statusFlags description presentValue outOfService reliability executionParameters foreignAddress membershipGroups defaultA defaultB function priorityForWriting trueCommand falseCommand position activeInactiveText executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInputA statusInputB prioritizedOutput statusOutput securityGroups

Data Species
String StatusFlagsType String boolean boolean ReliabilityEnum ExecutionParametersType int String boolean boolean LogicNodeFunctionEnum ControlPriorityEnum BooleanCmdEnum BooleanCmdEnum PointType BooleanEnumTagsType TriggerType int int float String BooleanStatusType BooleanStatusType BooleanPriorityType BooleanStatusType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rTo:Op} {rwP:Op} {rwT:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi~:Op} {rTi~:Op} {rTo~:Op} {rTo~:Op} {rwP:Ad}

Config

Visual Engineering

Security

Loop
Table A-44 Tab
Status

Loop object properties quick reference. Name

objectType statusFlags description eventState reliability outOfService ackedTransitions toOffnormal toFault toNormal presentValue

Data Species
String StatusFlagsType String EventStateEnum ReliabilityEnum boolean EventTransitionBitsType EventTimestampsType EventTimestampsType EventTimestampsType float

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Op} {rwT:Op} {rwP:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rTo:Op}

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A27

Appendix A MailRecipient

Object Property Quick Reference

Table A-44 Tab

Config

Loop object properties quick reference. (continued) Name Data Species

ExecutionParametersType int String float ActionEnum EngUnitsEnum EngUnitsEnum float float float float float float float ControlPriorityEnum float DurationType int EventTransitionBitsType NotifyTypeEnum DurationType EventTransitionBitsType String float float PointType DecimalFormatType TriggerType int int float String BooleanStatusType TriggerType FloatStatusType FloatStatusType FloatPriorityType FloatStatusType ActionEnum TriggerType TriggerType SecurityGroupBitsType

Attributes
{rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi:Op} {To:Ad} {rTi~:Op} {rTi~:Op} {rTo~:Op} {rTo~:Op} {rTi:Op} {To:Ad} {Ti:Ad} {rwP:Ad}

executionParameters foreignAddress membershipGroups defaultSetpoint defaultAction outputUnits controlledVariableUnits proportionalConstant integralConstant maxIntegralGain derivativeConstant bias maximumOutput minimumOutput priorityForWriting covIncrement Alarm Setup timeDelay notificationClass eventEnable notifyType inhibitTime eventTriggerEnable alarmText errorLimit deadband Visual position decimalFormat Engineering executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInhibit eventTrigger controlledVariable setpoint prioritizedOutput statusOutput action covTrigger resetIntegral Security securityGroups

MailRecipient
Table A-45 Tab
Status

MailRecipient object properties quick reference. Name

objectType statusFlags notificationInput validDays timeRange address subject routeAcks alarmFields ackFields alertFields position securityGroups

Data Species
String StatusFlagsType NotificationTriggerType DaysOfWeekBitsType TimeRangeType MailRecipientsType String boolean EventFieldBitsType AckFieldBitsType AlertFieldBitsType PointType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {Ti:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

Visual Security

A28

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference MailService

MailService
Table A-46 Tab
Status

MailService object properties quick reference. Name

objectType statusFlags description enabled smtpHost fromAddress outboxRetryTime username password position debugOn securityGroups

Data Species
String StatusFlagsType String boolean String String int String String PointType boolean SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

Visual Engineering Security

Math
Table A-47 Tab
Status

Math object properties quick reference. Name

objectType statusFlags description presentValue outOfService reliability executionParameters foreignAddress membershipGroups defaultA defaultB defaultC defaultD function units outputHighLimit outputLowLimit priorityForWriting covIncrement inputHighLimit inputLowLimit position decimalFormat executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusOutput prioritizedOutput statusInputA statusInputB statusInputC statusInputD securityGroups

Data Species
String StatusFlagsType String float boolean ReliabilityEnum ExecutionParametersType int String float float float float MathNodeFunctionEnum EngUnitsEnum float float ControlPriorityEnum float float float PointType DecimalFormatType TriggerType int int float String FloatStatusType FloatPriorityType FloatStatusType FloatStatusType FloatStatusType FloatStatusType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Op} {rwP:Op} {rwT:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTo~:Op} {rTo~:Op} {rTi~:Op} {rTi~:Op} {rTi~:Op} {rTi~:Op} {rwP:Ad}

Config

Visual Engineering

Security

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A29

Appendix A MultistateInput

Object Property Quick Reference

MultistateInput
Table A-48 Tab
Status

MultistateInput object properties quick reference. Name

objectType statusFlags description eventState reliability outOfService ackedTransitions toOffnormal toFault toNormal changeOfStateTime changeOfStateCount timeOfStateCountReset elapsedActiveTime timeOfActiveTimeReset changeOfStateAlertFlag activeTimeAlertFlag presentValue executionParameters foreignAddress membershipGroups defaultInput timeDelay notificationClass eventEnable notifyType inhibitTime eventTriggerEnable alarmText changeOfStateAlertLimit activeTimeAlertLimit lastCosCountAlert lastActiveTimeAlert alertNotificationClass periodicAlerts alertText alarmValues faultValues position stateText executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInhibit eventTrigger statusChangeOfStateCount statusElapsedActiveTime resetChangeOfStateCountTrigger resetElapsedActiveTimeTrigger changeOfStateTrigger changeOfStateAlertTrigger elapsedActiveTimeAlertTrigger statusInput statusOutput securityGroups

Data Species
String StatusFlagsType String EventStateEnum ReliabilityEnum boolean EventTransitionBitsType EventTimestampsType EventTimestampsType EventTimestampsType TimestampType int TimestampType DurationType TimestampType boolean boolean int ExecutionParametersType int String int DurationType int EventTransitionBitsType NotifyTypeEnum DurationType EventTransitionBitsType String int DurationType int DurationType int boolean String MultistateBitsType MultistateBitsType PointType IntegerEnumTagsType TriggerType int int float String BooleanStatusType TriggerType IntegerStatusType IntegerStatusType TriggerType TriggerType TriggerType TriggerType TriggerType IntegerStatusType IntegerStatusType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Op} {rwT:Op} {rwP:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rP:Op} {rP:Op} {rP:Op} {rP:Op} {rP:Op} {wP:Ad} {wP:Ad} {rwT:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {wP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi:Op} {To:Ad} {rTo:Op} {rTo:Op} {Ti:Ad} {Ti:Ad} {To:Ad} {To:Ad} {To:Ad} {rTi~:Op} {rTo~:Op} {rwP:Ad}

Config

Alarm Setup

Visual Engineering

Security

A30

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference MultistateLog

MultistateLog
Table A-49 Tab
Status

MultistateLog object properties quick reference. Name

objectType statusFlags description lastArchiveTimestamp executionParameters foreignAddress membershipGroups bufferSize stopWhenFull archiveSetup logEnableDefault collectionMode daysOfTheWeek timeRange interval deltaLogging units position chartType chartColor chartTemplateUrl stateText executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData buffer doArchiveTrigger doClearTrigger recordedTrigger archivedTrigger logEnable statusInput lastValue securityGroups

Data Species
String StatusFlagsType String TimestampType ExecutionParametersType int String int boolean LogArchiveSetupType boolean LogControlNodeCollectionModeEnum DaysOfWeekBitsType TimeRangeType int boolean EngUnitsEnum PointType LogControlNodeChartTypeEnum ColorType UrlType IntegerEnumTagsType TriggerType int int float String LogRecordBufferType TriggerType TriggerType TriggerType TriggerType BooleanStatusType IntegerStatusType int SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {wP:Ad} {rwP:Ad} {rP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {wP:Ad} {Ti:Ad} {Ti:Ad} {To:Ad} {To:Ad} {rTi:Op} {rTi~:Op} {wP:Ad} {rwP:Ad}

Config

Visual

Engineering

Security

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A31

Appendix A MultistateOutput

Object Property Quick Reference

MultistateOutput
Table A-50 Tab
Status

MultistateOutput object properties quick reference. Name

objectType statusFlags description eventState reliability outOfService ackedTransitions toOffnormal toFault toNormal changeOfStateTime changeOfStateCount timeOfStateCountReset elapsedActiveTime timeOfActiveTimeReset changeOfStateAlertFlag activeTimeAlertFlag presentValue priorityArray relinquishDefault inInterstartDelay executionParameters foreignAddress membershipGroups restartDisable minimumOnTime minimumOffTime perStateMinimumOnTime interstartDelayTime timeDelay notificationClass eventEnable notifyType inhibitTime eventTriggerEnable alarmText changeOfStateAlertLimit activeTimeAlertLimit lastCosCountAlert lastActiveTimeAlert alertNotificationClass periodicAlerts alertText position stateText commandTags

Data Species
String StatusFlagsType String EventStateEnum ReliabilityEnum boolean EventTransitionBitsType EventTimestampsType EventTimestampsType EventTimestampsType TimestampType int TimestampType DurationType TimestampType boolean boolean int IntegerPriorityArrayType int boolean ExecutionParametersType int String boolean DurationType DurationType boolean DurationType DurationType int EventTransitionBitsType NotifyTypeEnum DurationType EventTransitionBitsType String int DurationType int DurationType int boolean String PointType IntegerEnumTagsType IntegerCommandTagsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Op} {rwT:Op} {rwP:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rP:Op} {rP:Op} {rP:Op} {rP:Op} {rP:Op} {wP:Ad} {wP:Ad} {rTo:Op} {rTi~:Op} {rwP:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {wP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Priorities

Config

Alarm Setup

Visual

A32

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference MultistateOverride

Table A-50 Tab

Engineering

MultistateOutput object properties quick reference. (continued) Name

executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInhibit eventTrigger statusChangeOfStateCount statusElapsedActiveTime resetChangeOfStateCountTrigger resetElapsedActiveTimeTrigger changeOfStateTrigger changeOfStateAlertTrigger elapsedActiveTimeAlertTrigger statusInput statusOutput manualCommand emergencyCommand prioritizedOutput statusFeedbackOutput booleanStatusFeedbackOutput securityGroups

Data Species
TriggerType int int float String BooleanStatusType TriggerType IntegerStatusType IntegerStatusType TriggerType TriggerType TriggerType TriggerType TriggerType IntegerStatusType IntegerStatusType IntegerPriorityType IntegerPriorityType IntegerPriorityType IntegerStatusType BooleanStatusType SecurityGroupBitsType

Attributes
{Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi:Op} {To:Ad} {rTo:Op} {rTo:Op} {Ti:Ad} {Ti:Ad} {To:Ad} {To:Ad} {To:Ad} {rTi~:Op} {rTo~:Op} {wP:Ad} {wP:Ad} {rTo~:Op} {rTo:Op} {rTo:Op} {rwP:Ad}

Security

MultistateOverride
Table A-51 Tab
Status

MultistateOverride object properties quick reference. Name

objectType statusFlags description inOverride executionParameters foreignAddress membershipGroups priorityForWriting overrideTime overrideValue position stateText minExecuteTime maxExecuteTime averageExecuteTime userData statusInOverride prioritizedOutput securityGroups

Data Species
String StatusFlagsType String boolean ExecutionParametersType int String ControlPriorityEnum int int PointType IntegerEnumTagsType int int float String BooleanStatusType IntegerPriorityType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rTo:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTo~:Op} {rTo~:Op} {rwP:Ad}

Config

Visual Engineering

Security

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A33

Appendix A Ndio0to10VInput

Object Property Quick Reference

Ndio0to10VInput
Table A-52 Tab
Status

Ndio0to10VInput object properties, quick reference. Name

objectType statusFlags description eventState reliability outOfService ackedTransitions toOffnormal toFault toNormal presentValue syncFlag executionParameters foreignAddress membershipGroups units covIncrement ioIndex linearization timeDelay notificationClass eventEnable notifyType inhibitTime eventTriggerEnable alarmText minPresentValue maxPresentValue highLimit lowLimit deadband limitEnable position decimalFormat executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInhibit eventTrigger covTrigger statusOutput securityGroups

Data Species
String StatusFlagsType String EventStateEnum ReliabilityEnum boolean EventTransitionBitsType EventTimestampsType EventTimestampsType EventTimestampsType float boolean ExecutionParametersType int String EngUnitsEnum float int NdioLinearizationTableType DurationType int EventTransitionBitsType NotifyTypeEnum DurationType EventTransitionBitsType String float float float float float LimitEnableBitsType PointType DecimalFormatType TriggerType int int float String BooleanStatusType TriggerType TriggerType FloatStatusType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Op} {rwT:Op} {rwP:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rwT:Op} {rT:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi:Op} {To:Ad} {To:Ad} {rTo~:Op} {rwP:Ad}

Config

Alarm Setup

Visual Engineering

Security

A34

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference Ndio0to10VOutput

Ndio0to10VOutput
Table A-53 Tab
Status

Ndio0to10VOutput object properties quick reference. Name Data Species

String StatusFlagsType String EventStateEnum ReliabilityEnum boolean EventTransitionBitsType EventTimestampsType EventTimestampsType EventTimestampsType float FloatPriorityArrayType float ExecutionParametersType int String EngUnitsEnum float int float NdioLinearizationTableType DurationType int EventTransitionBitsType NotifyTypeEnum DurationType EventTransitionBitsType String float float float float float LimitEnableBitsType PointType DecimalFormatType FloatCommandTagsType TriggerType int int float String BooleanStatusType TriggerType TriggerType FloatStatusType FloatStatusType FloatStatusType FloatPriorityType FloatPriorityType FloatPriorityType FloatStatusType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Op} {rwT:Op} {rwP:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rTo:Op} {rTi~:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi:Op} {To:Ad} {To:Ad} {rTi~:Op} {rTo~:Op} {rTo~:Op} {wP:Ad} {wP:Ad} {rTo~:Op} {rTo:Op} {rwP:Ad}

objectType statusFlags description eventState reliability outOfService ackedTransitions toOffnormal toFault toNormal presentValue Priorities priorityArray relinquishDefault Config executionParameters foreignAddress membershipGroups units covIncrement ioIndex offset linearization Alarm Setup timeDelay notificationClas eventEnable notifyType inhibitTime eventTriggerEnable alarmText minPresentValue maxPresentValue highLimit lowLimit deadband limitEnable Visual position decimalFormat commandTags Engineering executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInhibit eventTrigger covTrigger statusInput statusOutput statusOutput manualSetpoint emergencylSetpoint prioritizedOutput statusFeedbackOutput Security securityGroups

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A35

Appendix A NdioBinaryInput

Object Property Quick Reference

NdioBinaryInput
Table A-54 Tab
Status

NdioBinaryInput object properties quick reference. Name

objectType statusFlags description eventState reliability outOfService ackedTransitions toOffnormal toFault toNormal changeOfStateTime changeOfStateCount timeOfStateCountReset elapsedActiveTime timeOfActiveTimeReset changeOfStateAlertFlag activeTimeAlertFlag presentValue syncFlag executionParameters foreignAddress membershipGroups ioIndex polarity timeDelay notificationClass eventEnable notifyType inhibitTime eventTriggerEnable alarmText changeOfStateAlertLimit activeTimeAlertLimit lastCosCountAlert lastActiveTimeAlert alertNotificationClass periodicAlerts alertText alarmValue alarmValueEnabled position activeInactiveText executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInhibit eventTrigger statusChangeOfStateCount statusElapsedActiveTime resetChangeOfStateCountTrigger resetElapsedActiveTimeTrigger changeOfStateTrigger changeOfStateAlertTrigger elapsedActiveTimeAlertTrigger statusOutput securityGroups

Data Species
String StatusFlagsType String EventStateEnum ReliabilityEnum boolean EventTransitionBitsType EventTimestampsType EventTimestampsType EventTimestampsType TimestampType int TimestampType DurationType TimestampType boolean boolean boolean boolean ExecutionParametersType int String int PolarityEnum DurationType int EventTransitionBitsType NotifyTypeEnum DurationType EventTransitionBitsType String int DurationType int DurationType int boolean String boolean boolean PointType BooleanEnumTagsType TriggerType int int float String BooleanStatusType TriggerType IntegerStatusType IntegerStatusType TriggerType TriggerType TriggerType TriggerType TriggerType BooleanStatusType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Op} {rwT:Op} {rwP:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rP:Op} {rP:Op} {rP:Op} {rP:Op} {rP:Op} {wP:Ad} {wP:Ad} {rwT:Op} {rT:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {wP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi:Op} {To:Ad} {rTo:Op} {rTo:Op} {Ti:Ad} {Ti:Ad} {To:Ad} {To:Ad} {To:Ad} {rTo~:Op} {rwP:Ad}

Config

Alarm Setup

Visual Engineering

Security

A36

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference NdioBinaryOutput

NdioBinaryOutput
Table A-55 Tab
Status

NdioBinaryOutput object properties quick reference. Name

objectType statusFlags description eventState reliability outOfService ackedTransitions toOffnormal toFault toNormal changeOfStateTime changeOfStateCount timeOfStateCountReset elapsedActiveTime timeOfActiveTimeReset presentValue priorityArray relinquishDefault inInterstartDelay executionParameters foreignAddress membershipGroups ioIndex polarity minimumOnTime minimumOffTime restartDisable interstartDelayTime timeDelay notificationClass eventEnable notifyType inhibitTime eventTriggerEnable alarmText changeOfStateAlertLimit activeTimeAlertLimit alertNotificationClass periodicAlerts alertText position activeInactiveText commandTags

Data Species
String StatusFlagsType String EventStateEnum ReliabilityEnum boolean EventTransitionBitsType EventTimestampsType EventTimestampsType EventTimestampsType TimestampType int TimestampType DurationType TimestampType boolean BooleanPriorityArrayType boolean boolean ExecutionParametersType int String int PolarityEnum DurationType DurationType boolean DurationType DurationType int EventTransitionBitsType NotifyTypeEnum DurationType EventTransitionBitsType String int DurationType int boolean String PointType BooleanEnumTagsType BooleanCommandTagsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Op} {rwT:Op} {rwP:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rP:Op} {rP:Op} {rP:Op} {rP:Op} {rP:Op} {rwT:Op} {rTi~:Op} {rwP:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Priorities

Config

Alarm Setup

Visual

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A37

Appendix A NdioContainer

Object Property Quick Reference

Table A-55 Tab

Engineering

NdioBinaryOutput object properties quick reference. (continued) Name

executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInhibit eventTrigger statusChangeOfStateCount statusElapsedActiveTime resetChangeOfStateCountTrigger resetElapsedActiveTimeTrigger changeOfStateTrigger changeOfStateAlertTrigger elapsedActiveTimeAlertTrigger statusInput statusOutput prioritizedOutput statusFeedbackOutput securityGroups

Data Species
TriggerType int int float String BooleanStatusType TriggerType IntegerStatusType IntegerStatusType TriggerType TriggerType TriggerType TriggerType TriggerType BooleanStatusType BooleanStatusType BooleanPriorityType BooleanStatusType SecurityGroupBitsType

Attributes
{Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi:Op} {To:Ad} {rTo:Op} {rTo:Op} {Ti:Ad} {Ti:Ad} {To:Ad} {To:Ad} {To:Ad} {rTi~:Op} {rTo~:Op} {rTo~:Op} {rTo:Op} {rwP:Ad}

Security

NdioContainer
Table A-56 Tab
Status Config AlarmSetup Visual

NdioContainer object properties quick reference. Name

objectType statusFlags description alarmText alertText position icon size backgroundColor alarmPageUrl debug verbose securityGroups

Data Species
String StatusFlagsType String String String PointType UrlType DimensionType ColorType UrlType boolean boolean SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Op} {rwP:Op} {rwP:Ad}

Engineering Security

NdioHighSpeedCounterInput
Table A-57 Tab
Status

NdioHighSpeedCounterInput object properties, quick reference. Name

objectType statusFlags description reliability outOfService presentValue syncFlag

Data Species
String StatusFlagsType String ReliabilityEnum boolean float boolean

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwT:Op} {rwP:Op} {rwT:Op} {rT:Ad}

A38

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference NdioResistiveInput

Table A-57 Tab

Config

NdioHighSpeedCounterInput object properties, quick reference. Name

executionParameters foreignAddress membershipGroups units ioIndex countScale rateHistory rateInterval rateScale rateUnits position decimalFormat executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData rawOutput countOutput bootAdjust totalOutput rateOutput securityGroups

Data Species
ExecutionParametersType int String EngUnitsEnum int float int int float EngUnitsEnum PointType DecimalFormatType TriggerType int int float String long long long FloatStatusType FloatStatusType SecurityGroupBitsType

Attributes
{rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rPo:Op} {rPo:Op} {rPo:Ad} {rTo~:Op} {rTo:Op} {rwP:Ad}

Visual Engineering

Security

NdioResistiveInput
Table A-58 Tab
Status

NdioResistiveInput object properties, quick reference. Name

objectType statusFlags description eventState reliability outOfService ackedTransitions toOffnormal toFault toNormal presentValue syncFlag executionParameters foreignAddress membershipGroups units covIncrement ioIndex linearization timeDelay notificationClass eventEnable notifyType inhibitTime eventTriggerEnable alarmText minPresentValue maxPresentValue highLimit lowLimit deadband limitEnable

Data Species
String StatusFlagsType String EventStateEnum ReliabilityEnum boolean EventTransitionBitsType EventTimestampsType EventTimestampsType EventTimestampsType float boolean ExecutionParametersType int String EngUnitsEnum float int NdioLinearizationTableType DurationType int EventTransitionBitsType NotifyTypeEnum DurationType EventTransitionBitsType String float float float float float LimitEnableBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Op} {rwT:Op} {rwP:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rwT:Op} {rT:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

Alarm Setup

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A39

Appendix A NdioProcessor

Object Property Quick Reference

Table A-58 Tab

Visual Engineering

NdioResistiveInput object properties, quick reference. (continued) Name

position decimalFormat executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInhibit eventTrigger covTrigger statusOutput securityGroups

Data Species
PointType DecimalFormatType TriggerType int int float String BooleanStatusType TriggerType TriggerType FloatStatusType SecurityGroupBitsType

Attributes
{rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi:Op} {To:Ad} {To:Ad} {rTo~:Op} {rwP:Ad}

Security

NdioProcessor
Table A-59 Type
General

NdioProcessor object properties quick reference. Tab

Status Config

Name
objectType statusFlags description procEnable procNum alarmText alertText position icon size backgroundColor alarmPageUrl securityGroups deviceStatusAverageExecuteTime deviceStatusTotalExecuteTime deviceStatusExecuteCycles deviceStatusObjectCount deviceStatusStartTime deviceStatusPingDelay deviceStatusDisplayDots deviceStatusDisabled notificationClass

Data Species
String StatusFlagsType String boolean NdioProcessorEnum String String PointType UrlType DimensionType ColorType UrlType SecurityGroupBitsType PointType int int int String int boolean boolean int

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwT:Ad} {rwT:Ad} {rwT:Ad} {rwT:Ad} {rwT:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

AlarmSetup Visual

Security DeviceStatus Status

Config

AlarmSetup

NdioThermistorType3Input
Table A-60 Tab
Status

NdioThermistorType3Input object properties, quick reference. Name

objectType statusFlags description eventState reliability outOfService ackedTransitions toOffnormal toFault toNormal presentValue syncFlag

Data Species
String StatusFlagsType String EventStateEnum ReliabilityEnum boolean EventTransitionBitsType EventTimestampsType EventTimestampsType EventTimestampsType float boolean

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Op} {rwT:Op} {rwP:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rwT:Op} {rT:Ad}

A40

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference NotificationClass

Table A-60 Tab

Config

NdioThermistorType3Input object properties, quick reference. Name

executionParameters foreignAddress membershipGroups units covIncrement ioIndex linearization offset tempUnits timeDelay notificationClass eventEnable notifyType inhibitTime eventTriggerEnable alarmText minPresentValue maxPresentValue highLimit lowLimit deadband limitEnable position decimalFormat executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInhibit eventTrigger covTrigger statusOutput securityGroups

Data Species
ExecutionParametersType int String EngUnitsEnum float int NdioLinearizationTableType float NdioTempUnitsEnum DurationType int EventTransitionBitsType NotifyTypeEnum DurationType EventTransitionBitsType String float float float float float LimitEnableBitsType PointType DecimalFormatType TriggerType int int float String BooleanStatusType TriggerType TriggerType FloatStatusType SecurityGroupBitsType

Attributes
{rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi:Op} {To:Ad} {To:Ad} {rTo~:Op} {rwP:Ad}

Alarm Setup

Visual Engineering

Security

NotificationClass
Table A-61 Tab
Status

NotificationClass object properties quick reference. Name

objectType statusFlags description notificationClass ackRequired eventPriorities position notificationOutput masterOut slaveIn securityGroups

Data Species
String StatusFlagsType String int EventTransitionBitsType EventPrioritiesType PointType NotificationTriggerType SlaveSyncType SlaveSyncType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {To:Ad} {rTo:Ad} {rTi:Ad} {rwP:Ad}

Config

Visual Engineering

Security

NotificationService
Table A-62 Tab
Status

NotificationService object properties quick reference. Name

objectType statusFlags description

Data Species
String StatusFlagsType String

Attributes
{rT:Op} {rT:Op} {rwP:Op}

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A41

Appendix A PeriodicTrigger

Object Property Quick Reference

Table A-62 Tab

Config Visual Engineering

NotificationService object properties quick reference. (continued) Name

alarmArchiveAddress archiveMode position debug unackedEventTable eventHistoryTable unackedAlertTable alertHistoryTable securityGroups

Data Species
AddressesType NotificationArchiveEnum PointType boolean DxSetType DxSetType DxSetType DxSetType SecurityGroupBitsType

Attributes
{rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {wP:Ad} {wP:Ad} {wP:Ad} {rwP:Ad}

Security

PeriodicTrigger
Table A-63 Tab
Status

PeriodicTrigger object properties quick reference. Name

objectType statusFlags description executionParameters foreignAddress membershipGroups triggerPeriod position executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData trigger securityGroups

Data Species
String StatusFlagsType String ExecutionParametersType int String DurationType PointType TriggerType int int float String TriggerType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {To:Ad} {rwP:Ad}

Config

Visual Engineering

Security

PollAlways
Table A-64 Tab
Status Config AlarmSetup Visual

PollAlways object properties quick reference. Name

objectType statusFlags description alarmText alertText position icon size backgroundColor alarmPageUrl securityGroups

Data Species
String StatusFlagsType String String String PointType UrlType DimensionType ColorType UrlType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Security

PollArchiveService
Table A-65 Tab
Status

PollArchiveService object properties, quick reference. Name

objectType statusFlags description

Data Species
String StatusFlagsType String

Attributes
{rT:Op} {rT:Op} {rwP:Op}

A42

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference PollOnDemand

Table A-65 Tab

Config

PollArchiveService object properties, quick reference. (continued) Name

group0 group1 group2 group3 group4 group5 group6 group7 position pollGroup0Trigger pollGroup1Trigger pollGroup2Trigger pollGroup3Trigger pollGroup4Trigger pollGroup5Trigger pollGroup6Trigger pollGroup7Trigger debugOn securityGroups

Data Species
PollArchiveGroupType PollArchiveGroupType PollArchiveGroupType PollArchiveGroupType PollArchiveGroupType PollArchiveGroupType PollArchiveGroupType PollArchiveGroupType PointType TriggerType TriggerType TriggerType TriggerType TriggerType TriggerType TriggerType TriggerType boolean SecurityGroupBitsType

Attributes
{rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {Ti:Ad} {Ti:Ad} {Ti:Ad} {Ti:Ad} {Ti:Ad} {Ti:Ad} {Ti:Ad} {rwP:Ad} {rwP:Ad}

Visual Engineering

Security

PollOnDemand
Table A-66 Tab
Status Config AlarmSetup Visual

PollOnDemand object properties quick reference. Name

objectType statusFlags description alarmText alertText position icon size backgroundColor alarmPageUrl securityGroups

Data Species
String StatusFlagsType String String String PointType UrlType DimensionType ColorType UrlType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Security

PrinterRecipient
Table A-67 Tab
Status

PrinterRecipient object properties quick reference. Name

objectType statusFlags notificationInput validDays timeRange routeAcks printerName alertNotificationClass position securityGroups

Data Species
String StatusFlagsType NotificationTriggerType DaysOfWeekBitsType TimeRangeType boolean PrinterNameType int PointType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {Ti:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

AlarmSetup Visual Security

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A43

Appendix A Program

Object Property Quick Reference

Program
Table A-68 Tab
Status

Program object quick reference. Name

objectType statusFlags description executionParameters foreignAddress membershipGroups typeString displayTypeString position decimalFormat icon executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData sourceCode classFile inDebugSession securityGroups

Data Species
String StatusFlagsType String ExecutionParametersType int String String String PointType DecimalFormatType UrlType TriggerType int int float String String byte[ ] boolean SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {wP:Ad} {wP:Ad} {rT:Ad} {rwP:Ad}

Config

Visual

Engineering

Security

RemotePrinterRecipient
Table A-69 Tab
Status

RemotePrinterRecipient object properties quick reference. Name

objectType statusFlags notificationInput validDays timeRange routeAcks printerName alertNotificationClass position securityGroups

Data Species
String StatusFlagsType NotificationTriggerType DaysOfWeekBitsType TimeRangeType boolean PrinterNameType int PointType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {Ti:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

AlarmSetup Visual Security

Schedule
Table A-70 Tab
Status

Schedule object properties quick reference. Name

objectType statusFlags description isActive overrideIn holidayOverride nextEventTime nextEventValue activeSchedule

Data Species
String StatusFlagsType String boolean BooleanPriorityType BooleanStatusType DateTimeType BooleanStatusType DailyRefType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rTo:Op} {rTi:Op} {rTi~:Op} {rTo:Op} {rTo:Op} {T:Op}

A44

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference ServiceContainer

Table A-70 Tab

Config

Schedule object properties quick reference. (continued) Name

executionParameters foreignAddress membershipGroups priorityForWriting effectivePeriod activeInactiveText sunday monday tuesday wednesday thursday friday saturday specialEvents holidaySchedule specialCleanup trueCommand falseCommand position activeColor inactiveColor templateUrl executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData holidayOverrideDefault statusOutput prioritizedOutput covTrigger onActiveTrigger onInactiveTrigger masterOut slaveIn securityGroups

Data Species
ExecutionParametersType int String ControlPriorityEnum DateRangeType BooleanEnumTagsType DailyScheduleType DailyScheduleType DailyScheduleType DailyScheduleType DailyScheduleType DailyScheduleType DailyScheduleType SpecialEventListType SpecialEventType int BooleanCmdEnum BooleanCmdEnum PointType ColorType ColorType UrlType TriggerType int int float String boolean BooleanStatusType BooleanPriorityType TriggerType TriggerType TriggerType SlaveSyncType SlaveSyncType SecurityGroupBitsType

Attributes
{rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {wP:Ad} {wP:Ad} {wP:Ad} {wP:Ad} {wP:Ad} {wP:Ad} {wP:Ad} {wP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad} {rTo~:Op} {rTo~:Op} {To:Ad} {To:Ad} {To:Ad} {rTo:Ad} {rTi:Ad} {rwP:Ad}

Visual

Engineering

Security

ServiceContainer
Table A-71 Tab
Status Config Visual Security

ServiceContainer object properties quick reference. Name

objectType statusFlags description position securityGroups

Data Species
String StatusFlagsType String PointType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A45

Appendix A Station

Object Property Quick Reference

Station
Table A-72 Tab
Status

Station object properties quick reference. Name

objectType statusFlags description currentTime bootTime lastDownTime lastAliveTime activeUserChange isRunning osArch osName osVersion javaVendor javaVersion release addressBook httpPort httpsPort enableSSL authenticationType defaultPage pstoreFlushTime snsBackupTime interstationSendTime membershipGroups announcementTTL enableAnnouncement minAnnouncementFreq maxAnnouncementFreq alarmText alertText notificationClass position alarmPageUrl userList nextHandle securityGroups strongPasswords

Data Species
String StatusFlagsType String DateTimeType TimestampType TimestampType TimestampType boolean boolean String String String String String String AddressBookType int int boolean StationAuthenticationEnum UrlType int int int String int boolean int int String String int PointType UrlType UserListType int SecurityGroupBitsType boolean

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwT:Ad} {rT:Ad} {rT:Ad} {rP:Ad} {T:Ad} {rT:Ad} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {rT:Op} {wP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {P:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {rP:Ad} {rwP:Ad} {rwP:Ad}

Config

AlarmSetup

Visual Engineering Security

StringLog
Table A-73 Tab
Status

StringLog object properties quick reference. Name

objectType statusFlags description lastArchiveTimestamp

Data Species
String StatusFlagsType String TimestampType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rP:Op}

A46

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference TimeSyncService

Table A-73 Tab

Config

StringLog object properties quick reference. (continued) Name

executionParameters foreignAddress membershipGroups bufferSize stopWhenFull archiveSetup logEnableDefault collectionMode daysOfTheWeek timeRange interval position chartType chartColor chartTemplateUrl executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData buffer doArchiveTrigger doClearTrigger recordedTrigger archivedTrigger logEnable input securityGroups

Data Species
ExecutionParametersType int String int boolean LogArchiveSetupType boolean LogControlNodeCollectionModeEnum DaysOfWeekBitsType TimeRangeType int PointType LogControlNodeChartTypeEnum ColorType UrlType TriggerType int int float String LogRecordBufferType TriggerType TriggerType TriggerType TriggerType BooleanStatusType FlexBindingType SecurityGroupBitsType

Attributes
{rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {wP:Ad} {wP:Ad} {wP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {wP:Ad} {Ti:Ad} {Ti:Ad} {To:Ad} {To:Ad} {rTi:Op} {rTi~:Op} {rwP:Ad}

Visual

Engineering

Security

TimeSyncService
Table A-74 Tab
Status

TimeSyncService object properties quick reference. Name

objectType statusFlags description serverReport1 serverReport2 serverReport3 serverEnabled serverPort clientEnabled clientPollFrequency clientResetTolerance timeProtocolServer1 timeProtocolServer2 timeProtocolServer3 position debugOn securityGroups

Data Species
String StatusFlagsType String String String String boolean int boolean int int TimeSyncServerType TimeSyncServerType TimeSyncServerType PointType boolean SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config

Visual Engineering Security

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A47

Appendix A Totalizer

Object Property Quick Reference

Totalizer
Table A-75 Tab
Status

Totalizer object properties quick reference. Name

objectType statusFlags description presentValue persistentValue executionParameters foreignAddress membershipGroups defaultInput units totalizationInterval startTime position decimalFormat executeTrigger minExecuteTime maxExecuteTime averageExecuteTime userData statusInput statusTotal resetTotalTrigger updateOutputTrigger securityGroups

Data Species
String StatusFlagsType String float float ExecutionParametersType int String float EngUnitsEnum TotalizerNodeIntervalEnum TimestampType PointType DecimalFormatType TriggerType int int float String FloatStatusType FloatStatusType TriggerType TriggerType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rwT:Op} {wP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rP:Ad} {rwP:Ad} {rwP:Ad} {Ti:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rTi~:Op} {rTo~:Op} {Ti:Ad} {To:Ad} {rwP:Ad}

Config

Visual Engineering

Security

UiEngineService
Table A-76 Tab
Status

UiEngineService object properties quick reference. Name

objectType statusFlags description averageExecuteTime totalExecuteTime executionCycles overruns objectCount startTime averageInterCycleDelay lateStarts cycleTime displayDots position securityGroups

Data Species
String StatusFlagsType String float int int int int String float int int boolean PointType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config Visual Security

VasRecipient
Table A-77 Tab
Status

VasRecipient object properties quick reference. Name

objectType statusFlags notificationInput validDays timeRange

Data Species
String StatusFlagsType NotificationTriggerType DaysOfWeekBitsType TimeRangeType

Attributes
{rT:Op} {rT:Op} {Ti:Ad} {rwP:Ad} {rwP:Ad}

Config

A48

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference Property Quick References

Table A-77 Tab

Visual Security

VasRecipient object properties quick reference. (continued) Name

position securityGroups

Data Species
PointType SecurityGroupBitsType

Attributes
{rwP:Ad} {rwP:Ad}

WebUiService
Table A-78 Tab
Status

WebUiService object properties quick reference. Name

objectType statusFlags description averageExecuteTime totalExecuteTime executionCycles overruns objectCount startTime averageInterCycleDelay lateStarts cycleTime displayDots position securityGroups

Data Species
String StatusFlagsType String float int int int int String float int int boolean PointType SecurityGroupBitsType

Attributes
{rT:Op} {rT:Op} {rwP:Op} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rT:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad} {rwP:Ad}

Config Visual Security

Variable Types
Variable types used by standard Niagara objects include the following:
boolean BooleanPriorityType BooleanStatusType BooleanTriggerType DateRangeType DateTimeType DateType DimensionType DurationType EventPrioritiesType EventTimestampsType EventTransitionBitsType float FloatPriorityType FloatStatusType FloatTriggerType int IntegerPriorityType IntegerStatusType IntegerTriggerType LimitEnableBitsType MailRecipientsType NotificationTriggerType PointType ScaleOffsetType StatusFlagsType String TimeRangeType TimestampType TimeSyncServerType TimeType TriggerType

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A49

Appendix A Property Quick References

Object Property Quick Reference

boolean
primitive

BooleanPriorityType
value auto priority rw boolean rw boolean rw ControlPriorityEnum

BooleanStatusType
status value rw StatusFlagsType rw boolean

BooleanTriggerType
value rw boolean

DateRangeType
startDate endDate rw rw DateType DateType

DateTimeType
date time year month day weekday hour minute second nextDay prevDay rw rw rw rw rw rw rw rw rw r r DateType TimeType int MonthEnum int WeekdayEnum int int int DateTimeType DateTimeType

DateType
year month day weekday nextDay prevDay rw rw rw rw r r int MonthEnum int WeekdayEnum DateType DateType

DimensionType
width height rw rw int int

DurationType
duration rw int

A50

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference Property Quick References

EventPrioritiesType
toOffnormalPriority toFaultPriority toNormalPriority rw rw rw int int int

EventTimestampsType
eventTime ackTime count rw rw rw TimestampType TimestampType int

EventTransitionBitsType
toOffnormal toFault toNormal rw rw rw boolean boolean boolean

float
primitive

FloatPriorityType
value auto priority rw rw rw float boolean ControlPriorityEnum

FloatStatusType
status value rw rw StatusFlagsType float

FloatTriggerType
value rw float

int
primitive

IntegerPriorityType
value auto priority rw rw rw int boolean ControlPriorityEnum

IntegerStatusType
status value rw rw StatusFlagsType int

IntegerTriggerType
value rw int

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A51

Appendix A Property Quick References

Object Property Quick Reference

LimitEnableBitsType
lowLimitEnabled highLimitEnabled rw rw boolean boolean

MailRecipientsType
toList ccList bccList rw rw rw String String String

NotificationTriggerType

PointType
x y rw rw int int

ScaleOffsetType
scale offset rw rw float float

StatusFlagsType
inAlarm fault overridden outOfService unackedAlarm down rw rw rw rw rw r boolean boolean boolean boolean boolean boolean

String
primitive

TimeRangeType
startTime endTime exclusive rw rw rw TimeType TimeType boolean

TimestampType
dateTime rw DateTimeType

TimeSyncServerType
useSupervisor hostName rw rw boolean String

TimeType
hour minute rw rw int int

A52

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference Property Quick References

second hundredth

rw rw

int int

TriggerType

Enumerations
Enumeration types used by standard Niagara objects include the following:
ActionEnum AlertTypeEnum GxEndpointEnum GxHyperlinkEnum

AnalogLogNodeOutputFunctionEnum GxJustificationEnum ArchiveModeEnum BooleanCmdEnum CommDataBitsEnum CommFlowControlEnum CommParityEnum CommStopBitsEnum ComparisonNodeFunctionEnum ControlPriorityEnum DatabaseTypeEnum EngUnitsEnum EventStateEnum EventTypeEnum ExecutionFrequencyEnum ExecutionOrderEnum FunctionGeneratorNodeModeEnum GxBooleanKeyEnum GxDirectionEnum GxDisplayUnitsEnum GxLayerEnum GxOrientationEnum GxShapeEnum LogControlNodeChartTypeEnum LogControlNodeCollectionModeEnum LogicNodeFunctionEnum MathNodeFunctionEnum MonthEnum NotificationArchiveEnum NotifyTypeEnum PolarityEnum PollArchiveEnum ReliabilityEnum StationAlarmEnum StationAuthenticationEnum TotalizerNodeIntervalEnum WeekdayEnum

ActionEnum
0 1 direct reverse

AlertTypeEnum
0 1 2 changeOfStateCount runtime equipmentFailure

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A53

Appendix A Property Quick References

Object Property Quick Reference

AnalogLogNodeOutputFunctionEnum
0 1 2 3 4 current minimum maximum average sum

ArchiveModeEnum
0 1 2 archive_disabled archive_local archive_remote

BooleanCmdEnum
0 1 2 true false auto

CommDataBitsEnum
5 6 7 8 dataBits_5 dataBits_6 dataBits_7 dataBits_8

CommFlowControlEnum
0 1 2 4 8 none RtsCtsOnInput RtsCtsOnOutput XonXoffOnInput XonXoffOnOutput

CommParityEnum
2 3 1 0 4 even mark odd none space

CommStopBitsEnum
1 3 2 stopBit_1 stopBits_1_5 stopBits_2

ComparisonNodeFunctionEnum
0 1 2 3 4 5 A_GT_B A_GTE_B A_EQU_B A_LT_B A_LTE_B A_NE_B

A54

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference Property Quick References

ControlPriorityEnum
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 level_1 level_2 level_3 level_4 level_5 level_6 level_7 level_8 level_9 level_10 level_11 level_12 level_13 level_14 level_15 level_16

DatabaseTypeEnum
0 1 2 3 Cloudscape MSDE MS_SQL_Server Oracle

EngUnitsEnum
EngUnitsEnum (also see About Units, page 5-6)
0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 square_meters square_feet milliamperes amperes ohms volts kilovolts megavolts volt_amperes kilovolt_amperes megavolt_amperes volt_amperes_reactive kilovolt_amperes_reactive megavolt_amperes_reactive degrees_phase power_factor joules kilojoules watt_hours kilowatt_hours btus therms ton_hours joules_per_kilogram_dry_air btus_per_pound_dry_air cycles_per_hour cycles_per_minute hertz grams_of_water_per_kilogram_dry_air percent_relative_humidity millimeters meters inches 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 centimeters_of_water inches_of_water millimeters_of_mercury centimeters_of_mercury inches_of_mercury degrees_Celsius degrees_Kelvin degrees_Fahrenheit degree_days_Celsius degree_days_Fahrenheit years months weeks days hours minutes seconds meters_per_second kilometers_per_hour feet_per_second feet_per_minute miles_per_hour cubic_feet cubic_meters imperial_gallons liters us_gallons cubic_feet_per_minute cubic_meters_per_second imperial_gallons_per_minute liters_per_second liters_per_minute us_gallons_per_minute 114 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 256 257 258 259 260 261 262 263 264 265 266 267 currency10 kilohms megohms millivolts kilojoules_per_kilogram megajoules joules_per_degree_Kelvin joules_per_kilogram_degree_Kelvin kilohertz megahertz per_hour milliwatts hectopascals millibars cubic_meters_per_hour liters_per_hour kilowatt_hours_per_square_meter kilowatt_hours_per_square_foot megajoules_per_square_meter megajoules_per_square_foot watts_per_square_meter_degree_Kelvin milliseconds kilograms_per_cubic_meter Kbtus Mbtus radians_per_sec decibels grams milligrams metric_tons milliliters kiloliters micrometers

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A55

Appendix A Property Quick References

Object Property Quick Reference

EngUnitsEnum (continued) (also see About Units, page 5-6)

33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 feet watts_per_square_foot watts_per_square_meter lumens luxes foot_candles kilograms pounds_mass tons kilograms_per_second kilograms_per_minute kilograms_per_hour pounds_mass_per_minute pounds_mass_per_hour watts kilowatts megawatts btus_per_hour horsepower tons_refrigeration pascals kilopascals bars pounds_force_per_square_inch 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 degrees_angular degrees_Celsius_per_hour degrees_Celsius_per_minute degrees_Fahrenheit_per_hour degrees_Fahrenheit_per_minute no_units parts_per_million parts_per_billion percent percent_per_second per_minute per_second psi_per_degree_Fahrenheit radians revolutions_per_minute currency1 currency2 currency3 currency4 currency5 currency6 currency7 currency8 currency9 268 269 270 271 272 273 274 275 276 277 278 279 280 kilometers milliliters_per_second megawatt_hours gallons_per_hour killowatts_per_hour delta_fahrenheit kiloamperes kilojoules_per_hour kg_of_water_per_dry_air candles raw_value kilocalories_per_hour ph_value

EventStateEnum
0 1 2 3 4 64 normal fault offnormal high_limit low_limit unknown

EventTypeEnum
0 1 2 3 4 5 change_of_bitstring change_of_state change_of_value command_failure floating_limit out_of_range

ExecutionFrequencyEnum
0 1 2 3 4 5 6 7 never slower normal faster fastest minutely on_trigger fixed_minutely

A56

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference Property Quick References

ExecutionOrderEnum
0 1 2 input processor output

FunctionGeneratorNodeModeEnum
0 1 sinusoid ramp

GxBooleanKeyEnum
0 1 2 3 4 5 6 value in_alarm fault overridden out_of_service unacked_alarm down

GxDirectionEnum
0 1 2 3 north south east west

GxDisplayUnitsEnum
0 1 2 none abbreviated full

GxEndpointEnum
0 1 2 3 4 5 6 7 8 9 open l_north_east l_north_west l_south_east l_south_west t_north t_south t_east t_west cross

GxHyperlinkEnum
0 1 2 disabled binding url

GxJustificationEnum
0 1 2 center left right

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A57

Appendix A Property Quick References

Object Property Quick Reference

GxLayerEnum
0 1 2 3 4 5 6 7 top layer_1 layer_2 layer_3 layer_4 layer_5 layer_6 background

GxOrientationEnum
0 1 2 auto vertical horizontal

GxShapeEnum
0 1 rectangle ellipse

LogControlNodeChartTypeEnum
0 1 2 3 4 5 plot area bar candle bar_3d candle_3d

LogControlNodeCollectionModeEnum
0 1 change_of_value interval

LogicNodeFunctionEnum
0 1 2 3 A_AND_B A_OR_B A_XOR_B A_NOT_B

MathNodeFunctionEnum
0 1 2 3 4 5 6 7 8 9 minimum maximum summation average difference abs sqrt ln log exp 10 11 12 13 14 15 16 17 18 19 sin cos tan asin acos atan reset multiplication division power

A58

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference Property Quick References

MonthEnum
0 1 2 3 4 5 6 7 8 9 10 11 Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec

NdioProcessorEnum
-1 0 1 2 3 4 5 6 7 undefined first_onboard_processor second_onboard_processor third_onboard_processor fourth_onboard_processor first_processor_slot_0 second_processor_slot_0 first_processor_slot_1 second_processor_slot_1

NdioTempUnitsEnum
0 1 2 degrees_celsius degrees_fahrenheit degrees_kelvin

NotificationArchiveEnum
0 1 2 3 archive_disabled archive_local archive_remote archive_local_no_SQL

NotifyTypeEnum
0 1 2 3 4 alarm event ack_notification alert display_ack

PolarityEnum
0 1 normal reverse

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A59

Appendix A Property Quick References

Object Property Quick Reference

PollArchiveEnum
0 1 2 3 4 5 6 7 8 archive_disabled archive_group_0 archive_group_1 archive_group_2 archive_group_3 archive_group_4 archive_group_5 archive_group_6 archive_group_7

ReliabilityEnum
0 1 2 3 4 5 6 7 8 no_fault_detected no_sensor over_range under_range open_loop shorted_loop no_output_value unreliable_other process_error

StationAlarmEnum
0 1 2 3 4 5 6 7 stationUp stationDown stationBoot powerLost powerLostShutdown powerRestored batteryTestFailed batteryTestPassed

StationAuthenticationEnum
0 1 none basic

TotalizerNodeIntervalEnum
0 1 hourly minutely

WeekdayEnum
0 1 2 3 4 5 6 Sun Mon Tue Wed Thu Fri Sat

A60

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

Appendix A

Object Property Quick Reference Resource Count Range

Resource Count Range

Table 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 AnalogInput AnalogLog AnalogOutput AnalogOverride ApiRecipient AuditLogService BackupService BinaryInput BinaryLog BinaryOutput BinaryOverride Bundle Calendar Command Comparison Composite Container ControlEngineService CpAnalogNode, CpBinaryNode, CpIntegerNode, CpStringNode DatabaseService DateTimeTrigger ErrorLogService FunctionGenerator GxBarGraph GxBoolean GxDamper GxFan GxFloat

31 to 53 63 to 116 115 to 160 72 to 132 41 to 57 16 to 21 38 to 1043 22 to 28 80 to 136 115 to 160 91 to 155 41 to 55 48 to 74 72 to 132 32 to 42 48 to 80 48 to 74 30 to 42 60 to 70

GxImage GxInteger GxPage GxPipe GxSpectrum GxText GxTimePlot IntegerLog IntToFloat LogService Logic Loop MailRecipient MailService Math MultistateInput MultistateLog MultistateOutput MultistateOverride Ndio0to10VInput

42 to 64 43 to 80 54 to 77 18 to 33 48 to 81 49 to 86 58 to 94 115 to 160 35 to 51 33 to 47 67 to 101 75 to 137 24 to 47 29 to 50 67 to 101 79 to 141 115 to 160 93 to 161 39 to 55 70 to 126 93 to 160 90 to 146 104 to 168 30 to 53 54 to 84 53 to 84 70 to 126 70 to 126 22 to 34 51 to 6 36 to 46

PollAlways PollArchiveService PollOnDemand PrinterRecipient Program RemotePrinterRecipient Schedule ServiceContainer Station StringLog TimeSyncService Totalizer UiEngineService WebUiService

30 to 42 33 to 47 30 to 42 22 to 34 52 and up 27 to 39 72 to 132 600 and up 89 to 200 115 to 160 41 to 63 42 to 62 40 to 47 25 to 33

Note: Program objects are typically large consumers of resource counts. Whenever possible, use standard control or apps objects when engineering a station database.
The resource count for any portion of a running station (container or primitive object) can be checked by clicking the object in the JDE Tree View, and selecting from the menu bar Search > Resource Count. You can also open a host connection using a browser and use the prism resources page to check a stations resource count allocations. See Checking Resource Count, page 1-25.

35 to 51

Ndio0to10VOutput NdioBinaryInput

55 to 63 38 to 50 38 to 1043 50 to 72 45 to 82 47 to 82 44 to 73 43 to 70 43 to 80

NdioBinaryOutput NdioContainer NdioHighSpeedCounterInput NdioProcessor NdioResistiveInput NdioThermistorType3Input NotificationClass NotificationService PeriodicTrigger

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

A61

Appendix A Resource Count Range

Object Property Quick Reference

A62

Niagara Release 2.3.5 Niagara Standard Programming Reference Revised: April 20, 2004

INDEX

Numerics
0to10VInput object (Ndio) 10-13 0to10VOutput object (Ndio) 10-16 4-20mA input, (Ndio) 10-13

A
abbreviations for units 5-6 accessing archives 4-21 account enabled 1-20 ackedTransitions property 5-11, 5-12 resetting flags 5-11 action, Loop object 5-92 active xii, 3-1 ActiveUsers view, Station object 1-22 AddressBook 1-15 host address 1-16 monitor function 1-16 poll archive group 1-16 station access 1-15 station relationship 1-16 Admin Tool xii, 1-10, 1-26, 4-3 adminfiles.txt 1-28 Administrator user 1-17 Admin-level commands 3-2 AdminTool object 6-18 to 6-25 audit log notes 6-25 elementName reference 6-20 examples 6-23 changing limitEnable for AIs 6-24 changing log object end times 6-23 stopping FunctionGenerators 6-24 property quick reference A-4 using wildcards 6-25 alarm xii, 1-21, 1-23, 5-8, 5-11, 5-13
Niagara Release 2.3.5 Niagara Standard Programming Reference

alarm console 5-14, 9-7 alarm delay AnalogInput object 5-21 BinaryInput object 5-39 BinaryOutput object 5-51 MultistateInput object 5-109 MultistateOutput object 5-121 alarm detection AnalogInput object 5-19 BinaryInput object 5-38 BinaryOutput object 5-49 MultistateInput object 5-107 MultistateOutput object 5-120 alarm inhibit AnalogInput object 5-20 BinaryInput object 5-39 BinaryOutput object 5-51 MultistateInput object 5-108 MultistateOutput object 5-121 alarm notification AnalogInput object 5-20 BinaryInput object 5-38 BinaryOutput object 5-51 MultistateInput object 5-108 MultistateOutput object 5-121 standalone JACE-4/5 9-7 alarm setup properties 5-13 Alarms view, Station object 1-23 alarmText property container objects 7-5 control objects 5-14 pass-up process 7-5 station 1-12 alerts xii, 5-109 BI change-of-state (COS) 5-40 BI runtime (active time) 5-40 MSI alarm setup properties 5-110

Revised: April 20, 2004

Index-1

Index

MSI change-of-state (COS) 5-110 MSI runtime (active time) 5-110 alertText property container objects 7-5 control objects 5-14 pass-up process 7-5 analog xii AnalogInput object 5-15 to 5-22, 10-8 alarm delay 5-21 alarm detection 5-19 alarm inhibit 5-20 alarm notification 5-20 examples 5-22, 10-32 fault conditions 5-21 property quick reference A-4 AnalogLog object 6-26 to 6-31 chartType examples 6-31 delta logging 6-29 property quick reference A-5 statusOutput 6-29 AnalogOutput object 5-23 to 5-28 command limits 5-26 command tags 5-28 examples 5-28 property quick reference A-6 AnalogOverride object 5-29 to 5-32 directly available 5-31 property quick reference A-7 remaining override time 5-32 with Command object 5-32 ApiRecipient object 9-8 property quick reference A-7 apps objects 6-1 to 6-62 AdminTool 6-18 AnalogLog 6-26 BinaryLog 6-32 common properties 6-5 common things 6-4 IntegerLog 6-41 MultistateLog 6-44 Program 6-47 Schedule 6-52 selecting 6-3 StringLog 6-60

archive (SQL) storage 4-34 archive log data format 4-20 storage 6-10 troubleshooting 4-34 archiveSetup property 6-17 archiving properties files 1-30 area chartType 6-31 attributes of properties 2-5 notation for A-1 examples A-2 AuditLogService object 4-6 to 4-7 property quick reference A-7

B
BackupService object 4-8 to 4-9 property quick reference A-8 BACnet xii, 1-3, 5-2, 5-3, 5-15, 5-23, 5-42, 5-101, 5-112,
6-2, 6-35, 6-52, 9-1, 9-2, A-2

heritage in apps objects 6-2 heritage in control objects 5-3 Ndio objects 10-8 terminology 5-3 bacnet.properties file 1-31 bar chartType 6-31 bar_3d chartType 6-31 bias, Loop object 5-90, 5-92 binary xii BinaryInput object 5-33 to 5-41, 10-8 alarm delay 5-39 alarm detection 5-38 alarm inhibit 5-39 alarm notification 5-38 alerts 5-40 examples 5-41 Ndio 10-20 property quick reference A-8 routinely configured properties 5-37 BinaryLog object 6-32 to 6-34 property quick reference A-9 BinaryOutput object 5-42 to 5-52, 10-8 alarm delay 5-51

Index-2

Niagara Standard Programming Reference

Niagara Release 2.3.5 Revised: April 20, 2004

Index

alarm inhibit 5-51 alarm notification 5-51 command tags 5-49 control-related properties 5-48 examples 5-52 Ndio 10-24 priority levels 5-47 property quick reference A-10 routinely configured properties 5-48 BinaryOverride object 5-53 to 5-56 directly available 5-55 property quick reference A-11 remaining override time 5-56 with Command object 5-56 buffer size, log objects 6-10 bufferSize property 6-16 Bundle object 7-14 to 7-18 example 7-17 known issues 7-16 property quick reference A-11 when to use 7-16

C
Calendar object 6-35 to 6-40 calendar template 6-40 Calendar view 6-39 master/slave 6-38 outputs 6-38 processing and priorities 6-38 property quick reference A-12 candle chartType 6-31 candle_3d chartType 6-31 chartTemplateUrl property 6-14 chartType property examples 6-31 checking JACE-4/5 CPU utilization 1-25 JACE-5 Flash space 1-26 object count 1-25 resource count 1-25 child dependencies 1-7 GxPage 7-24

ServiceContainer 7-34 child object xii classes, notification 9-2 collectionMode property 6-17 command xiii Command object 5-57 to 5-58 examples 5-58 AnalogOverride 5-32 BinaryOverride 5-56 MultistateOverride 5-126 property quick reference A-12 command tags AnalogOutput object 5-28 BinaryOutput object 5-49 MultistateOutput object 5-119 commands xiii, 3-1 to 3-6 Admin-level 3-2 all available, by object 3-3 control 3-1 debug 5-5 resetAckedTransitions 5-11 Comparison object 5-59 to 5-61 example 5-61 property quick reference A-13 composite adding properties 7-11 editor 7-10 inputs and default values 7-12 property names 7-10 reasons to 7-9 reasons to not 7-13 composite link types 2-10 Composite object 7-19 to 7-21 example 7-21 known issues 7-16 property quick reference A-13 constant value, Math object 5-98 Container object 7-22 to 7-23 property quick reference A-14 container objects xiii, 7-1 to 7-36 Bundle 7-14 common properties 7-6 common things 7-4 Composite editor 7-10

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

Index-3

Index

Container 7-22 functions 7-3 GxPage 7-24 layer control 7-3 NdioContainer 10-10 NdioProcessor 10-11 PollAlways 7-29 PollOnDemand 7-31 ServiceContainer 7-34 standard views 3-7 that composite 7-8 control commands 3-1 control objects xiii, 5-1 to 5-131 AnalogInput 5-15 AnalogOutput 5-23 AnalogOverride 5-29 Binary Output 5-42 BinaryInput 5-33 Command 5-57 common properties 5-8 common things 5-5 Comparison 5-59 CpAnalogNode 5-62 CpBinaryNode 5-65 CpIntegerNode 5-67 CpStringNode 5-69 DateTimeTrigger 5-71 event-types 5-11 FunctionGenerator 5-73 IntToFloat 5-77 like Ndio objects 10-8 Logic 5-79 Loop 5-83 Math 5-95 MultistateInput 5-101 MultistateOutput 5-112 MultistateOverride 5-124 notificationClass property 5-13 PeriodicTrigger 5-128 selecting 5-4 Totalizer 5-130 ControlEngineService object 4-10 to 4-15 execution frequencies 4-14 execution order 4-15

object execution 4-14 property quick reference A-15 COV, COS xiii CpAnalogNode object 5-62 to 5-64 example 5-64 property quick reference A-15 CpBinaryNode object 5-65 to 5-66 example 5-66 property quick reference A-16 CpIntegerNode object 5-67 to 5-68 example 5-68 property quick reference A-16 CpStringNode object 5-69 to 5-70 example 5-70 CPU temperature, JACE-NP and JACE-NX 1-27 CPU utilization, JACE-5 1-25 current selected color 8-8

D
data enumerations 2-2 primitives 2-2 data species xiii, 2-1 DatabaseBrowser view 4-19 List Filters 4-25 Summary Information 4-26 vs. Web browser 4-25 DatabaseService object 4-16 to 4-27 DatabaseBrowser view 4-19 property quick reference A-17 SQL queries 4-24 output types 4-23 running 4-21 summary and useful URLs 4-26 DateTimeTrigger object 5-71 to 5-72 property quick reference A-17 daysOfTheWeek property 6-17 ddns.properties file 1-31 debug command 5-5 debugger, Program object 6-50 default stateText value 5-118

Index-4

Niagara Standard Programming Reference

Niagara Release 2.3.5 Revised: April 20, 2004

Index

views, by object 3-8 delta logging 6-29 dependencies xiii, 1-7 derivative gain, Loop object 5-92 dialup section, AddressBook 1-16 drivers.properties file 1-27, 1-31

E
editor Calendar object 6-39 composite 7-10 link 2-6 Program object 6-49 properties files 1-28 Schedule object 6-58 engineering units 5-6 enumerations xiii, 2-2, A-53 ActionEnum A-53 AlertTypeEnum A-54 AnalogLogNodeOutputFunctionEnum A-54 ArchiveModeEnum A-54 BooleanCmdEnum A-54 CommDataBitsEnum A-54 CommFlowControlEnum A-54 CommParityEnum A-54 CommStopBitsEnum A-54 ComparisonNodeFunctionEnum A-55 ControlPriorityEnum A-55 EngUnitsEnum 5-6, A-55 EventStateEnum A-56 EventTypeEnum A-56 ExecutionFrequencyEnum A-56 ExecutionOrderEnum A-57 FunctionGeneratorNodeModeEnum A-57 GxBooleanKeyEnum A-57 GxDirectionEnum A-57 GxDisplayUnitsEnum A-57 GxEndPointEnum A-57 GxHyperlinkEnum A-57 GxJustificationEnum A-57 GxLayerEnum A-58 GxOrientationEnum A-58

GxShapeEnum A-58 LogControlNodeChartTypeEnum A-58 LogControlNodeCollectionModeEnum A-58 LogicNodeFunctionEnum A-58 MathNodeFunctionEnum A-58 MonthEnum A-59 NdioProcessorEnum A-59 NdioTempUnitsEnum A-59 NotificationArchiveEnum A-59 NotifyTypeEnum A-59 PolarityEnum A-59 PollArchiveEnum A-60 ReliabilityEnum A-60 StationAlarmEnum A-60 StationAuthenticationEnum A-60 TotalizerNodeIntervalEnum A-60 WeekDayEnum A-60 ErrorLogService object 4-28 to 4-30 property quick reference A-18 eventEnable property 5-13 events xiii, 5-11 eventState property 5-12 eventTriggerEnable property 5-14 event-type objects 5-11 alarm setup properties 5-13 status properties 5-12 executeTrigger property 4-15 apps objects 6-4 control objects 5-5 execution of objects 4-13, 4-14 executionParameters ControlEngineService 4-14 expansion boards, I/O 10-7 external links 1-12, 1-26, 2-9

F
facets (views) 3-8 fault conditions 5-21 Flash space, JACE-4/5 1-26 foreignAddress property 5-9, 6-6 foundation object Station 1-9

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

Index-5

Index

FunctionGenerator object 5-73 to 5-76 examples 5-76 property quick reference A-18 ramp mode 5-75 sinusoid mode 5-75

G
General tab, UserAdmin 1-18 Gx objects 8-1 to 8-34 common properties 8-4 common things 8-3 current selected color 8-8 execution of 8-2 graphic file / color-based types 8-3 GxBarGraph 8-10 GxBoolean 8-13 GxDamper 8-16 GxFan 8-18 GxFloat 8-20 GxImage 8-22 GxInteger 8-24 GxPipe 8-26 GxSpectrum 8-28 GxText 8-30 GxTimePlot 8-33 isvisible input 8-7 keyboard shortcuts 8-9 pre-designed types 8-2 shortcuts 8-8 Gx submenu 8-8 gx.properties file 1-32, 8-15 GxBarGraph object 8-10 to 8-12 property quick reference A-18 GxBoolean object 8-13 to 8-15 property quick reference A-19 GxDamper object 8-16 to 8-17 property quick reference A-20 GxFan object 8-18 to 8-19 property quick reference A-20 GxFloat object 8-20 to 8-21 property quick reference A-21 GxImage object 8-22 to 8-23

property quick reference A-21 GxInteger object 8-24 to 8-25 property quick reference A-22 GxPage object 7-24 to 7-28 composite 7-28 layer control 7-26 property quick reference A-22 GxPipe object 8-26 to 8-27 property quick reference A-23 GxSpectrum object 8-28 to 8-29 property quick reference A-23 GxText object 8-30 to 8-32 link flexibility 8-32 property quick reference A-24 GxTimePlot object 8-33 to 8-34 property quick reference A-24

H
hierarchies, in objects 1-4 HighSpeedCounterInput object (Ndio) 10-29 host address 1-16 host properties files 1-28 Hot Links tab, UserAdmin 1-19 HTTP port, station 1-11

I
image file reference 8-8 inactive xiii, 3-1 incoming archives 4-34 index property (Ndio) 10-5 inhibitTime property 5-14 input xiii IntegerLog object 6-41 to 6-43 property quick reference A-25 similarity to AnalogLog 6-43 integral and derivative gain, PID control 5-90 integral gain, PI control 5-92 integral overshoot, PI control 5-92 internal links 2-8 interval property 6-17

Index-6

Niagara Standard Programming Reference

Niagara Release 2.3.5 Revised: April 20, 2004

Index

IntToFloat object 5-77 to 5-78 example 5-78 property quick reference A-25 IP address 1-16 isVisible input 8-7 applications for 8-7

J
JACE I/O expansion boards 10-7 JACE-4/5 checking CPU utilization 1-25 checking Flash space 1-26 JACE-NP and JACE-NX, monitoring CPU temperature 1-27 JAR file xiii, 1-8

K
keyboard shortcuts for moving objects 8-9

L
layer control container objects 7-3 GxPage 7-26 license.properties file 1-32 licensing services 4-3 limits and guidelines station resources 1-24 links 2-5 to 2-13 categories 2-7 external 2-9 internal 2-8 local link 2-8 colors 2-11 data flow 2-12 editor 2-6 GxText flexibility 8-32 notification objects 9-3 resources 2-13

rules 2-11 service objects 7-36 types 2-10 composite 2-10 LonTalk local binding 2-10 Lontalk network binding 2-10 normal 2-10 trigger 2-10 ui 2-10 links view 2-7 List Filters, DatabaseBrowser 4-25 Local Library xiv, 5-78, 6-18, 8-27, 10-2 local links 2-8 log objects 6-7 to 6-17 archive (SQL) storage 6-10 archiveSetup property 6-17 bufferSize property 6-10 collectionMode property 6-17 commands 6-15 common properties 6-15 daysOfTheWeek property 6-17 interval property 6-17 location of JACE controller 6-11 WebSupervisor 6-11 log samples 6-7 order of 6-9 log selector 6-14 LogTable 6-7 stopWhenFull property 6-16 timeRange property 6-17 trigger inputs 6-15 trigger outputs 6-15 views 6-12 visual properties 6-30 log servlet 4-33 log storage 6-10 LogChart 6-12 controls and toolbar 6-13 title from description 6-5, 6-16 logEnableDefault property 6-17 Logic object 5-79 to 5-82 examples 5-82 property quick reference A-26

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

Index-7

Index

truth tables 5-81 LogService object 4-31 to 4-35 property quick reference A-26 LonTalk local binding link 2-10 LonTalk network binding link 2-10 LonWorks xiv, 1-3, 2-6, 3-8, 5-2, 7-31, A-2 Lonworks 5-78 Loop object 5-83 to 5-94 action 5-92 bias 5-90, 5-92 configuration guidelines PI mode 5-92 PID mode 5-93 P-only mode 5-90 examples 5-93 loop terminology 5-88 output calculation PI configuration 5-91 statusInhibit 5-89 output limits 5-90, 5-92 PI control 5-90 integral gain 5-92 overshoot 5-92 PID control 5-93 P-only control 5-89 property quick reference A-27 repeats per minute 5-91 statusInhibit 5-89

M
MailRecipient object 9-9 to 9-12 example e-mails 9-12 property quick reference A-28 MailService object 4-36 to 4-38 outbox 4-38 property quick reference A-28 master/slave Calendar objects 6-38 data flow 2-13 NotificationClass objects 9-2, 9-7 Schedule objects 6-57 Math object 5-95 to 5-100

cascading multiple 5-100 for valve compenstation 5-99 NaN 5-98 property quick reference A-29 reset function 5-99 MAX_VALUE, MIN_VALUE 2-2 mime.properties file 1-32 monitor function, in AddressBook 1-16 multistate xiv MultistateInput object 5-101 to 5-111 alarm delay 5-109 alarm detection 5-107 alarm inhibit 5-108 BACnet guidelines 5-105 examples 5-111 property quick reference A-30 routinely configured properties 5-105 stateText 5-105 MultistateLog object 6-44 to 6-46 property quick reference A-31 similarity to BinaryLog 6-46 MultistateOutput object 5-112 to 5-123 alarm delay 5-121 alarm detection 5-120 alarm inhibit 5-121 alarm notification 5-121 BACnet guidelines 5-118 command tags 5-119 control-related properties 5-118 examples 5-123 property quick reference A-32 routinely configured properties 5-117 stateText 5-117 MultistateOverride object 5-124 to 5-127 directly available 5-126 property quick reference A-33 remaining override time 5-127 with Command object 5-126

N
names of objects 1-5 NaN (not a number) 5-98

Index-8

Niagara Standard Programming Reference

Niagara Release 2.3.5 Revised: April 20, 2004

Index

Ndio objects 10-1 to 10-41 common things 10-8 inputs 10-5 like control objects 10-8 outputs 10-6 ndio.properties file 1-32 Ndio0to10VInput object 10-13 to 10-15 property quick reference A-34 Ndio0to10VOutput object 10-16 to 10-19 property quick reference A-35 NdioBinaryInput object 10-20 to 10-23 property quick reference A-36 NdioBinaryOutput object 10-24 to 10-29 property quick reference A-37 NdioContainer object 10-10 property quick reference A-38 NdioHighSpeedCounterInput object 10-29 to 10-33 property quick reference A-38 NdioProcessor object 10-11 property quick reference A-40 NdioResistiveInput object 10-33 to 10-37 properties quick reference. A-39 NdioThermistorType3Input object 10-38 to 10-41 property quick reference A-40 niagarad.properties file 1-32 node xiv normal links 2-10 notification classes 9-2 notification objects 9-1 to 9-19 common properties 9-4 general notes 9-3 linking 9-3 MailRecipient 9-9 NotificationClass 9-5 PrinterRecipient 9-13 recipients 9-2 RemotePrinterRecipient 9-15 SnmpRecipient 9-17 NotificationClass object 9-5 to 9-7 master/slaves 9-2 property quick reference A-41 notificationClass property 5-13 NotificationService object 4-39 to 4-40 property quick reference A-41
Niagara Release 2.3.5 Niagara Standard Programming Reference

O
object count, checking for station 1-25 object model (integration platform) 1-3 object type xiv objects xiv, 1-1, 1-3 categories 1-7 commands 3-1 dependencies 1-7 execution 4-13 Gx execution 4-48 hierarchies 1-4 libraries 1-8 names (and rules) 1-5 property quick references A-3 shadow 1-3 swid 1-6 views 3-6 on_demand_transient property 2-5, A-1 outbox, MailService object 4-38 outgoing archives 4-34 outOfService property 5-12 output xiv output limits, Loop object 5-90, 5-92 output types, SQL queries 4-23 outputs, Ndio 10-6

P
parent xv parent dependencies 1-7 peer station, AddressBook 1-16 PeriodicTrigger object 5-128 to 5-129 property quick reference A-42 persistent property 2-5, A-1 PI loop output 5-91 plot chartType 6-31 PollAlways object 7-29 to 7-30 property quick reference A-42 PollArchiveService object 4-41 to 4-44 AddressBook setup 1-16 property quick reference A-42

Revised: April 20, 2004

Index-9

Index

PollOnDemand object 7-31 to 7-33 cache, view 7-33 property quick reference A-43 port HTTP (Station) 1-11 SMTP (MailService) 4-36 Time (TimeSyncService) 4-46 port.properties file 1-32 presentValue property 5-12 primitive xv data species 2-2 objects 1-4 PrinterRecipient object 9-13 to 9-14 property quick reference A-43 priority levels 5-47 priority variable types 2-4 Prism servlet 1-25 Program object 6-47 to 6-51 debugger 6-50 editor 6-49 property quick reference A-44 simple example 6-51 TRIPL language 6-50 properties xv, 2-1, 2-5 files in Niagara 1-27 quick references, by object A-3 proportional gain, loop 5-90, 5-92 protocol services 4-3

Remote Library xv RemotePrinterRecipient object 9-15 to 9-16 property quick reference A-44 repeats per minute, Loop object 5-91 reset function, Math object 5-99 resetAckedTransitions command 5-11 ResistiveInput object (Ndio) 10-33 resource count checking station 1-25 comparison by object A-61 links 2-13 log objects 6-10 running an SQL query 4-21

S
Schedule object 6-52 to 6-59 editor 6-58 master/slave 6-57 outputs 6-57 processing and priorities 6-56 property quick reference A-44 security administrator 1-20 security groups 1-21, 7-5 security mask, user 1-20 securityGroups property about 1-21 apps objects 6-6 control objects 5-10 station 1-13 selecting apps objects 6-3 container objects 7-3 control objects 5-4 selector, log 6-14 service objects 4-1 to 4-50 adding or removing 4-4 AuditLogService 4-6 BackupService 4-8 common properties 4-5 ControlEngineService 4-10 core services 4-2 DatabaseService 4-16

Q
queries, SQL 4-22, 4-24

R
ramp mode, FunctionGenerator 5-75 ras.properties file 1-32 recipient objects 9-2 remaining override time AnalogOverride object 5-32 BinaryOverride object 5-56 MultistateOverride object 5-127

Index-10

Niagara Standard Programming Reference

Niagara Release 2.3.5 Revised: April 20, 2004

Index

ErrorLogService 4-28 LogService 4-31 MailService 4-36 NotificationService 4-39 PollArchiveService 4-41 TimeSyncService 4-45 UiEngineService 4-47 WebUiService 4-49 ServiceContainer object 7-34 to 7-36 linking child services 7-36 property quick reference A-45 services xv, 4-1 to 4-50 additional 4-2 core 4-2 optional 4-2 licensing 4-3 protocol (integration) 4-3 SMTP 4-36 SnmpRecipient object 9-17 sns xv, 1-12 spy utility 1-25 SQL database,database tables 4-19 SQL queries 4-21, 4-24 output types 4-23 running 4-21, 4-22 Standard Output xv, 1-25, 4-13, 4-37, 4-40, 4-43, 4-46, 5-5,
5-84, 6-4, 6-20

stopWhenFull property 6-16 StringLog object 6-60 to 6-62 FlexBinding input 6-62 subordinate station, AddressBook 1-16 supervisor station, AddressBook 1-16 swid xv, 1-6 in property sheets 1-6 sysmon (JACE-NP and JACE-NX) 1-27 system.properties file 1-33, 1-34

T
tables, database 4-19 ThermistorType3Input object (Ndio) 10-38 time zone 6-8 timeDelay property 5-13 timeRange property 6-17 timestamp xvi, 4-6, 4-28 archive format 4-20 log format 6-7 notes 6-8 TimeSyncService object 4-45 to 4-46 property quick reference A-47 Totalizer object 5-130 to 5-131 property quick reference A-48 transient property 2-5, A-1 Tree View xvi, 7-2, 8-8 trigger xvi trigger links 2-10 TRIPL program 6-50

station xv, 1-1 administrator user 1-17 alarm types 1-23 limits and guidelines 1-24 object count 1-25 overview 1-2 resource count 1-25 Station object 1-9 to 1-31 ActiveUsers view 1-22 AddressBook view 1-15 Alarms view 1-23 property quick reference A-46 UserAdmin view 1-17 station.properties file 1-33 statusColors.properties file 1-33 statusFlags property 2-3, 5-8, 10-9 statusInhibit property, Loop object 5-89

U
UiEngineService object 4-47 to 4-48 property quick reference A-48 units 5-6 URL xvi user messages 1-22 UserAdmin 1-17 General tab 1-18 Hot Links tab 1-19

Niagara Release 2.3.5 Niagara Standard Programming Reference

Revised: April 20, 2004

Index-11

Index

Security tab 1-20 account enabled 1-20 security administrator 1-20 security mask 1-20 UTC (Universal Time, Coordinated) 6-8

V
valve compensation , Math object 5-99 variable types 2-3 to 2-4, A-49 boolean (primitive) 2-2, A-50 BooleanPriorityType A-50 BooleanStatusType A-50 BooleanTriggerType A-50 DateRangeType A-50 DateTimeType A-50 DateType A-50 DimensionType A-50 DurationType A-50 EventPrioritiesType A-51 EventTimestampsType A-51 EventTransitionBitsType A-51 float (primitive) 2-2, A-51 FloatPriorityType A-51 FloatStatusType A-51 FloatTriggerType A-51 int (primitive) 2-2, A-51 IntegerPriorityType A-51 IntegerStatusType A-51

IntegerTriggerType A-51 LimitEnableBitsType A-52 MailRecipientsType A-52 NotificationTriggerType A-52 PointType A-52 ScaleOffsetType A-52 StatusFlagsType A-52 String (primitive) 2-2, A-52 TimeRangeType A-52 TimestampType A-52 TimeSyncServerType A-52 TimeType A-53 TriggerType A-53 VasRecipient object 9-18 to 9-19 view cache PollOnDemand 7-33 views xvi, 3-6 to 3-11 all available, by object 3-8 special 3-7 standard 3-6

W
Web Supervisor xvi, 1-2, 1-15, 4-2, 4-8, 4-16, 4-36, 4-39,
4-45, 4-49, 7-16, 7-26, 9-13

WebUiService object 4-49 to 4-50 property quick reference A-49 Win32SysMonDriver 1-27 Workspace xvi, 3-7, 7-2 WorkspaceEditor xvi, 3-7, 7-4

Index-12

Niagara Standard Programming Reference

Niagara Release 2.3.5 Revised: April 20, 2004

You can help make this manual even better!

Please help us make our documentation as useful as possible. Use this form to advise us of errors, descriptions that are not clear, or provide any other helpful information. Mail this form to: Tridium, Inc. 3951 Westerre Parkway, Suite 350 Richmond, Virginia 23233 Attention: Tridium Documentation Team Or fax it to us at: (804) 747-5204 Or e-mail your comments to us at: documentation@tridium.com Thank you for taking the time to help us improve our documentation!

Documentation Comment Form

Document Title: Document Version:
Niagara Standard Programming Reference Niagara Release 2.3.5, Revised: April 20, 2004

Page #

Problem Found or Suggested Change

Your Name: Your Company: