Flow Limiter
Overview
The flow limiter system limits daily outflow from a water tank. It uses an Internet of Things (IoT) device to monitor water flow and limit it to a daily max, and to connect to the cloud and report flow data to the cloud. The cloud sends text-message alerts when anomalies are detected. The cloud allows users to view historical data.
The images below show the water flow subsystem and IoT device as-installed.
Context
The farm (or ranch) supplies water to troughs from a large rain-filled collection tank. Occasionally, cattle destroy a ballcock in a trough and water flows unchecked through the valve, overflowing the trough. If not caught in time, the leaking valve empties the collection tank. When the tank is empty, there's no more water for cattle until it's refilled.
Files Locations
Images
User Manual
The flow limiter system provides measurement and reporting of water flow, and water shutoff in case of excessive flow along with an alert. It comprises three subsystems which work together:
Cloud subsystem saves measurements for display, and sends alerts for anomalous conditions
IoT (Internet of Things) subsystem reports flow data and shuts off water in case of excessive flow.
Water subsystem has the sensor that measures flow, the valve that shuts it off, and a filter and bypass valves.
Cloud Subsystem
The cloud subsystem monitors and stores flow and valve state data sent by the IoT device. Its most important function is to send an alert when it detects a valve state change, warning you that water flow has been inhibited or re-enabled. This is a rare but important occurrence. It can also display the flow data over various timeframes. The flow display looks like this:
The cumulative daily flow graph displays how much water has been consumed each day. It resets to zero at midnight, and rises to the daily total water use during the subsequent 24 hours. The flow rate displays the rate of water flow averaged over 5-minute intervals.
IoT Device
The IoT device is a small red microcomputer mounted to the electronics circuit board. It is the brains of the flow limiter - it measures the signal from the flow sensor, commands the valve on or off, and reports flow and valve position data to the cloud. The IoT device has several modes, and is operated using buttons on the device in a manner akin to setting a watch. It has a display that shows information depending on the mode.
The buttons are unlabeled, and a bit difficult to find. With the IoT device mounted to the circuit board and displaying text:
Button A is the big button next to the display screen
Button B is the small button on the side of the device, above the screen. There is a label on the circuit board
The power button is the small button on the opposite side of the device, below and to the right of the screen. There is a label on the circuit board.
The circuit board to which the IoT device is plugged has three lights:
White: 12 volts good. This should be on whenever the electronics box mains adapter is connected to mains power
Green: 5 volts good. This should be on whenever the white light is on
Red: Valve closed, flow inhibited. When the IoT device closes the valve, this light illuminates. The valve has a return spring that opens it if the light is off.
Power on/off
Power the device on or off by pressing and holding the power button. It powers on automatically upon first application of power, or if USB-C is plugged into the connector on the end of the device. Upon power-on, it tries to connect to the Wifi SSID that is hard-coded into its firmware, Once connected to Wifi, it connects to the cloud, then starts measuring water flow. The normal display after power on is:
Wifi..... IoT... Daily Flow: 0
If it is unable to connect to wifi, or to connect to the cloud, it prints dots until it succeeds.
The IoT device has a small internal battery which keeps it running for a couple of hours in case of power loss. After the battery has discharged, it powers off, but will automatically power back on and recharge the battery when mains power is reapplied.
Modes
Button A cycles through modes as follows:
Flow Display -> Display/Set Flow Limit -> Display/Set Time -> Display/Set Valve override -> Display/Set simulation mode
Each mode displays different information about the IoT device, and allows changing operation settings.
Flow Display
The device starts operation in Flow Display mode, where it displays daily cumulative water flow (in liters) and flow-rate. This is the normal mode. In this mode, Button B resets cumulative water flow. Cumulative water flow also resets to 0 at midnight each night. If cumulative water flow had exceeded the flow limit and the valve had closed, the valve will re-open when cumulative flow is reset to 0.
Button A changes to Display/Set Flow Limit.
Flow Limit
In Display/Set Flow Limit mode, Button B cycles through the flow limit (liters) settings: 2000 -> 1000 -> 500 -> 200 -> 100 -> 20. The flow limit is the value which, when daily cumulative flow exceeds the limit, the valve is closed and remains closed until a reset event (midnight or button B).
Button A advances to Display/Set Time mode.
Flow limit value 20 liters is for test purposes - if you are working on fixing a broken line, it lets you reset flow and thereby cause the valve to open, but will close the valve and shut off flow before much water escapes (in case the break is not fixed).
Set Time
In Display/Set Time mode the display shows the date and time. Button B initiates set-time submode. Then it works like a watch: Button A cycles through the values which can be changed (year/month/day/hour/minute) and Button B increments the current value. The display provides guidance on what is being changed and the function of each button. After all the date/time fields have been selected, button A exits set-time submode and returns to Flow Display. If set-time submode was not entered, Button A advances to Display/Set Valve Override mode.
Valve Override
In Display/Set valve override mode, the display shows cumulative flow, and whether the valve is closed (Flow: Inhibited), or open (Flow: On). Button B toggles valve state. Button A advances to Display/Set Simulation mode.
Valve override enables easily opening and closing the valve during leak detection and repair activities.
Simulation
In Display/Set simulation mode, water flow simulation can be turned on or off. When on, the IoT device generates flow signals which simulate those of the real flow sensor. The rest of the logic behaves as if the real sensor were sending the signals, including reporting flow to the cloud, and shutting off the valve (which also shuts off simulated flow). Button B toggles flow simulation, and the display reports its current state. Button A advances to Flow Display mode.
Simulation mode is used for software and system test. It generates a random flow amount that varies hourly, and runs from 8am to 6pm, and averages around 1500 liters per day. Thus, setting flow limit to 1000 liters or lower will normally cause it to shut off flow when simulated flow exceeds the limit.
Running the IoT device standalone
You can remove the red IoT device from the circuit board by unplugging mains power and sliding the device right until it clears the pins it's plugged into. You can take it to your house and plug a USB C cable into it. It will power up and connect to the cloud via your wifi. Then you can run the simulator. Reinstall it on the circuit board using the reverse procedure - make sure the pins are aligned with the IoT device and mains power is unplugged.
Water Subsystem
The water subsystem has a bypass valve, and isolation valves for isolating the flow sensor and shutoff valve for maintenance. The acrylic box keeps rain off the flow sensor and shutoff valve.
Recommended mounting is using hooks screwed into a base which support the upper (bypass) line, and the rest of the assembly hangs from the bypass line. The valve box can be screwed to mounting board. Leave room to access both unions outside the valve box. When the unions are uncoupled, the flow sensor and valve can be removed from inside box by removing the box lid & shimmying things a bit.
The valve has LEDs visible through the box lid which indicate its state:
Open
Closed
Stuck
The valve defaults to open via spring return, so if no LEDs are on, it is open. After operating, the valve indicates its state on the LEDs, but after being open a while the charge stored in the valve dissipates and the light goes off.
Engineering Documentation
System Design
The flow limiter system monitors water flow out of the collection tank using a flow sensor. The flow sensor is inline with an electrically-operated shutoff valve. When the total flow during a 24-hour period exceeds a user-set value, the device closes the shutoff valve until the end of the current 24-hour period, at which time it is re-opened. In this way, water usage is limited to the user-set amount each 24 hours.
The device publishes flow data and shutoff valve state to the cloud. The cloud is responsible for sending text message alerts when:
The shutoff valve is closed or opened by the device
The device fails to connect to the cloud for a certain duration (warning of possible device failure). Limit 1 message/day
Water flow for a day is below a threshold. Limit: 1 message/day. Rationale: no flow could indicate an empty tank, or blocked piping. It could also trigger a false alert if there are no cattle to consume water. (Question: Should the system provide a way to suppress text alerts??)
The device provides a display which shows aggregate water usage in the current 24-hour period. The cloud provides a web-accessible page which shows historical water usage.
The device can power-on and perform its main function without a web connection. A web connection is highly valuable for delivering alerts, but the main function of limiting excessive flow doesn't depend on it.
The shutoff valve is normally-open, and only closed when the device detects excessive water use. This provides failure-resilience, as well as a way to bypass the system simply by unplugging it.
The system design is expandable to multiple installations, uniquified by a device ID. The device keeps current settings and other installation-specific data in non-volatile memory on the device. Non-volatile memory is initialized by loading an initialization program into the device during system-build.
System Block Diagram
The system block diagram is shown below.
The system is partitioned into three sections:
Water subsystem, outside the shed, and inline with the main water pipe from the tank to the farm
IoT device and associated electronics, inside the shed, with wifi or cellular connectivity to the internet and AC-power provided by electric outlet in the shed
The cloud app, hosted on Amazon Web Services (AWS)
User Interfaces
The water subsystem provides a manually-operated bypass valve, which allows water to flow irregardless of the shutoff valve. This is intended for diagnostic use when hunting for leaks, or in case of a system failure that shuts off water to the farm.
The device provides the following user interface (UI) capabilities:
Display cumulative water use in the current 24-hour period. Useful when diagnosing leaks or deciding on limit setting, without need to connect to the web.
Re-enable flow after it has been inhibited. Implemented as a "clear accumulated flow" button-press, which re-opens shutoff valve
Set date/time (why is this needed? cloud should take care of time) (I think it's needed to timestamp cumulative flow measurements so AWS graphing can use it as a timeseries)
Set daily water-use limit. Limit setting supports a very small value (20 liters) for testing system operation.
Open or close shutoff valve
Enable flow simulation
Requirements
Cloud
The cloud shall provide a graphical display of historical water use, limited to 2 years. Status: delivered
The cloud shall display the cumulative water use in the current 24-hour period. Status: delivered
The cloud shall display the time of the last connect by the device. Status: To Do
The cloud shall send a text alert if the device hasn't connected in the last 24 hours. Status: delivered
The cloud shall send a text alert if the device has either opened or closed the shutoff valve. Alert-detection shall be tolerant of lost messages from the device. Status: email alerts delivered. Text message alerts: To Do
The cloud shall send a text alert if cumulative water flow in the last 24-hour period was less than 10 liters. Status: Outplan at present, TBD if there's a real need
The cloud shall support multiple destinations for text alerts. Rationale: envision Bruce, Paul & maybe Lou as destinations. Status: delivered
The cloud shall provide standard AWS user authentication, authorization and privacy features to limit and protect user access. Status: delivered
The cloud shall provide standard AWS device authentication and privacy features to authenticate connected devices and ensure integrity of messages. Status: delivered
IoT Device
The IoT device shall measure water flow. Status: delivered
The IoT device shall control the shutoff valve. Status: delivered
The IoT device shall track water usage from midnight to midnight (24-hour period). Status: delivered
The IoT device shall provide a UI for setting the daily water limit. Status: delivered
The IoT device shall close the shutoff valve when it determines water use in the current period exceeds the daily limit. Status: delivered
The IoT device shall open the shutoff valve at the beginning of each 24-hour period. Status: delivered
The IoT device shall by default display cumulative use in the current 24-hour period on its local display. Status: delivered
The IoT device shall enable setting current date/time. Status: delivered
Date-time shall be maintained across power outage and reboot. Status: delivered
The IoT device shall report cumulative water use for the current 24-hour period as well as shut-off valve state to the cloud. Status: delivered
The IoT device shall report to the cloud every 10 minutes. Rationale: just less than the max 15-minute time recommended for AWS IoT devices. Status: delivered 5 minute updates
The IoT device shall be capable of using WiFi or cellular wireless networks to access the cloud. Status: Wifi only delivered
The IoT device shall support updating FW when necessary from a connected PC. Status: delivered
The IoT device shall output logs and debug messages to the USB serial port. Status: delivered
The IoT device shall draw power from a wall-wart to be provided at installation. Status: delivered
The IoT device shall include a water flow simulator that can be enabled in place of the actual flow sensor. Rantionale: enables testing much of the design. Status: delivered
The IoT device shall have a unique device ID. Status: delivered
The IoT device shall report its device ID along with data reports to the cloud. Rationale: support multiple devices Status: delivered
Water Subsystem
The water subsystem is the flow sensor and associated valves and wiring to the IoT device
The water subsystem shall be physically remote from the IoT device. Status: delivered
The water subsystem shall provide a cable of length 10 feet for connection to the IoT device. Note: cable routing to be determined at system installation. Status: delivered
The water subsystem shall interface to 3/4 inch poly tubing carrying water from the tank, and to the farm. Status: delivered
The water subsystem shall use 3/4 inch components for carrying water. Status: delivered
The water subsystem shall provide a bypass valve. Note: this requirement is redundant with the "normally open, unplug for flow" requirement, but is envisioned as a more user-friendly way of enabling flow when needed. Status: delivered
The bypass valve shall be labeled. Status: Not delivered - it's obvious from looking at it.
The water subsystem shall provide isolation valves that enable the flow-sensor leg to be isolated from water pressure and flow to travel through the bypass valve. Rationale: it may be desirable to disconnect the flow sensor for some period of time without affecting flow to the farm. Status: delivered
The water subsystem shall provide a water flow sensor with 30 liters/min minimum capability, connected to the IoT device. Status: delivered
The water subsystem shall provide a normally-open shutoff valve, controlled by the cable from the IoT device. Rationale: Unplug to enable water flow. Status: delivered
The water subsystem shall provide a filter that protects the flow sensor from contaminants. Status: delivered
Non-functional Requirements
The IoT device shall operate in an indoor, unheated environment, min temp 0 C, max temp 40C. Status: delivered
The IoT device shall provide protection against ambient sawdust, insects. Rationale: it is envisioned to be placed in a shed, and may be exposed to things that happen in sheds and workshops. Status: delivered
The water subsystem shall operate outdoors, min temp 0 C, max temp 40C; protection from rainfall shall be provided. TBD: who provides the rainfall protection? Status: delivered
The water subsystem shall measure water flow with an accuracy of +/- 40% of actual flow. Rationale: The sensor spec states 3% accuracy, but anecdotal reports suggest 40% is nearer reality. Status: delivered
The water subsystem shall operate up to 100psi water pressure. Status: delivered
The water subsystem shall protect itself from contaminants (e.g. vegetation) which may enter the rainwater tank and be pumped through the system. Status: delivered
Non-requirements
The following items were considered for inclusion as requirements, but are not considered justified, and are specifically excluded:
Timezone or daylight savings adjustments. Time set on the IoT device will be considered local time. The user can change time, or not, when daylight savings starts or ends. Recommendations is not to bother with it - an hour here or there doesn't matter.
IoT device authentication & authorization. The device will be on private property, and no protection against use by unauthorized persons who have physical access to the device will be provided.
Dust protection for the water subsystem is not envisioned to be needed.
Messages from the cloud to the IoT device. They are not envisioned to be needed, so they will not be enabled. Rationale: reduced attack surface.
IoT device Over The Air (OTA) FW update. Any FW update needed is envisioned to be done by connecting a PC to the device. Discussion: OTA update would be desirable if it can be secured, so as to avoid the need to physically move a computer or the device. This would be a WANT priority - do it if easy and safe.
IoT Thing Software
The IoT Thing software runs on an M5StickC Plus, and is built in the Arduino environment. See the README in the github repository for installation and build details. The IoT Thing software repo can be cloned from git@github.com:PaulBouchier/FlowLimiter.git.
In addition to the code for the IOT device, a sketch must be run to initialize EEPROM variables used by the IoT software. This is the FlowLimiterEEPROM sketch, which must be modified, built and loaded into the M5StickPlus device prior to loading the FlowLimiter software. The FlowLimiterEEPROM code is in a repo which can be cloned from https://github.com/PaulBouchier/FlowLimiterEEPROM
Arduino Libraries Installation
Follow these instructions to download the Arduino 1.8 software and the M5Stack libraries:
https://docs.m5stack.com/en/arduino/arduino_development
The Wifi Client library should be installed by default. Use the library manager to install libraries: arduino-mptt, ArduinoJson, M5GFX, M5StickCPlus
Hardware Design
IoT Subsystem
The schematic for the IoT subsystem is shown below.
Flow Limiter Schematic
Flow Limiter PCB Layout
Flow Limiter Cable
Bill of Materials
The Bill of Materials (BOM) for flow limiter system hardware is shown below.
Component power usage:
Motorized valve: 12V, 48mA when operating, 25mA when closed. Removing power causes spring to open valve.
M5StickC: 500mA @ 5V (2.5W)
The power supply is spec'd at 12V, 500mA (6W)
Cloud Architecture
The diagram below shows the architecture of the cloud part of the flow limiter system.
Firmware Release Process
Update secrets.h to use Bruce's wifi SSID