HTequi/HTequi-firmware/lib/ArduinoOSC-0.2.2

ArduinoOSC

OSC library for Arduino (ESP, Teensy, AVR, etc.)

ArduinoOSC is OSC Library for Arduino. OSC packet parsing is based on the oscpkt and optimized for Arduino.

NOTE : BREAKING API CHANGES (v0.2.0 or later)

Almost all APIs has been changed in v0.2.0 and got much simpler. Please check below if you use previous versions.

Supported Platform

This library is tested for following platforms and interfaces.

• ESP32 (WiFi, Serial)
• ESP8266 (WiFi, Serial)
• Teensy 3.x (Ethernet, Serial, Serial1, 2, 3...)
• Arduino Mega (Ethernet, Serial, Serial1, 2, 3)
• Arduino Uno (Ethernet, Serial)

Feature

• simpler usage than ever
  • callback registration with lambda
  • osc packet sending in one-line
• support pattern-matching (wildcards)
• support basic OSC types
  • TF (bool: true, false)
  • i (int32_t)
  • h (int64_t)
  • f (float)
  • d (double)
  • s (string)
  • b (bundle)
• does NOT support timestamp values.

Usage

Please see examples for detals.

WiFi

#include <ArduinoOSC.h>
OscWiFi osc;

void setup()
{
    WiFi.begin(ssid, pwd);
    WiFi.config(ip, gateway, subnet);
    osc.begin(recv_port);
    
    // add callbacks...
    osc.subscribe("/lambda", [](OscMessage& m)
    {
        // do something with osc message
        Serial.print(m.arg<int>(0));    Serial.print(" ");
        Serial.print(m.arg<float>(1));  Serial.print(" ");
        Serial.print(m.arg<String>(2)); Serial.println();
    });
}

void loop()
{
    osc.parse(); // should be called
    osc.send(host, send_port, "/send", 1, 2.2F, 3.3, "string"); // send osc packet in one line
}

Ethernet

#include <ArduinoOSC.h>
OscSerial osc;

void setup()
{
    Ethernet.begin(mac, ip);
    osc.begin(recv_port);	
    
    // add callbacks...
}

void loop()
{
    osc.parse(); // should be called
    osc.send(host, send_port, "/send", 1, 2.2F, 3.3, "string");
}

Serial

#include <ArduinoOSC.h>

void setup()
{
    Serial.begin(115200);
    osc.attach(Serial);
	
	// add callbacks...
}

void loop()
{
    osc.parse(); // should be called
    osc.send("/send", 1, 2.2F, 3.3, "string");
}

Subscribe Callbacks / Publish OSC (TBD)

// TODO: TBD
// osc.subscribe("/int32", i);
// osc.subscribe("/float", f);
// osc.subscribe("/string", s);
// osc.subscribe("/blob", b);

osc.subscribe("/callback", onOscReceived); // old style (v0.1.x)

osc.subscribe("/lambda", [](OscMessage& m)
{
    Serial.print("lambda : ");
    Serial.print(m.ip()); Serial.print(" ");
    Serial.print(m.port()); Serial.print(" ");
    Serial.print(m.size()); Serial.print(" ");
    Serial.print(m.address()); Serial.print(" ");
    Serial.print(m.arg<int>(0)); Serial.print(" ");
    Serial.print(m.arg<float>(1)); Serial.print(" ");
    Serial.print(m.arg<String>(2)); Serial.println();
});
osc.subscribe("/wildcard/*/test", [](OscMessage& m)
{
    Serial.print("wildcard : ");
    Serial.print(m.ip()); Serial.print(" ");
    Serial.print(m.port()); Serial.print(" ");
    Serial.print(m.size()); Serial.print(" ");
    Serial.print(m.address()); Serial.print(" ");
    Serial.print(m.arg<int>(0)); Serial.println();

});
osc.subscribe("/need/reply", [](OscMessage& m)
{
    Serial.println("/need/reply");

    int i = 12;
    float f = 34.56F;
    double d = 78.987;
    String s = "hello";
    bool b = true;

    osc.send(host, send_port, "/send", i, f, d, s, b);
});

// TODO: TBD
// osc.publish(host, send_port, "/value", value);
// osc.publish(host, send_port, "/millis", &millis);

Limitation for AVR Boards (Uno, Mega, etc.)

• max number of arguments is 3
• max packet data size is 64 byte
• max number of callbacks is 8
• osc packet is not queued (only latest packet can be held inside)
• bundle is not supported
• limited API (see below and examples/UnoMegaAvr/*)

Read API Limitation

m.arg<type>(index) cannot be used in AVR. Please use old APIs.

m.getArgAsInt32(0);
m.getArgAsFloat(1);
m.getArgAsString(2);

Send API Limitation

In sending osc, one-line feature is not available in AVR. Please create OscMessage and send(msg) after that.

OscMessage msg(host, send_port, "/send"); // WiFi, Ethernet
OscMessage msg("/send");                  // Serial
msg.push(i).push(f).push(s);
osc.send(msg);

TBD

• one-line subscriber for single variable

// directly changes variable 'i' if message with "/int32" comes
int32_t i;
osc.subscribe("/int32", i);

• one-line publisher for single variable

// send "value" automatically
float value;
osc.publish(host, send_port, "/value", value);

• one-line publisher for function which returns single value

// send the result of "millis()" automatically
osc.publish(host, send_port, "/millis", &millis);

• automatically detect the type of arguments (without template arguments)

int32_t i = m.arg<int32_t>(0);
float   f = m.arg<float>(1);
String  s = m.arg<String>(2);
// becomes
int32_t i = m.arg(0);
float   f = m.arg(1);
String  s = m.arg(2);

License

MIT