SAGA UDP API Resources

Authentication

The UDP endpoint requires no authentication. It's assumed that the network setup is taking care of protection.

Behavior

The UDP endpoint creates a global property called 'udp_datagram' for each interaction. It creates this global property since there are no headers or path information as there are, for example, in a HTTP call to identify and sort the incoming request. The property value contains the JSON stringified payload as well the remote address and port of the sender.

Example

{
   "info": {
      "size": 24,
      "port": 32947,
      "family": "IPv4",
      "address": "172.19.0.1"
   },
   "message": "{\"type\":\"Buffer\",\"data\":[47,116,111,116,101,109,47,108,105,103,104,116,0,0,0,0,44,102,0,0,0,0,0,0]}"
}

Processing of UDP Datagrams

The SAGA instance will create a script that is bound to '/properties/udp_datagram'. In there, you first need to unwrap the payload.

  const message = Buffer.from(JSON.parse(property.value.message)).data;  

Based on the message content and the IP address, one way of processing could be finding or creating a SAGA bot with the given IP address and create a new property for this bot with the given message. This way, the data is routed to a properly scoped script that can handle the data.

Here is an example script that is assuming OSC messages; it's using the OSC data structure to find or create a SAGA bot based on the given OSC message path, adding the IP address and port as well as the OSC message arguments as properties to the bot. Bot Scripts will do the specific processing. The script assumes understanding of properties and dynamic behaviors.

const message = osc.fromBuffer(Buffer.from(JSON.parse(property.value.message).data));
const path = message.address.replace(/^\//,"").split("/");
const property_name = path.pop(); //the last segment of the path becomes the property name
const name = path.join(".");
const address = `${property.value.info.address}:${property.value.info.port}`

const bot = (await Bot.findOrCreate({name}))[0]; // returns array hence [0]
await BotProperty.addValueNotify("address", address,bot._id)
await BotProperty.addValueNotify(property_name,message.arguments,bot._id,true)
done();