Extended e-stim commands

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 E-Stim systems 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 main index!

Extended command basics

The commmands detailed here can be sent as part of the data stream between two apps. After talking with eStim, we agreed that the semicolon character would be suitable for 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 implemented was the GOTO command. It takes the form ;GOTO=12,15,40,63

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.

The command details here are as implemented in Estim Control/Server version 2.4 and above (and changes will be noted). If you are using an earlier version, not all commands may be available. Please update your software.

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

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

I've tried to be reasonably accepting with parameters, so you don't have to send too 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.

Commands and supported platforms

The table here is correct for version 2.4 of both Android and desktop apps. In older versions of some apps, certain commands may not be available, or certain options to those commands may not be available. You are strongly recommended to update your software. The original version of this page includes more detail about which versions suport which commands. The Android column indicates if the command is supported by estim4android when running in server (slave) mode. If no response is indicated, the standard status of the 2B will usually be returned.

Command

Description

Option & response

Android

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.

With four parameters, eg ;GOTO=10,25,40,30 set output A to 10, B to 25, setting C to 40 and D to 30. It will take 30 seconds to reach levels, mode and power are unchanged
With five parameters, eg ;GOTO=15,37,30,30,45 the fifth parameter is the time taken to reach the required levels
With seven parameters, eg ;GOTO=24,12,17,50,90,8,H parameter 6 is the 2B program, and parameter 7 is the power level

With 7 params

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 begin "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 ECS 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.

A multiple line response, each starting with ;STATUS:option=value as in the example above. The following options may be reported:
delayfirst If false, then the random setting 'delay before first setting' has not been ticked, so a random sequence 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 ECS 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 of the random loop
loopboosta, loopboostb The amount by which the power on each channel will increase each time the random loop restarts
looptimeout If true, then the loop mode will stop after the loopruntime number of minutes
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
sequence If true, the software is playing a sequence of selected favourites
coundtown 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 number of the server software, which is used to determine which commands are available. See the old details page for earlier builds
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.

percent only

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")

Yes

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: ;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

To turn off, ;DELAYFIRST=OFF
To turn on, but not alter the time period, ;DELAYFIRST=TRUE
To turn on and set the time period, ;DELAYFIRST=5

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.

To turn off, ;RANDOMDELAY=false
To use a delay of between one and five minutes in random mode, ;RANDOMDELAY=60,300

RANDROMRUN

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

Turn on, do not alter settings, ;RANDOMRUN=true
Turn on, with a random run time of between 45 and 200 seconds, ;RANDOMRUN=45,200

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.

To turn off, ;LOOPBOOST=off
To turn on, with channel A increasing by 4 and channel B by 2, on each loop, ;LOOPBOST=4,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.

To set the loop to run until manually stopped, ;LOOPTIMEOUT=off
To set the loop to run for an hour; at the end of one hour, the current setting will finish, then the outputs will remain at zero, ;LOOPTIMEOUT=60

UP
DOWN
APLUS
AMINUS
BPLUS
BMINUS
CPLUS
CMINUS
DPLUS
DMINUS

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

Although supported, note tht ;UP and ;DOWN generate two sets of commands at the remote end, and are considered experimental.

Yes

MOVE

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.

To 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, ;MOVE=30,20,60

HALT

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

Allows playback, by specifying all four main settings, together with rise, run, and fall times, plus program mode and power level

To 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, ;PLAY=20,30,45,70,30,120,20,8,H

SEQSET

Turns on the Seq flag for the numbered favourite (starting from zero), so that it will be included in sequences and random loops.

Numbers start at 0. To turn tick the box for the second favourite in the list on the server, ;SEQSET=1

SEQUNSET

Does the opposite of SEQSET, ie unticks the Seq checkbox for the specified favrouite.

MSG

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

Yes

SYSTEM

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
estim4android will return ;STATUS:type=E4A,1
The number is the build level, which indicates the supported commands; 24 is the current level of command support in Estim Control/Server. Android support is level 1. As of July 2017, supported version will both automatically execute the SYSTEM command when in slave mode, after receiving an incoming connection. This ensures the capabilities of the remote end can be detected easily.

Notes

One thing to be aware of with 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.

Many of these remote commands are not presently sent from one app to another, but they can easily be generated by a web interface - which will hopefully soon be part of StimBroker - to allow a remote user as much control over the 2B as if they had installed the app.

HTTP commands in Estim Control/Server

As well as accepting commands via a standard connection, ECS has an HTTP command mode. This is designed principally to make it easier to build a web page to control the 2B, without having to dick around with websockets.

An extended command sent via an HTTP connection would look something like GET http://some.place.on.line:7846/;GOTO=12,15,40,63,120 HTTP/1.1

An ordinary command might just look like GET http://some.place.on.line:7846/A12 HTTP/1.1

ECS will parse the first one as ;GOTO=12,15,40,63,120 and the second as A12. In the manual settings panel of ECS preferences, tick the HTTP Slave box to enable support.

Back to the tech page.