This tutorial will explain to you how to create a Python server for receiving custom sex devices instructions from WickedWhims using socket.
This tutorial expects you how to code in Python and how to handle connectivity to your intended sex device.

1. Example socket listener

Check out the sex_devices_listener.py example socket listener that allows to connect a custom sex device to WickedWhims and receives actions to perform for a sex device.

When attempting to connect a custom sex device with WickedWhims the user has the ability to define the host address and port. The initial connection with WickedWhims requires an appropriate one time return message with sex devices information. From there WickedWhims will continue to establish new connections and send actions for sex devices every time the user interacts with the game in relation to sex actions. WickedWhims doesn't check if the listener is still alive or ready and will continue to attempt sending actions until explicitly disconnected in-game by the user.

2. Communication protocol

Every message from WickedWhims is sent in two parts as two separate messages. The first part is a 10 bytes string message that contains an integer that is the size of the second upcoming part. The second part is a JSON formatted string message that contains the command to perform and additional relevant to the command data in a form of a dictionary.

GetDevices Command

{
    'command': 'GetDevices',
    'version': 1,
}

The 'GetDevices' command is the only message that expects a return message with sex devices name and brand. The return message should be a dictionary with a 'devices' entry that is a list of dictionaries per device that consists of the device name in 'device_name' entry and device model in 'device_model' entry. This information is used when a user establishes a connection to display the name and model of the device which assures everything is working correctly.

{
    'devices': [{
        'device_name' : 'my toy name',
        'device_model': 'Toy Brand Name',
    }, ]
}

Actions Command

{
    'command': 'Actions',
    'actions': [],
    'version': 1,
}

The 'Actions' command contains a list of actions to be interpreted as actions for the intended sex devices.

{
    'action'  : "vibrate",
    'strength': 100,
    'duration': 200,
}

Each action within the 'actions' list is a dictionary that consists of the 'action' entry which is the action command, 'strength' entry which is the strength of the action, and the 'duration' entry which is the duration of the action in milliseconds.

Here's a list of all possible action commands ('action' entry) that can be received:

• "stop" which is intended to stop all devices from performing any actions.
• "vibrate" which is intended to vibrate with the included strength and duration.
• "pump" which is intended to perform pumping motion with the included strength and duration.
• "rotate" which is intended to perform rotating motion with the included strength and duration.
• "finger" which is intended to perform fingering motion with the included strength and duration.
• "suck" which is intended to perform sucking with the included strength and duration.
• "thrust" which is intended to perform thrusting motion with the included strength and duration.
• "depth" which is intended to define depth of other motions with the included strength and duration.
• "oscillate" which is intended to perform oscillating with the included strength and duration.

The strength entry is an integer value from 0 to 100 which is meant to represent how strong should be the action on the scale from 0 to 100. If an action is set to strength equal to 0 then this can be expected as stopping the action from being performed.

The duration entry is an integer value that represents time in milliseconds of how long should the action be performed from the moment of receiving the message with the action. WickedWhims splits single long actions into multiple shorter actions with different strengths to allow for performing modulating in strength patterns rather than a monotone in strength single action. How actions per received message are interpreted is up to the developer of the sex device listener.

3. Example post-handshake confirmation message

Below is an example message your listener may receive. It is the "post-handshake" message that is sent right after the "GetDevices" return message is received by WickedWhims to confirm the sex devices are connected and functional. WickedWhims constructs this message as an action pattern of vibrate that lasts 300 milliseconds with 3 strengths that each lasts 100 milliseconds, two first vibration strengths are 100% and the last one is 0% to stop it. This is sent as 3 separate actions in one message that looks like this.

{
    'command': 'Actions',
    'actions': [
        {
            'action'  : 'vibrate',
            'strength': 100,
            'duration': 100,
        }, {
            'action'  : 'vibrate',
            'strength': 100,
            'duration': 100,
        }, {
            'action'  : 'vibrate',
            'strength': 0,
            'duration': 100,
        },
    ],
    'version': 1,
}

Last update: 23rd of February 2025