Extended commands for the E-Stim 2B
As I've explored ways of controlling the 2B remotely, it's become apparent that there are some things that you can do easily with a remote connection, and some that are a bit trickier - or might just be reinventing the wheel. In many of those cases, it's best to tell the Mac (or PC) software what to do, and take the potentially unreliable web connection out of the equation.
Extended commands are my way of adding extra features and information that can be sent between two bits of software that are designed to work with the eStim 2B, without confusing things if one of those bits of software knows nothing about what's going on. They provide extra functions, but if sent to the 2B itself, will be ignored, so you don't get any unpleasant surprises.
NB. This page is a bit techy; if you just want to use the software, rather than code a web page, or write other software that works with mine, you really don't need to know any of this. Head back to the index!
The basics
After talking with eStim, we agreed that the semicolon character would be suitable to starting extended commands, as the box will never respond to these, even if they are sent to it by mistake (my software intercepts them, but it's best to be safe). So, an extended command for the 2B will always start with a semicolon. I've also made some other restrictions at the moment, mostly in the interests of making things as simple as possible to interpret, whether in RealStudio, JavaScript or anything else.
If a command has parameters, they're specified by following the command with = followed by the parameters, with a comma between each one. There are no spaces anywhere in the command. For instance, the first extended command I've implemented available was the GOTO command. It takes the form
;GOTO=12,15,40,63
Where the numbers are, in order, the settings for A channel, B channel, C setting and D setting. The software sets the C and D parameters, then gradually increases the settngs, for the current mode and power level, from 10% of the A/B settings to 100%, over a period of thirty seconds.
If a fifth paramter is passed, and is greater than thirty, then that will be used as the time over which the settings are increased - and there's no upper limit. This command will work via the direct remote control, as well as via HTTP, incidentally. Via HTTP it would look like this (over 120 seconds):
GET http://some.place.on.line:7846/;GOTO=12,15,40,63,120 HTTP/1.1
If there are seven parameters (version 1.1.2 and above), then the sixth is the mode number, and the seventh is the power level, allowing you to specify a complete set of settings remotely.
Responses to extended commands
Many commands don't actually send a specific response; you'll simply get back the current status of the unit, however you're connected. When a command does need to send a response, that too will start with a semicolon, followed by a token, which depends on the command that is sending the response, followed by a colon, and then the response text. For example, the GETSTATUS command will return a response like this:
;STATUS:delayfirst=false
;STATUS:delayvalue=
;STATUS:delaybetween=true
;STATUS:mindelay=60
;STATUS:maxdelay=300
;STATUS:randomtimes=true
;STATUS:minrun=45
;STATUS:maxrun=200
;STATUS:randompower=false
;STATUS:checks=true
;STATUS:timeout=600
;STATUS:random=false
;STATUS:loop=false
;STATUS:sequence=false
;STATUS:countdown=0
;STATUS:targeta=0
;STATUS:targetb=0
while the GETFAVS command returns the list of favourites, with a line like this for each one:
;FAV:Pulse-48-36-50-35,30,180,20,1,Pulse,48,36,50,35,H
All lines end with CR-LF (\r\n).
The latest version of the web scripts sends a GETSTATUS command when the page loads, which will determine the build number of the server software, which can then be used to determine whether or not certain functions can be used in the web script or not, and display extra controls on the web page if required. The SYSTEM command just returns the type of remote app, and is also supported on the Android server; Android 'levels' indicate which functionality is available in server mode.
Parameters
I've tried to be reasonably accepting with parameters, so you don't have to send to many commands to do what you want. Where an option can be turned on or off, you can send 'on' or 'true' and either 'off' or 'false' for instance. At the receiving end, all commands are converted into upper case, so you can use mixed case to send the commands, and it won't make any difference.
Extended command set
So, here's the full list of supported extended commands, as of version 1.1.5. I'll be updating the web script to use more of these. For the current status of web control, see this page. Remember, I've just given the command name here; if you're talking to the software, it needs prefixing with a semicolon, and in HTTP mode, it will be part of a URL, as in the example above.
GOTO
Sets the box to a specific power level and setting, specified by the first four parameters (A, B, C, D). If no rise time is specified as a fifth parameter, 30 seconds will be used as long as both channels are less than 50, otherwise 60. Sixth and seventh parameters can specify the program mode and power level. Examples:
GOTO=10,25,40,30
Sets ouput A to 10, output B to 25, setting C to 40, and setting D to 30. Rise time will default to 30 seconds; mode and power unchanged
GOTO=15,37,30,30,45
Sets output A to 15, B to 37, settings C and D to 30, and takes 45 seconds to get there
GOTO=24,12,17,50,90,8,H
Set channel A to 24, B to 12, mode to Milk (8) and power level to High. Setting C is 17, setting D is 50, and the 2B will take 90 seconds to reach the specified level. Android level 1
SAVE
Saves the current settings of the box to the Favourites list, so that it can be selected later. It will be saved in the same way as clicking Save current on the Mac/PC screen, but the name will being "R-" so that remotely-saved favourites can be spotted easily later. Settings that are saved automatically have their Seq option ticked, so will be included in a sequence.
PLAYSEQ
Starts playing the Favourites that have their Seq option ticked.
STOPSEQ
Stops playing the current sequence, cancel loop and random modes, and sets outputs to zero. If the buildno is not known, or is less than 16, then the server might not understand this command, and it's prudent to send a standard 'K' command to shut down box outputs.
CLEARSEQ
Unticks the Seq option on all the Favourites currently stored on the Mac/PC. If you did this before starting a session, then saved the settings you reached remotely, and started a sequence, only those you've just saved would be selected.
GETSTATUS
Returns the status of various system settings, in the format shown above. This allows you to know if the box is in random mode, what the timeout is, how long it's progressed through a current sequence, and so on. This is an explanation of the values that are returned:
delayfirst
If false, then the advanced setting 'delay before first setting' has not been ticked, so a random sequnce will start immediately
delayvalue
If there's a number, this is the number of minutes that the software will wait before playing the first in a random sequence of settings
delaybetween
If true, the software will wait for a random period between settings in a random sequence
mindelay
maxdelay
These are the number
of seconds for the lower and upper limit of the delay between items in a random sequence
randomtimes
Whether or not run times will be varied in a random sequence
minrun
maxrun
Shortest and longest run times (in seconds) for a program in a random sequence, when randomtimes is activated
randompower
If set to true, then the software will also vary the maximum output in random mode by plus or minus 10%
checks
If true, then commands to change level will be refused if they are more than five steps from the previous level
timeout
The number of seconds used for the Slave timeout mode
random
If true, the software is currently working through a random program
loop
If true, the software is in random loop mode, and so will not stop unless told to do so
looppower
If true, then the power will increase by loopboosta and loopboostb for each iteration if the loop (from 1.1.3/build 16)
loopboosta
loopboostb
The amount by which the power on each channel will increase each time the random loop restarts
(from 1.1.3/build 16)
looptimeout
If true, then the loop mode will stop after the loopruntime number of minutes (from 1.1.3/build 16)
loopruntime
The number of minutes after which loop mode will terminate; at the end of this time, the current program will finish, and loop mode will stop (from 1.1.3/build 16)
sequence
If true, the software is playing a sequence of selected favourites
countdown
The number of seconds for the current timer to run, usually the run-time of the current setting in sequence or random mode
targeta
targetb
The levels to which outputs will be increased in the current mode
version
The current version of the server software
buildno
An internal version of the server software. Version 1.1.3 corresponds to buildno 16; this is used by the web script to work out if certain extended commands can be sent or not. Version 1.1.5 is build 18.
percent
When the server is increasing or decreasing levels, this value will be returned as a status response, to indicate how much of the change has been completed. Build 19 and above. Android level 1.
GETFAVS
This command returns a list of all the favourites stored on the Mac or PC that's running in slave mode. It allows the remote users to see the settings. A line is returned for each favourite, starting with the token ;FAV:
The next part of the line consists of comma-separated values, in the order favourite name, rise time, run time, fall time, sequence, program name, A setting, B setting, C setting, D setting, power level
Time settings are in seconds; power level is "L" or "H", and sequence is "0" it unticked or "1" if ticked.
Program names are used because this is also the format of the saved favourites file; the names can be mapped to program numbers via the defnition Array("Pulse","Bounce","Continuous","Asplit","Bsplit","Wave","Waterfall","Squeeze","Milk","Throb","Thrust","Random","Step","Training")
Android level 1.
CHECKS
This command can be used to disable, or enable the safety check for remote commands that stops steps of more than five at a time being sent to the box. One parameter, either on/true to enable checks or off/false. For safety, if the parameter is omitted, or not understood, checks will be turned on. Example:
CHECKS=TRUE
TIMEOUT
Sets the value, in seconds, of the Slave timeout. You may want to use this if you are planning to start a random sequence, or some other task where the remote control may not send any commands for a long time, and you don't want the software to shut the box outputs down as a result. To set the timeout to fifteen minutes, for example, use the command
TIMEOUT=900
DELAYFIRST
Controls the delay before first setting option in random mode; this command can take either an on/off value (corresponding to turning the checkbox on or off) or a number of minutes, which will turn the checkbox on and set the delay to that number of minutes. Examples:
DELAYFIRST=OFF
Turn the option off
DELAYFIRST=TRUE
Turn the option on, don't alter the time period
DELAYFIRST=75
Turn the option on and set the time period to 75 minutes
RANDOMDELAY
Controls whether or not there's a random delay between settings in random playback. If called with one parameter, use on/off, true/false to tick or untick the option. Called with two parameters, they specify the minimum and maximum delay in seconds, and turn the option on. Examples:
RANDOMDELAY=false
Turn the feature off
RANDOMDELAY=60,300
Use a random delay of between one and five minutes between settings in random mode
RANDOMRUN
Controls whether or not the run time is randomly adjusted in random playback. As with random delay, you can turn it on or off, or specify minimum and maximum values, eg
RANDOMRUN=true
Turn the option on, do not alter the current settings
RANDOMRUN=45,200
Turn the option on, with a random run time of between 45 and 200 seconds for each setting
RANDOMPOWER
On or off; controls whether or not the maximum levels of a sequence will be altered by a random amount of up to plus or minus ten percent
PLAYRANDOM
Starts playing random settings, options selected, using the favourites that have their Seq option checked
PLAYLOOP
The same as playrandom, but continually loops through all the checked favourites
LOOPBOOST
Controls whether or not the power levels in loop mode increase each time the loop repeats. Parameters are on/true, off/false, or the values for the A and B channels. Values above 10 will be ignored. (from 1.1.3) Examples:
LOOPBOOST=off
Turn off the option
LOOPBOOST=4,2
Turn the option on, and set it so that channel A increases by 4 each time through the loop, and channel B by 2.
LOOPTIMEOUT
Controls whether or not the loop mode runs indefinitely, or stops after the end of the setting that's running when the timeout expires. Parameter is on, off or the time in minutes. (from 1.1.3/build 16) Examples:
LOOPTIMEOUT=off
Loop mode will run until manually stopped
LOOPTIMEOUT=60
Loop mode will run for around an hour; when the hour is up, the current setting will finish and return to zero.
UP, DOWN, APLUS, AMINUS, BPLUS, BMINUS
Added in buildno 18, these commands make an adjustment to the box outputs relative to the current levels, either increasing or decreasing by one. UP and DOWN affect both channels, while the others affect either channel A or channel B. For web use, it's preferable to use these, as it avoids potential changes in output if the box controls or server software have changed levels, and the web page has not been updated. For example, even with checks on, a user could turn the box from 50 down to 46, and the + button on the web page would normally send the command to set power to 51. By sending APLUS or BPLUS, then power level will increase to 47, and the web page update appropriately. Web scripts 1.3 and above use this safer method of adjusting power. Note that the UP and DOWN commands are considered experimental.
Build 21 adds CPLUS, CMINUS, DPLUS and DMINUS commands, which have the corresponding effect on the two settings. Android level 1.
MOVE
Added in build 20, the move command instructs the box to change A and B levels to the specified setting over a specific time. Values are absolute, and can be higher or lower than the current settings. Mode and power are not changed, and it's possible to increase one channel while decreasing another. An error response will be given if the number of steps required to change to the new settings is more than the number of seconds specified. Example:
MOVE=30,20,60
Adjust the current levels from whatever they are, until the A channel is set to 30, and B to 20, taking one minute to make the change.
HALT
Added in build 20, this command cancels any current timers or loops, without altering the levels, leaving both channels running at whatever setting they have reached when the command is issued. So, for example, if a favourite or move has been started, and the levels are reaching the limit of what the user can bear, the HALT command will stop them increasing any further, and cancel any timers or random loops.
PLAY
From build 21, this allows playback, by specifying all four main settings, together with rise, run, and fall times, plus program mode and power level.For example
PLAY=20,30,45,70,30,120,20,8,H
Set power output to high, and program to 8 (Milk). The server will increase the levels to channel A at 20, B 30, setting C 45 and setting D 70, over a period of 30 seconds. It will then continue for two minutes, before dropping back to zero over twenty seconds.
SEQSET
Build 21. Turns on the Seq flag for the numbered favourite (starting from zero), so that it will be included in sequences and random loops. Examples:
SEQSET=1
Tick the Seq box for the second favourite in the list on the server.
SEQUNSET
Build 22. Does the opposite of SEQSET, ie unticks the Seq checkbox for the specified favrouite.
MSG
Build 22. Android level 1. Displays the message specified in large type in a box on the screen of the slave computer. For example
MSG=Take some poppers, this is going to hurt
SYSTEM
Build 24. Returns a status message with the platform and build number, to allow distinguishing between Mac/Window and Android. ECS will return
STATUS:type=ECS,24
and the Android app will return
STATUS:type=E4A,1
if it supports certain extended commands. The 1 is the current level of functionality for the Android server.
Since version 2.2.2 of ECS, and the first public release of the Android app with Broker support, when a new connection is received by a slave unit, the first thing it does is execute it's the SYSTEM extended command. This ensures that the remote device knows that it's connected to something that supports extended commands, and which platform, enabling it to request favourites, or send other commands, rather than relying on the standard E-Stim command set.
Notes
One thing to be aware of with this extended commands is that some of them can take longer than the Slave timeout option that's included on the ECS software controlling the 2B. For example, if the timeout is set to 600 seconds (ten minutes), and you send the GOTO command, also specifying 10 minutes, it's likely that instead of continuing at the level you requested, the box will get there and almost immediately set the outputs to zero, because the request for an update of the settings that the web script sends after the GOTO command will be more than 600 seconds after the GOTO was sent.
This is one reason why I've added commands to alter some of the settings remotely, though I've not yet implemented them in my web interface, or in the master mode of the software.