circuitpython-microosc 0.6

Minimal OSC parser and server for CircuitPython and CPython

Introduction

Minimal OSC parser, server, and client for CircuitPython and CPython

Open Sound Control is an efficient data transport encoding/protocol for real-time performance messages for music or other similar endeavors. The OSC byte encoding is designed to be semi-human readable and efficient enough for UDP packet transmission.

OSC Messages are defined by an “OSC Address” (e.g. “/1/faderA”) and optional “OSC Arguments”, one or more possible of several data types (e.g. float32 or int32). OSC doesn’t pre-define specific OSC Addresses, it is up the the sender and receiver to agree upon them.

This “MicroOSC” library is a minimal UDP receiver (“OSC Server”) and parser of OSC packets. The MicroOSC UDP receiver supports both unicast and multicast UDP on both CircuitPython and CPython.

Since this is a minimal OSC library, it can parse and emit OSC packets with only the following OSC data types:

• floating point numbers (“float32”)

• integer numbers (“int32”)

• strings

Requirements

To run this library you will need one of:

• CircuitPython board with native wifi support, like those based on ESP32-S2, ESP32-S3, etc.

• Desktop Python (CPython) computer

To send OSC messages, you will need an OSC UDP sender (aka “OSC client”). Some easy-to-use OSC clients are:

• TouchOSC

• OSCSend for Ableton Live

To receive OSC messages, you will need an OSC UDP receiver (aka “OSC server”). Some easy-to-use OSC clients are:

• Protokol for Mac/Win/Linux/iOS/Android

Dependencies

This driver depends on:

• Adafruit CircuitPython

Please ensure all dependencies are available on the CircuitPython filesystem. This is easily achieved by downloading the Adafruit library and driver bundle or individual libraries can be installed using circup.

Installing from PyPI

On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally from PyPI. To install for current user:

pip3 install circuitpython-microosc

To install system-wide (this may be required in some cases):

sudo pip3 install circuitpython-microosc

To install in a virtual environment in your current project:

mkdir project-name && cd project-name
python3 -m venv .venv
source .env/bin/activate
pip3 install circuitpython-microosc

Installing to a Connected CircuitPython Device with Circup

Make sure that you have circup installed in your Python environment. Install it with the following command if necessary:

pip3 install circup

With circup installed and your CircuitPython device connected use the following command to install:

circup install microosc

Or the following command to update an existing version:

circup update

Usage Example

import time, os, wifi, socketpool
import microosc

UDP_HOST = "224.0.0.1"  # multicast UDP
UDP_PORT = 5000

ssid = os.getenv("CIRCUITPY_WIFI_SSID")
password = os.getenv("CIRCUITPY_WIFI_PASSWORD")

print("connecting to WiFi", ssid)
wifi.radio.connect(ssid, password)

socket_pool = socketpool.SocketPool(wifi.radio)

def fader_handler(msg):
   """Used to handle 'fader' OscMsgs, printing it as a '*' text progress bar
   :param OscMsg msg: message with one required float32 value
   """
   print(msg.addr, "*" * int(20 * msg.args[0]))  # make a little bar chart

dispatch_map = {
    "/": lambda msg: print("\t\tmsg:", msg.addr, msg.args),  # prints all messages
    "/1/fader": fader_handler,
    "/filter1": fader_handler,
}

osc_server = micro_osc.Server(socket_pool, UDP_HOST, UDP_PORT, dispatch_map)

print("MicroOSC server started on ", UDP_HOST, UDP_PORT)

last_time = time.monotonic()

while True:

    osc_server.poll()

    if time.monotonic() - last_time > 1.0:
        last_time = time.monotonic()
        print(f"waiting {last_time:.2f}")

References

• Open Sound Control Spec 1.0

• OSC Message examples

• OSC info and tools

• TouchOSC apps for Mac/Win/Linux

Documentation

API documentation for this library can be found on Read the Docs.

For information on building library documentation, please check out this guide.

Testing

Install pytest with pip3 install pytest --upgrade and run pytest -v

Contributing

Contributions are welcome! Please read our Code of Conduct before contributing to help this project stay welcoming.