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 modules support BASIC scripts. 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.
Debugging
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:
- Maximum Script Size:
- Please check the the maximum script size allowed for your device by visiting your device’s specs page on our website.
- Several devices have limits of 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
- Variables
- Inputs and Outputs
- Relay Outputs
- Math operations
- Timers
- Time
- LOG
Organization/Loops/Routines
- The DO Loop
- The DO WHILE loop
- The FOR loop
- The SUB Routine
Elements
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
OR
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
Variables
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 |
Relay 1: | relay1 | Read/Write |
Relay 1 (400 Series): | io.relay1 | Read/Write |
Counter 1: | count1 | Read/Write |
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.
Relay Outputs
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
Math Operations
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)
Timers
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
Date/Time
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
LOG
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
Organization/Loops/Routines
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 of the X-310. 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 of the WebSwitch Plus. 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.