Web Interface and API’s

The main Valve provides the interface for all connected sensors. Each sensor does host its own HTTP interface however it can only be accessed from token based authentication via its parent Valve.

The Valve Web Interface

MQTT API

The MQTT api is disabled by default and has to be configured under the main configuration menu. Once a MQTT gateway IP is provided as well as a password and username if required the device will begin broadcasting it's events and listening for commands.

The default MQTT inbound topic is "Water/ShutoffRecv", this can be configured as well. The inbound commands are as follows

• "open", opens the valve
• "close", closes the valve
• "check", the valve will respond with its current status
• "lock_open", the valve will lock in an open state. This will move the valve to open if currently closed.
• "lock_closed", the valve will lock in a closed state. This will move the valve to a closed state if currently open

The device will also publish notifications to its outbound topic of "Water/ShutoffSend". These messages are in JSON format and follow the following format.

doc["event"] = "EventTypeHere";
doc["Sensor"] = "Sensor Name that triggered this event";
doc["Name"] = "Name of the event";
doc["Action"] = "Action taken in response to the event";
doc["Outcome"] = "Outcome of that action";
doc["Reason"] = "Reason for taking that action if appropriate";

Examples of events are:

• ReceivedMQTTClose
• ReceivedMQTTOpen
• ReceivedMQTTCheck
• MissingSensor
• LowSensorCount
• ReceivedLockOpen
• ReceivedLockClose
• ReceivedManualOpen
• ReceivedManualClose
• ReceivedCloseFrom
• ServerStarted
• ReceivedButtonOpen
• ReceivedButtonClose

Water Valve HTTP API

The HTTP API is enabled by default and is the only interface that the current Sensor firmware is able to use. This API can be disabled however this would leave the valve under manual or MQTT operation only. This HTTP API has several endpoints:

• /command/sensorclose,
  • Description: Signal coming from the sensor to the valve telling the valve that a sensor has been triggered by water or manual interaction.
  • Inputs
    • Token (Previously negotiated during the sensor enrollment)
    • From (sensor MAC)
    • Pretty (Sensor Name)
    • FirmwareVer (Sensor firmware version)
    • Index (The sensor channel that was triggered on the sensor device)
• /command/sensornoop
  • Description: No operation, a sensor must communicate with valve at least every 90 seconds, these are sent every 30 seconds when no other packets need to be sent, this allows the valve to verify that sensors are still operational.
  • Inputs
    • Token (Previously negotiated during the sensor enrollment)
    • From (sensor MAC)
    • Pretty (Sensor Name)
    • FirmwareVer (Sensor firmware version)
    • Index (The sensor channel that was triggered on the sensor device)
• /Senslogin
  • Description: Sensors need to login to the valve to get a token
  • Inputs
    • OPTIONAL userid, (only required if the valve is configured to use a username)
    • OPTIONAL pwd, (only required if the valve is configured to use a password)

There is also an extensive set of HTTP API endpoints used by the web interface that could also be used externally. All of these require a valid token provided by the /login endpoint.

• /update (Start a firmware update from the file provided)
• /uploadSpiffs (Start a Spiffs filesystem update from the file provided)
• /GetSensors (Return a JSON string containing all registered sensors and their values)
• /command/reboot (reboot the ESP32)
• /command/close (manually close the valve)
• /command/open (manually open the valve)
• /command/lockclose (Manually lock the valve closed)
• /command/lockopen (Manually lock the valve open)
• /UserPassDelete (Delete credentials from the device, allowing the device to function without login)
• /GetConfig (Get the current configuration in JSON)
• /GetESPInfo (Get the ESP program space and memory utilization in JSON)
• /DumpTokens (Debug, commented out in code, dumps a list of all authentication tokens to the serial port)
• /GetIPInfo (return the ESP32 network settings in JSON)
• /GetLogs (return the last 20 log events in JSON)
• /GetHealth (return the device health in JSON)
• /DeleteSensor (Delete a specific sensor)
• /clearNetwork (Clear the network config, defaults back to DHCP)
• /CheckTokenPost (Check if a token is still valid via HTTP Post)
• /CheckToken (Check if a token is still valid via HTTP Get)
• /logout (Log out and remove the token)
• /login (log in, get a token)
• /form (accept settings as form input)

Water Sensor HTTP API

The HTTP interface on each sensor is used for communication from Water Valve to Sensor. These are the implemented endpoints

• /update (Start a firmware update from the file provided)
• /uploadSpiffs (Start a Spiffs filesystem update from the file provided)
• /DumpTokens (Debug, commented out in code, dumps a list of all authentication tokens to the serial port)
• /login (log in, get a token)
• /logout (Log out and remove the token)
• /CheckToken (Check if a token is still valid via HTTP Get)
• /EnableDisableSensor (Enable or disable one of the 10 sensor inputs, disconnected inputs may be left floating so this allows them to be ignored)
• /form (accept settings as form input)
• /clearNetwork (Clear the network config, defaults back to DHCP)
• /GetHealth (return the device health in JSON)
• /GetLogs (return the last 20 log events in JSON)
• /GetIPInfo (return the ESP32 network settings in JSON)
• /GetESPInfo (Get the ESP program space and memory utilization in JSON)
• /GetSensors (Return a JSON string containing all registered sensors and their values)
• /GetConfig (Get the current configuration in JSON)
• /UserPassDelete (Delete credentials from the device, allowing the device to function without login)
• /command/reboot (reboot the ESP32)

Downloads

• Water Valve Firmware Code (Arduino IDE)
• Water Sensor Firmware Code (Arduino IDE)