Neuron® C Programmer's Guide Revision 5 C o r p o r a t i o n 078-0002-01E Echelon, LNS, LonBuilder, LonManager, LonMaker, LonTalk, LONWORKS, Neuron, NodeBuilder, 3120, 3150, and the Echelon logo are trademarks of Echelon Corporation registered in the United States and other countries. LONMARK and ShortStack are trademarks of Echelon Corporation. Touch Memory is a trademark of the Dallas Semiconductor Corp. Other brand and product names are trademarks or registered trademarks of their respective holders. ® Neuron Chips, Serial LonTalk Adapters, and other OEM Products were not designed for use in equipment or systems which involve danger to human health or safety or a risk of property damage and Echelon assumes no responsibility or liability for use of these products in such applications. Parts manufactured by vendors other than Echelon and referenced in this document have been described for illustrative purposes only, and may not have been tested by Echelon. It is the responsibility of the customer to determine the suitability of these parts for each application. ECHELON MAKES NO REPRESENTATION, WARRANTY, OR CONDITION OF ANY KIND, EXPRESS, IMPLIED, STATUTORY, OR OTHERWISE OR IN ANY COMMUNICATION WITH YOU, INCLUDING, BUT NOT LIMITED TO, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, SATISFACTORY QUALITY, FITNESS FOR ANY PARTICULAR PURPOSE, NONINFRINGEMENT, AND THEIR EQUIVALENTS. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the prior written permission of Echelon Corporation. Document No. 29300 Printed in the United States of America. Copyright ©1990-2001 by Echelon Corporation Echelon Corporation 550 Meridian Avenue San Jose, CA. USA 95126 www.echelon.com ii Preface Preface This manual describes how to write programs using the Neuron® C language. Neuron C is a programming language based on ANSI C that is designed for Neuron Chips and Smart Transceivers. It includes network communication, I/O, and event-handling extensions to ANSI C, which make it a powerful tool for the development of LONWORKS® applications. Key concepts in programming with Neuron C are explained through the use of specific code examples and diagrams. A general methodology for designing and implementing a LONWORKS application is also presented. Neuron C Programmer’s Guide iii Audience The Neuron C Programmer’s Guide is intended for application programmers ® who are developing LONWORKS applications. Readers of this guide are assumed to have some C programming experience. For a complete description of ANSI C consult the following references: • American National Standard X3.159-1989, Programming Language C, D.F. Prosser, American National Standards Institute, 1989. • Standard C: Programmer’s Quick Reference, P. J. Plauger and Jim Brodie, Microsoft Press, 1989. • C: A Reference Manual, Samuel P. Harbison and Guy L. Steele, Jr., 3rd edition, Prentice-Hall, Inc., 1991. • The C Programming Language, Brian W. Kernighan and Dennis M. Ritchie, 2nd edition, Prentice-Hall, Inc., 1988. Content The Neuron C Programmer’s Guide • Outlines a recommended general approach to developing a ® LONWORKS application • Explains key concepts of programming in Neuron C through the use of code fragments and examples Related Manuals The NodeBuilder® User’s Guide lists and describes all tasks related to LONWORKS application development using the NodeBuilder Development Tool. Refer to that guide for detailed information on the user interface and features of the NodeBuilder tool. The LonBuilder® User’s Guide lists and describes all tasks related to LONWORKS application development using the LonBuilder Development Tool. Refer to that guide for detailed information on the user interface to the LonBuilder tool. The Neuron C Reference Guide provides the reference information for writing programs using the Neuron C language. The NodeBuilder Errors Guide lists and describes all warning and error messages related to the NodeBuilder software. The LonMaker® User’s Guide lists and describes all tasks related to LONWORKS network development and maintenance using the LonMaker Integration Tool. Refer to that guide for detailed information on the user interface and features of the LonMaker tool. The Gizmo 4 User's Guide describes the Gizmo 4 hardware and software. Refer to that guide for detailed information on the hardware and software interface of the Gizmo 4. iv Preface Typographic Conventions for Syntax Type Used For Example boldface type keywords network literal characters { Italic type abstract elements identifier square brackets optional fields [bind-info] vertical bar a choice between input | output two elements For example, the syntax for declaring a network variable is network input | output [netvar modifier] [class] type [bind-info] identifier Punctuation other than square brackets and vertical bars must be used where shown (quotes, parentheses, semicolons, etc.). Code examples appear in the Courier font: #include <mem.h> unsigned array1[40], array2[40]; // See if array1 matches array2 if (memcmp(array1, array2, 40) != 0) { // The contents of the two areas do not match } Neuron C Programmer’s Guide v Contents Preface iii Audience iv Content iv Related Manuals iv Typographic Conventions for Syntax v Contents vi Chapter 1 Overview 1-1 What Is Neuron C? 1-2 Unique Aspects of Neuron C 1-2 Differences between Neuron C and ANSI C 1-11 Neuron C Language Implementation Characteristics 1-13 Chapter 2 Focusing on a Single Device 2-1 What Happens on a Single Device? 2-2 The Scheduler 2-2 Timers 2-12 Input/Output 2-16 Examples 2-39 Input Clock Frequency and Timer Accuracy 2-45 Chapter 3 How Devices Communicate Using Network Variables 3-1 Major Topics 3-2 Overview 3-2 Declaring Network Variables 3-5 Connecting Network Variables 3-11 Network Variable Events 3-11 Synchronous Network Variables 3-17 Processing Completion Events for Network Variables 3-19 Polling Network Variables 3-21 Explicit Propagation of Network Variables 3-24 Monitoring Network Variables 3-26 Authentication 3-28 Chapter 4 Using Configuration Properties to Configure Device Behavior 4-1 Overview 4-2 Declaring Configuration Properties 4-2 Instantiation of Configuration Properties 4-5 Accessing Property Values from a Program 4-8 Advanced Configuration Property Features 4-9 Chapter 5 Using Functional Blocks to Implement a Device Interface 5-1 Overview 5-2 Functional Block Declarations 5-3 Scope Rules 5-8 Accessing Members and Properties of a Functional Block from a Program 5-9 The Director Function 5-11 Chapter 6 How Devices Communicate Using Application Messages 6-14 Introduction to Application Messages 6-15 Layers of Neuron Software 6-16 Implicit Messages: Network Variables 6-16 Application Messages 6-17 vi Preface Constructing a Message 6-17 Sending a Message 6-24 Receiving a Message 6-25 Example 6-29 Explicit Addressing 6-30 Sending a Message with the Acknowledged Service 6-31 Preemption Mode and Messages 6-35 Asynchronous and Direct Event Processing 6-36 Using the Request/Response Mechanism 6-37 Application Buffers 6-44 Chapter 7 Additional Features 7-1 The Scheduler 7-2 Scheduler Reset Mechanism 7-4 Bypass Mode 7-5 Watchdog Timer 7-6 Additional Predefined Events 7-7 Sleep Mode 7-9 Error Handling 7-13 Access to Device Error Status 7-14 Chapter 8 Memory Management 8-1 Reallocating On-Chip EEPROM 8-2 Allocating Buffers 8-3 Using Neuron Chip Memory 8-12 Memory Use 8-22 Usage Tip for Memory Mapped I/O 8-23 What to Try When a Program Doesn't Fit on a Neuron Chip 8-24 System Library on a Neuron 3120 Chip 8-30 Appendix A Neuron C Tools Stand-Alone Use A-1 Standalone Tools A-2 Switches for Stand-Alone Tools A-6 Appendix B Neuron C Function Libraries B-1 Definitions B-2 LonBuilder Support for Libraries B-2 NodeBuilder Support for Libraries B-4 Tradeoffs, Advantages, and Disadvantages B-5 Library Construction Using the Librarian B-6 Techniques for Circumventing Limitations of Libraries B-8 Appendix C Neuron C Custom System Images C-1 Definitions C-2 Custom Images C-3 NodeBuilder Use of Custom Images C-5 Tradeoffs, Advantages, and Disadvantages C-5 Custom Image Construction Using the Linker C-7 Techniques for Circumventing Limitations of Custom Images C-10 Neuron C Programmer’s Guide vii 1 Overview This chapter introduces the Neuron C Version 2 programming language. It describes the basic aspects of the language and gives an overview to using the LONWORKS platform and the Neuron C programming language to construct interoperable devices and systems. The chapter also introduces key concepts of Neuron C such as event-driven scheduling, network variables, configuration properties, and functional blocks (which are implementations of functional profiles). A secondary goal of this chapter is to introduce fundamental material on Neuron C concerning Neuron C types, storage classes, data objects, and how the Neuron C language compares to the ANSI C language. What Is Neuron C? Neuron C is a programming language based on ANSI C that is designed for Neuron Chips and Smart Transceivers. It includes network communication, I/O, and event-handling extensions to ANSI C, which make it a powerful tool for the development of LONWORKS applications. Following are a few of these new features: • A new network communication model, based on functional blocks and network variables, that simplifies and promotes data sharing between like or disparate devices. • A new network configuration model, based on functional blocks and configuration properties, that facilitates interoperable network configuration tools. • A new type model based on standard and user resource files that expands the market for interoperable devices by simplifying integration of devices from multiple manufacturers. • An extensive built-in set of I/O objects supporting the powerful I/O capabilities of Neuron Chips and Smart Transceivers. • Powerful event-driven programming extensions, based on new when statements, provide easy handling of network, I/O, and timer events.