ControlByWeb

How to write, debug, and text BASIC scripts for ControlByWeb products.

Introduction:

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.


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'.

BASIC script error check utility screenshot

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
  • Variables
  • Inputs and Outputs
  • Relay Outputs
  • Math operations
  • Timers
  • Time
  • EMAIL
  • 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
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
    

Email

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. 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.

Back to Top