Socket server and external control

Shoebot allows you to control your image output live before actually outputting it to a file. More, it can be controlled via external applications through a socket server, and you can even control Shoebot scripts through a network.

Making scripts that work with the socket server

If you run a script with the socketserver option (-s), you'll see a line in the terminal indicating that the socketserver is active:

  $ sbot -ws /usr/share/shoebot/examples/socketcontrol.bot
  Listening on port 7777...

(Note that this will call Shoebot in its windowed mode. The socket server is not available in oneshot mode.)

This effectively creates a socket that begins listening to incoming connections. In case you want a port other than the default one (7777), specify it with the -p option:

  $ sbot -wsp 31337 /usr/share/shoebot/examples/socketcontrol.bot

Now you would fire up your application to connect to the script in order to control the window. In the examples dir you will find a socketcontrol.bot script, as well as a Pure Data patch (socketcontrol.pd) to control it, which we'll look over below.

The only necessary code to have a controllable script is specifying the variables we will want to access from outside, using the var() function:

  var(name, type, value, min, max)

'name' should be a string with the name we will use to refer to this variable; 'type' should be either NUMBER, BOOLEAN or TEXT (BUTTON doesn't work for outside access); 'value' is the starting value, 'min' and 'max' are optional parameters that specify the minimum and maximum values to create the variables window (so you can leave them out if you're not using the var window). An example:

  var('spam', NUMBER, 30)
  var('eggs', NUMBER, 20)

(Important: The socket server was only tested with NUMBER type variables. Try the others and tell us about it!)

You can after use these variables inside the draw() loop, and they can be controlled via socket messages. The message format is the variable name and value separated by a space (e.g. "spam 10"). Following is a walkthrough in creating a Shoebot script and a Pure Data patch to control it.

Socket server example with Pure Data

In this example, we'll create a simple shape, and control its colour fill values with a Pure data patch.

We'll begin the script with the window dimensions:

  size(200,200)

Afterwards, we have to specify the variables which can be accessed from outside.

  var('one', NUMBER, 186)
  var('two', NUMBER, 186)
  var('three', NUMBER, 93)

Now we have to define our setup() and draw() methods. We'll have to specify one-time commands in setup(), and the drawing commands inside the draw() function.

  def setup():
      # set the colour range to 255
      colorrange(255)

  def draw():
      # dark green background
      background(76,102,51)

Still inside the draw() loop, we'll now call on the variables we specified above to set the fill color:

      red = one
      green = two
      blue = three

      fill(red, green, blue)

And finally, we just have to specify the shape we want to see.

      star(100, 100, 20, outer=25, inner=15)

This is all we need for the Shoebot script. Try running it (without forgetting the -ws options!)

So far it doesn't change; now we'll create a very simple Pure Data patch to send messages to the Shoebot window.

The Pure Data side is even simpler. We just need to send appropriate messages to the socket server. We start by making three VSliders:

We will now need a netsend object in order to send our messages. It helps to connect it to a number box or toggle to ensure the connection is active.

We now have to make appropriate messages to be piped into the netsend object. The appropriate message format is "send <variable_name> <value>", so we just use the $ substitution feature in PD in order to pass the values to netsend:

Finally, we need to create a couple of message boxes to control the netsend object.

Notice that it's connecting to the default socketserver port. You can totally replace 'localhost' by an IP address to control the Shoebot script from another machine!

So now our client/server pipeline is complete, it's time to run the Shoebot script again, turn on the netsend object in the PD patch (by clicking the connect message) and play with the sliders. Do check the socketcontrol2.bot example for another possible use of external input.