BASIC Script Tutorial
How to write, debug, and text BASIC scripts for ControlByWeb products.
BASIC is a computer programming language that has been in use for many years. Many ControlByWeb modules have an interpreter that supports many BASIC commands; however, not all BASIC commands are supported. The individual ControlByWeb product's users manual will have more details and examples for all supported commands. A script program used on ControlByWeb modules allows for custom logic and capacities beyond regular settings found in the product's web setup pages.
Most of ControlByWeb advanced products support BASIC scripts (X-300, X-301, X-310, X-320, etc). The X-600M uses a different language for the coding, called LUA. Please see the X-600M's users manual for more information.
This tutorial is not designed to be a comprehensive resource on programming. It is written to give more explanations to users who do not have programming experience. This tutorial will assist in creating a custom BASIC script to do advanced logic tasks on ControlByWeb modules. Also included are a few examples and tricks that more advanced users may find useful to modify for particular applications. Please use this guide along with a ControlByWeb product's users manual and examples to create a script.
To begin talking about the functionality of a script, it is helpful to share an example given in many introductory programming classes ... Think of the standard instructions given on a bottle of shampoo: "Lather, Rinse, Repeat". If these instructions are given to a computer, would the computer ever stop washing hair? No, because there is no exit from the cycle 'Lather, Rinse, Repeat'. The computer would continuously repeat the steps of Lather and Rinse. The point of this simple example is to illustrate that every action and step must be programmed into the script. The script will perform exactly as written.
Every script is written with a different goal in mind. A script written to email every 10 minutes will be very different from a script written to unlock a door during business hours. Even two scripts written for the same purpose may be written differently.
Before the programming steps are shown, it is important to show debugging steps. Every program may have typos, mistakes, or logic errors. Three methods are given to help find errors. All three methods may be used to verify that a script will work correctly.
Method 1 - A Windows utility has been developed to assist in finding errors in scripts. This is a command line utility and is available here: BASIC Script Error Check utility
Method 2 - Anytime a program is uploaded to a module and the code is run, a message will indicate if the programming is running, finished, or has an issue. The module will attempt to identify the error and point out the line in which the error is located.
As you can see in the picture below, the Interpreter Status shows that I misspelled an external variable. It should be spelled 'extvar1'.
Method 3 - Bench test the program. It is highly recommended to explore all options and test all functionality before the module is connected up to live equipment. A bench test should demonstrate that the script will function exactly as intended.
Rules & Restrictions:
Some basic notes to keep in mind when writing and using a script:
- All scripts must be written and then saved to a text file (*.txt) and then uploaded to the module.
- The scripts should be designed to continuously repeat and run within a DO loop. The module will not automatically keep running through the script so you must instruct it to do so.
Basic formatting rules and restrictions:
- The maximum script size is 2KB. To minimize script size, condense logic and delete whitespace.
- Spacing is important: "a=1" will not work. "a = 1" is correct. You must have one space between all operations.
- Only one operation per line.
- You may have up to five nested operations. An example would be up to five IF statements within each other.
- Variables are case sensitive. Commands/logic are not case sensitive.
- Comments may be inserted into the code by using the ' apostrophe or REM (for remark). It is good practice to include comments in your code for explanation.
- All scripts will start when the module boots up and will restart any time settings are submitted. Scripts should be written accordingly.
- The "Run Script" offers the option to enable or disable the script. If the script is disabled, the ControlByWeb module will not run the script program.
This guide will cover the elements of BASIC supported on CBW modules with some descriptions, explanations, and examples. Please refer to the correct users manual for information on a specific module.
The first few examples will only include a short section of code. The latter examples will be complete scripts and are fully functioning programs.
For your convenience, all commands are in capital letters in the following examples:
Common elements of the BASIC script used on ControlByWeb units:
- The LET statement
- The IF Statement
- Inputs and Outputs
- Relay Outputs
- Math operations
- The DO Loop
- The DO WHILE loop
- The FOR loop
- The SUB Routine
The LET Statement
The LET statement assigns a value to a variable or output. The variable or output to be assigned must be on the left, and the value to be assigned must be on the right.
LET relay1 = 1 'Assigns the value of 1 to the variable "relay1" 'Will turn relay on LET relay1 = 0 'Will turn off relay1 LET extvar1 = 100 'Change external variable 1 to value of 100 LET a = 20 'Will assign a value of 20 to the variable "a"
The IF, ELSE, END IF Function
The IF statement allows the script to check specific criteria. If the statement is found to be true, it will run the code following the IF statement. If the statement is found to be false, the script will not run the code following the IF statement. Also if the IF statement is found to be false, the script will run the code following the ELSE statement. The ELSE statement is optional. The 'END IF' signifies the end of the code associated with the IF statement. Each IF statement must have an 'END IF'.
You may use the following operands: =, <, >, <=, >=, or <> (<> is the equivalent of 'not equal to' or != in some program languages)
IF (variable) (=, <, >, <=, >=, <>) (expression) THEN (code to be run if true) ELSE (code to be run if false) END IF
Note that the ELSE statement and (code to be run if false) is optional. See the following example:
IF (variable) (=, <, >, <=, >=, <>) (expression) THEN (code to be run if true) END IF
Please note that every IF statement must have an END IF statement associated with it. If there are two IF statements nested one within another, there must be two END IF statements.
Indenting is a popular method to help show nested IF statements and is recommended to separate each IF statement visually and insure that each IF statement has an END IF associated with it.
IF a = b THEN '1st IF statement (code to be run if a = b) IF b = c THEN '2nd IF statement (code to be run if a = b and b = c) END IF 'END IF for 2nd IF statement END IF 'END IF for 1st IF statement
IF a = b THEN '1st IF statement (code to be run if a = b) IF b = c THEN '2nd IF statement (code to be run if a = b and b = c) ELSE 'ELSE for 2nd IF statement (code to be run if a = b and b <> c) (<> - not equal to) END IF 'END IF for 2nd IF statement ELSE 'ELSE for 1st IF statement (code to be run if a <> b) (<> - not equal to) END IF 'END IF for 1st IF statement
Example 1: Check an input and if the input is on, turn on a relay. Please note that in this example there is no method of turning the relay off.
'This command will turn on relay1 when input1 is on. IF input1 = 1 THEN 'Check to see if input1 is on LET relay1 = 1 'Turn on relay1 only if input1 is on END IF
Example 2: Check an input and have the relay follow the input. The relay will turn on if the input is on.
'This command will turn on relay1 when input1 is on, and turn off 'relay1 when input1 is off IF input1 = 1 THEN 'Check to see if input1 is on LET relay1 = 1 'If input1 is on, then relay1 will turn on ELSE 'Else (If input1 is off (input1 = 0)) LET relay1 = 0 'Then it will turn off relay1 END IF 'Declare the end of the IF
Example 3: Turn on a relay if both inputs are on. A real-world example could be to turn on a light indicating that both elevators are malfunctioning and that patrons should take the stairs. To check multiple items, the IF statements may be stacked inside of each other.
'This command will only turn on relay1 when input1 AND input2 are 'both on, otherwise relay1 will be off. IF input1 = 1 THEN 'If input1 is on IF input2 = 1 THEN 'If input2 is on LET relay1 = 1 'Turn on relay1 ELSE 'If input2 is off (input2 = 0) LET relay1 = 0 'Turn off relay1 END IF 'End of IF input2 = 1 ELSE 'If input1 is off (input1 = 0) LET relay1 = 0 'Turn off relay1 END IF 'End of IF input1 = 1
Example 4: Turn on a relay if either input 1 or 2 are on. A real-world example would be to sound an alarm if either a front door or back door is open.
'This command will turn on relay1 when input1 OR input2 is on, 'otherwise relay1 will be off. 'You may also follow the method above in example 3, 'but with the logic reversed. IF input1 = 1 THEN 'If input1 is on LET relay1 = 1 'Turn on relay1 (if input 1 is on) END IF IF input2 = 1 THEN 'If input2 is on LET relay1 = 1 'Turn on relay1 (if input2 is on) END IF IF input1 = 0 THEN 'If input 1 is off IF input2 = 0 THEN 'If input2 is off LET relay1 = 0 'Turn off relay1 if both input1 and input2 'are off END IF END IF 'END IF for 1st IF statement
The script incorporates two main types of variables: User-defined (internal) and external variables. For the purpose of this tutorial, inputs and outputs fall under variables.
Here is a sample list with descriptions of possible input and output names as used within a script. Many devices have multiple inputs or outputs, only the first is shown here. The analog (ana1), temperature sensor (temp1), and digital input (input1) are read only and cannot be assigned values. The relay (relay1), counter (count1), and external variable (extvar1) can be either read or can be assigned a value. The remote relay (rmt_relay1) can only be written:
|Analog 1:||ana1||Read only|
|Sensor 1 (temp/humidity):||temp1||Read only|
|Input 1:||input1||Read only|
|External Variable 1:||extvar1||Read/Write|
|Remote Relay 1:||rmt_relay1||Write only|
This is a reference list for all of our products. Not all modules contain all of the Inputs and Outputs listed above. Some modules contain multiples of the above mentioned Inputs and Outputs, (i.e. input1, input2, input3, and input4). Please refer to the appropriate users manual for information regarding a specific module.
Relays and Remote Relays may be turned off, on, toggled, and pulsed from the script
LET relay1 = 0 'Turn relay1 off LET relay2 = 1 'Turn relay2 on LET relay3 = 2 'Pulse relay 3 according to pulse time in setup pages 'Pulsing will turn the relay on for the specified 'time, and then turn off LET rmt_relay4 = 5 'Toggle remote relay 4
Variables: Internal Variables(Only to be used within the script)
Up to 10 user variables may be used within the script. These variables may be used to hold values, be used as flags, or used in calculations. These must be single character and lower case (i.e., a, b, c, d, e, f, g, h, i, j). Internally they can be accessed from any point within the script and are stored as floating point numbers. Floating point numbers may be positive or negative and can have decimal places.
LET a = 5 'Assign the value of 5 to variable a. LET b = temp1 + temp2 'Add temperature values 1 and 2 together LET b = b + temp3 'Add another temperature value to the existing 'value of b. The previous 'command and this command will add three 'temperature values together. 'The previous value of b will be overwritten LET extvar1 = b / 3 'Average of temp1, temp2, and temp3 is assigned 'to external variable 1 LET d = relay1 'Read the state of relay1 and assign the value 'to 'a'. State will be 0 or 1
Variables: External Variables
External variables may be used to create user-interaction with the script. They are variables that can be changed or viewed external to the script. External variables may be used to display a value calculated within the script. They may also be used to input logic or a value into the script (a desired temperature for instance). Some modules have specific external variables that only function as binary (on or off), and other variables that hold a floating point value.
This example will display a value calculated within the script. The external value will display a count of how many inputs are on.
LET a = 0 'Reset the value of 'a' IF input1 = 1 THEN 'Check to see if input1 is on LET a = a + 1 'Increment 'a' by 1 END IF IF input2 = 1 THEN 'Check to see if input2 is on LET a = a + 1 'Increment 'a' by 1 END IF LET extvar1 = a 'Set extvar1 equal to the value of 'a' for display
The following operations may be performed within the BASIC script: + - * / %
These symbols are fairly explanatory. We have included some examples below:
Please note the spacing is required. "LET a=temp1/2" will not work. "LET a = temp1 / 2" will work.
LET extvar0 = temp1 + temp2 LET extvar1 = extvar0 / 2 LET extvar2 = temp1 * 105.4 LET extvar3 = temp3 - temp2
% Modulus will return the remainder of a division. It is useful in a few specific circumstances. See a few examples of MODULUS below:
LET extvar0 = 1234 % 1000 '(extvar0 would be set to 234) LET extvar1 = 1234 % 100 '(extvar1 would be set to 34) LET extvar2 = 1234 % 10 '(extvar2 would be set to 4)
Six timers are available for use within the BASIC script. t0, t1, t2, t3, t4, t5 The timers can be assigned a value greater than 0, and will start counting down until 0 is reached. The timer counts down by 1 every tenth of a second, or 0.1 seconds, so t1 = 600 would be equivalent to 60.0 seconds. The timers will start counting down as soon as a value is assigned:
Please note that the timers do not stop the program. The program will assign the timers a value and move on to other parts of the script. Extra steps must be taken to hold the script in specific spot while the timer is counting down to 0, or check later when a timer is equal to 0.
Example 1: Set timer for a couple of random times
LET t1 = 100 'Timer = 10.0 seconds LET t2 = 36000 'Timer = 60 minutes Note: 60 minutes = 3600.0 seconds
Example 2: A straightforward method of using the timer. Please note the script will only run in the SUB routine until the timer is finished counting down. This method is clean because the program will do nothing while the counter is counting down. This uses a SUB and DO WHILE routine, which are covered later. The approach of using SUB routines are useful if the same section of code is used many times. A real-world example for this script would be that an alarm sounds after a door has been open for 10 seconds. The alarm will turn off after the door has been closed. A door sensor is connected to input1.
'This example will turn on a relay after an input has been on for 10 seconds LET relay1 = 0 'Make sure the relay is off when script starts DO 'Begin main program loop IF input1 = 1 THEN 'Checks if input1 is on - Door is open CALL delay 'Calls the delay function IF input1 = 1 THEN 'After the delay is done, it will check the door again LET relay1 = 1 'Turns the relay on, sounding alarm END IF ELSE 'IF input1 is off - door is closed LET relay1 = 0 'Turn relay1 off, turning off the alarm after closed door END IF 'End of IF input1 = 1 LOOP 'Loop main programmed END 'End main program loop SUB delay 'SUB function LET t1 = 100 'Set timer = 10.0 seconds DO WHILE t1 > 0 'Loop while timer is counting down LOOP 'End of the DO WHILE loop END SUB 'End of the SUB routine
Example 3: This is the same as Example 2 above, but includes a trigger to exit the timer if the input turns off before 10 seconds is up. This will help insure that the alarm will only turn on if the door has been open for 10 seconds. The timer will restart any time the door closes and is a better setup than the example above.
'This example will turn on a relay after an input has been on for 10 seconds LET relay1 = 0 'Make sure the relay is off when script starts DO 'Begin main program loop IF input1 = 1 THEN 'Checks if input1 is on - Door is open CALL delay 'Calls the delay function IF input1 = 1 THEN 'After the delay is done, it will check the door again LET relay1 = 1 'Turns the relay on, sounding alarm END IF ELSE 'IF input1 is off - door is closed LET relay1 = 0 'Turn relay1 off, turning off the alarm after closed door END IF 'End of IF input1 = 1 LOOP 'Loop main program END 'End Main Program loop SUB delay 'SUB function LET t1 = 100 'Set timer = 10.0 seconds DO WHILE t1 > 0 'Loop while timer is counting down to 0.0 seconds. IF input1 = 0 THEN 'If the input turns off (door closed), it will exit loop LET t1 = 0 'Sets timer to 0 to exit loop END IF 'End of IF input1 = 0 LOOP 'Loop the DO WHILE statement above END SUB 'End of the SUB routine
Example 4: The same example as above: after an input turns on (door opens), wait 10 seconds before turning on a relay (alarm). This is a little more complex as it uses a flagging variable instead of a sub routine. The script will continue to run through the entire program loop while the timer is counting down. This method is beneficial if the script is doing multiple items and cannot stop while a timer is running. This is the best universal type setup and is most often used because it will work well if the script is doing multiple items.
LET a = 0 'Timer flag variable set to 0 before loop begins LET relay1 = 0 'Start the script with the relay off DO 'Begin main program loop IF input1 = 1 THEN 'If input turns on - door open IF a = 0 THEN 'If timer has not already been set LET t1 = 100 'Set timer to 10.0 seconds LET a = 1 'Set timer flag so the timer is not constantly reset to 100 END IF ELSE 'IF input1 is off - door is closed LET relay1 = 0 'Turn the relay off if input 1 is off - turn alarm off LET a = 0 'reset timer flag variable END IF IF t1 = 0 THEN 'If timer has now counted down to 0 IF input1 = 1 'Make sure the input is still on (door still open) IF a = 1 THEN 'If timer flag is set to active LET relay1 = 1 'Turn on relay (sound alarm) LET a = 0 'Reset the timer flag END IF ELSE 'If input has been turned off LET a = 0 'Turn off timer flag variable so relay will remain off END IF END IF LOOP 'Loop main program END 'End Main Program loop
Example 5: The following script is also designed to turn on a buzzer after a door has been open for 10 seconds. This script will continually run through all of the code, but does not include a flag variable like example 4. This is a very simple piece of code, very small, and more efficient that the other examples. The concept is that the timer is continually set to 10 seconds while the door is closed. If the timer expires, then the buzzer will sound. As soon as the door closes again, the timer will be reset and the buzzer will turn off.
DO IF input1 = 0 THEN 'If door is closed LET t1 = 100 'Set timer for 10 seconds LET relay1 = 0 'Turn off buzzer END IF IF t1 = 0 THEN 'If timer is expired (door has been open for 10 sec) LET relay1 = 1 'Turn on buzzer END IF LOOP 'Loop the program END 'End main program loop
Example 6: The following script uses two different timers at the same time. Timer 1 will turn on a buzzer if a door has been open for 30 seconds. Timer 2 will turn on a different buzzer connected to relay2 when a window has been open for 6 hours. Both timers are run separately and will operate correctly regardless of the other timer operation.
LET t1 = 0 LET t2 = 0 DO 'Door Buzzer IF input1 = 0 THEN 'If door is open then LET t1 = 300 'Set timer for 30.0 seconds LET relay1 = 0 'Turn off relay ELSE IF t1 = 0 THEN 'If timer has expired LET relay1 = 1 'Turn on Door buzzer END IF END IF 'Window Buzzer IF input2 = 0 THEN 'If window is closed LET t2 = 21600.0 'Six hours or 21600.0 seconds LET relay2 = 0 'Keep relay off if input2 is off (window closed) ELSE 'Else if windows is open IF t2 = 0 THEN 'and timer has expired LET relay2 = 1 'Turn the relay on END IF END IF LOOP 'loop the program END
The current date and time may be used for logic within the script. This may be useful in many circumstances. The date uses mm/dd/yyyy format, and the clock time uses hh:mm:ss (24 hour time):
IF time > 05:00:00 THEN 'Check to see if current time is after 5:00AM LET relay1 = 1 'Turn on relay1 if it is after 5:00AM END IF IF time < 21:00:00 THEN 'Check to see if current time is before 9:00PM LET relay1 = 0 'Turn off relay1 if it is before 9:00PM END IF IF date > 06/30/2014 THEN LET extvar1 = 1 'Set extvar1 to 1 if current date is after 6/30/2014 END IF
Time and Date variables are also available for use. Up to five date variables are available, and up to five time variables are available. More information may be found in the users manual.
LET et1 = 16:30:00 'Set the time variable to a specific time LET et2 = et1 + 3600 'Increment et1 by 1 hour (3600 seconds) LET ed1 = 03/17/2015 'Set the date variable to a specific date LET ed2 = ed1 + 1 'Add 1 day to the date held in date variable 1
Example 1: Send an email at 4:00 AM every day with information about sensor 1.
IF time = 04:00:00 THEN EMAIL temp1 END IF
Example 2: Only send an email if input1 turns on after 10PM and before 5AM. Input1 is connected to a door sensor to alert someone that a door has opened outside of business hours. It will send an email immediately and then every 5 minutes as long as the door is open.
LET t1 = 0 'Set timer to 0 DO IF time < 05:00:00 THEN 'If earlier than 5:00 AM IF input1 = 1 THEN 'Check to see if input1 is on IF t1 = 0 THEN 'Check to see if email sent in last 5 minutes EMAIL input1 'Send an email according to input1 email config LET t1 = 3000 'Timer is 5 minutes or 300.0 seconds END IF END IF END IF IF time > 22:00:00 'If later than 10 PM IF input1 = 1 THEN 'Check to see if input1 is on IF t1 = 0 THEN 'Check to see if email sent in last 5 minutes EMAIL input1 'Send an email according to input1 email config LET t1 = 3000 'Timer is 5 minutes or 300.0 seconds END IF END IF END IF LOOP END
Example 3: Turn on relay1 on weekdays (M-F) 8am to 5pm and 10am to 2pm on Saturday. This will unlock a door during business hours. This could be a magnetic lock that will lock the door. A manual keyed lock may also be used to secure the door as an independent door lock mechanism.
'Calculate which day of the week it is. j will be the day of the week starting on Monday. 'Monday = 0, Tuesday = 1, Wednesday = 2, Thursday = 3, Friday = 4, Saturday = 5, Sunday = 6 'Note the numbers corresponding to dayofweek may be changed by adding a different number to date Do LET i = date + 3 'Date is an integer and add 3 days LET j = i % 7 'Modulus command to find remainder of division by 7 days LET extvar3 = j 'Set day of week to external variable for debugging IF j < 5 THEN 'If day is Mon to Fri (days 0 - 4) IF time > 08:00:00 THEN 'If time is after 8AM IF time < 17:00:00 THEN 'If time is before 5 PM LET relay1 = 1 'Turn on relay1 ELSE LET relay1 = 0 'Turn off relay1 if after 5PM END IF ELSE LET relay1 = 0 'Turn off relay1 if before 8AM END IF END IF IF j = 5 THEN 'If day is Saturday (day 5) IF time > 10:00:00 THEN 'If time is after 10AM IF time < 14:00:00 THEN 'If time is before 2PM LET relay1 = 1 'Turn on relay1 ELSE LET relay1 = 0 'Turn off relay1 if after 2PM END IF ELSE LET relay1 = 0 'Turn off relay1 before 10AM END IF END IF IF j = 6 'If day is Sunday (day 6) LET relay1 = 0 'Turn off relay1 END IF LOOP END
Example 4: This code will return what day of the year it is. For example, June 30 is day 181 (on non-leap years).
'Note, script will need to be updated on leap years. LET a = date - 11 'Days since 1/1/1970 minus 11 leap days since 1970 LET a = a % 365 'Output is day of the year (0-364) LET a = a + 1 'Changing output to day of year (1-365) LET extvar3 = a 'Show day of year for debugging purposes IF a <= 181 THEN ' (code to run or flag to be set if June 30 or earlier) END IF IF a > 181 THEN ' (code to run or flag to set if July 1 or later) END IF
The script has the ability to send email. A compatible SMTP server and email addresses must be configured in the setup pages. A few options exist for the EMAIL statement. A few examples are shown below:
EMAIL 'Send email to all addresses under the Network Tab EMAIL relay2 'Send state change message according to email preferences for relay2 EMAIL temp1 'Send state change message according to email preferences for sensor1 EMAIL ana1 'Send state change message according to email preferences for analog1
Example 1: Send an email alarm every hour while the temperature is greater than 32 degrees. Also will reset the alarm after temperature drops below 30 degrees. A real-world example would be freezer monitoring. A restaurant's large walk in freezer may malfunction or the door may be left open. The CBW module can send the manager an email/text if the temperature rises above freezing. This script will continuously send an email/text every hour while the malfunction is occurring to prevent the loss of food.
LET a = 0 'Email sent flag LET t1 = 0 'Set timer = 0 DO 'Beginning of main program (looping) IF temp1 > 32 THEN 'If temperature is more than 32 IF a = 0 THEN 'Check the email sent flag (0 = not sent) EMAIL temp1 'Send email LET a = 1 'Set email sent flag to true LET t1 = 36000 'Set timer to 3600.0 seconds (1 hour) END IF END IF IF temp1 < 30 'If temperature is less than 30 LET a = 0 'Reset email sent flag END IF IF t1 = 0 THEN 'If timer has expired (1 hour has passed since last email) LET a = 0 'Change email sent flag to false to trigger another email END IF LOOP 'Main program loop END 'End of main program
Example 2: Send an email only one time when input is on and temperature is more than 45 degrees. A real-world example could be a large commercial refrigerator that is occasionally used to hold excess fruit and vegetable produce. An email alert is only needed when the refrigerator is actually being used (as indicated by input1) and temperature has risen above 42 degrees. If the refrigerator is not being used, it is turned off to conserve electricity and so email notification would not be needed (input1 would be off).
LET a = 0 'Email sent flag DO 'Begin main program (looping) IF input1 = 1 THEN 'If Input is on IF temp1 >= 42 THEN 'If temperature is more than or equal to 45 degrees IF a = 0 THEN 'Check the email sent flag EMAIL temp1 'Send email LET a = 1 'Set email sent flag to prevent multiple emails END IF ELSE 'Else if temp less than 42 LET a = 0 'Reset email sent flag END IF ELSE 'Else if input1 is off LET a = 0 'Reset email sent flag END IF LOOP 'Loop main programmed END 'End of main program
A log may be triggered from the script: LOG. The log will record the inputs and outputs as configured in the logging preferences in the setup.
Example 1: Log whenever input1 is triggered. A flag is utilized to only log once any time the input turns on. A real-world example would be to log the time whenever a door is open at a remote site.
LET a = 0 'Log flag DO 'Begin main program (looping) IF input1 = 1 'If input1 is on IF a = 0 'If log flag is false LOG 'Put an entry in the log LET a = 1 'Set log flag to true END IF ELSE 'If input1 is off LET a = 0 'Set log flag to false END IF LOOP 'Loop main program END 'End of main program
The Do Loop
The DO loop is necessary to keep the program repeating. Without the loop, the script would only run once upon startup and upon submitting settings within the CBW module. You may have seen this in some previous examples.
DO (insert code here) LOOP END
Some lines of code may only need to be run once before the main body of the script continually repeats. This would be a convenient method to insure that relays, counters, etc are in a specific state before the main body of the script starts repeating. An example would be that all relays must be off when a script starts.
(code to only run once) DO (insert repeating code here) 'Main body of the script LOOP END
Example 1: Continuously turn on a relay if the input turns on. This could be a door sensor to a secured room, and an alarm connected to the relay should sound if the door is opened.
DO 'Signals the start of the repeated section of code IF input1 = 1 THEN 'Checks input1 to see if it is on LET relay1 = 1 'If true, turns on relay1 to activate alarm ELSE 'Else if input1 is off LET relay1 = 0 'Turn off relay1 END IF LOOP 'Program will cycle back to the DO and restart END
The DO WHILE Function
The DO WHILE loop will continue looping while the condition is true. It will not exit the loop until the condition is false.
DO WHILE (variable) ( =, <, >, <=, >=, <>) (expression) (code to be looped) LOOP
Example 1: This statement will continuously loop keeping relay1 on while input1 is on. Note how there is no method of turning relay1 off. The CBW module will not run code in other parts of the script until this loop is exited by turning input1 off.
DO WHILE input1 = 1 LET relay1 = 1 LOOP
Example 2: This statement will stop in the DO WHILE loop until the timer has counted down to zero.
LET t1 = 100 DO WHILE t1 > 0 'wait LOOP
Example 3: This script will turn on relay1 20 seconds after input1 has turned on. If input1 turns off, the timer will be stopped. This is a complete script. A real-world example would be an alarm sounds if a door has been open for 20 seconds. As soon as the door closes, the alarm will turn off.
DO IF input1 = 1 THEN 'Checks to see if input1 is on LET t1 = 200 'Set timer = 20.0 seconds DO WHILE t1 > 0 'Continues until t1 equals 0 IF input1 = 0 THEN 'If input1 turns off LET t1 = 0 'Exit loop by setting timer to 0 END IF LOOP IF input1 = 1 THEN 'Check to make sure input is still on after delay LET relay1 = 1 'Turn on relay1 END IF ELSE 'If input1 = 0 LET relay1 = 0 'Turn off relay1 END IF LOOP 'Loop the program back to DO END
The FOR Loop
The FOR loop will loop through a section of code a predefined number of times. The NEXT statement always follows the section of code to be looped
LET t1 = 100 FOR (variable) ( =, <, >, <=, >=, <>) (expression) TO (expression) (code to be looped) NEXT (variable)
Example 1: Toggle relay1 for ten times waiting 3 seconds between each toggle. After a > 9, the FOR loop will stop.
FOR a = 0 TO 9 'Starts the FOR loop starting with a = 0 until a > 9 LET relay1 = 5 'Toggles relays1 LET t1 = 30 'Timer to wait 3.0 seconds DO WHILE t1 > 0 LOOP NEXT a 'Increment 'a' by 1, and restart loop until a > 9
The SUB Routine
The SUB routine adds the ability to separate a piece of code that is commonly used. This may help cut down on script size. Note that the sub routine name is case sensitive and can have a max name length of 20 characters. The CALL statement is used to jump to the sub routine function. The sub routine is typically listed below the main DO program loop.
DOCALL (sub routine name) LOOP END SUB (sub routine name) (code to be run) END SUB
Example 1: An alarm light timing sequence may be called from two different sources, a button connected to input1, or remotely by turning on external variable 1. The alarm will continue as long as input1 or extvar1 remain on.
DO IF input1 = 1 THEN 'if button is pushed CALL alarm 'start alarm sequence END IF IF extvar1 = 1 THEN 'if remote functionality enabled CALL alarm 'start alarm sequence END IF LOOP END SUB alarm 'sub routine 'alarm' LET relay1 = 1 'turn on relay1 CALL delay 'call delay sub routine LET relay1 = 0 'turn off relay1 CALL delay 'call delay sub routine LET relay1 = 1 'repeat a few times CALL delay LET relay1 = 0 END SUB 'end of Sub routine SUB delay 'sub routine 'delay' LET t1 = 50 'set timer = 5.0 seconds DO WHILE t1 > 0 'waiting until timer counts to 0 'wait LOOP END SUB 'end of sub routine
Sample BASIC Scripts:
These examples are complete scripts. All scripts include a description and comments. These are available for example and may be tailored to fit your needs.
Example 1: This script will count the number of times that input 2 is on by incrementing the value of external variable 0 every time the input is triggered.
LET extvar0 = 0 'Sets extvar0 to 0 before beginning the repeating program DO IF input2 = 1 THEN 'If input2 is on CALL on 'Call the sub program END IF LOOP 'Loop main program END 'End of main program SUB on 'Beginning of sub routine LET extvar0 = extvar0 + 1 'Add 1 to extvar0 DO WHILE input2 = 1 'Stay looping while input2 is on LOOP 'repeat END SUB 'End of sub routine
Example 2: Often, a person desires to have manual control of an automated system. The following example script will show one of the many methods available to enable manual control. Extvar1 will be used to enable manual control. If Extvar1 is off, the module will operate in automatic mode. If Extvar1 is on, manual mode is enabled and the script will not operate. The script, when in automatic mode, is designed to simply turn on a relay when an input is on, and turn off the relay when the input is off. In manual mode, the relay may be manually turned on or off independent of the input state.
LET extvar1 = 0 'Set to automatic mode when script starts as a fail safe DO 'Beginning of main program DO WHILE extvar1 = 0 'Loop when extvar1 signifies automatic mode IF input1 = 1 THEN 'Relay1 will follow Input1 LET relay1 = 1 ELSE LET relay1 = 0 END IF 'End of IF statement LOOP 'End of DO WHILE loop LOOP 'Loop the main program END 'End of the main program
Example 3: This example will emulate a 3-way switch as used in typical building wiring. Two different switches will toggle a light on and off. An example would be two switches can be used to turn on or off building lighting.
LET a = input1 'Set a = input1 before looping begins LET b = input2 'Set b = input2 before looping begins DO IF a <> input1 THEN 'If a is not equal to input1 LET relay1 = 5 'Toggle relay1 (switch the state of relay1) LET a = input1 'Set a equal to the new input1 state END IF IF b <> input2 THEN 'If b is not equal to input2 LET relay1 = 5 'Toggle relay1 (switch the state of relay1) LET b = input2 'Set b equal to the new input2 state END IF LOOP 'Repeat/loop the program END 'End
Example 4: This script checks the difference between temperature sensors 1 and 2. It then assigns that value to external variable 1. If the value is greater than a value set by the user in external variable 0, it will then turn on relay 1. Otherwise relay 1 is turned off.
A real-world example use of this script would be having a room that consistently gets hot (due to an oven). The script will automatically turn on a fan only when needed to move cooler air into the room. The difference in temperature may be viewed by looking at external variable 1. The temperature difference when the fan turns on may be modified by adjusting external variable 0.
'basic script that reacts to extvar4 changing states LET a = 300 'evaluate temperature difference every 30.0 seconds LET t0 = 0 'start timer at 0 'loop forever DO 'if our timer is expired then IF t0 <= 0 THEN LET t0 = a 'reset timer LET extvar1 = temp1 - temp2 'find difference 'if difference is greater than user specified different IF extvar1 > extvar0 THEN LET relay1 = 1 'turn relay on ELSE LET relay1 = 0 'turn relay off END IF END IF LOOP 'main program LOOP END 'end of main program
Example 5: This script will send an email when a sensor is off for 30 minutes, then send another email if the sensor turns back on. If the sensor goes off for less than 30 minutes, then turns back on, no email will be sent. A real-world example would be perhaps if the power goes out for 30 minutes, then an email will be send every 30 minutes until the power turns back on.
LET a = 0 'flagger variable to prevent multiple emails LET b = 0 'alarm state for sensor off for 30 minutes LET t1 = 0 'set timer to 0 DO 'begin main program loop IF input1 = 0 THEN 'check if sensor is off IF a = 0 THEN 'if no email sent LET t1 = 18000 'set timer for30 min LET a = 1 'set flag to send email in 30 minutes END IF IF t1 = 0 THEN IF a = 1 THEN 'send email when timer = 0 EMAIL input1 'if input11 off for 30 min send email LET b = 1 'set alarm on LET a = 0 'reset timer END IF END IF ELSE 'if sensor is on LET a = 0 'reset email sent flag variable to 0 IF b = 1 THEN 'if alarm was activated EMAIL input1 'send email that sensor is okay LET b = 0 'email 'everything okay' sent END IF END IF LOOP END
Example 6: This script is designed to run on an WebRelay - 10. It uses one button (extvar0 and extvar1) to turn on or off multiple relays for ease of use. User can click one button to turn on a set number of relay all at once. Note that the external variables are reset to a value of 2 after each use so the end user may turn on or off lights as needed after the main group has been turned on or off.
LET extvar0 = 2 LET extvar1 = 2 DO IF extvar0 = 1 THEN 'If external variable 0 is changed to 1 LET relay1 = 1 'Turn on the following relays LET relay2 = 1 LET relay3 = 1 LET relay4 = 1 LET relay5 = 1 LET relay6 = 1 LET relay7 = 1 LET relay8 = 1 LET relay9 = 1 LET relay10 = 1 LET extvar0 = 2 'Change extvar0 to the number 2 for manual control END IF IF extvar0 = 0 THEN 'If external variable 0 is changed to 0 LET relay1 = 0 'Turn off the following relays LET relay2 = 0 LET relay3 = 0 LET relay4 = 0 LET relay5 = 0 LET relay6 = 0 LET relay7 = 0 LET relay8 = 0 LET relay9 = 0 LET relay10 = 0 LET extvar0 = 2 'Change extvar0 to the number 2 for manual control END IF IF extvar1 = 1 THEN 'If external variable 1 is changed to 1 LET relay3 = 1 'Turn on two relays LET relay4 = 1 LET extvar1 = 2 'Change extvar1 to the number 2 for manual control END IF IF extvar1 = 0 THEN 'If external variable 1 is changed to 0 LET relay3 = 0 'Turn off two relays LET relay4 = 0 LET extvar1 = 2 'Change extvar1 to the number 2 for manual control END IF LOOP END
Example 7: This script is designed to operate on an X-310 with a boiler with a fan connected to the relays. The fan has a 30-second delay timer after the boiler turns on or turns off. The temperature is controlled via extvar1. If the average of three temperatures is lower than extvar1, then the boiler will turn on until the average temperature is above extvar1 + 1. If the average temperature exceeds 80F, then an email alert will be sent. Average temperature is written to Extvar2. Extvar3 may be turned on for a 1Hour boiler on override. NOTE: This script with comments exceeds the 2KB size limit. The comments must be removed before uploading the script to a unit.
LET a = 100 'Avg Temp variable LET relay1 = 0 'Boiler Relay LET relay4 = 0 'Fan relay LET extvar3 = 0 '1 Hr Boiler Override set to off 'extvar0 has already been configured to switch between automatic and manual mode 'extvar1 has already been configured to input desired temperature 'extvar2 has already been configured to show the calculated average temp DO 'Main Program Loop IF extvar3 = 1 THEN '1 Hour boiler on override LET relay1 = 1 'Turn boiler on sequence CALL delayFan LET relay4 = 1 LET t1 = 33000 'Wait 55 minutes DO WHILE t1 <> 0 CALL calcTemp IF extvar3 = 0 THEN LET t1 = 0 END IF LOOP LET extvar3 = 0 'Turn boiler off sequence LET relay1 = 0 CALL delayFan LET relay4 = 0 END IF CALL calcTemp IF extvar0 = 0 THEN 'Automatic Mode enabled 'Turn on Boiler IF a < extvar1 THEN 'If cooler than set temp IF relay1 = 0 THEN 'If boiler is off LET relay1 = 1 'Boiler on CALL delayFan '30 second delay LET relay4 = 1 'Fan on END IF END IF 'Turn off boiler IF a > extvar1 + 1 THEN 'If hotter than set temp + 1 IF relay1 = 1 THEN 'If boiler is on LET relay1 = 0 'Turn off boiler CALL delayFan '30 second delay LET relay4 = 0 'Turn off fan END IF END IF END IF LOOP 'main program loop END 'End of main program 'Delay the fan by 30 seconds after boiler turns on and turns off SUB delayFan Let t1 = 3000 '300.0 seconds DO WHILE t1 <> 0 CALL calcTemp LOOP END SUB 'End of SUB delayFan 'Averaging 3 temperatures SUB calcTemp LET i = 0 'sum LET j = 0 'count 'Check each temperature to insure it is valid before sum IF temp1 > 10 THEN IF temp1 < 100 THEN LET i = i + temp1 LET j = j + 1 END IF END IF IF temp2 > 10 THEN IF temp2 < 100 THEN LET i = i + temp2 LET j = j + 1 END IF END IF IF temp3 > 10 THEN IF temp3 < 100 THEN LET i = i + temp3 LET j = j + 1 END IF END IF 'Averaging the temperatures If j <> 0 THEN 'If more than 0 temperatures are summed together LET a = i / j 'Division of total temperature / total summed LET extvar2 = a 'Assign the average temperature to extvar2 IF a < 60 THEN 'Email if average temp is under 60 EMAIL END IF IF a > 80 THEN 'Email if average temp is over 80F EMAIL END IF ELSE 'Set a to 100 to keep boiler from operating if temps invalid LET a = 100 LET extvar2 = 0 END IF END SUB 'End of SUB calcTemp
Example 8: This script is for a WebSwitch Plus and is used by a coffee shop to automatically turn on a boiler to heat water for the coffee for a specific amount of time at certain times of the day and whenever someone walks in through the door. The script also enables the shop owner to manually turn on the boiler through a button at the store and while logged onto the WebSwitch Plus. NOTE: This script with comments exceeds the 2KB size limit. The comments must be removed before uploading the script to a unit.
- Input1 is a motion sensor that detects when someone comes in the front door
- Input2 is a push button that the shop owner can press to heat the water
- Extvar1 is how long the boiler will be on for when a customer walks through the door
- Extvar2 is how long the boiler will be on for when the owner pushes the button
- Relay 1 is the boiler
- Extvar0 allows relay1 to be controlled through the webpages without the script interfering
LET c = 0 'business hours flag DO 'set custom timers LET a = extvar1 LET b = extvar2 'assign day of week LET e = date + 3 LET d = e % 7 'Check day of week IF d < 5 THEN 'if day is Monday - Friday IF time > 09:00:00 THEN IF time < 17:00:00 THEN 'if business hours LET c = 1 'business hours = true 'intermediate variable to avoid too many nested if's END IF END IF 'Turn on boiler every two hours during the day, timer will be set to turn off boiler later IF time = 07:00:00 THEN LET relay1 = 1 LET t1 = 3000 END IF IF time = 09:00:00 THEN LET relay1 = 1 LET t1 = 3000 END IF IF time = 11:00:00 THEN LET relay1 = 1 LET t1 = 3000 END IF IF time = 13:00:00 THEN LET relay1 = 1 LET t1 = 3000 END IF IF time = 15:00:00 THEN LET relay1 = 1 LET t1 = 3000 END IF END IF 'business hours IF c = 1 THEN LET c = 0 IF input1 = 1 THEN IF t1 = 0 THEN 'if boiler is not already running LET relay1 = 1 'turn on boiler when customer walks in the door LET t1 = a 'set boiler timer (extvar1) END IF END IF END IF 'push button contact switch IF input2 = 1 THEN LET relay1 = 1 'manually turn on boiler LET t1 = b 'set boiler timer (extvar2) END IF 'web control IF extvar0 = 1 THEN LET relay1 = 1 'boiler controlled manually through webpage. LET t1 = b 'set boiler timer (extvar2) LET extvar0 = 0 'turn off extvar0 END IF 'Turn off relay when timer is expired IF t1 = 0 THEN 'if timer has expired LET relay1 = 0 'turn boiler off END IF LOOP 'repeat main program END 'end of main program
For other BASIC script resources, please see the individual product's users manual. Also, please feel free to contact tech support for advice or troubleshooting help.