Digital Loggers, Inc.
Customize your power controller using simple, powerful BASIC scripting.


Advanced Power Control - Scripting

On its own, a power switch isn't very smart.  Add custom functionality using the built-in simple BASIC scripting language. It's really simple. No programming experience is required.  Have a look at the sample scripts.  Give it a try.  Need help?  Call (408) 330-5599 or send an email.

Hardware Requirements

User-defined program scripts are stored in non-volatile EEPROM.  The current Web Power Switch 5, DIN Relay II, and Ethernet Power Controller III include expanded EEPROM.   Scripting can be used without EEPROM, but scripts will be lost after power-off.  Scripting will automatically be enabled in the latest firmware.   Memory upgrades are available for earlier units.  Script controlled LCD, clock-calendar and RS-232 transmission functions are limited to products with appropriate serial hardware installed.

Entering Scripts

First, review the commands and samples below for a quick overview of the BASIC script language.  Log in as admin and use the Scripting link to access the programming page.  After entering a command on each line, press EDIT, or just return and the command will be copied.  If there's a syntax error in the command, the screen will refresh without changes. After you've entered a script, check the "Enable Scripting" checkbox.  Once enabled, start the script using the RUN button or any other method below.

Supported Commands

You may enter up to 127 of the commands below.  Commands are executed in sequence with a "step delay" between each command.  The step delay can be as short as 1 second (one command per second) or slower if you desire. Enter BASIC commands from the list below one at a time in the Script Listing section on the page http://Your_IP/script.htm.  Press "Edit" after entering each command.

Multiple Threads

For advanced users:  A thread is a process. You can run a multiple programs, or the same program up to 63 times simultaneously.  Multiple programs may be run by multiple threads. Code space is shared.  Up to 63 threads may run concurrently.  Be careful when starting threads, it's easy to start multiple simultaneous threads unintentionally.

Starting Scripts

There are several ways to start scripts: 

Enabling/Disabling Scripting

You must disable scripting (uncheck the enable box) to stop all threads before editing scripts.  You must enable scripting before any script will start.  Pressing the hardware reset-to-defaults switch resets to the default login and disables scripting.   Instead of clicking "EDIT" after entering each command, you can just press enter.

Stopping a Script

A script terminates automatically when the END command is reached. Click STOP ALL THREADS to stop everything manually.  You can also stop all scripts via http using http://Your_IP/script.cgi?stop

Relay Debounce Warning

Even with the scripting step delays, it is possible to create a script which will rapidly cycle a relay. This rapid cycling could result in a over current condition, tripped breaker, or stress to the power controller or attached equipment. To protect against damage to attached equipment or to the power controller,  the response time of attached relays is  limited by hardware to about ~500ms in newer products.  Before running multiple threads, please test your script.

Scripting Commands (Instructions)

Parentheses indicate variables. Enter just the variable without parantheses.  For example, AUTOPING 1 will look for the IP address stored in string 1.

AUTOPING (N)

This command enables autoping at the IP address specified in string N.  For example, if STRING 1 is 192.168.0.101, AutoPing will run (per the settings on the SETUP page) at that IP address.  Note that AutoPing operation begins only after a series of successful pings are used to establish a reliabile connection.


NOP No operation

Useful as a debugging command, delay, or branch target.  Causes a delay equal to the program step delay. Equivalent to SLEEP 0

END Ends execution

Terminates thread. Only one thread is stopped.

RUN (L) Create Thread

Create a new execution thread at line number (L)

GOTO (L) Branch

Unconditional branch to line (instruction) number (L)

GOSUB (L) Subroutine Call

Calls a subroutine at line (L)  Used with RETURN.

RETURN

Execution will continue on the line following the calling GOSUB after the RETURN instruction is reached. Note: Subroutines are "emulated" by new execution threads. The parent counts as a thread.  63 simultaneous threads are allowed.

ON (NN) Activate Relay

Turns relays on. ie. ON 123 Turns on 1,2,3 leaving
2,4-8 unaffected (NN) is a list, ie ON 1357 sequentially turns odd outlets on.  To prevent excessive inrush currents, the sequence delay timer (On Sequence Delay value in the delay section of the setup page)  is used for multi-relay ON instructions.  In a DIN Relay, activating a relay closes the NO contacts and opens the NC contacts.

OFF (NN) Deactivate Relay

Turns relays off, ie. ON 123 Turns on 1,2,3
leaving 4-8 unaffected.  OFF commands act immediately.  In a DIN Relay, activating a relay closes the NO contacts and opens the NC contacts.

RESTORE Restores All Relays

Restores all in numeric sequence relays to the
settings before power loss, ie."pre-powerloss" state. Sequence delay timing applies.

CYCLE Cycles Relays

Turns relays OFF, then ON, ie. CYCLE 13 reboots outlets 1 & 3

BEEP (T) Activate Beeper

Activates audio alarm in units so equipped, such as the Ethernet Power Controller II. Use BEEP ON to start a continuous alarm, BEEP OFF to stop the alarm.   The beeper can also be activated for 1-254 seconds with BEEP, ie. BEEP 120 will start the beeper for 120 seconds.  BEEP 0 is equivalent to BEEP OFF.  Beep 255 is equivalent to BEEP ON.

SLEEP (T) Sleep Delay

Causes a delay.  Delay length can be specified in hours, minutes or seconds.  Useful for periodic tasks.  Ie. Weekly reboots.
Usage:  SLEEP 1 S  sleeps for one second
               SLEEP 2 H  sleeps for two hours
               SLEEP 3 D  sleeps for 3 days
               All numeric ranges are 0-255

LOG ($) Report to Syslog

Sends string variable ($) to a the selected SYSLOG server at the IP specified on the Setup page.

DISPLAY ($) Display Text on LCD

Sends a string ($) to the LCD display (on products so equipped).  See formatting commands below.

PRINT ($)

Sends string ($) to RS-232 Port 1 on Ethernet Power Controller II/III products, and to the internal TTL serial port on other products.  Serial ports may be used to configure or restart routers, Linux machines, UPSs, or to send messages to via modem or SMS.

String Variables

A literal string may be entered directly, ie "HELLO WORLD".  A string may also include text generated by the power switch.  % strings below are automatically generated and updated by the power switch.

 %% - literal '%' character
 %a  - current Bus A -
 %A  - voltage Bus A
 %b  - current Bus B
 %B  - voltage Bus B
 %o  - Outlets state in the form "12456" (ON are displayed)
 %O - Outlets state in the form "++-+++--"
 %n - Serial number
 %f  - Firmware version
 %d - System time/date
 %M - MAC address
 %i - IP address
 %m - IP network mask
 %g - IP gateway

LCD Control Strings

Strings preceded by \ are used to control the position of characters on the LCD and to clear the LCD display.

 \\ - literal \
 \1 - position cursor line 1 beginning
 \2 - position cursor line 2 beginning
 \f - clear screen
 \n - new line
 \r - carriage return
 \v - clear end of current line



Sample Scripts

LINE 1             GOTO 1

 Creates an infinite loop.
 

Print Text to the LCD

STRING 1            \f ?IP=? %I      ; Clear LCD, Text =?IP =?

 LINE 1             DISPLAY 1        ; Print string 1 to the LCD
 LINE 2             END                    ; Terminates thread.

Clicking RUN 1, clears the LCD and displays ?IP=192.168.0.100? on the first line.  This message will be automatically displayed after power-up once the "enable scripting" box is checked.
 

Display Power Status on LCD

STEP DELAY            1                         ; Set execution speed to 1 instruction/s

 STRING 1   \f  ?BUS A=?%A ?V BUS B=? %B  ; Text and measurements.
 LINE 3             DISPLAY 1         ; Displays string
 LINE 4             SLEEP 3            ; Sleeps for 3 s
 LINE 5             GOTO 3              ; Infinite loop

Clicking RUN 3 clears the display and displays the voltage measurements updated every 5 seconds.  If line 1 is END, nothing will happen at power-up.
 

 
Sequential Power Cycle

LINE 6             CYCLE 1234        ; Reboot devices on outlets 1,2,3,4
 LINE 7             SLEEP 7 DAYS   ; Sleep for a week
 LINE 8             BEEP 5 S            ; Beeps for 5 seconds
 LINE 9             GOTO 6               ; Infinite loop to reboot once
weekly

 Clicking RUN 6 causes devices 1,2,3,4 to be power cycled.  Each week the system will beep for 5 seconds repeat the reboot.
 

AutoPing Example - Restart Devices and Phone Home

In this example, a script is started as a result of loss-of-connectivity detected by AutoPing.  This script uses an AutoPing failure to reboot equipment and report the failure via dial-up modem connected to the RS-232 port:
 
LINE 10          RUN 20
LINE 11          CYCLE 5678
LINE 12          END

LINE 20         PRINT 1
LINE 21         SLEEP 5
LINE 22         PRINT 2
LINE 23         END

strings:

STRING 1        AT&F\nATD123456789\n
STRING 2        ATH0\n

This script will cycle the outlets 5, 6, 7, and 8. It will simultaneously dial the number 123456789 using the Hayes modem connected to the Port 1.

Several AutoPing targets can be "joined" so that the task (be it a script or simple outlet[s] reboot) will be performed only if one of the targets responds. "Joining" requires autoping target tasks be identical. Joined targets can be "split" to work individually.
 

Power Monitoring and Reporting to Syslog

STRING 1: "%a, %A, %b, %B"
LINE 1     SLEEP 10 min
LINE 2     LOG 1
LINE 3     GOTO 1


Clicking RUN 1 start a loop which reports the power and current on each bus every 10 minutes to a SYSLOG server.  What better way to bill your clients for power?  You could also use our free Windows power monitoring utility.
 


Starting the AutoPing Function on Power-up

STRING 1:  192.168.0.101
LINE 1    AUTOPING 1

Since scripts start automatically on LINE1 after power-up, this program will activate AutoPing on the IP address 192.168.0.101 whenever power is restored.

Starting AutoPing on Power-up and Restarting it Daily

STRING 1:  192.168.0.101
LINE 1    AUTOPING 1
LINE 2    SLEEP 24 HOURS
LINE 3   GOTO 1

Since scripts start automatically on LINE1 after power-up, this program will activate AutoPing on the IP address 192.168.0.101 whenever power is restored.  It will then "sleep" for a day and restart AutoPing the next day.

 

Have a smart script or unique way to use your switch?  Share it.  We'll acknowledge your contribution.  engineering(at)digital-loggers.com