1 files changed, 103 insertions, 0 deletions
diff --git a/diller/README.md b/diller/README.md
new file mode 100644
index 0000000..322ec45
--- /dev/null
+++ b/diller/README.md
@@ -0,0 +1,103 @@
+# TODOs / Notes
+
+Is registration required? Can't the firmware just send an update without a value on every boot?
+
+# MQTT
+
+## Device / Sensor hierarchy 
+
+	/<device id>
+	  /sensors
+		/<sensor id>
+		  /value
+		  /type				(retained)
+		  /name				(retained)
+		  /description		(retained)
+	  /type                 TODO: remove?
+	  /firmware				For updating the device's firmware
+
+## Device registration flow
+
+	sub: /registration/<random id>
+	pub: /registration {}
+
+# Diller serial API
+
+## Network settings
+
+Request:
+
+Update network settings. If no paramters are given, no changes are done.
+
+	network [ip=..] [gateway=..] [ssid=..]
+
+Response:
+
+The command will always return the current values. If the ssid was recently set, the ip, gateway and netmask fields may be missing.
+	
+	ok ip=.. gateway=.. netmask=.. ssid=..
+
+## Register property
+
+Request:
+
+	register-property id=.. type=.. name=.. description=..
+
+Type examples:
+
+* `temperature`
+* `switch` - boolean switches
+* `humidity`
+* `rtc`
+
+Response:
+
+	ok
+
+## Publish property value
+
+Request:
+
+	set-property id=.. [value=..] [name=..] [description=..]
+
+Response:
+
+	ok
+
+The value might not be updated directly, but may be buffered on the device if it is not yet connected.
+
+## Publish raw MQTT message
+
+Request:
+
+	publish topic=.. [qos=..] [retain=..]
+	<next lines are payload. Double EOL completes payload>
+
+Response:
+
+	ok
+
+## Reset the device
+
+Request:
+
+	reset
+
+Response
+
+	ok
+
+# Example session
+
+	require('main').main();
+
+Get the current network configuration to update the Arduino's LCD display
+
+	> network 
+	< ok ip=1.3.3.7 netmask=255.255.255.0 gateway=1.3.3.1 ssid=awesome
+
+Register the properties. This is done on every boot to keep the server in sync with the firmware's features. Old properties will not be removed.
+
+	> set-property id=temp-0 value=12.3 type=temperature name=Water
+	< ok
+