Introduction
============
.. image:: https://readthedocs.org/projects/circuitpython-microosc/badge/?version=latest
:target: https://circuitpython-microosc.readthedocs.io/
:alt: Documentation Status
.. image:: https://img.shields.io/discord/327254708534116352.svg
:target: https://adafru.it/discord
:alt: Discord
.. image:: https://github.com/todbot/CircuitPython_MicroOSC/workflows/Build%20CI/badge.svg
:target: https://github.com/todbot/CircuitPython_MicroOSC/actions
:alt: Build Status
.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
:target: https://github.com/astral-sh/ruff
:alt: Code Style: Ruff
Minimal OSC parser, server, and client for CircuitPython and CPython
`Open Sound Control <https://opensoundcontrol.stanford.edu/>`_ 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 <https://hexler.net/touchosc>`_
* `OSCSend for Ableton Live <https://www.ableton.com/en/packs/connection-kit/>`_
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 <https://hexler.net/protokol>`_
Dependencies
=============
This driver depends on:
* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_
Please ensure all dependencies are available on the CircuitPython filesystem.
This is easily achieved by downloading
`the Adafruit library and driver bundle <https://circuitpython.org/libraries>`_
or individual libraries can be installed using
`circup <https://github.com/adafruit/circup>`_.
Installing from PyPI
=====================
On supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from
PyPI <https://pypi.org/project/circuitpython-microosc/>`_.
To install for current user:
.. code-block:: shell
pip3 install circuitpython-microosc
To install system-wide (this may be required in some cases):
.. code-block:: shell
sudo pip3 install circuitpython-microosc
To install in a virtual environment in your current project:
.. code-block:: shell
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:
.. code-block:: shell
pip3 install circup
With ``circup`` installed and your CircuitPython device connected use the
following command to install:
.. code-block:: shell
circup install microosc
Or the following command to update an existing version:
.. code-block:: shell
circup update
Usage Example
=============
.. code-block:: python
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 <https://opensoundcontrol.stanford.edu/spec-1_0.html>`_
* `OSC Message examples <https://opensoundcontrol.stanford.edu/spec-1_0-examples.html>`_
* `OSC info and tools <https://wiki.thingsandstuff.org/OSC>`_
* `TouchOSC apps for Mac/Win/Linux <https://hexler.net/touchosc>`_
Documentation
=============
API documentation for this library can be found on `Read the Docs <https://circuitpython-microosc.readthedocs.io/>`_.
For information on building library documentation, please check out
`this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.
Testing
=======
Install ``pytest`` with ``pip3 install pytest --upgrade`` and run ``pytest -v``
Contributing
============
Contributions are welcome! Please read our `Code of Conduct
<https://github.com/todbot/CircuitPython_MicroOSC/blob/HEAD/CODE_OF_CONDUCT.md>`_
before contributing to help this project stay welcoming.
Raw data
{
"_id": null,
"home_page": null,
"name": "circuitpython-microosc",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "adafruit, blinka, circuitpython, micropython, microosc, OSC, MIDI, OpenSoundControl, protocol, UDP, multicast",
"author": null,
"author_email": "Tod Kurt <tod@todbot.com>",
"download_url": "https://files.pythonhosted.org/packages/48/22/5c0548da7d65f7d8e4922e6e8c0ac4e4b814360b364f498df95b4a864376/circuitpython_microosc-0.6.tar.gz",
"platform": null,
"description": "Introduction\n============\n\n\n.. image:: https://readthedocs.org/projects/circuitpython-microosc/badge/?version=latest\n :target: https://circuitpython-microosc.readthedocs.io/\n :alt: Documentation Status\n\n.. image:: https://img.shields.io/discord/327254708534116352.svg\n :target: https://adafru.it/discord\n :alt: Discord\n\n.. image:: https://github.com/todbot/CircuitPython_MicroOSC/workflows/Build%20CI/badge.svg\n :target: https://github.com/todbot/CircuitPython_MicroOSC/actions\n :alt: Build Status\n\n.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\n :target: https://github.com/astral-sh/ruff\n :alt: Code Style: Ruff\n\n\nMinimal OSC parser, server, and client for CircuitPython and CPython\n\n\n`Open Sound Control <https://opensoundcontrol.stanford.edu/>`_ is an efficient data transport\nencoding/protocol for real-time performance messages for music or other similar endeavors.\nThe OSC byte encoding is designed to be semi-human readable and efficient enough for\nUDP packet transmission.\n\nOSC Messages are defined by an \"OSC Address\" (e.g. \"/1/faderA\") and optional \"OSC Arguments\",\none or more possible of several data types (e.g. float32 or int32). OSC doesn't pre-define\nspecific OSC Addresses, it is up the the sender and receiver to agree upon them.\n\nThis \"MicroOSC\" library is a minimal UDP receiver (\"OSC Server\") and parser of OSC packets.\nThe MicroOSC UDP receiver supports both unicast and multicast UDP on both CircuitPython and CPython.\n\nSince this is a minimal OSC library, it can parse and emit OSC packets with\nonly the following OSC data types:\n\n* floating point numbers (\"float32\")\n* integer numbers (\"int32\")\n* strings\n\n\nRequirements\n============\n\nTo run this library you will need one of:\n\n* CircuitPython board with native ``wifi`` support, like those based on ESP32-S2, ESP32-S3, etc.\n* Desktop Python (CPython) computer\n\nTo send OSC messages, you will need an OSC UDP sender (aka \"OSC client\").\nSome easy-to-use OSC clients are:\n\n* `TouchOSC <https://hexler.net/touchosc>`_\n* `OSCSend for Ableton Live <https://www.ableton.com/en/packs/connection-kit/>`_\n\nTo receive OSC messages, you will need an OSC UDP receiver (aka \"OSC server\").\nSome easy-to-use OSC clients are:\n\n* `Protokol for Mac/Win/Linux/iOS/Android <https://hexler.net/protokol>`_\n\nDependencies\n=============\nThis driver depends on:\n\n* `Adafruit CircuitPython <https://github.com/adafruit/circuitpython>`_\n\nPlease ensure all dependencies are available on the CircuitPython filesystem.\nThis is easily achieved by downloading\n`the Adafruit library and driver bundle <https://circuitpython.org/libraries>`_\nor individual libraries can be installed using\n`circup <https://github.com/adafruit/circup>`_.\n\nInstalling from PyPI\n=====================\n\nOn supported GNU/Linux systems like the Raspberry Pi, you can install the driver locally `from\nPyPI <https://pypi.org/project/circuitpython-microosc/>`_.\nTo install for current user:\n\n.. code-block:: shell\n\n pip3 install circuitpython-microosc\n\nTo install system-wide (this may be required in some cases):\n\n.. code-block:: shell\n\n sudo pip3 install circuitpython-microosc\n\nTo install in a virtual environment in your current project:\n\n.. code-block:: shell\n\n mkdir project-name && cd project-name\n python3 -m venv .venv\n source .env/bin/activate\n pip3 install circuitpython-microosc\n\nInstalling to a Connected CircuitPython Device with Circup\n==========================================================\n\nMake sure that you have ``circup`` installed in your Python environment.\nInstall it with the following command if necessary:\n\n.. code-block:: shell\n\n pip3 install circup\n\nWith ``circup`` installed and your CircuitPython device connected use the\nfollowing command to install:\n\n.. code-block:: shell\n\n circup install microosc\n\nOr the following command to update an existing version:\n\n.. code-block:: shell\n\n circup update\n\nUsage Example\n=============\n\n.. code-block:: python\n\n import time, os, wifi, socketpool\n import microosc\n\n UDP_HOST = \"224.0.0.1\" # multicast UDP\n UDP_PORT = 5000\n\n ssid = os.getenv(\"CIRCUITPY_WIFI_SSID\")\n password = os.getenv(\"CIRCUITPY_WIFI_PASSWORD\")\n\n print(\"connecting to WiFi\", ssid)\n wifi.radio.connect(ssid, password)\n\n socket_pool = socketpool.SocketPool(wifi.radio)\n\n def fader_handler(msg):\n \"\"\"Used to handle 'fader' OscMsgs, printing it as a '*' text progress bar\n :param OscMsg msg: message with one required float32 value\n \"\"\"\n print(msg.addr, \"*\" * int(20 * msg.args[0])) # make a little bar chart\n\n dispatch_map = {\n \"/\": lambda msg: print(\"\\t\\tmsg:\", msg.addr, msg.args), # prints all messages\n \"/1/fader\": fader_handler,\n \"/filter1\": fader_handler,\n }\n\n osc_server = micro_osc.Server(socket_pool, UDP_HOST, UDP_PORT, dispatch_map)\n\n print(\"MicroOSC server started on \", UDP_HOST, UDP_PORT)\n\n last_time = time.monotonic()\n\n while True:\n\n osc_server.poll()\n\n if time.monotonic() - last_time > 1.0:\n last_time = time.monotonic()\n print(f\"waiting {last_time:.2f}\")\n\n\nReferences\n==========\n\n* `Open Sound Control Spec 1.0 <https://opensoundcontrol.stanford.edu/spec-1_0.html>`_\n* `OSC Message examples <https://opensoundcontrol.stanford.edu/spec-1_0-examples.html>`_\n* `OSC info and tools <https://wiki.thingsandstuff.org/OSC>`_\n* `TouchOSC apps for Mac/Win/Linux <https://hexler.net/touchosc>`_\n\nDocumentation\n=============\nAPI documentation for this library can be found on `Read the Docs <https://circuitpython-microosc.readthedocs.io/>`_.\n\nFor information on building library documentation, please check out\n`this guide <https://learn.adafruit.com/creating-and-sharing-a-circuitpython-library/sharing-our-docs-on-readthedocs#sphinx-5-1>`_.\n\nTesting\n=======\n\nInstall ``pytest`` with ``pip3 install pytest --upgrade`` and run ``pytest -v``\n\nContributing\n============\n\nContributions are welcome! Please read our `Code of Conduct\n<https://github.com/todbot/CircuitPython_MicroOSC/blob/HEAD/CODE_OF_CONDUCT.md>`_\nbefore contributing to help this project stay welcoming.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Minimal OSC parser and server for CircuitPython and CPython",
"version": "0.6",
"project_urls": {
"Homepage": "https://github.com/todbot/CircuitPython_MicroOSC"
},
"split_keywords": [
"adafruit",
" blinka",
" circuitpython",
" micropython",
" microosc",
" osc",
" midi",
" opensoundcontrol",
" protocol",
" udp",
" multicast"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "991a737828e9d2ce2d7fc07ca06ba893edc164d4b23712c8555c8b4011a1736e",
"md5": "ef3786cc6a781d07e3ed305f9581101c",
"sha256": "940af9ad5f067147a2d3a7a63c5d0851ea3918da31d0176545b2bc41dd2a7a6b"
},
"downloads": -1,
"filename": "circuitpython_microosc-0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ef3786cc6a781d07e3ed305f9581101c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 8116,
"upload_time": "2025-08-14T01:10:48",
"upload_time_iso_8601": "2025-08-14T01:10:48.159803Z",
"url": "https://files.pythonhosted.org/packages/99/1a/737828e9d2ce2d7fc07ca06ba893edc164d4b23712c8555c8b4011a1736e/circuitpython_microosc-0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "48225c0548da7d65f7d8e4922e6e8c0ac4e4b814360b364f498df95b4a864376",
"md5": "3bec9c20ea4dc760a27f347d8d3aade4",
"sha256": "b83dff50b66c21ff40c97b5743373b8fc447445cd6c5b339381e4008b8923df4"
},
"downloads": -1,
"filename": "circuitpython_microosc-0.6.tar.gz",
"has_sig": false,
"md5_digest": "3bec9c20ea4dc760a27f347d8d3aade4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 31626,
"upload_time": "2025-08-14T01:10:49",
"upload_time_iso_8601": "2025-08-14T01:10:49.385795Z",
"url": "https://files.pythonhosted.org/packages/48/22/5c0548da7d65f7d8e4922e6e8c0ac4e4b814360b364f498df95b4a864376/circuitpython_microosc-0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 01:10:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "todbot",
"github_project": "CircuitPython_MicroOSC",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "Adafruit-Blinka",
"specs": []
}
],
"lcname": "circuitpython-microosc"
}
JSON
