The Broker protocol builds on my extended e-stim commands, and runs as a service (presently at stimbroker.xyz) that connects two estim apps together, allowing one to control the other's 2B. The protocol here is for the current (February 2018) version, as implemented in version 1.0 of the server. Note that some of the commands previously supported, for registration and setting user visibility, have been removed, because that's now handled by the website.
If you wanted to build an app to connect to the StimBroker service, it will need to make a TCP connection to port 37846 on the host stimbroker.xyz, and then respond to the commands, or use a WebSockets connection to port 37847. As of version 0.99 the server will bridge between TCP and Websocket connections.
As with extended commands, all commands in the Broker protocol start with a ; and all responses are likewise prefixed with a semicolon. If a connection has been established between two users, then data is checked to see if it is a valid Broker command or response; if it is, then it's acted on, otherwise data is passed through to the remote connection. If there is no remote connection, anything that's not a command is ignored.
Here's a simple session, where nigel@roughsex.org is connecting to hello@stimbroker.xyz.
;info:estim broker 0.9 - 0 users registered - use ;help for assistance
They they send a register command, to sign in, using their StimBroker id followed by a semicolon and then their PIN (earlier versions didn't need a PIN)
;register=nigel@roughsex.org;12345
From broker version 1.00, aka protocol 2, an extended version of the register command can be used, which sets the user's profile, and allows for future expansion. This is
;register=nigel@roughsex.org;12345;v2;This is my profile text
which is acknowledged by the server, and the message now includes the service expiry date and nickname:
;registered:nigel@roughsex.org;expires:2017-09-05;nick:LondonSubNigel
The slave then does nothing; it's just waiting for an inbound connection. The master side issues a connection request with the command, specifying a nickname, rather than an email address
;connect=LondonSubNigel
and the server sends this message to the slave, indicating who is trying to connect, again now using the nickname, not the address:
;connect=stim0001
When the user of the slave system confirms they want to accept, they send the command
;accept=stim0001
Both sides then receive the message
;connected
and now all data (stim commands, status from the 2B) is passed between the two users. If either user disconnects for any reason, the message
;disconnected
is sent to the other party to let them know.
This is the complete list of commands supported by the Broker protocol as at February 2018. Commands listed in earlier versions and not here are no longer supported. As of Feb 2018 the broker uses the extended register command to determine the protocol version. If the non-extended version is used, protocol 1 is assumed. The server handles protocol differences automatically - so if a protocol 1 client requests a user list, the response won't include profiles. The profile text of a protocol 1 user is set to 'not supported', and a protocol 2 user will receive an error if they attempt to send a chat message to them.
A 'protocol 2' client includes Estim Control/Server version 2.50 and above, or the LiveStim page. Other apps will be updates shortly.
;accept=stim0001
Request a connection to another user. Pass their nickname. If the user is found, there will be no response until they reply. If they accept a connection, the response will be ;connected but if they reject the request, the response will be ;denied
If the requested user is already connected to someone, or is not connected to the broker, the response will include their user name, and will be either ;busy or ;unavailable respectively, eg ;busy:stim0001
A connect request cannot be made without registering first; if registration has not been completed, the message ;error:not registered will be sent
If a user with a secondary id tries to connect to a user other than their own primary id, or a user with a primary id tries to connect to someone else's secondary id, the ;unavailable response will be issued.
A client using protocol 2 will receive an extended connect request, with the profile information of the requesting user, eg
;connect=LondonSubNigel;I want to do real bad things with you
;disconnected message to the other user, while still remaining connected to the broker service
;end except that the connection to the broker is closed as well
Protocol 1: register with the Broker, using an email address as an ID, and the PIN for the associated account eg ;register=nigel@roughsex.org;12345
Protocol 2 and above: the v parameter specifies the protocol version, and the remaining text is the user's profile to be displayed in the user list eg ;register=nigel@roughsex.org;12345;v2;Looking for someone to control my 2B
A successful result will display a ;registered message that includes the expiry date after which access will be rejected with a 'subscription expired' message, eg ;registered:nigel@roughsex.org;expires:2017-09-05 and a failure will return the response ;failed followed by a code and a descriptive message. The codes are presently 1 for no account found, 2 for subscription expired and 3 for banned. If the reason is an expired subscription, the expiry date will also be included , eg ;failed:2=subscription expired;expired:2017-07-05
;reject=LondonSubNigel and the user will receive the ;denied response
;user:LondonSubNigel
;user:stim0001
;total:2
Users connected with a secondary id are visible only to users signed in with the matching primary id. Users connected with protocol 2 or above will see a semicolon after the user name, followed by the profile text, eg
;user:LondonSubNigel;This is nigel, the creator of StimBroker
;user:stim0001; This is nigel's secondary account
;total:2
As well as the changes mentioned above, the updated protocol adds some extra features.
The broadcast message may be sent from the server, to all connected users. Apps should display the message as soon as possible. This is intended to allow for things like system maintenance messages. Clients will receive a message like
;broadcast:System going offline for maintenance. Back in five minutes
The chat function is in addition to the pre-existing messaging between users supported by apps. This allows clients to exchange messages with other connected StimBroker users, for example to negotiate prior to taking control of someone's estim unit. The command is sent specifying the nickname of the member you want to send to, followed by a semicolon and then the text of the message. For example, to send a message to LondonSubNigel you would send
;chat=LondonSubNigel;Hello. Do you fancy letting me control your 2b?
The receiving end, assuming your nickname was StimMaster, would receieve the message as
;chat=StimMaster;Hello. Do you fancy letting me control your 2b?
If a chat cannot be send, an ;error response will be returned. There are presently three options:
;error:not registered is sent if the other user is not connected to StimBroker
;error:not supported is sent if the other user is using protocol 2, which does not support chat
;error:user is busy is sent if the other user is connected (as master or slave) to someone else
There is no limit on the number of simultaneous chats imposed by the server.
My apps support auto-connection, allowing users to specify in their preferences that when a connection is made in Master mode, the app should attempt to connect to a specific user, or that in slave mode, connections from a specific user should be accepted automatically.
This is handled entirely in the app, by the app recognising the incoming request, and sending the ;accept response, or issuing the ;connect command as soon as it connects. The same mechanism can be used to build a blacklist of connections to automatically reject, as well.
If you are supporting StimBroker in your own code, you should provide a similar mechanism. You should not simply accept all connection requests without allowing the user to see who wants to control their 2B and giving them a chance to reject the connection. Where possible, you should probably display the profile for the incoming connection, to help the user make their choice.
Back to the tech page.