update README and library info to v0.2.0

README.md

@@ -2,121 +2,238 @@
 
 OSC library for Arduino (ESP, Teensy, AVR, etc.)
 
-ArduinoOSC is OSC Library for Arduino, based on the great work [ArdOSC]().
-Though [ArdOSC]() can only be used with EthernetShield, ArduinoEthernet or device with W5100, this library expands the supported streams to WiFi, Ethernet, Serial (TBD), and the others which are derived from Stream class.
-For the [ArdOSC]() License, See ArduinoOSC/avr/Lisence.txt
+ArduinoOSC is OSC Library for Arduino. OSC packet parsing is based on the [oscpkt](http://gruntthepeon.free.fr/oscpkt/html/) and optimized for Arduino.
 
-## Usage
+## NOTE : BREAKING API CHANGES (v0.2.0 or later)
 
-### via ```WiFiUdp```
+Almost all APIs has been changed in `v0.2.0` and got much simpler.
+Please check below if you use previous versions.
+
+
+## Supported Platform
+
+This library is tested for following platforms and interfaces.
+
+- ESP32 (WiFi, Serial)
+- ESP8266 (WiFi, Serial)
+- Teensy 3.x (Ethernet, Serial, Serial1, 2, 3...)
+- Arduino Mega (Ethernet, Serial, Serial1, 2, 3)
+- Arduino Uno (Ethernet, Serial)
 
-``` c++
-#include <WiFi.h>
-#include <WiFiUdp.h>
-#include <ArduinoOSC.h>
 
-WiFiUDP udp;
-ArduinoOSCWiFi osc;
+## Feature
 
-const char* ssid = "your-ssid";
-const char* pwd = "your-password";
-const char* host = "xxx.xxx.xxx.xxx";
-const int recv_port = 10000;
-const int send_port = 12000;
+- simpler usage than ever
+    - callback registration with lambda
+    - osc packet sending in one-line
+- support pattern-matching (wildcards)
+- support basic OSC types
+	- TF (bool: true, false)
+	- i (int32_t)
+	- h (int64_t)
+	- f (float)
+	- d (double)
+	- s (string)
+	- b (bundle)
+- does NOT support timestamp values.
+
+## Usage
+
+Please see examples for detals.
+
+### WiFi
+
+```C++
+#include <ArduinoOSC.h>
+OscWiFi osc;
 
 void setup()
 {
     WiFi.begin(ssid, pwd);
-    osc.begin(udp, recv_port);
-    osc.addCallback("/ard/aaa", &callback);
+    WiFi.config(ip, gateway, subnet);
+    osc.begin(recv_port);
+
+    // add callbacks...
+    osc.subscribe("/lambda", [](OscMessage& m)
+    {
+        // do something with osc message
+        Serial.print(m.arg<int>(0));    Serial.print(" ");
+        Serial.print(m.arg<float>(1));  Serial.print(" ");
+        Serial.print(m.arg<String>(2)); Serial.println();
+    });
 }
 
 void loop()
 {
-    osc.parse();
+    osc.parse(); // should be called
+    osc.send(host, send_port, "/send", 1, 2.2F, 3.3, "string"); // send osc packet in one line
 }
+```
+
+### Ethernet
+
+```C++
+#include <ArduinoOSC.h>
+OscSerial osc;
 
-void callback(OSCMessage& m)
+void setup()
 {
-    //create new osc message
-    OSCMessage msg;
-    msg.beginMessage(sourceIp, send_port);
-
-    // read & set same argument
-    msg.setOSCAddress("/ard/aaa");
-    msg.addArgInt32(m.getArgAsInt32(0));
-    msg.addArgFloat(m.getArgAsFloat(1));
-    msg.addArgString(m.getArgAsString(2));
-
-    // send osc message
-    osc.send(msg);
+    Ethernet.begin(mac, ip);
+    osc.begin(recv_port);	
+
+    // add callbacks...
+}
+
+void loop()
+{
+    osc.parse(); // should be called
+    osc.send(host, send_port, "/send", 1, 2.2F, 3.3, "string");
 }
 ```
 
-### via ```Serial```
+### Serial
 
-```c++
-#include "ArduinoOSC.h"
-ArduinoOSCSerial osc;
+```C++
+#include <ArduinoOSC.h>
 
 void setup()
 {
-    osc.begin(Serial, 115200);
-    osc.addCallback("/ard/aaa", &callback);
-    delay(5000);
+    Serial.begin(115200);
+    osc.attach(Serial);
+
+	// add callbacks...
 }
 
 void loop()
 {
-    osc.parse();
+    osc.parse(); // should be called
+    osc.send("/send", 1, 2.2F, 3.3, "string");
 }
+```
 
-void callback(OSCMessage& m)
+
+### Subscribe Callbacks / Publish OSC (TBD)
+
+```C++
+// TODO: TBD
+// osc.subscribe("/int32", i);
+// osc.subscribe("/float", f);
+// osc.subscribe("/string", s);
+// osc.subscribe("/blob", b);
+
+osc.subscribe("/callback", onOscReceived); // old style (v0.1.x)
+
+osc.subscribe("/lambda", [](OscMessage& m)
 {
-    //create new osc message
-    OSCMessage msg;
-    msg.beginMessage();
-
-    // read & set same argument
-    msg.setOSCAddress(m.getOSCAddress());
-    msg.addArgInt32(m.getArgAsInt32(0));
-    msg.addArgFloat(m.getArgAsFloat(1));
-    msg.addArgString(m.getArgAsString(2));
-
-    //send osc message
-    osc.send(msg);
-}
+    Serial.print("lambda : ");
+    Serial.print(m.ip()); Serial.print(" ");
+    Serial.print(m.port()); Serial.print(" ");
+    Serial.print(m.size()); Serial.print(" ");
+    Serial.print(m.address()); Serial.print(" ");
+    Serial.print(m.arg<int>(0)); Serial.print(" ");
+    Serial.print(m.arg<float>(1)); Serial.print(" ");
+    Serial.print(m.arg<String>(2)); Serial.println();
+});
+osc.subscribe("/wildcard/*/test", [](OscMessage& m)
+{
+    Serial.print("wildcard : ");
+    Serial.print(m.ip()); Serial.print(" ");
+    Serial.print(m.port()); Serial.print(" ");
+    Serial.print(m.size()); Serial.print(" ");
+    Serial.print(m.address()); Serial.print(" ");
+    Serial.print(m.arg<int>(0)); Serial.println();
+
+});
+osc.subscribe("/need/reply", [](OscMessage& m)
+{
+    Serial.println("/need/reply");
+
+    int i = 12;
+    float f = 34.56F;
+    double d = 78.987;
+    String s = "hello";
+    bool b = true;
+
+    osc.send(host, send_port, "/send", i, f, d, s, b);
+});
+
+// TODO: TBD
+// osc.publish(host, send_port, "/value", value);
+// osc.publish(host, send_port, "/millis", &millis);
 ```
 
-## Supported Communication Library
 
-- WiFiUdp (ESP)
-- EthernetUDP
-- Serial (Max7 example included)
+## Limitation for AVR Boards (Uno, Mega, etc.)
 
+- max number of arguments is 3
+- max packet data size is 64 byte
+- max number of callbacks is 8
+- osc packet is not queued (only latest packet can be held inside)
+- bundle is not supported
+- limited API (see below and `examples/UnoMegaAvr/*`)
 
-## Tested Platform
+### Read API Limitation
 
-- EPS32 w/ arduino-esp32
-- Teensy 3.2, 3.5, 3.6
-- Arduino Uno
+`m.arg<type>(index)` cannot be used in AVR. 
+Please use old APIs.
 
+```C++
+m.getArgAsInt32(0);
+m.getArgAsFloat(1);
+m.getArgAsString(2);
+```
 
-## Limitation for AVR Platforms
+### Send API Limitation
 
-- OSC packet size is limited to 128 bytes
-- OSC type is limited only to INT32, FLOAT, STRING
-- OSC argument size is limited to 15
+In sending osc, one-line feature is not available in AVR.
+Please create `OscMessage` and `send(msg)` after that.
 
-currently, other platforms are also limited (because expansion is not applied)
+```C++
+OscMessage msg(host, send_port, "/send"); // WiFi, Ethernet
+OscMessage msg("/send");                  // Serial
+msg.push(i).push(f).push(s);
+osc.send(msg);
+```
 
 
+## TBD
 
-## TODO
+- one-line subscriber for single variable
+
+```C++
+// directly changes variable 'i' if message with "/int32" comes
+int32_t i;
+osc.subscribe("/int32", i);
+```
+
+- one-line publisher for single variable
+
+```C++
+// send "value" automatically
+float value;
+osc.publish(host, send_port, "/value", value);
+```
+
+- one-line publisher for function which returns single value
+
+```C++
+// send the result of "millis()" automatically
+osc.publish(host, send_port, "/millis", &millis);
+```
+
+- automatically detect the type of arguments (without template arguments)
+
+```C++
+int32_t i = m.arg<int32_t>(0);
+float   f = m.arg<float>(1);
+String  s = m.arg<String>(2);
+// becomes
+int32_t i = m.arg(0);
+float   f = m.arg(1);
+String  s = m.arg(2);
+```
 
-- re-write library and support NON-AVR platform for more safety and flexible use
-- more examples
 
 ## License
 
-MIT
+MIT

library.json

@@ -13,7 +13,7 @@
         "url": "https://github.com/hideakitai",
         "maintainer": true
     },
-    "version": "0.1.7",
+    "version": "0.2.0",
     "license": "MIT",
     "frameworks": "arduino",
     "platforms": "*"

library.properties

@@ -1,5 +1,5 @@
 name=ArduinoOSC
-version=0.1.7
+version=0.2.0
 author=hideakitai
 maintainer=hideakitai
 sentence=OSC library for Arduino (ESP, Teensy, AVR, etc.)