Integration OSC & Events

Controlling Protopixel Mapping Tool using OSC

Protopixel has a native Open Sound Control interface exposed in port 2345.

Controlling standard contents

You can affect the contents in your project by sending OSC messages to this port. The OSC address schema is like follows:

/<type>/<name>/<param> <value>
/<type>/<name>/<param>

With those parameters:

• <type> is the entity type, and at the moment it can only be Content.
• <name> is the name of the entity.
• <param> is the parameter of the entity to be modified. You can see those parameter names by accessing to the Content section in the WebApp. If the parameter is inside a parameter group, you can use / to separate group from the parameter name. See the examples.
• <value> is the new value of the parameter. It can be omitted if the parameter is a button.

Getting all parameters from a content

CONTENT_NAME="color"
curl -H "Content-Type: application/json" -X POST \\
	--data '{"command":"getSimpleConfContent", "args":["$CONTENT_NAME"]}' \\
	<http://localhost:8181/api/v1/core/get> | python -m json.tool
  
{
    "result": {
        "Zone": "",
        "color levels": [
            255,
            255,
            255,
            255
        ],
        "enabled": true,
        "lock_gui": false,
        "params": {
            "color": [
                33,
                87,
                118,
                255
            ]
        },
        "params_in_manager": false,
        "projection parameters": {
            "height": 1,
            "width": 1
        },
        "projection type": "flatsimple",
        "python script": "lib/programs/color.py",
        "reload": null,
        "renderable": true,
        "save_params_in_mood": true,
        "texture filtering": "linear",
        "texture horizontal offset": 0,
        "texture vertical offset": 0,
        "uid": "4218023060"
    }
}

OSC Messages Examples

# enable content
/Content/mycontent/enabled 1

# disable content
/Content/mycontent/enabled 0

# play video content
/Content/rainbow.mp4/params/play

# stop video content
/Content/rainbow.mp4/params/stop

# change color for a color content (R, G, B, A)
/Content/color/params/color 255 100 100 255

Sending OSC to custom scripts

Inside a custom script, you can register an OSC endpoint like this:

@content.OSC("/acc")
def acceleration(x, y, z):
    """
    This function handles OSC user input in address "/acc", with 3 arguments: x,y,z.
    Use pl.OSC decorator to define handles like this. Multiple scripts can listen to
    the same address simultaneously.
    """
    global color2
    r = normalize(x)
    g = normalize(y)
    b = normalize(z)
    color2 = ofColor(r, g, b)

Please take into account that if the number of arguments sent does not match the function signature, the message will not be delivered.

Sending events to Spaces

Protopixel Spaces can integrate with other elements such as presence sensors via its API.

The API entry is the following:

/api/v1/external/toggle/%button_name/%status

example:
curl <http://localhost:8181/api/v1/external/toggle/Button1/On>

To tie it to a particular action, go to the space as Manager and select My Rules in the menu.

You can check the API specification to see the syntax of the HTTP queries you can send to our ecosystem.

Adding an event means triggering a mood from an external trigger via HTTP, the information sent to execute a trigger must be configured through HTTP.

Then Click on Add Rule → Add Event → Learn and trigger the event. You can now select it.

Connecting it to sensors

The usual way to do this is to use Domoticz to configure the Zwave and add a script:

1. Go to Setup → More options → Events.
2. Use the / button to create a new script and select Lua → Device.
3. Paste the following code.
4. Update the URL if necessary.

BASE_URL = "<http://localhost:8181/api/v1/external/toggle/>"

commandArray = {}

-- loop through all the changed devices
for deviceName,deviceValue in pairs(devicechanged) do
    deviceName = string.gsub(deviceName," ","%%20")
    deviceValue = string.gsub(deviceValue," ","%%20")
    commandArray[#commandArray+1] = { OpenURL = BASE_URL..deviceName.."/"..tostring(deviceValue) }
end

return commandArray