MicroOsc

MicroOsc is a simple and lightweight Open Sound Control (OSC) library for the Arduino frameworks that supports Arduino, Teensy, esp8266 and ESP32 platforms.

MicroOsc provides a unified API to work over Serial (SLIP) and over UDP (Ethernet or Wifi).

It does not hold on to state and error checking is minimal.

Examples are provided for Arduino and a few applications (Pure Data, Max, Node JS).

MicroOsc was inspired by TinyOSC by Martin Roth.

Supported Features

MicroOsc currently supports:

Full address and format matching
Message parsing
Message writing
Bundle parsing (as individual messages)
Send Types
- b: blob (byte array)
- f: float
- d: double
- i: int (int32)
- h: int64
- s: string
- m: midi
- I: impulse (message with no arguments; OSC v1.1)
- T: TRUE (message with no arguments)
- F: FALSE (message with no arguments)
- N: NULL (message with no arguments)
Receive Types
- b: blob (byte array)
- f: float
- d: double
- i: int (int32)
- s: string
- m: midi

Unsupported Features

MicroOsc will eventually but currently does yet not support:

Send types not yet supported:
- t: timetag
Receive Types not yet supported:
- h: int64
- t: timetag
- T: true
- F: false
- I: impulse
- N: nil

MicroOsc will probably never support:

bundle writing (receiving is supported)
timetags
Regular expression matching

Classes

MicroOsc contains 2 classes:

MicroOsc : the main Class
MicroOscMessage : a received OSC message

Overview of all OSC receiving methods of MicroOsc

MicroOsc Method	Description
`void onOscMessageReceived(callback)`	Check for messages and execute callback for every received message

Overview of all OSC parsing methods of MicroOscMessage

MicroOscMessage Method	Description
`void onOscMessageReceived(callback)`	Check for messages and execute callback for every received message
`bool checkOscAddress(const char* address)`	Returns `true` if the address matches exactly
`bool checkOscAddressAndTypeTags(const char* address,const char * typetags)`	Returns `true` if the address and argument type tags match exactly
`int32_t nextAsInt()`	Returns the next argument as a 32-bit int
`float nextAsFloat()`	Returns the next argument as a 32-bit float
`const char* nextAsString()`	Treats the next argument as a C string and returns a pointer to the data
`uint32_t nextAsBlob(const uint8_t **blobData)`	Treats the next argument as a blob of data and fills a pointer with the address to a byte array
`int nextAsMidi(const uint8_t **midiData)`	Treats the next value as MIDI and fills a pointer with the address to the MIDI data

Advanced MicroOscMessage methods

Advanced MicroOscMessage Method	Description
`void copyAddress(char * destinationBuffer, size_t destinationBufferMaxLength)`	Copies the address into a `char*` destinationBuffer of maximum length destinationBufferMaxLength
`void copyTypeTags(char * destinationBuffer, size_t destinationBufferMaxLength)`	Copies the type tags into a `char*` destinationBuffer of maximum length destinationBufferMaxLength

Overview of all sending OSC methods of MicroOsc

MicroOsc Method	Description
`void sendInt(const char *address, int32_t i)`	Send a single int OSC message
`void sendFloat(const char *address, float f);`	Send a single float OSC message
`void sendString(const char address, const char str)`	Send a single string OSC message
`void sendBlob(const char address, unsigned char b, int32_t length)`	Send a single blob (array of bytes) OSC message
`void sendDouble(const char *address,double d)`	Send a single double OSC message
`void sendMidi(const char address,unsigned char midi)`	Send a single MIDI OSC message
`void sendInt64(const char *address, uint64_t h)`	Send a single Int64 OSC message
`void sendImpluse(const char *address)`	Send a message with no arguments
`void sendMessage(const char address, const char format, ...)`	Send an OSC message with any mnumber of arguments of diffrent types

Initialization

There are currently 2 supported transport protocols. Serial (with SLIP) and UDP (Ethernet or WiFi). The 2 versions are identical except for their initialization.

OSC SLIP

#include <MicroOscSlip.h>
// The number 128 between the < > below  is the maximum number of bytes reserved for incomming messages.
// Outgoing messages are written directly to the output and do not need more reserved bytes.
MicroOscSlip<128> myOsc(&Serial);

In setup() don't forget to start Serial:

  Serial.begin(115200);

OSC UDP

Initialize UDP and network details first:

#include <WiFiUdp.h>
WiFiUDP myUdp;
unsigned int myReceivePort = 8888;
IPAddress mySendIp(192, 168, 1, 210);
unsigned int mySendPort = 7777;

Initialize and include MicroOsc:

#include <MicroOscUdp.h>
// The number 1024 between the < > below  is the maximum number of bytes reserved for incomming messages.
// Outgoing messages are written directly to the output and do not need more reserved bytes.
MicroOscUdp<1024> myOsc(&myUdp, mySendIp, mySendPort);

In setup() don't forget to start your UDP instance:

 myUdp.begin(myReceivePort);

The destination can be changed during runtime:

myOsc.setDestination(IPAddress destinationIp, unsigned int destinationPort)

Receive OSC

Defining a function for the reception of OSC messages

To receive OSC messages you must first create a function in which you will check the message address and get the message arguments:

// FUNCTION THAT WILL BE CALLED WHEN AN OSC MESSAGE IS RECEIVED:
void myOscMessageParser( MicroOscMessage& receivedOscMessage) {
   // DO MESSAGE ADDRESS CHECKING AND ARGUMENT GETTING HERE
}

Triggering the reception of OSC messages

In loop() you need to trigger the reception of the messages:

myOsc.onOscMessageReceived( myOscMessageParser );

Check address and argument types of a MicroOscMessage

MicroOsc will return a reference to a MicroOscMessage when it receives an OSC message. The following functions are members of MicroOscMessage.