https://github.com/todbot/circuitpython_microosc
Minimal OSC parser, server, and client for CircuitPython and CPython
https://github.com/todbot/circuitpython_microosc
Last synced: 8 months ago
JSON representation
Minimal OSC parser, server, and client for CircuitPython and CPython
- Host: GitHub
- URL: https://github.com/todbot/circuitpython_microosc
- Owner: todbot
- License: mit
- Created: 2023-08-20T16:58:27.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-01-06T20:58:43.000Z (over 2 years ago)
- Last Synced: 2024-10-09T22:42:08.798Z (over 1 year ago)
- Language: Python
- Homepage:
- Size: 81.1 KB
- Stars: 10
- Watchers: 3
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.rst
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
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 `_ 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:
.. 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 `_
* `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.