Working With OSC

OSC (Open Sound Control) is a protocol for inter-application communication across networks. It effectively defines a set of rules and packet formats to enable applications to talk to each other. We can use OSC to control Simmetri via an external app that lives somewhere on the network or locally on the same computer. Alternatively, we could use Simmetri to drive an external app as well.

OSC Example Using an iOS device:

In the following example, we'll use an app running on an IOS device called Unipad to send messages to a Simmetri show (if you have an Android device, you can search for an OSC app on the Play Store). 

STEP 1:  Get iOS device and Simmetri on Same Network

To get this example to work, both the computer running Simmetri and the iOS device need to reside on the same network. There's a couple of ways to do this. One way is to enable the Personal Hotspot on the iOS device then have the computer connect directly to the Hotspot. Another way is to have both connected to the same WiFi network, though you may need to configure the WiFi router to dispatch OSC traffic to the computer's IP address via a port forward (for port 8001). 

STEP 2:  Get iOS Device Setup with Unipad App 

Once both your computer and iOS device are on the same network, we can proceed with the example.

• First off, install the Unipad app on your iOS device (search for "Unipad remote" from the App Store).
• Next tap New Connection in Unipad and configure 'Host' set to your computer's IP address on the local network and set 'Port' to 8001. Also, ensure the 'Protocol' is set to OSC.
• Once done, click Connect.
• Next, click the Green controller icon at the top of Unipad.
• From the menu the appears, tap "Change PadType".
• Finally, select 'GAMEPAD' and click OK. You should see a set of buttons on the screen.

Step 3:  Configure Simmetri to receive OSC messages

• If not already, let's start with a fresh Simmetri show. Click File/New to create a new universe (aka 'show').
• Next, undock the Browser Panel at the top-left of the screen
• Click the + button at the bottom right of the Browser Panel
• From the menu, select Scripts / Extensions / Open Sound Control (osc)
• Click Play at the bottom right of the screen
• Your OS might ask you to allow Simmetri through the firewall. Be sure to ensure both Private and Public network checkboxes and checked and click Allow access.

Now when you press a button on the OSC iOS app, Simmetri should print a message showing you it received the message.

• Note: If you mistakenly didn't allow access when the OS asked you to, you can enable it manually by going into the system firewall settings and selecting Allow An App or feature through Windows Defender Firewall. Next click Change Settings and find 'Simmetri Editor' in the list and ensure both the public and private boxes are checked then click OK.
• If your IOS device display turns off, the connection might get closed. To reconnect, open Unipad and click the green controller icon, then select Reconnect from the menu.

Step 4: Create a Simmetri Show that Interacts with the OSC Inputs

Once you have everything setup and working such that pressing buttons on the iOS app causes messages to appear in Simmetri, we can move on to creating a simple example of influencing something in the space.

• Click Stop at the bottom right of the screen
• Undock the Toolbox Panel on the left-side of the screen
• Click Entities from the top list
• Click Box from the bottom list
• Draw a small box in the center of the space
• Right-click to exit draw mode
• Undock the browser panel
• Ensure TerrainSpace is selected from the left-most list
• Click scripts from the center list
• Double-click the OSC Example icon. A code window should appear.

The pre-written script shown has been setup to work with the Unipad. If we look inside the 'onInit()' function, we can see where it registers functions to get called when Unipad sends certain messages:

function GlobalScript:onInit()
	local oscServer = getUniverse():getLibrary():findObjectByName("OSCServer")

	-- Register some handlers at specific OSC addresses
	oscServer:register("/touch/start", self, self.onButtonPress)
	oscServer:register("/touch/end", self, self.onButtonRelease)
	oscServer:register("/touch/pos", self, self.onPadTouch)
	oscServer:register("/touch/pos2", self, self.onPadTouch)

	-- Also register a function to catch any unhandled messages
	oscServer:register(nil, self, self.onUnhandledMessage)

end

The 'register()' function basically says "when I receive a message of the form "/touch/...", call a function on myself called 'onButtonPress()', etc". The Unipad app happens to send messages in the form of "/touch/..." which is why we register our handlers in such a fashion. Other OSC apps may communicate differently hence why the last statement in the function above will print whatever messages may come in so we can figure out what messages to register with.

Step 5:  Link Your OSC Inputs to Interesting Functions/Actions in Simmetri 

Finally, let's do something with our cube when a button is pressed.

• Find the 'onButtonPress()' function in the script
• Next, in the script window, place the cursor after the 'print()' statement and press enter a couple of times to create some space to type. You should have something like this:
  

  function GlobalScript:onButtonPress(control_id)
  	print(control_id .. " Pressed!", 1)
  
  	
  end

• Next, undock the Heierarchy Panel from the right side of the screen
• Now drag-and-drop the BoxEntity item from the hierarchy list onto to script window on the line after the 'print()' statement.

• Your 'onButtonPress()' function should now look like this:
  

  function GlobalScript:onButtonPress(control_id)
  	print(control_id .. " Pressed!", 1)
  	BoxEntity = findObjectByUid("16UJDTYCFJC9K1K31DZDDRICG4/12J0ABHO4QVAQ2Z3SZ342BN5PK")
  
  end

• Finally let's add a line of code to make the box hop. On the following line, write the following statement:

  function GlobalScript:onButtonPress(control_id)
  	print(control_id .. " Pressed!", 1)
  	BoxEntity = findObjectByUid("16UJDTYCFJC9K1K31DZDDRICG4/12J0ABHO4QVAQ2Z3SZ342BN5PK")
  	BoxEntity:getRigidBody():applyCentralImpulse(vector3(0,1,0))
  end

• Press Play
• Press a button on the IOS app. The box should hop.

Depending on how large a box you created, you may need to increase or decrease the number '1' in the script above to make the cube hop reasonably. For fun, one last thing we can do is have the camera track our jumping box.

• From the Toolbox panel, click Cameras from the top list
• Click Track Object from the bottom list
• Click the box you drew in the space
• Right-click to exit draw mode

Now when we make the box hop, the camera will track it.