docs for osc_send

README.md

@@ -7,6 +7,7 @@ mot - MIDI and OSC Tools
 mot consists of several MIDI and OSC command line tools. These are mainly of interest to debug and check OSC messages and MIDI devices. There are applications to:
 * `midi_echo`: prints MIDI messages coming from a connected MIDI device.
 * `osc_echo`: prints OSC messages arriving at a certain UDP port.
+* `osc_send`: sends OSC messages from STDIN to a certain host.
 * `midi_to_osc`: a MIDI to OSC bridge which sends MIDI messages coming from a connected MIDI device to an OSC target.
 * `midi_roundtrip_latency`: measure MIDI round-trip latency.
 
@@ -69,7 +70,7 @@ mot midi_echo 0
 
 This application prints OSC messages which are received on a certain UDP port. This application is ideal to check if a) a OSC messages are being received and b) the OSC messages received are in the expected place or type.
 
-~~~~~~
+~~~~~~bash
 mot osc_echo 127.0.0.1:6666
 ~~~~~~
 
@@ -79,7 +80,7 @@ This application sends incoming MIDI messages over OSC to an OSC receiver. This
 
 It also allows to create a virtual MIDI port. This can be useful e.g. to send messages from a browser window, over MIDI, to a network. If mot is running, a browser can send messages to a virtual port which is then translated to UDP messages on a network.
 
-~~~~~~
+~~~~~~bash
 mot midi_to_osc 127.0.0.1:5566 /midi_transport 6666
 ~~~~~~
 
@@ -89,10 +90,25 @@ This application receives OSC messages and sends them to a MIDI device. This is
 
 It also allows to create a virtual MIDI port. The following example receives OSC on UDP port 5566 and sends it to a virtual midi port. 
 
-~~~~~~
+~~~~~~bash
 mot osc_to_midi 127.0.0.1:5566 /m 6666
 ~~~~~~
 
+### OSC send
+
+This application sends OSC messages read from STDIN and sends the message to the specified host and port. This can be used to check if manually constructed OSC messages arrive on a listening server or to check message handlers. See the example below.
+
+There is limited support for typed OSC message arguments and there are a few limitations. Each line that comes in via STDIN is split on whitespace. The first token is interpreted as the OSC method, the other tokens are seen as OSC message arguments. If an argument is an integer or a float the corresponding OSC type is used, otherwise the OSC argument is a string. String arguments with spaces are not supported. 
+
+~~~~~~bash
+#Listen to incoming osc messages in the background
+mot osc_echo 127.0.0.1:6666 &
+#Send an OSC message
+echo "/test 12 15.2 str_arg\n" |  mot osc_send 127.0.0.1:6666
+#Response generated by osc_echo:
+msg: OscMessage { addr: "/test", args: [Int(12), Float(15.2), String("str_arg")] }
+~~~~~~
+
 ### MIDI round-trip latency
 
 This application sends out a MIDI message as quickly as possible when a MIDI message is received. It can be used to measure MIDI round-trip latency if it is used together with the Teensy patch in the `misc` directory.  If all goes wel a relatively constanc round-trip latency of less than 1m should be no problem. An example on macOS can be seen below: