Basic Programming manual V1.
CONTENTS Introduction to Basic Programming.....................................2 Basic Features..................................................................... 3 Basic Fundamentals............................................................4 Scheduling a Program....................................................... 4 Listening Programs............................................................ 4 Error Handling................................................................... 4 Grammar and Examples..
Contents MIN (number, number)................................................. 26 MOD (number, number)............................................... 26 NEXT................................................................................ 26 NOT................................................................................. 27 ON number GOSUB labels.......................................... 27 ON number GOTO....................................................... 27 OPEN......................................
01 / 2 BASIC PROGRAMMING
Basic Programming Each Storm data logger contains a built-in BASIC interpreter (as of firmware version 1.4.2) allowing for more complex procedures and more specific control over operations performed by the data logger. Many traditional BASIC commands and features have been combined with an added subset of Storm-specific operations to create the Basic programming language available on the Storm.
BASIC PROGRAMMING Basic Fundamentals Understanding the available functions and commands as well as the overall operations and flow of Basic is essential to its use within the Storm. Primary Basic concepts and examples are provided below, followed by a listing of all available commands and functions. Each command is given a description and an example of its use. Additional examples are included at the end of this manual. Before a Basic program can be used, it must first be installed on the Storm.
Basic Programming Grammar and Examples Basic programming examples provided throughout the manual will follow a specific format. All Basiccommands and functions will be capitalized while all variables and strings may contain both uppercase and lowercase lettering. Though this format is used, the Basicinterpreter is not casesensitive with respect to commands and functions. Variables, however, are case-sensitive.
BASIC PROGRAMMING Control Statements and Loops Basic supports traditional control statements such as GOTO and GOSUB as well as single and multi-line IF-THEN statements and SWITCH-CASE statements. GOTO and GOSUB can jump to labels or line numbers within the code. Line numbers may be used in the Basic program, but they are not required. Loops are also allowed using FOR, WHILE, REPEAT, and DO statements.
Basic Programming File and Serial I/O Files stored on the Storm’s local file system can be accessed for reading, writing, and appending of data. The OPEN command allows files to be opened and assigned a number for use throughout the program. Using the INPUT and PRINT commands with the file’s assigned number allows Basic to read and write to the opened file. Other commands such as EOF, LINE INPUT, SEEK, and TELL allow for further traversal and manipulation of data files.
02 / 8 COMMANDS AND FUNCTIONS
Commands and Functions The Storm’s implementation of Basic uses both commands and functions to perform actions and return values, though each is syntactically different.
COMMANDS AND FUNCTIONS Single-dimensional array: ARRAY myArray(5) FOR i = 1 TO 5 myArray(i) = i * 2 REM Duplicate the number’s value inside the array NEXT i REM myArray(i) now contains values 2 4 6 8 10 Multi-dimensional array: ARRAY myArray$(3,7) REM 2-dimensional string array (3 rows, 7 columns) FOR i = 1 TO 3 FOR j = 1 TO 7 myArray$(i,j) = str$(i * j) REM str$ converts a number to a string NEXT j NEXT i REM myArray$(i,j) now contains values 1 2 3 4 5 6 7 2 4 6 8 10 12 14 3 6 9 12 15 18 21
ASIN (number) Returns the arc-sine value of the given number. var = ASIN(0) REM sets var to0 var = ASIN(1) REM sets var to 1.5708 (PI/2) ATAN (number) Returns the arc-tangent value of the given number. var = ATAN(0) REM sets var to 0 var = ATAN(1) REM sets var to 0.785398 (PI/4) BREAK Causes an immediate exit from a loop or SWITCH statement.
COMMANDS AND FUNCTIONS CHR$ (number) Returns the number’s ASCII character representation. ASC( ), converting a character to its ASCII numerical value, is the opposite function of CHR$( ). var$ = CHR$(65) REM sets var to A var = ASC(“A”) REM sets var to 65 CLEARSDI ( ) Clears the SDI-12 cache. Prior to a Basic program running, the SDI-12 cache is empty. All Basic programs share the same SDI-12 cache. When an SDI-12 value is retrieved, a cache of the query and response is recorded.
Commands and Functions COS (number) Returns the cosine value of the given number. var = COS(0) REM sets var to 1 var = COS(PI) REM sets var to -1 DATETIME Used to retrieve parts of the current date and time. Available arguments are DATE, DATE$, TIME, TIME$, DAY, JDAY, MONTH, YEAR, SECONDS, MINUTES, HOURS, EPOCH, EPOCHDAY. DATE and TIME return integer values of the current date and time formatted as YYMMDD and HHMMSS respectively.
COMMANDS AND FUNCTIONS CASE 15: path = 2 BREAK CASE 30: path = 3 BREAK CASE 45: path = 4 BREAK DEFAULT: path = -1 BREAK END SWITCH DELAY Causes the program to pause execution for the specified number of seconds. A decimal number may be used to specify more specific and smaller time increments (e.g. milliseconds). SLEEP and DELAY are identical commands. SLEEP 2.5 DELAY 0.25 REM pauses the program for 2.5 seconds REM pauses the program for 0.25 seconds DO Begins an infinite loop encompassed by DO and LOOP.
Commands and Functions ELSEIF Optionally used as part of an IF statement to indicate another condition to evaluate. The option is evaluated if all previous options have resulted in FALSE. Multiple ELSEIF conditions may be tested If the condition evaluates to TRUE, all following conditions will not be tested.
COMMANDS AND FUNCTIONS END SUB Declares the end of a subroutine (begun with the SUB statement). volume = calc_volume(3, 4, 5) REM sets volume to 60 SUB calc_volume(h, w, d) vol = h * w * d RETURN vol END SUB END WHILE Marks the end of a conditional WHILE-WEND loop. END WHILE may also be used instead of WEND.
Commands and Functions EULER A read-only constant containing the number 2.7182818284590452. var = EULER REM sets var to the euler constant EXP (number) Returnseuler raised to the power of the given number. Identical to EULER^number. var = EXP(0) REM sets var to 1, equivalent to EULER^0 var = EXP(1) REM sets var to 2.71828, equivalent to EULER^1 var = EULER^2 REM sets var to 7.38906, equivalent to EXP(2) FALSE A read-only constant containing the number 0.
COMMANDS AND FUNCTIONS FOR Begins a loop encompassed by FOR and NEXT with an optional STEP command. The default STEP is 1, meaning each iteration of the loop will increase the variable by 1. Negative STEPs may be used to count backwards.
Commands and Functions COUNTERX Returns a new counter measurement from the specified Digital port.TheXfollowing the identifier specifies which digital portis measured.See SetValue to change the counter value of a specific digital port. GETVALUE COUNTER1, c1$ REM sets c1$ to the Digital port’s count GETVALUE COUNTER2, c2$ REM sets c1$ to the Digital port’s count DIGITALX Returns a new measurement from the specified Digital port.
COMMANDS AND FUNCTIONS SENSORRAW Returns a sensor’s most recent raw/unprocessed value. A raw value is the value of a measurement prior to slope, offset, function or digits are applied to it. If an unknown sensor is specified, the Error String (default is -99.99) is returned. Prior raw values can be returned by adding an additional numerical parameter. The number 1 indicates the most recent measurement, 2 the previous measurement, 3 the value processed three scans prior, etc.
Commands and Functions GOSUB Branches to the specified LABEL or line number within the program. Once a RETURN statement is reached, execution is passed back to the statement immediately following GOSUB. Subroutines, defined with the SUB command, provide a much more flexible method of executing and running portions of code and should be used instead of GOSUB.
COMMANDS AND FUNCTIONS H377C (number) Returns the temperature, in degrees Celsius, of the given number (expecting a 0-5V analog voltage reading) based on the math equation for the WaterLog model H-377 temperature probe. var = H377C(3.25) REM sets var to 23.1779 H377F (number) Returns the temperature, in degrees Fahrenheit, of the given number (expecting a 0-5V analog voltage reading) based on the math equation for the WaterLog model H-377 temperature probe. var = H377F(3.25) REM sets var to 73.
Commands and Functions INPUT Read from a file or serial port that has been previously opened with the OPEN command. An optional delimiter (stop character) may be specified for retrieving data. The default delimiter for files is a space; the end of transmission EOT (0x04) character is used for serial communication. When used with a serial port, an additional variable may be specified to set the timeout, in milliseconds, for reading from the port (default is 100ms).
COMMANDS AND FUNCTIONS LABEL Identifies a specific location by name. Commands such as GOTO and GOSUB can refer to and send execution to named LABELs. Line numbers are a special case of LABELs and do not require the LABEL prefix to be named.
Commands and Functions LN (number) Returns the natural logarithm of the given number. The LOG function should be used if a common (base-10) logarithm is required. var = LN(3) REM sets var to 1.09861 LOCAL Used within a subroutine, LOCAL marks the given variable as valid only within that subroutine. Variables within a subroutine are accessible anywhere within the program otherwise.
COMMANDS AND FUNCTIONS LTRIM$ (string) Returns the given string with all whitespace removed from only the left side. var$ = LTRIM$(“ A1,B2,C3,D4 “) REM sets var$ to “A1,B2,C3,D4 “ MAX (number, number) Returns the maximum value of the two given numbers.
Commands and Functions NOT Negates the expression immediately following. The ! operator may alternatively be used. OPEN “SiteID.csv” FOR READING AS #1 WHILE (NOT EOF(#1)) LINE INPUT #1, var$ REM reads each line of the log file WEND CLOSE #1 ON number GOSUBlabels Branches to one of a list of labels(with an expected RETURN) based on the given number. For example, if the given number is 1, the first GOSUB listed is used, if the number is 2, the second GOSUB, etc.
COMMANDS AND FUNCTIONS ENDIF ON var GOTO critical,moderate,okay LABEL critical SETVALUE DIGITAL1, 1 SETVALUE DIGITAL2, 1 SETVALUE DIGITAL3, 1 END LABEL moderate SETVALUE DIGITAL1, 0 SETVALUE DIGITAL2, 1 SETVALUE DIGITAL3, 1 END LABEL okay SETVALUE DIGITAL1, 0 SETVALUE DIGITAL2, 0 SETVALUE DIGITAL3, 1 END OPEN Opens a file, serial port, or connects to a listening port.All files and non-listening ports will be automatically closed when a program ends.
Commands and Functions File: OPEN “SiteID.csv” FOR APPENDING AS #1 PRINT #1, “A1,B2,C3,D4” CLOSE #1 REM Check if file exists, OPEN #1 FOR READING will fail if it does not FileExists = 1 FileName$ = “LogFile.
COMMANDS AND FUNCTIONS OR A logical operator used between two expressions in conditional statements (e.g. IF, WHILE, etc.). Returns TRUE if the left, right, or both expressions are TRUE, FALSE if both are FALSE. var = 100 IF (var > 0 OR var < 50) var = 1 IF (var > 0 OR var < 150) var = 1 REM sets var to 1 REM sets var to 1 PI A read-only constant containing the number 3.1415926535897932. var = PI REM sets var to 3.14159 PRINT Writes characters to a file or serialport.
Commands and Functions REM Begins a comment extending to the end of the line. An apostrophe (“ ‘ ”) may alternatively be used to start a comment. REM This is a comment ‘ This is also a comment var = 1 REM This is a valid comment var = 2 ‘ This is also a valid comment REPEAT Begins a conditional loop encompassed by REPEAT and UNTIL. The condition is given after the UNTIL statement and while evaluated as TRUE, will continue to iterate through the loop.
COMMANDS AND FUNCTIONS RINSTR (string, string, number) Returns the position, starting at 1, of the first occurrence of the second given string within the first given string beginning at the right. If the string is not found, zero is returned. The third parameter is an optional number, defaulting to the last element of the string, indicating the starting position for the search. INSTR may be used to begin searching for a string from the left, rather than the right.
Commands and Functions SETPORT Sets the serial port settings for unopened communication ports. Serial ports are opened with the following defaults: baud rate = 9600, data bits = 8, parity = none, stop bits = 1, flow control = none, transmit char delay = 0, transmit line delay = 0. If other port settings are desired, they must be specified prior to opening the port. Parity can be set to None, Even, or Odd. Flow Control can be set to None, Software, Hardware, or Both.
COMMANDS AND FUNCTIONS SENSORFUNCTION Sets a sensor’s function, specified by the Use Function option under the Processing section of the Storm’s Sensor Setup screen. Setting a sensor’s function will automatically enable the function for use as well. If an unknown sensor is specified, an N/A is returned. Functions from SDI-12 or Basic programs are retrieved by specifying the name of the sensor followed by the parameter’s name surrounded by parentheses.
Commands and Functions Empty elements in the array are created if two delimiters are next to each other. The TOKEN function, on the other hand, does not add empty elements if two or more delimiters are in sequence. The array will be automatically sized (larger or smaller) based on the number of strings that are produced by the split. The number of strings produced will also be returned by the function.
COMMANDS AND FUNCTIONS SUB Declares a user-defined subroutine. Subroutines can specify and accept multiple parameters and can return a number or string value using the RETURN statement. The END SUB statement marks the end of a subroutine. Though not required, it is recommended that any subroutine returning a string value should name routine with a trailing dollar-sign (“$”).
Commands and Functions TAN (number) Returns the tangent value of the given number. var = TAN(PI/4) var = TAN(0) REM sets var to 1 REM sets var to 0 TELL (filenumber) Returns the current read position of the given file number. REM Presuming SiteID.csv contains: REM Digital1,Analog2,WindSpeed REM 56.23,2.25,126.5 OPEN “SiteID.
COMMANDS AND FUNCTIONS TOKEN (string, array, string) Splits apart a string into an array of strings. The first parameter provides the string to split apart. The second parameter provides the array which the new substrings will fill. The optional third parameter provides the delimiters or characters that determine where to split the primary string. If more than one delimiter is specified, splitting will occur at each character given.
Commands and Functions UPPER$ (string) Returns the given string as all uppercase. var$ =UPPER$(“a1,b2,c3,d4”) REM sets var$ to A1,B2,C3,D4 USING Used with the PRINT statement to specify the format of the given number. Format is specified using hashes (“#”). If more hashes are provided than needed, the beginning is space-filledand the end zero-padded. If not enough hashes are given before the decimal, the hash format is returned. var = 128.265 OPEN “SiteID.csv” FOR WRITING AS #2 PRINT #2, var USING “####.
COMMANDS AND FUNCTIONS WHILE Marks the beginning of a conditional WHILE-WEND loop. The condition is specified after the WHILE keyword. As long as the condition evaluates to TRUE, the loop will continue to iterate. Once the condition evaluates to FALSE, the loop will exit. REM Presuming SiteID.csv contains: REM Digital1,Analog2,WindSpeed REM 56.23,2.25,126.5 OPEN “SiteID.
03 / EXAMPLE PROGRAMS 41
EXAMPLE PROGRAMS The following programs are provided for reference when creating and using the Basic interpreter. AutoPrint.bas REM REM Prints out the last line of the log file to the RS-232 Com port When set up to run with the sensors, prints out their values every scan LogFile$ = “SiteID.
Example Programs CompassCorrection.bas REM Determines true wind direction as a bouy rotates, REM based off recorded compass and wind direction GETVALUE SENSOR “Compass”, WindDirVal GETVALUE SENSOR “WD”, CompassVal TrueWindDirVal = WindDirVal + CompassVal IF (TrueWindDirVal >= 360) THEN TrueWindDirVal = TrueWindDirVal - 360 END IF SensorAvg.
EXAMPLE PROGRAMS Listener.
Example Programs VR2C.bas REM Communicate with and retrieve data from an RS-232 sensor SerialNum$ = “450065” SETPORT 9600,8,None,1,None,0,0 OPEN “RS-232 COM” AS #4 PRINT #4 “\r” REM Wake up sensor SLEEP 0.100 REM Wait for sensor to fully wake up REM COMMAND FORMAT: *SSSSSS.
Xylem 1) The tissue in plants that brings water upward from the roots; 2) a leading global water technology company. We’re 12,000 people unified in a common purpose: creating innovative solutions to meet our world’s water needs. Developing new technologies that will improve the way water is used, conserved, and re-used in the future is central to our work. We move, treat, analyze, and return water to the environment, and we help people use water efficiently, in their homes, buildings, factories and farms.
