Crestron SIMPL+ Programming Manual Download

Page: 1 / 60

Crestron

SIMPL+



Software
Programming Guide

Summary of Contents for SIMPL+

Page 1: ...Crestron SIMPL Software Programming Guide ...

Page 2: ...n by the Technical Documentation department at Crestron Electronics Inc 15 Volvo Drive Rockleigh NJ 07647 1 888 CRESTRON All brand names product names and trademarks are the property of their respective owners 2003 Crestron Electronics Inc ...

Page 3: ...t Types 13 All About Variables 16 Arrays 20 Operators Expressions and Statements 22 Operators 22 Expressions 23 Statements 24 Controlling Program Flow Branching 24 if else 24 switch case 26 Controlling Program Flow Loops 27 for Loops 27 while and do until Loops 29 Exiting from Loops Early 30 Using System Functions 30 User Defined Functions 31 Function Definitions 32 Defining Local Variables In Fun...

Page 4: ...g Processing Order 49 How SIMPL and SIMPL Interact 49 Forcing a Task Switch 49 Debugging 50 Compiler Errors 50 Run time Errors 50 Debugging with Print 51 Software License Agreement 52 Return and Warranty Policies 54 Merchandise Returns Repair Service 54 CRESTRON Limited Warranty 54 ii Contents Programming Guide DOC 5789A ...

Page 5: ...ed directly to the control system Input signals are sent from the control system and are received within the SIMPL module Output signals are sent from the SIMPL module to the control system Events are functions that are triggered through input signals from the control system I O signals can be either digital analog or serial and are declared within the SIMPL module Events tell the SIMPL module tha...

Page 6: ...ractice a happy medium can be found that makes programming both efficient and fun What is Needed to Use SIMPL SIMPL version 2 0 requires a CNX series control processor and SIMPL Windows v1 23 or later SIMPL version 3 0 accompanies SIMPL Windows v2 00 or later and may be used to program either a 2 Series control system or a CNX series control system Where Can I Get More Information This guide shoul...

Page 7: ...ed To define a push event function for that signal program this function to yield the desired actions From the skeleton program find the commented line of code that says push Uncomment the function block by removing the surrounding comment characters and edit it to read the following PUSH speak Print Hello world n This function causes the string hello world plus a carriage return and line feed to ...

Page 8: ...ontrol processor As was mentioned earlier SIMPL programs cannot run all by themselves They must be enclosed inside a SIMPL wrapper This section discusses how to set up this program in SIMPL Windows Create a new SIMPL Windows program and add a control processor from the Configuration Manager Notice that only CNX series or 2 Series control processors are compatible with SIMPL For this example use th...

Page 9: ...r select Status Window Assert Signals The signal is driven to the high state which triggers the push event In the Incoming Data window the string Hello world appears Click on the De Assert button to drive the signal low and trigger the release event In the Incoming Data window the string Goodbye cruel world appears By clicking on the Positive Pulse button both strings appear one after the other si...

Page 10: ...values to be assigned to alphanumeric names This is extremely useful for writing changeable and readable code This last compiler directive deserves more discussion since using constant definitions are a very important part of writing readable code To illustrate this examine the following example PUSH vcr_select switcher_input 3 switcher_output 2 video projector PUSH dvd_select switcher_input 4 swi...

Page 11: ...unctions and defined constants are allowed to be declared and defined within libraries Global variable declarations are not allowed Functions however can contain local variables Other advantages are 1 Modularity SIMPL programs can grow to be large and can be better organized by taking sections of code and placing them into a User Library It is best to create libraries that contain sets of related ...

Page 12: ...t1 dinput2 dinputn ANALOG_INPUT ainput1 ainput2 ainputn STRING_INPUT sinput1 size sinput2 size sinputn size BUFFER_INPUT binput1 size binput2 size binputn size Digital and analog output variables are declared in the same way except the word input is replaced with output as follow shown below String output variables do not include a size value There is no output version of the buffer variable DIGIT...

Page 13: ...ram they do not have this property unless the signals they are connected to are explicitly made non volatile through the use of special symbols Structures Sometimes sets of data are needed rather than individual pieces Variables store a piece of data but are not related to other variables in any way Structures are used to group individual pieces of data together to form a related set Before struct...

Page 14: ...ey occur Event functions allow the user to execute code in response to some change that has occurred to one or more of the input signals feeding the SIMPL module from the SIMPL program Two things must be realized about event functions They can be used with input variables only not with locally defined variables Also they are only triggered by the operating system at the appropriate time that is th...

Page 15: ...mmand GOTO DISC itoa disc_number This program uses the itoa function to convert the analog value in disc_number into a string value which can be concatenated onto CD_command The string concatenation operator and system functions i e itoa are discussed in later sections of the manual and in the latest revision of the SIMPL Language Reference Guide Doc 5797 Compound Events Sometimes it is desired to...

Page 16: ...d as follows EVENT this code runs anytime anything on the input list changes Be careful when using this global event function If the user has a SIMPL program in which a change on any input causes the same code to execute this type of event is useful However if additional inputs are added at a later time remember that this event function exists and is caused when these new inputs change as well Thi...

Page 17: ...tal analog and serial The table below takes a closer look at the type of data conveyed by these signal types SIMPL Signal Types SIGNAL TYPE DATA EXAMPLE Digital Single bit Button push release Analog 16 bit 0 to 65 535 Volume level Serial Up to 255 bytes Serial data input from a COM port This table illustrates that digital signals only transfer a single bit of information between SIMPL and SIMPL Of...

Page 18: ...cksum byte on the end to insert or remove characters from a string or to parse information out of a string for use elsewhere Functions that are designed to work explicitly with string signals and string variables are discussed in detail in the latest revision of the SIMPL Language Reference Guide Doc 5797 Serial data is also unique in that unlike digital or analog signals the data may not appear a...

Page 19: ... them but rather point to locations in memory where a string exists Since the data stored at a particular location in memory can change at some later time there is no guarantee that the string data is still there As a result SIMPL does not allow a string output to be examined Examine the following code example DIGITAL_OUTPUT d_out ANALOG_OUTPUT a_out STRING_OUTPUT s_out PUSH someEvent d_out 1 set ...

Page 20: ... Unless otherwise specified with a compiler directive all variables in SIMPL are non volatile which means that they remember their values even after the control system is shut off This can be extremely useful though it does require some caution In the 2 series control system the compiler directive DEFAULT_VOLATILE can be used to change this behavior so that the variable s values are not retained a...

Page 21: ...when treating numbers as signed The table after this paragraph lists operators and functions that are unsigned and those that are signed Any operators or functions that are not shown here do not need special consideration Unsigned Signed Operators and Functions DESCRIPTION UNSIGNED OPERATORS FUNCTIONS SIGNED OPERATORS FUNCTIONS Less than S Less than or equal to S Greater than S Greater than or equ...

Page 22: ...ing2 size stringn size The number in square brackets following the variable name defines the size of the string variable When declaring strings choose a size that is large enough to hold any amount of data that might be needed but that is not overly large so as to waste space That is it is unnecessary to set the variable size to 100 characters when a given variable in an application does not conta...

Page 23: ...er of possible crosspoints can grow very large Thus creating a literal string expression for each case would be very inefficient Instead build the control string dynamically as the program runs An easy way to do this is through the use of the string concatenation operator Note that this is identical to the addition operator but the SIMPL compiler is smart enough to know whether integers are added ...

Page 24: ...len argData checksum checksum byte argData i return argData chr checksum In this example i and checksum are local variables that only exist inside the function CalcChecksum This example also introduces an additional way to implement a local variable by passing it as an argument to the function as was done with the STRING variable argData The concept of local variables and argument passing is discu...

Page 25: ...the example above the following statements are all valid in SIMPL j 5 set an integer variable to 5 myArray1 3 j set the 3rd element of the array to 5 myArray1 j 2 100 set the 10th element of the array to 100 myArray2 j 1 k set the j 1 element of myArray2 to the value of k m myArray2 j k 1 set the variable m to the value in the j k 1 element of the array myArray3 2 test set the 3rd element of the s...

Page 26: ...ned in the previous paragraph use these operators with integers in all but one case The exception is the operator when used with string variables In this case the operator performs a concatenation instead of addition which is very handy for generating complex strings from smaller parts This is discussed in more detail later Bitwise Operators Arithmetic operators deal with integers as a whole Bitwi...

Page 27: ...t two expressions contained an equal sign It is very important to recognize that this operator can have two different meanings based upon where it is used In the first example above the equal sign can serve as an assignment operator assign the value 3 to the variable a or as an equivalency comparison operator does the variable a equal 3 However an expression cannot contain an assignment it would t...

Page 28: ...ranching In any substantial program making decisions must control the program SIMPL provides two constructs for branching the program based on the value of expressions if else and the switch case statement if else if else is the most commonly used branching construct In its most basic form it is structured as follows if expression1 do something here Where expression1 represents any valid SIMPL exp...

Page 29: ...1 evaluates to FALSE Obviously there can never be a case where both sections of code execute together The following example is designed to control a CD changer Before telling the CD player to go to a particular disc number it checks to see that the analog value which represents the disc number does not exceed the maximum value DEFINE_CONSTANT NUMDISCS 100 ANALOG_INPUT disc_number STRING_OUTPUT CD_...

Page 30: ...hat the if else construct can be used for making complex decisions Also it was used for making a choice between mutually exclusive conditions conditions that cannot coexist the syntax can become cumbersome For this particular case SIMPL offers the switch case construct Think of switch case as a compact way of writing an if else construct The basic form of the switch case is shown after this paragr...

Page 31: ... the flow of a program by making decisions and branching Sometimes a program should execute the same code a number of times This is called looping SIMPL provides three looping constructs the for loop the while loop and the do until loop for Loops The for loop is useful to cause a section of code to execute a specific number of times For example consider clearing each element of a 15 element string...

Page 32: ... index to be reduced by some value each time though the loop The for loop flexibility can be enhanced further by using expressions instead of constant values for the start end and step values For example there might be a need to add up the value of each byte in a string in order to calculate the value of a checksum character Since the length of the string can change as the program runs the number ...

Page 33: ...which they occur to rerun the same code forever However due to the multi tasking nature of the operating system an endless loop in one module does not cause the rest of the SIMPL program including other SIMPL modules to stop running This is discussed in more detail in Understanding Processing Order on page 49 This example shows an endless loop That is a loop that runs forever and never exits The p...

Page 34: ... readable in some cases The basic question to ask is whether or not the loop needs to run through at least one time If so a do until is the best choice If instead the value of an expression should be checked then use the while loop Exiting from Loops Early All three loops discussed above have built in ways to exit The for loop exits when the index variable reaches the stated maximum The while loop...

Page 35: ... hold the return value of the function This value can be either an integer or a string depending on the nature of the function Clearly if a given function returns an integer value an integer variable must be used to accept this value and a string variable for those functions that return strings In the itoa examples shown above the return value is the ASCII string which represents the number being ...

Page 36: ...be passed to functions Variables are passed to functions through the function s argument list This is also called parameter passing or function arguments Function arguments can be thought of as passing a value into a function Other variables or literal values can be passed to function arguments Function arguments are another way of defining local variables The difference between declaring a local ...

Page 37: ...ithin this function then the list can remain empty Otherwise a parameter is defined by giving a variable type and name i e INTEGER myIntArgument One or more functions are possible by separating each with a comma Function definitions are global to the SIMPL module in which they are defined That is any event function the Function Main or even another user defined function can call a user defined fun...

Page 38: ...yout suggested by the template should prevent most of these errors Defining Local Variables In Functions The concept of local variables was introduced in the section All About Variables In this section we will discuss the topic in greater detail and present a number of examples What is a local variable A local variable is a variable i e an integer or string with a limited life span and limited sco...

Page 39: ... nature most functions require access to one or more variables that have been declared elsewhere in the program either as global variables or as local variables in a different function The question is how can your function access these variables As we have already seen global variables are available everywhere in a program thus you can simply use such variables to share data between functions and ...

Page 40: ...ction This reference can be thought of the memory location where the original variable lives When a function argument is defined as ByVal only the value of the variable and not the variable itself is passed to the function so the original variable cannot be modified within the function As an example below is a function which takes two strings as arguments It inserts one string into the other at a ...

Page 41: ... shown below STRING_FUNCTION strfunc1 function returns a string INTEGER_FUNCTION intfunc1 function returns an integer FUNCTION func1 function has no return value Clearly functions defined using the STRING_FUNCTION keyword will return a string value and those defined using the INTEGER_FUNCTION keyword will return an integer value Function declared using the function keyword would have no return val...

Page 42: ...endChecksum PLAY PUSH vcr_stop vcr_out appendChecksum STOP In this example the system function byte is used inside the function to get the numeric value of each byte in the string After the checksum has been calculated the chr function is used to append the corresponding ASCII character to the end of the command string Realize that this example is useful for just one very simple type of checksum F...

Page 43: ...o easily insert and remove compact flash cards i e AV2 PRO2 and PAC2 Data storage is a valuable powerful and important part of programming The ability to store and retrieve data from a removable data source can provide many useful and powerful solutions Some of these solutions include the ability to backup data transferring data from one control system to another reading and writing data to and fr...

Page 44: ...tem upon system startup If so it will call the user defined function ReadMyCompactFlashCard to perform any file read operations on the compact flash card If the compact flash card was not found in the control system the program will wait for the card to be inserted before continuing Once inserted the same function ReadMyCompactFlashCard is called Reading and Writing Data Once the existence of the ...

Page 45: ...ileHandle FileOpen CF0 MyFile txt _O_CREAT if nFileHandle 0 nNumBytes ReadInteger nFileHandle myInt nNumBytes ReadLongInteger nFileHandle myLongInt nNumBytes ReadString nFileHandle myStr FileClose nFileHandle EndFileOperations The functions ReadStructure and WriteStructure automate the reading and writing of the individual fields within the structure These functions do not return the number of byt...

Page 46: ...nNumBytes FileClose nFileHandle EndFileOperations Working with Time Up until now this manual has discussed elements of the SIMPL language that have no concept of time This means that each statement in a SIMPL program executes after the previous statement is completed There are times when programming where there is a need to have control over exactly when the statements in the program execute This ...

Page 47: ...he digital output signal specified is driven high and a task switch occurs Such a task switch is necessary in order for the rest of the SIMPL program to recognize that the digital signal has indeed gone high After the time specified has expired the digital output is driven low and another task switch occurs The following program causes the digital output signal preset_1 to be pulsed for a half a s...

Page 48: ...ents Functions Available During Wait Events FUNCTION DESCRIPTION CancelWait name Removes the named wait from the schedule The code never executes CancelAllWait Removes all pending waits from the schedule PauseWait name Stops the timer for the named wait The code does not execute until the timer is started again using ResumeWait ResumeWait name Resumes the timer for the named wait which had been pa...

Page 49: ...pth treatment of working with incoming serial data BUFFER_INPUT To review what was discussed earlier serial data entering a SIMPL program may be treated as either a STRING_INPUT or as a BUFFER_INPUT What is the difference and which one should be used The difference between a STRING_INPUT and BUFFER_INPUT is quite simple The value of a STRING_INPUT is always the last value of the serial signal that...

Page 50: ...ach application should dictate whether it is appropriate to use a STRING_INPUT or a BUFFER_INPUT In general use STRING_INPUTs when the serial signal that is feeding it is being driven from a logic symbol like a Serial Send Analog to Serial or Serial Gather In these cases the serial data is issued on a single logic wave Therefore it is certain that the entire string is copied into the STRING_INPUT ...

Page 51: ...st data that comes from other devices are delimited with a certain character or characters to denote the end of the command In many instances a carriage return or carriage return followed by a line feed is used The getc function is the most basic way to remove data from a buffer Each call of getc pulls one character out of the buffer and returns that character s ASCII value as the function s retur...

Page 52: ...each subsequent line into a different array element Another possibility is that any code that is needed to further act upon the data could be built directly into this loop Thus removing the need to store more than one line of data Once the data has been removed from the buffer and stored in a known format in this case one complete command from the device the desired data can be extracted Using the...

Page 53: ...ogic wave That is if this event caused a change to one of the output signals that signal would be valid one logic wave after the event was triggered In this simple case a SIMPL program acts identically to a SIMPL logic symbol from a timing standpoint In addition for multiple SIMPL events triggered on the same logic wave whether or not they are in the same module these events multi task run at the ...

Page 54: ...job is to recognize exactly what the compiler means and make the necessary changes The following list provides the most common causes of compiler errors Missing a semi colon at the end of a statement Having a semi colon where it does not belong e g before an opening brace of a compound statement Trying to use a variable that has not been declared or misspelling a variable Attempting to assign a va...

Page 55: ... specification string variable list The specification string is a string which determines what the output looks like It can contain static text intermixed with format specifiers A format specifier is a percentage sign followed by a type character For example d is a format specifier for a decimal value and s is the format specifier for a string Consider this specific example INTEGER extension STRIN...

Page 56: ...commands data or instructions from or to another computer b for local campus or wide area network internet or web hosting services or c pursuant to any rental sharing or service bureau arrangement The Software is designed as a software development and customization tool As such Crestron cannot and does not guarantee any results of use of the Software or that the Software will operate error free an...

Page 57: ...of ninety 90 days from the date of receipt and b that any hardware accompanying the Software will be subject to its own limited warranty as stated in its accompanying written material Crestron shall at its option repair or replace or refund the license fee for any Software found defective by Crestron if notified by you within the warranty period The foregoing remedy shall be your exclusive remedy ...

Page 58: ...lamps are not covered This warranty extends to products purchased directly from CRESTRON or an authorized CRESTRON dealer Purchasers should inquire of the dealer regarding the nature and extent of the dealer s warranty if any CRESTRON shall not be liable to honor the terms of this warranty if the product has been used in any application other than that for which it was intended or if it has been s...

Page 59: ...Crestron SIMPL Software This page intentionally left blank Programming Guide DOC 5789A SIMPL 55 ...

Page 60: ...Crestron Electronics Inc Programming Guide DOC 5789A 15 Volvo Drive Rockleigh NJ 07647 04 03 Tel 888 CRESTRON Fax 201 767 7576 Specifications subject to www crestron com change without notice ...

Search results

Summary of Contents for SIMPL+

Reviews:

Related manuals for SIMPL+

Brands by name

Popular brands

Crestron SIMPL+, Programming Manual

Search results

Summary of Contents for SIMPL+

Reviews:

Related manuals for SIMPL+

Brands by name

Popular brands