Crestron SIMPL+ Software Programming Guide
This document was prepared and written 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.
Crestron SIMPL+ Software Contents SIMPL+ 1 Introduction ............................................................................................................................... 1 What is SIMPL+? ........................................................................................................ 1 For Whom is this Guide Intended?.............................................................................. 1 Using SIMPL vs. SIMPL+..............................................................
Software Crestron SIMPL+ Wait Events ............................................................................................................... 43 Working with Strings............................................................................................................... 45 BUFFER_INPUT ...................................................................................................... 45 Removing Data From Buffers .............................................................................
Crestron SIMPL+ Software SIMPL+ Introduction What is SIMPL+? SIMPL+ is a language extension to SIMPL Windows. It does not replace SIMPL, but instead it enhances it. With SIMPL+ it is now possible to use a procedural “Clike” language to code elements of the program that were difficult, or impossible with SIMPL alone. A SIMPL+ program is a module that directly interacts with the control system. In order to interact with the control system, a module must contain a few essential elements.
Crestron SIMPL+ Software Using SIMPL vs. SIMPL+ SIMPL+, while exciting and powerful, does present the programmer with somewhat of a dilemma, namely, when to program in SIMPL and when in SIMPL+. The answer of course is not cut-and-dry, and just about any task can be accomplished entirely in one language or the other. However, the true power of Crestron control system programming is unleashed when the strengths of both environments are harnessed simultaneously.
Crestron SIMPL+ Software Start creating a new SIMPL+ program while running SIMPL Windows. Select File | New | New SIMPL+ Module. The SIMPL+ programming environment appears. Instead of a blank window, a skeleton program filled with commented code shows up. This commented out code makes it easy to remember the language syntax and structure. Simply locate the necessary lines, uncomment them, and add the appropriate code.
Crestron SIMPL+ Software Function Main { Print( “I am born!”\n ); } This causes the text “I am born” to be sent out the computer port only upon startup. To save the file, from the menu, select File | Save. Assign the name, My first SIMPL+. To compile the file, select Build | Save and Compile. This command saves the code module, compiles it, and tells SIMPL Windows how to present it to the SIMPL programmer. SIMPL+ version 2.
Crestron SIMPL+ Software program by clicking on the compile toolbar button or selecting Project | Convert/Compile. The compile process automatically recognizes that there is a SIMPL+ module in the program and compiles it along with the SIMPL code (even though it was already compiled when it was saved; SIMPL Windows always recompiles because it must link the modules together with the SIMPL Windows program). After compilation, transfer the program when prompted by SIMPL Windows.
Software Crestron SIMPL+ #SYMBOL_NAME - Allows the user to specify the name that SIMPL Windows uses for this module. If this directive is left out, the filename will be used by default. #HINT - Provides text that appears in the SIMPL Windows status bar whenever the module icon is clicked on. #CATEGORY – (SIMPL+ 3.0 and later) Specifies the SIMPL Windows symbol tree category number for this SIMPL+ module, which controls where the SIMPL+ module is listed in the symbol tree in Program Manager.
Crestron SIMPL+ Software #DEFINE_CONSTANT VCR_INPUT 3 #DEFINE_CONSTANT DVD_INPUT 4 #DEFINE_CONSTANT VPROJ_OUTPUT 2 PUSH vcr_select { switcher_input = VCR_INPUT; switcher_output = VPROJ_OUTPUT; // video projector } PUSH dvd_select { switcher_input = DVD_INPUT; switcher_output = VPROJ_OUTPUT; // video projector } Note the use of capital letters for the constant definitions.
Crestron SIMPL+ Software Crestron-Libraries are provided from Crestron and are contained within the Crestron Database. Variable Declarations Variables can be thought of as storage areas to keep data. When writing all but the most basic of programs, users need to use variables to store values. Any variable used in a SIMPL+ program must be declared before it is used. This also tells the operating system how much space must be reserved to hold the values of these variables.
Crestron SIMPL+ Software variables are also available with the INTEGER and STRING datatype. Integers are 16 bit quantities. For the 2-series control system, 32 bit quantities are supported with the LONG_INTEGER datatype. Both INTEGER and LONG_INTEGER are treated as unsigned values. Signed versions for both of these datatypes are available by using the SIGNED_INTEGER and SIGNED_LONG_INTEGER datatypes.
Crestron SIMPL+ Software User-Defined Functions The term checksum byte is commonly used in serial communications to represent a byte (or bytes) that is appended to a command string. This byte is calculated from the other characters in the string using some specified algorithm. Checksum bytes are used to provide error-checking when communicating between devices. In programming, it is common to reuse the same code over and over again.
Crestron SIMPL+ This example assumes that the camera unit being controlled continues to move in a given direction until a stop command is issued. Some devices function this way, but others do not. Software DIGITAL_INPUT cam_up, cam_down, cam_left, cam_right; STRING_OUTPUT camera_command; PUSH cam_left { camera_command = "MOVE LEFT"; } RELEASE cam_left { camera_command = "STOP"; } CHANGE Events Change events can be triggered by digital, analog, string, or buffer inputs.
Crestron SIMPL+ Software CHANGE output_value PUSH button1, button2 { } A useful feature of SIMPL+ event functions is that a single input can have more than one event function defined for it. This makes it possible to write one event function for a specific input only and another event function for a group of inputs. Refer to the following example.
Crestron SIMPL+ Software while (1) { // code in here runs // continuously } } This loop runs continuously for as long as the control system is on. If a construct like this is used, it is recommended that a ProcessLogic or Delay function in the loop be included to allow the logic processor a chance to handle the rest of the system. If one of these statements is not included, the operating system forces a task switch at some point in time.
Crestron SIMPL+ Software Analog Inputs/Outputs Analog signals are used in SIMPL to accomplish tasks for which digital signals are inadequate. Typical examples include volume control and camera pan/tilt control. In SIMPL+, analog signals take on even greater importance since they provide an easy way of transferring data (16 bits at a time) into and out of SIMPL+ modules. In SIMPL+, analog signals are treated much as they are in SIMPL.
Crestron SIMPL+ Software SIMPL+ program. The value of any output is the value of the signal as seen by the outside SIMPL program at that instant. This is critical considering that SIMPL+ does not necessarily “propagate” outputs to the SIMPL program each time they are changed in the program. As a general rule, assume that analog and serial outputs are propagated at the time they are assigned new values. However, digital signals are not propagated until a task switch occurs.
Crestron SIMPL+ Software The 'if' language construct is described in detail in “Controlling Program Flow: Branching”. Evaluation of TRUE and FALSE expressions are covered in “Operators, Expressions, and Statements” on page 22. In this example, the digital output, d_out, and the analog output, a_out, are set to 0 on system startup in the Function Main.
Crestron SIMPL+ Software When an integer has a value of between 0 and 32767, it is identical whether it is considered signed or unsigned. However, numbers above 32767 may be treated as negative numbers. If they are, they will have a value of x – 65536, where x is the unsigned value of the number. This means that the value 65,535 has a signed value of –1, 65534 is –2, etc. This scheme is referred to as two’s complement notation.
Crestron SIMPL+ Software Examine one more example: INTEGER a, b, c, d; Function Main() { a = 100; b = -4; c = a / b; // c = 0 (100/65532) d = a S/ b; // d = -25 (100/-4) } Notice that c calculates to zero because the / operator is unsigned. It treats the variable b as +65,532. Since the / operator truncates the decimal portion of the result, c becomes zero. In regard to the variable d, since the signed division operator S/ was used, b is treated as –4 and the result is –25.
Crestron SIMPL+ Software name, as was done when it was declared. When assigning a value to a string, that value is always assigned starting at the first character position. It is important to note that the length of the this value does not exceed total length allocated for myString (in this case, 50 characters). If the declared variable is not large enough to hold the data being assigned to it, the data is truncated to as many characters as the string can hold.
Crestron SIMPL+ Software Notice how the constant parts of the string are entered directly. The interesting thing about the format specification is the %d sequences, which are known as “type specifiers”. Variable Scope Variable declarations in a SIMPL+ program can be either global or local. Global variables are defined in the "Define Variables" section of the code, and "exist" throughout the entire SIMPL+ program.
Crestron SIMPL+ Software The first two examples above define 1D and 2D integer arrays, respectively. The last example looks like it declares a 2D array of strings, yet the comments states that it actually declares a 1D array of strings. Recall that in “Strings”, it was necessary to define the maximum size of the string in square brackets, which is the same notation used for arrays. So, in the example above, nine-element array of 50-byte strings is being declared.
Crestron SIMPL+ Software Operators, Expressions, and Statements This section deals with the core programming elements in SIMPL+. Operators Operators take one or two “operands” and combine them in some way to produce a result. In SIMPL+ operators can be binary (takes two arguments) or unary (takes a single argument). For example, the + operator is binary (e.g., x + y), while the – operator can be binary or unary (e.g., x – y, or –x are valid). Most operators in SIMPL+ are binary.
Crestron SIMPL+ Software Expressions As reading through the later parts of this guide, as well as the latest revision of the SIMPL+ Language Reference Guide (Doc. 5797), the term expression is mentioned in many places. For example, in describing the syntax of the if-else construct, it may be described as the following: if (expression1) { // code to execute } else if (expression2) { // code the execute } In the above example, expression1 and expression2 can be any valid SIMPL+ expression.
Crestron SIMPL+ Software Branching” and “Controlling Program Flow: Loops” on pages 24 and 27, respectively. Statements Statements in SIMPL+ consist of function calls, expressions, assignments, or other instructions. Statements can be of two types: simple or complex. Simple statements end in a semicolon (;).
Crestron SIMPL+ Software Expressions EXPRESSION EVALUATES TO a=3 true if a=3, false otherwise b*4 - a/3 true as long as the result is non-zero 1 always true 0 always false One limitation with the if construct, as shown above, is that the code inside the if is run whenever expression1 evaluates as TRUE, but any code after the closing braces runs regardless. It is often useful to execute one set of code when a condition is TRUE and then another set of code if that same condition is FALSE.
Crestron SIMPL+ Software today = getDayNum(); // gets the current day of the week if (today = 0) { // code to run on } else if (today = 5) { // code to run on } else if (today = 6) { // code to run on } else { // code to run on } // is today Sunday? Sundays // is today Friday? Friday // is today Saturday? Saturdays // only gets here if the first three // conditions are false all other days NOTE: There can be as many if-else statements in a single construct as necessary.
Crestron SIMPL+ Software Examine an example using the switch-case construct. Perhaps there is a variable that should hold the number of days in the current month. The following example uses switch-case to set the value of this variable.
Crestron SIMPL+ Software To see an example of the for loop use the situation alluded to above. That is, a need to clear each string element in a string array. A program to accomplish this might look like the following.
Crestron SIMPL+ Software while and do-until Loops The for loop discussed in an earlier section is useful for iterating through code a specific number of times. However, sometimes the exact number of times a loop should repeat is unknown. Instead, it may be necessary to check to see if a condition is true after each loop to decide whether or not the loop should execute again. There are two looping constructs in SIMPL+ which allows execution of a loop only for as long as a certain condition is true.
Crestron SIMPL+ Software this code, the value of this expression determines whether or not the code should be executed again. Here lies the other difference between the while and do-until. The while loop executes as long as the expression remains TRUE. A do-until loop executes until an expression becomes TRUE. When deciding which type of loop should be used, first understand that using any of the three types of loops discussed here can solve many problems.
Crestron SIMPL+ Software programming task that has been predefined and given a name. Many of the examples in previous sections of this document have used special types of functions called system functions (or built-in functions). To employ system functions, use the following format. returnValue = FunctionName(Parameter1, Parameter2,...); The above syntax is called a function call, because it tells the function (calls it) to cause / perform an action.
Crestron SIMPL+ Software perform exactly like system functions with the only exception in that they must be defined before they are used. Function Definitions Since user-defined functions are created by the user (the SIMPL+ programmer), the user must make sure that the SIMPL+ compiler knows about these functions before the program tries to call them. This is accomplished by creating a function definition, which is different from a function call.
Crestron SIMPL+ Software The FUNCTION keyword is used to tell the SIMPL+ compiler that what follows is the definition of a function and not a function call. The FUNCTION keyword also specifies that there will be no return value for this function. INTEGER_FUNCTION and STRING_FUNCTION specify that an integer or string value will be returned as the result of the function. These keywords are also called the ‘function type’.
Crestron SIMPL+ Software This code causes a compile error, because the function MyUserFunction1 has been called before it has been defined. This can easily be remedied by reversing the order: INTEGER x; FUNCTION MyUserFunction1() { print("This is MyFunction1 runnning!\n"); } INTEGER_FUNCTION MyUserFunction2( INTEGER arg1, STRING arg2 ) { print("This is MyFunction2 runnning!\n"); } PUSH someSignal { call MyUserFunction1(); x = MyUserFunction2( x, 10 ); } This program compiles without any problems.
Crestron SIMPL+ Software Print("i = %d, j = %d, k = %d\n", i, j, k); Call sillyFunction(); Print("i = %d, j = %d, k = %d\n", i, j, k); Call anotherSillyFunction(); Print("i = %d, j = %d, k = %d\n", i, j, k); } In this program, it should be clear to see that both of the functions defined, as well as the push event, have access to the three global integers i, j, and k. Local variables, on the other hand, can only be accessed within the function in which they are defined.
Crestron SIMPL+ Software localStr = left(var3, 10); } Notice that the function shown above has three arguments, named var1, var2, and var3. var1 and var2 are integers, while var3 is a string. Shown below is an example of how to call this function from elsewhere in your program: Call some_function( intVal1, 5+1, stringVal1); Here we are assuming that the variable int1 has been defined as an integer earlier in the program, as has the string variable, string1.
Crestron SIMPL+ Software String1 = itoa(int1); position = find(“Artist”,CD_data); int3 = max(int1, int2); For clarity, here are some example statements using system functions that do not have return values: Print(“Variable int1 = %d\n”,int1); ProcessLogic(); CancelWait(VCRWait); It should be clear that, at least as far as system functions go, whether or not a function returns a value depends largely upon what that function is designed to do.
Crestron SIMPL+ Software Print(“5 raised to the power of 3 = %d\n”,power(5,3)); x = power(y,z); As a second example, we shall build a function which appends a simple checksum byte onto the end of a string. As was mentioned earlier in this manual, checksums are used by many devices to provide a basic form of error checking.
Crestron SIMPL+ Software To solve this problem, SIMPL+ has introduced the concept of function libraries. Simply put, a function library is a collection of user-defined functions placed in a separate file. A library can consist of only a single function, or can consist of every function you have ever written. More likely, you will organize your libraries so that each one contains related functions.
Crestron SIMPL+ Software flash card within the control system. The function will return an error code and the program can act accordingly. Other programs might prompt the end-user to insert a compact flash card. The function, WaitForNewDisk, will halt the program and resume when a compact flash card is detected within the control system.
Crestron SIMPL+ Software DIGITAL_INPUT readCompactFlashCard; DIGITAL_INPUT writeCompactFlashCard; INTEGER myInt; LONG_INTEGER myLongInt; STRING myStr[50]; PUSH writeCompactFlashCard { SIGNED_INTEGER nFileHandle; INTEGER nNumBytes; StartFileOperations() nFileHandle = FileOpen( "\\CF0\\MyFile.
Crestron SIMPL+ Software } myStruct struct; PUSH writeCompactFlashCard { SIGNED_INTEGER nFileHandle; INTEGER nNumBytes; StartFileOperations() nFileHandle = FileOpen( "\\CF0\\MyFile.
Crestron SIMPL+ Software PUSH startMe { Print("I’m starting now..."); Delay(500); //this equals 5 seconds Print("and I’m ending 5 seconds later.\n"); } It is important to realize that the control system never allows a SIMPL+ program to “lock up” the rest of the system for any significant amount of time.
Crestron SIMPL+ Software This syntax defines a wait event to occur at some time in the future, defined by the value of wait_time. While the wait event is pending execution, it is said to have been “scheduled”. The wait event may have an optional name, which can be used to refer back to the event elsewhere in the code.
Crestron SIMPL+ Software Pulse(PULSETIME, vproj_on); } Wait (1500, sysOnWait2) // 15 second delay pulse(PULSETIME, vproj_video); } // end of push event PUSH system_off { CancelWait(sysOnWait1); CancelWait(sysOnWait2); Pulse(2000, screen_up); Pulse(PULSETIME, vproj_off); Pulse(PULSETIME, vcr_off); Pulse(PULSETIME, dvd_off); Wait(500, sysOffWait) { Pulse(9500, lift_up); Pulse(PULSETIME, lights_pre_3); } } // end of push event Notice that in this example, the CancelWait function was used to cancel any pendi
Crestron SIMPL+ Software The Serial Send symbol simply generates the static text defined in its parameter field onto the output serial signal whenever the trigger input sees a rising signal. To make this concept even clearer, consider the following simple example. The SIMPL program shown below contains two Serial Send symbols, each one triggered by a button press. The outputs of these symbols are tied together so that both symbols can generate a string onto the same serial signal.
Crestron SIMPL+ Software second pass: jukebox_in = "k=My Way, Album=Very Good Yea" third pass: jukebox_in = "rs" If this signal, jukebox_in, were then connected to a STRING_INPUT of a SIMPL+ program, it is likely that the string might not be seen as one complete piece. Thus the artist’s name, the track name, and the album name might not be parsed out for display on a touchpanel. On the other hand, if a BUFFER_INPUT were used instead, this buffer would collect the data as it arrived.
Crestron SIMPL+ Software Notice that a do-until loop was used in the example above. Every time a change event is triggered for the data_in buffer, it is uncertain that only one character has been inserted. In fact, many characters may have been added since the last change event. Due to this possibility, continue to pull characters out of the buffer with getc until the buffer is empty, which is what the expression (len(data_in) = 0) reveals.
Crestron SIMPL+ Software tempStr = ""; } This example introduces two new system functions, which are extremely useful for string manipulation, the Find and Mid functions. To search for the existence of a substring inside of another string, use Find. If it is located, the return value of the function is the character position where this string was found. If the substring was not found, then Find returns zero.
Crestron SIMPL+ Software There are two ways to force a task switch: with the ProcessLogic function or the Delay function. To provide an immediate task switch out of the current SIMPL+ module use ProcessLogic. When the logic processor enters this module on the next logic solution, execution begins with the line immediately following. An immediate task switch also results from Delay, but the SIMPL+ module does not continue executing until the time specified has elapsed.
Crestron SIMPL+ Software To determine if a run-time error is occurring in your program, watch the status of the control system's computer port with a program such as the Viewport (available through SIMPL Windows or Crestron VisionTools Pro-e). An "Interrupt" message or some other error message can clue the user in to a problem. Locate the problem by strategically placing Print statements in the code. The Print statement is covered in the next section.
Crestron SIMPL+ Software Software License Agreement This License Agreement (“Agreement”) is a legal contract between you (either an individual or a single business entity) and Crestron Electronics, Inc. (“Crestron”) for software referenced in this guide, which includes computer software and, as applicable, associated media, printed materials, and “online” or electronic documentation (the “Software”).
Crestron SIMPL+ Software If You are a business or organization, You agree that upon request from Crestron or its authorized agent, You will within thirty (30) days fully document and certify that use of any and all Software at the time of the request is in conformity with Your valid licenses from Crestron of its authorized agent. Without prejudice to any other rights, Crestron may terminate this Agreement immediately upon notice if you fail to comply with the terms and conditions of this Agreement.
Crestron SIMPL+ Software Return and Warranty Policies Merchandise Returns / Repair Service 1. No merchandise may be returned for credit, exchange, or service without prior authorization from CRESTRON. To obtain warranty service for CRESTRON products, contact the factory and request an RMA (Return Merchandise Authorization) number. Enclose a note specifying the nature of the problem, name and phone number of contact person, RMA number, and return address. 2.
Crestron SIMPL+ Software This page intentionally left blank. Programming Guide – DOC.
Crestron Electronics, Inc. 15 Volvo Drive Rockleigh, NJ 07647 Tel: 888.CRESTRON Fax: 201.767.7576 www.crestron.com Programming Guide – DOC. 5789A 04.03 Specifications subject to change without notice.
