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/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: Code Style: Black
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.
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>`_.
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": "",
"name": "circuitpython-microosc",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "adafruit,blinka,circuitpython,micropython,microosc,OSC,MIDI,OpenSoundControl,protocol,UDP,multicast",
"author": "",
"author_email": "Tod Kurt <tod@todbot.com>",
"download_url": "https://files.pythonhosted.org/packages/04/4c/de23a061db191523331722596686325367d307c19504a9dffa98fefe6021/circuitpython-microosc-0.5.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\n\n.. image:: https://img.shields.io/discord/327254708534116352.svg\n :target: https://adafru.it/discord\n :alt: Discord\n\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\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n :alt: Code Style: Black\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\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\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.5",
"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": "",
"digests": {
"blake2b_256": "20067ecef6257790c54cbd796ea75f353ab423e7ff7800d04bacbcfd7e82bfe3",
"md5": "eaa5ad2f70d7eafc8016e85969f05f11",
"sha256": "aef7f60e3d7ccdda28f5c6a9acbff6d37ecf57f8347c085a64102dfb45cfeac3"
},
"downloads": -1,
"filename": "circuitpython_microosc-0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eaa5ad2f70d7eafc8016e85969f05f11",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7908,
"upload_time": "2024-01-06T20:59:11",
"upload_time_iso_8601": "2024-01-06T20:59:11.677868Z",
"url": "https://files.pythonhosted.org/packages/20/06/7ecef6257790c54cbd796ea75f353ab423e7ff7800d04bacbcfd7e82bfe3/circuitpython_microosc-0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "044cde23a061db191523331722596686325367d307c19504a9dffa98fefe6021",
"md5": "a96a2b5bce7197b64cf6629cfe2586ef",
"sha256": "8977001e04816b3de71df378da5894afbef6b2d579f0259b22d48953bc4a6c5c"
},
"downloads": -1,
"filename": "circuitpython-microosc-0.5.tar.gz",
"has_sig": false,
"md5_digest": "a96a2b5bce7197b64cf6629cfe2586ef",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 30742,
"upload_time": "2024-01-06T20:59:13",
"upload_time_iso_8601": "2024-01-06T20:59:13.331793Z",
"url": "https://files.pythonhosted.org/packages/04/4c/de23a061db191523331722596686325367d307c19504a9dffa98fefe6021/circuitpython-microosc-0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-06 20:59:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "todbot",
"github_project": "CircuitPython_MicroOSC",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "circuitpython-microosc"
}
JSON
