-
dScript User Manual v2.15 dScript User Manual Version 2.15 Copyright © 2016, Devantech Ltd. All rights reserved. www.robot-electronics.co.
-
dScript User Manual v2.15 Introduction dScript, derived from devantech Scripting language, is a multi-threaded language for our internet connected modules. dScript compiles to efficient byte codes which are interpreted by the modules on-board runtime firmware. dScript is an editor, compiler and programmer for all dScript enabled modules. Although dScript is not BASIC, the syntax of dScript will be familiar to anyone who has used Visual Basic or the small Basic chips and modules that are available.
-
dScript User Manual v2.15 Getting started This section will guide you through downloading and installing the dScript IDE, connecting a dScript module such as the dS1242 or dS3484, compiling and uploading firmware to the module and getting a first look at controlling the module from a webpage. PC requirements Windows 7 or later Network connection for viewing web pages USB port to program the module. You will also need an HTML editor of your choice. Installing the software http://www.robot-electronics.co.
-
dScript User Manual v2.15 Connecting the hardware Connect an ethernet cable from your network to the ethernet connector on the dScript module, then attach a USB cable from the PC to the USB connector on the module. Now plug in the 12vdc power supply into the DC jack connector and switch on. When prompted by windows navigate to the USBdriver folder and install the USB driver. Now run the dScript IDE and it should find your module and report its firmware version in the tool strip.
-
dScript User Manual v2.15 Second program Lets try something more interesting, please open the WebsiteGauges project from the examples directory. Look at the program and note the tcpip.ip address, you may need to change this and the subnet mask below to suit your network. Specifically, you need to make sure the PC is on the same subnet as the module. In this case 192.168.0.x and that the IP address is available. Once you've checked the IP address, you can build and run the program.
-
dScript User Manual v2.15 dScript IDE The dScript IDE (Integrated Development Environment) is used to write the programs that run on the modules, it has syntax highlighting to make the programs easier to read and invokes the program and website compilers. All labels are listed in the right panel and are for easy navigation of your code. Clicking a label will take you to that section in the main editor window. The message panel shows the status of the compiler, programmer and any errors found.
-
dScript User Manual v2.15 Version numbers The version numbers of the Manual (shown top right in the header above), the IDE and the module firmware should all be synchronised and show same version. For example: User Manual v1.23 IDE v1.23 (found in Help->About) Module Firmware v1.
-
dScript User Manual v2.15 Program structure All dScript programs are single page, single file programs. They begin with all the declarations needed, followed by the program instructions. The declarations are used to give meaningful names to all the variables and I/O ports that you will be using. The instruction section contains all the code to make your application work, the starting point for your code is the label "main". It need not be the first label, but you must include it somewhere in your code.
-
dScript User Manual v2.15 Constant declarations const Minus17 -17 const LogArraySize 24 var TemperatureLog[LogArraySize] var StartTemp Declaring numbers that can be used many times in your program as const can save time if you need to change it. Use the const anywhere in your program where you would otherwise use the number. main: StartTemp = Minus17 ... Constants can also have an expression as the parameter.
-
dScript User Manual v2.15 Labels A label is a marker for a point in your program. A label must start with an upper or lower case letter A-Z or a-z. Labels can be followed by any mix of upper or lower case letters A-Z or a-z, digits 0-9 or the underscore character _ A label must finish with a colon : The colon must immediately follow the label, it terminates the label but is not otherwise part of the label.
-
dScript User Manual v2.15 Variables The are two variable types, integer variables and string variables. Variable names must start with a letter and may be followed by letters ( A-Z, a-z ), digits ( 0-9 ) or an underscore ( _ ). No other characters are permitted in variable names. All variables are global and may be accessed from any subroutines or threads. Integer variables There are three types of integer variables used to store numbers.
-
dScript User Manual v2.15 Variable arrays A variable array is like a row of variables. To declare an variable array place the size of the array in square brackets immediately after the variable name. var TemperatureLog[24] This declares a row of 24 individual variables (or elements) which can be accessed by using an index number. The first element is at position 0 and the last element is at position 23 (not 24). To read or write an array element, specify the element number in the square brackets.
-
dScript User Manual v2.15 String variables A string variable is used to hold ASCII character strings. The length of the string variable may be up to the lesser of 65535 bytes or the remaining memory. The size of a string variable is declared by placing the size in square brackets immediately after the name. string myStringName[100] declares a string called myStringName which is can hold up to 100 characters. You can have any number of string variables up to the limit of the on-board RAM memory.
-
dScript User Manual v2.15 String byte arrays Strings can be used as byte variable arrays. Array elements are unsigned bytes and can hold positive values between 0 and 255. Strings used as byte arrays cannot store negative values. string myByteArray[10] The individual elements of this string may be accessed by myByteArray[0] = 5 which will load the number 5 into the first element of the array. The elements of the 10 byte array are numbered 0 to 9.
-
dScript User Manual v2.15 Non-volatile variables Some modules have an EEPROM for storing a small number of variables when power is switched off. The dS1242 & dS3484 have a 512 byte EEPROM on board. Either string or var variables can be located in this non-volatile memory. To declare a nonvolatile var use eevar, eeint16 or eeint8.
-
dScript User Manual v2.15 reach end of life for the EEPROM in less than 4 days! Try to limit updates. An hour counter which is updated every 10 minutes will last 19 years. The EEPROM used has a minimum write endurance of 1000000, it could be much more. Copyright © 2016, Devantech Ltd. All rights reserved. www.robot-electronics.co.
-
dScript User Manual v2.15 Digital I/O All Digital I/O such as relays, led's, general purpose I/O or virtual I/O are declared with the digitalport declaration. See module documentation for specific details of the port numbers.
-
dScript User Manual v2.
-
dScript User Manual v2.15 Logical operators Logical operators return true or false. Symbol Operation > Example Greater than A>B Greater or equal A >= B Less than A= < An example of using logical operators is the “if” command. if A > 5 goto label1 Copyright © 2016, Devantech Ltd. All rights reserved. www.robot-electronics.co.
-
dScript User Manual v2.15 Expressions Expressions are a sequence of variables and operators. They are used to assign values to either numeric or string variables. Numeric expressions X=A+B This will add the variables A and B together and assign the result to variable X. An expression may have any number of operations. X=A+B*C Expressions are always evaluated from left to right. No precedence is given to multiply and divide as some compilers do. If A=2, B=3 and C=4 then the expression above will yield 20.
-
dScript User Manual v2.15 String expressions The only operator used with strings is + and should be read as concatenation rather than addition as it joins two strings together to make one string. S1 = “This is ” S2 = “compiler!” S3 = S1 + “the dScript ” + S2 results in S3 containing “This is the dScript compiler” Numeric variables in string expressions Numeric variables can be included in string expressions.
-
dScript User Manual v2.15 Padding numeric output Sometimes when displaying numeric output, you will want to use a constant width, regardless of the number. To achieve this just add a number following the format control character. {D3} will display the number as three digits. 4 34 234 6234 That worked well except for the last number. If a number is larger than the number of places allocated it will use as many as needed to display the result. Make sure you plan for the largest expected number.
-
dScript User Manual v2.15 Formatting negative numbers When the number is negative a '–' sign is placed in front of the number. If you are specifying a width then this '–' sign counts as one of your characters. X = -59 S1 = “Variable X is “ + {D} X results in “Variable X is -59 S1 = “Variable X is “ + {D04} X results in “Variable X is -059 The '-' sign is never displayed when formatting in binary or hexadecimal formats.
-
dScript User Manual v2.15 dScript commands goto goto is used to transfer program execution to another point in the program. The target of a goto command is always a label. Example: goto label1 gosub gosub is used to call subroutines. The address of the next instruction following the gosub is stored on the stack, control is then transferred to the subroutine. A return command at the end of the subroutine then transfers control back to the instruction following the gosub command. Example: gosub IncA ... ..
-
dScript User Manual v2.15 if - multiple statement execution the syntax of the if command is: if then statements elseif statements else statements endif The compiler used the "then" keyword that follows the to determine if this is the single or multiple format of the "if" statement. The "elseif" command can follow "then" or "elseif" commands and must terminate with "elseif", "else" or "endif".
-
dScript User Manual v2.15 for, next The for/next commands are used to execute a set of instruction a specified number of times. The syntax is: for = start to end statements next An example: for X = 1 to 10 A=A+1 next ; X counts up each loop If end is greater than start, the count will increment by one each loop.
-
dScript User Manual v2.15 do loop The do loop will execute forever: do statements loop Optionally the do loop can have conditional tests at the beginning or end of the loop (but not both).
-
dScript User Manual v2.15 select case The syntax for the select command is: select case [statements] case to [statements] case is [statements] else [statements] endselect When no case expressions match, the else statements are executed. When more than one case expression matches, only the first matching block will be executed. Control then passes to the instruction following the endselect command.
-
dScript User Manual v2.15 Serial ports dScript Modules may implement one or more serial ports, these are declared at the start of your program. Because it takes time to send data out over a serial port we provide each port with both receive and transmit FIFO (first in first out) buffers. Once declared a serial port will receive and transmit in the background. Received data will be placed in the Rx Fifo ready for when your program wants to fetch it.
-
dScript User Manual v2.15 string s1[100] serialport LCD05 1 10 90 s1 = "Hello World" LCD05.Write(s1,0,11) Here we are sending 11 bytes from string s1 beginning at the first location (string indexes are zero based) to serial port 1 which we have named as LCD05. A better way is to place the byte count into the the write command is to used the string length parameter. LCD05.Write(s1,0, s1.Length) The length of a string is the number of bytes up to and excluding an 0x00 value.
-
dScript User Manual v2.15 Reading data from a serial port The "Read" command is used to read serial data, the syntax is: mySerialPortName.Read( , , ) Data read from the serial port is placed in a string - think of it as a byte array holding your incoming data. The following program will read and display the firmware version number of the LCD05. S1[0] = 15 ; LCD05 command to read firmware version LCD05.
-
dScript User Manual v2.15 Baud rate The default serial parameters are 9600, no parity, 2 stop bits. The baud rate can be changed with serialport.BaudRate = serialport RS485 2 100 200 RS485.BaudRate = baud34800 ; change baud rate to 34800 baud38400 is a predefined baud rate.
-
dScript User Manual v2.15 Stop bits The default is 2 stop bits. serialport RS485 2 100 200 RS485.StopBits = 1 ; set 1 stop bit RS485.StopBits = 2 ; set 2 stop bits Only 1 or 2 is allowed, any other value is ignored and StopBits will remain unchanged. Break Some systems require a "break" to be transmitted as a start of frame marker. A break is defined as the Tx line low for longer than one character frame. The break time used by dScript is 18 bit times.
-
dScript User Manual v2.15 TCP/IP ports Both client and server tcp/ip ports are available. A client port initiates communication while a server port listens for an incoming connection. Both are capable of transmitting and receiving. TCP/IP server To operate a tcp/ip server the module will require an IP address and a port number to listen on. The default IP address is 192.168.0.123 and the default mask is 255.255.255.0.
-
dScript User Manual v2.15 Here is a simple tcp/ip server example which just increments the first byte of the message and sends it back to the client. tcpip.ip tcpip.mask tcpip.port var string "192.168.0.136" "255.255.255.0" 17494 tcpLength tcpBuf[1024] thread TcpipExample tcpip TcpipExample: tcpip.Read(tcpBuf, tcpLength) tcpbuf[0] = tcpbuf[0] + 1 tcpip.Write(tcpBuf, tcpLength) threadsuspend main: threadstart TcpipExample threadsuspend Copyright © 2016, Devantech Ltd. All rights reserved. www.
-
dScript User Manual v2.15 TCP/IP client The tcp/ip client can initiate a communication to a tcp/ip server, we will use an ETH002 as an example. To do this you need to define a client port like this: clientport ETH002 "192.168.0.96" 17496 5000 The first parameter is the name of the client port that you will use in your program to refer to this port. In this case an ETH002, so that's what we will name it. Next is its IP or DNS address followed by the port number.
-
dScript User Manual v2.15 thread thread YardLightCtl FlashRedLed 100 const main: yardLightState = 2 threadstart YardLightCtl threadsuspend ; neither on or off to force initial setup YardLightCtl: if Adc1>600 then if yardLightState != on then clientOutBuf[0] = 0x20 ; Relay Active clientOutBuf[1] = 1 ; Relay 1 clientOutBuf[2] = 0 ; not timed ETH002.
-
dScript User Manual v2.15 UTC clock Coordinated Universal Time (UTC) is an international time standard. Your internet connected module has access to this time by using its UTC port. To use the UTC port add the following in your dScript header area. UTCport UTC 0 1 The first parameter (UTC) is the name of the port that you will use in the program to refer to it. The second is the time zone offset. Here in the UK we want to use GMT so just set this to zero.
-
dScript main: User Manual v2.15 threadsleep 100 ; give LCD modules time to power up s1 = " dS3484 Date & Time" s1[0] = 12 s1[1] = 19 s1[2] = 4 LCD05.Write(s1,0,s1.Length) do gosub lookUpDay gosub lookUpMonth s1 = " " + Day + " " + {d02} UTC.Day + " " + Month + " 20" + {d02} UTC.Year + " " + {d02} UTC.Hour + ":" + {d02} UTC.Minute + "." + {d02} UTC.Second s1[0] = 2 s1[1] = 41 LCD05.Write(s1,0,s1.Length) threadsleep 200 loop lookUpDay: select UTC.
-
dScript case 4 Month case 5 Month case 6 Month case 7 Month case 8 Month case 9 Month case 10 Month case 11 Month else Month endselect return Copyright © 2016, Devantech Ltd. All rights reserved. User Manual v2.15 = "MAY" = "JUN" = "JLY" = "AUG" = "SEP" = "OCT" = "NOV" = "DEC" = "Huh" www.robot-electronics.co.
-
dScript User Manual v2.15 HTTP web server Using the dScript web server, you can write and upload your own web pages to the module. Your website can display your own variables in any manner you choose, using AJAX techniques to keep the variables live and updated. You can use buttons on the web page to control things on the module and, of course, your own branding applied to the page. You can use CSS to format your website and include any images, logo's required.
-
dScript User Manual v2.15 First we need to add the following to the dScript program to define the relay: digitalport Rly1 1 so we have: tcpip.hostname tcpip.ip tcpip.mask digitalport Rly1 "dS3484" "192.168.0.136" "255.255.255.0" main: 1 do loop The button line on the web page needs some more code, change it to: We have given the button the id "Rly1" so we can refer to it to update the colour.
-
dScript User Manual v2.15 The last thing to add is a call to startAJAX() after the web page has been loaded. Do this by modifying the
tag like this: The new html page looks like this: Dweb Simple Test Page
-
dScript User Manual v2.15 Web page security Now that you can control your module from any browser on any PC/Laptop/Tablet/Phone from anywhere on the planet, what is to stop anyone who knows your incoming IP address from opening your gates, turning lights on or your heating off and generally messing up your life? Well one way is to change the web page file name from "index.htm" to something harder to guess. How about "EyRz2G5xXu94e.htm". This is almost like using the file name itself as a kind of password.
-
dScript User Manual v2.15 Installing the password on your browser Add the following below the html.password line: html.setup on This command will enable a built in web page that loads the password into your browser. Here is the complete dScript program for our simple website demo. tcpip.hostname tcpip.ip tcpip.mask "dS3484" "192.168.0.137" "255.255.255.0" html.password "bQq#dm@$%^5*xZ5tY0wN!fi38H_Y3" html.
-
dScript User Manual v2.15 Logging out. To log out add the following to the html on your page: Log out _loggedout.htm is a built in file that contains the “Logged out” message and a small piece of javascript to delete the authorisation cookie. More importantly, the filename is recognised by the module as a special file and it will invalidate the associated authorisation code. Here is the index.
-
dScript User Manual v2.15 If you wish, you can write your own _loggedout.htm file and load along with your other web pages. It will be used in preference to the built in file. It must be named _loggedout.htm otherwise it will not be recognised by the module as a special file to delete the authorisation cookie. Also to delete the cookie on the browser you should include the javascript:
