Updated readme

README.md

@@ -1,3 +1,65 @@
-# autowaterer
+# Autowaterer
 
-Homebrew automatic watering system based on ESP8266 and MQTT, for easy Home Assistant integration.
+Automatic watering system based on ESP8266 and MQTT, for easy Home Assistant integration.
+
+## MQTT interface
+
+The device is able to receive commands and upload telemetry through MQTT.
+
+### Telemetry topics
+
+`home/devices/autowaterer/moisture_sensors/<address>/value`
+
+The read value of the sensor at the address **\<address>** will be published here. The value will be between 0 and 100, which represents the measured moisture percentage. 0% will correspond to the minimum value that was ever read from that sensor and 100% to the maximum. These "min" and "max" values are being kept track of by the ESP itself. It is possible to reset these calibration values by publishing to the `cal_reset` topic (see below)
+
+----------------
+
+`home/devices/autowaterer/moisture_sensors/<address>/available`
+
+The availability of the sensor at the address **\<address>** will be published here. `online` and `offline` are the payloads for available and unavailable, respectively.
+
+-----------------
+
+`home/devices/autowaterer/command_result`
+
+The return code of commands issued to the ESP are published to this topic. The return code can be any of the following
+
+- `"0"` : Command successful
+- `"1"` : Invalid JSON
+- `"2"` : Invalid pump ID
+- `"3"` : You are trying to run too many pumps at the same time. Maximum is 4
+- `"4"` : You are trying to turn on a pump that is already on
+- `"5"` : Burst command iteration number too high
+- `"6"` : Invalid sensor address
+
+----------------
+
+`home/devices/autowaterer/log`
+
+A verbose log of events is published here. Good for debugging
+
+### Command topics
+
+`home/devices/autowaterer/pump_command`
+
+Used to control the outputs of some onboard GPIOs, to which the pumps are connected. The paylod must be a JSON of the following format:
+
+```
+{
+    "id" : <id - 0 thru 7> ,
+    "enable" : <enable - 1 to enable, 0 to disable> ,
+    "timeout" : <timeout - in seconds. Maximum 30 seconds>
+}
+```
+
+----------------
+
+`home/devices/autowaterer/moisture_sensors/burst`
+
+Used to trigger a burst of sensor readings, every 200 ms. The payload must be an integer between 0 and 9999. This will represent the amount of times the sensors will be sampled
+
+--------------------
+
+`home/devices/autowaterer/moisture_sensors/cal_reset`
+
+Used to reset the internal calibration of the moisture sensors. The payload must be a character representing the address of the pump of which it is desired to reset the calibration. This will have the effect of setting the internally tracked "max" to 0 and the "min" to 0x0FFF