Get started with oscpad

Oscpad is a simple way to make a touchscreen control panel which you can access via web browser.

Quick startup:

First, install the openssl lib, and cargo/rust. Then,

$ cargo install oscpad
$ ~/.cargo/bin/oscpad -mkconfigs server.conf gui.conf
$ ~/.cargo/bin/oscpad server.conf

Then, go to localhost:3030 with your web browser. Try two web browser windows at once! Both will be updated with the latest control states.

Configuration and etc

You configure the oscpad controls with a json file, like this one:

{
  "title": "test",
  "rootControl": 
    { "type": "sizer",
      "orientation": "vertical",
      "controls": [
      ,{ "type": "label"
       , "name": "lb3"
       , "label": "blah"
       }
      ,{ "type": "button"
      ,  "name": "b1"
       }
      ,{ "type": "slider"
       , "orientation": "horizontal"
       , "name": "hs2"
       }
      ]
    }
}

This file contains the four types of controls: label, button, slider, and sizer. The sizer contains the other three controls. Sizers and sliders have either vertical or horizontal orientation. You can nest sizers inside other sizers for more complex layouts. This one looks like so:

Once you're created a control panel, you can point it at an OSC program to receive messages from it. I have a haskell program 'oscrecv' which prints out OSC messages sent to it. Using the controls in the above example layout makes messages such as these:

[bburdette@nixosthe1:~/code/oscpad.wiki]$ oscrecv 127.0.0.1 7070
"2015-11-25 23:15:24.710061 UTC"
Just (Message {messageAddress = "b1", messageDatum = [ASCII_String {d_ascii_string = "b_pressed"}]})
"2015-11-25 23:15:25.055088 UTC"
Just (Message {messageAddress = "b1", messageDatum = [ASCII_String {d_ascii_string = "b_unpressed"}]})
"2015-11-25 23:15:26.352999 UTC"
Just (Message {messageAddress = "hs2", messageDatum = [ASCII_String {d_ascii_string = "s_pressed"},Float {d_float = 0.49405235}]})
"2015-11-25 23:15:26.493717 UTC"
Just (Message {messageAddress = "hs2", messageDatum = [ASCII_String {d_ascii_string = "s_moved"},Float {d_float = 0.49405235}]})
"2015-11-25 23:15:26.556471 UTC"
Just (Message {messageAddress = "hs2", messageDatum = [ASCII_String {d_ascii_string = "s_unpressed"},Float {d_float = 0.49405235}]})

One can send messages the other way, to change the state of the controls from the OSC side. The program oscsend (not my program) can do this, just sending the same message back to the server. Here I change the label text, then change the button state to pressed, then change the slider position.

[bburdette@nixosthe1:~]$ oscsend localhost 9000 "lb3" ss "label" "test text"

[bburdette@nixosthe1:~]$ oscsend localhost 9000 "b1" s "pressed"

[bburdette@nixosthe1:~]$ oscsend localhost 9000 "hs2" sf "location" 0.75

Here's the result of those commands:

All currently connected web clients will get updates, so that they all display the controls in the same state.

To run oscpad (after building oscpad using cargo, the command is just "cargo build") you'll need to have a server config file as well as the gui file. Oscpad will generate example files for you with the -mkconfigs command. This is 'genericconfig.json' from the oscpad/examples directory:

{ "guifile": "example_projects/echotest/echoguiconfig.json", 
  "htmlfile": "elm/index.html+main.js",
  "ip": "0.0.0.0",
  "http-port": "3030",
  "websockets-port": "1234",
  "oscrecvip": "localhost:9000",
  "oscsendip": "localhost:7070"
}

In it, the 'guifile' specifies the touch control layout. Next there's the html file to serve up, only needed if you are hacking on the elm code. If this entry is missing (the default with -mkconfigs), then oscpad uses a precompiled html string stored in the exe itself.

ip, the http-port and websockets-port specify the html web server and websockets ip addresses, respectively. By default ip is set to "0.0.0.0", which allows local or external access to the web server at your current IP address.

The oscrecvip is where oscpad receives OSC messages, and oscpad sends OSC messages to the oscsendip address.

A more elaborate example

This layout is for simulating the Cyclophone, a controller which sends out osc messages. It has 24 keys, 3 buttons, 3 knobs, and a 5 way selector switch. With this layout I can test the cyclophone audio engine without needing the physical instrument.

Since oscpad's OSC messages are in a different format from what the real cyclophone generates, the cyclosim program is necessary to translate. It also makes the 24 key sliders spring up to top of their range, similar to how the physical keys work on the cyclophone instrument.

Of note in the cyclophone gui layout file are the proportion arrays. For instance the top level sizer contains this line:

  "proportions": [0.1,0.2,0.7],

This sizer contains 3 controls (which are themselves sizers), and normally each one would get 1/3 of the available drawing space. The proportion array lets you change the relative size of each element. In general the numbers should add up to 1.