livello_serbatoio.ino File Reference

#include <LiquidCrystal.h>

Classes
class	LcdHelper
	Helper class to write on LCD. More...
class	MedianFilter
	Median filter manager. More...
class	ConsumptionData
	Manages the consumption statistics. More...
class	ReadingsAnalyzer
	Analyzes the readings from distance sensor to determine if the water level is increasing, decreasing or stationary. Permits also to detect sensor failure if the readings appear to be random. More...

Macros
#define	VERSION   "v0.13"
	Software for water tank level monitoring.
#define	BANNER   "GR25"
	Author and year of build.
#define	CONF_DEBUG   1
	Constant used to compile in DEBUG mode (Serial enabled).
#define	CONF_RELEASE   0
	Constant used to compile in RELEASE mode (Serial disabled).
#define	SENSOR_HCSR04   0
	Constant used to compile code for HC-SR04 ultrasonic sensor.
#define	SENSOR_JSNSR04T   1
	Constant used to compile code for JSN-SR04T ultrasonic sensor (waterproof).
#define	DEBUG   CONF_DEBUG
	Current configuration.
#define	SENSOR   SENSOR_HCSR04
	Current sensor.

Typedefs
typedef double	float64_t

Functions
static LiquidCrystal	lcd_if (RS, E, DB4, DB5, DB6, DB7)
	The instance of LCD HW.
int32_t	compare_float (const float64_t x, const float64_t y, const float64_t th)
	Determines if two float values are equal.
int32_t	round_float_value (const float64_t x)
	Round the given float value to the nearest integer.
void	initialize (void)
	Initializes all variables.
float64_t	compute_liters (float64_t read_distance)
	Computes the volume of water in the tank.
float64_t	compute_percentage (float64_t read_liters)
	Computes the percentage of filling of the tank.
void	turn_on_lcd_light (void)
	Turns on the LCD backlight.
void	turn_off_lcd_light (void)
	Turns off the LCD backlight.
void	print_error (void)
	Prints an error message to LCD if not in debug mode.
void	show_err_code_debug (void)
	Shows the current error code to LCD (only in debug mode).
void	update_lcd_debug (const float64_t distance_to_print)
	Updates the LCD.
void	monitorReadings (void)
float64_t	measure_level (void)
	Executes a measurement of water level.
void	control_led (const float64_t water_percentage)
	Controls the LED status depending on water level.
float64_t	sanitize_data (const float64_t data, const float64_t min_val, const float64_t max_val, const float64_t min_threshold, const float64_t max_threshold)
	Sanitizes the input value and contraints it in specified valid range.
void	update_lcd (const float64_t water_percentage, const float64_t liters)
	Updates the LCD with the actual parameters if needed.
void	autotest (void)
	Executes an autotest of LCD and LED.
void	print_stat (String str, const uint32_t stat)
	Prints on LCD the consumption statistic passed.
void	show_version (void)
	Prints the SW version on LCD.
void	show_params (void)
	Prints the tank parameters (diameter, number of tanks, max water heigh, max total capacity).
void	show_stats (void)
	Prints on LCD all the statistics.
void	enter_debug (void)
	Changes operative mode to DEBUG.
void	exit_debug (void)
	Changes operative mode to NORMAL.
void	button_interval_6_handle (void)
	Actions for sixth menu slot.
void	button_interval_5_handle (void)
	Actions for fifth menu slot.
void	button_interval_4_handle (void)
	Actions for fourth menu slot.
void	button_interval_3_handle (void)
	Actions for third menu slot.
void	button_interval_2_handle (void)
	Actions for second menu slot.
void	button_interval_1_handle (void)
	Actions for first menu slot.
void	show_menu_options (const uint32_t btn_press_time)
	Prints on LCD the menu options based on button press time.
void	do_menu_actions (const uint32_t btn_press_time)
	Performs the menu associated actions based on button press time.
void	manage_button (void)
	Manages the button events.
void	setup (void)
	Setup function (executed once).
void	loop (void)
	Loop function.

Variables
const int16_t	FILTER_SEED = 0
	Initial value for Median Filter.
const int16_t	FILTER_SIZE = 5
	Median Filter size.
const int16_t	ECHO_DPIN = 12
	Digital pin for ultrasonic sensor ECHO pin.
const int16_t	TRIG_DPIN = 11
	Digital pin for ultrasonic sensor TRIG pin.
const int16_t	LED_CAPACITY_DPIN = 13
	Digital pin for LED.
const int16_t	LCD_BUTTON_DPIN = 2
	Digital pin for Button.
const int16_t	LCD_LIGHT_DPIN = 9
	Digital pin for LCD backlight.
const uint16_t	TANK_NUMBER = 2U
	The number of tanks.
const float64_t	TANK_RADIUS_CM = 65.0 / 2.0
	The radius of the tank(s) in cm.
const float64_t	TANK_HEIGHT_CM = 150.0
	The height of the tank(s) in cm.
const float64_t	SENSOR_DISTANCE_CM = 19.0
	The distance between sensor and the highest water level in cm.
const float64_t	WATER_MAX_HEIGHT_CM = TANK_HEIGHT_CM - SENSOR_DISTANCE_CM
	The maximum water height in cm.
const float64_t	LOW_LEVEL_THRESHOLD = 40.0
	The percentage threshold used to indicate the low level of water.
const float64_t	EMPTY_LEVEL_THRESHOLD = 20.0
	The percentage threshold used to indicate the tank(s) emptiness.
const float64_t	CM3_PER_LITER = 1000.0
	Constant used to convert liters in cm^3 (1 l = 1000 cm^3).
const uint32_t	MEASURE_LF_INTERVAL = 30 * 1000
	Inteval between two measurements (low frequency) in milliseconds.
const uint32_t	MEASURE_HF_INTERVAL = 5 * 1000
	Inteval between two measurements (high frequency) in milliseconds.
const uint32_t	LCD_ON_TIME = 30 * 1000
	LCD backlight duration in milliseconds.
const uint32_t	SLEEP_TIME = 100
	Sleep time between two execution of loop in milliseconds.
const uint32_t	SHOW_STAT_TIME = 5000
	Duration for visualization of Statistics in milliseconds.
const uint32_t	SHOW_PARAM_TIME = 5000
	Duration for visualization of Tank Parameters in milliseconds.
const uint32_t	SHOW_VERSION_TIME = 3000
	Duration for visualization of SW Version in milliseconds.
const uint32_t	LED_CONTROL_TIME = 1000
	Period of LED blinking in milliseconds.
const uint32_t	READ_DISTANCE_TIME = 1000
	Period of distance reading from Median Filter in milliseconds.
const uint32_t	BTN_INTERVAL_1_TIME = 200
	Duration to trig Slot 1 of menu in milliseconds.
const uint32_t	BTN_INTERVAL_2_TIME = 2000
	Duration to trig Slot 2 of menu in milliseconds.
const uint32_t	BTN_INTERVAL_3_TIME = 3000
	Duration to trig Slot 3 of menu in milliseconds.
const uint32_t	BTN_INTERVAL_4_TIME = 4000
	Duration to trig Slot 4 of menu in milliseconds.
const uint32_t	BTN_INTERVAL_5_TIME = 5000
	Duration to trig Slot 5 of menu in milliseconds.
const uint32_t	BTN_INTERVAL_6_TIME = 6000
	Duration to trig Slot 6 of menu in milliseconds.
const float64_t	SENSOR_CALIBRATION = 1.0
	Sensor distance offset used for calibration in centimeters.
const float64_t	SENSOR_MIN_RANGE = 2.0
	Sensor minimum readable distance in centimeters.
const float64_t	SENSOR_MAX_RANGE = 450.0
	Sensor maximum readable distance in centimeters.
const float64_t	SENSOR_LSB = 58.0
	Sensor LSB to achieve distance from ECHO pulse time in usec/cm.
const int32_t	SENSOR_ACTIVATION_TH = 15
	Duration of TRIG signal to perform a measurement.
const uint32_t	SENSOR_RESPONSE_TIMEOUT_US = 500000UL
	Timeout in microseconds used to determine when the sensor reading is failed.
const uint32_t	SENSOR_NO_OBSTACLE_US = 38000UL
	ECHO pulse time in microseconds which indicates the absence of sensor readable obstacles.
const int32_t	LCD_COLS = 16
	Number of columns of LCD.
const int32_t	LCD_ROWS = 2
	Number of rows of LCD.
const byte	PROGRESS_CHAR = 1
	Index of special character used for progress bar.
const byte	ARROW_UP_CHAR = 2
	Index of special character used for arrow up.
const byte	ARROW_DOWN_CHAR = 3
	Index of special character used for arrow downn.
const int32_t	LCD_CHAR_SIZE = 8
	Size of special character definition array.
const byte	LCD_PROGRESS [LCD_CHAR_SIZE] = { 0x1F, 0x1F, 0x1F, 0x1F, 0x1F, 0x1F, 0x1F, 0x1F }
	Definition of special character used for progress bar.
const byte	LCD_ARROW_DOWN [LCD_CHAR_SIZE] = { 0x00, 0x00, 0x00, 0x1F, 0x0E, 0x04, 0x00, 0x00 }
	Definition of special character used for arrow down.
const byte	LCD_ARROW_UP [LCD_CHAR_SIZE] = { 0x00, 0x00, 0x04, 0x0E, 0x1F, 0x00, 0x00, 0x00 }
	Definition of special character used for arrow up.
const int16_t	RS = 3
	LCD's RS digital pin.
const int16_t	E = 4
	LCD's E digital pin.
const int16_t	DB4 = 5
	LCD's DB4 digital pin.
const int16_t	DB5 = 6
	LCD's DB5 digital pin.
const int16_t	DB6 = 7
	LCD's DB6 digital pin.
const int16_t	DB7 = 8
	LCD's DB7 digital pin.
const int32_t	ERR_OK = 0
	All ok. No error occurred.
const int32_t	ERR_SENS = 1
	Sensor reading error.
const int32_t	ERR_RANGE = 2
	Sensor reading out of range.
const int32_t	ERR_STAT = 3
	Consumption calculation error.
const int32_t	ERR_NOISY = 4
	Noisy error.
static volatile bool	led_on
	Indicates if LED is turned on (true) or off (false).
static volatile bool	led_status
	Indicates if LED is on or blinking (true) or off (false).
static volatile bool	in_debug
	Indicates if the SW is in DEBUG mode (true) or NORMAL mode (false).
static volatile bool	first_measure_done
	Establishes if the first measurements used to feed the Median Filter have been done (true) or not (false).
static volatile byte	last_btn_status
	Indicates if the button was pressed (HIGH) of not (LOW), to detect long pressure.
static volatile int32_t	err_code
	Contains the current error code (see Error Codes).
static volatile uint8_t	measure_analysis
	Contains the current analysis result.
static volatile uint32_t	timestamp_lcd_on
	Timestamp of the last LCD backlight activation in milliseconds.
static volatile uint32_t	timestamp_measurement
	Timestamp of the last reading from Median Filter in milliseconds.
static volatile uint32_t	timestamp_last_led_ctrl
	Timestamp of the last LED activation in milliseconds.
static volatile uint32_t	timestamp_last_read_dist
	Timestamp of the last sensor reading in milliseconds.
static volatile uint32_t	timestamp_btn_press
	Timestamp of the last button pressing in milliseconds.
static uint32_t	measure_interval
	Contains the current sensor reading period (based on current SW state) in milliseconds.
static float64_t	tank_capacity
	The capacity of one tank in liters.
static float64_t	maximum_capacity
	The capacity of all tanks summed in liters (assume all tanks equals).
static uint16_t	number_measures_done
	The number of measures done during initialization phase.
static float64_t	percentage
	The current water level in percentage.
static volatile float64_t	distance
	The last distance read from sensor (in centimeters).
static volatile float64_t	previous_liters
	The previous capacity read in liters.
static LcdHelper	lcd
	The LCD helper instance.
static MedianFilter	filter
	The Median Filter instance.
static ConsumptionData	stats
	The Consumption Data instance.
static ReadingsAnalyzer	analyzer
	Readings analyzer instance.

Macro Definition Documentation

BANNER

#define BANNER   "GR25"

Author and year of build.

CONF_DEBUG

#define CONF_DEBUG   1

Constant used to compile in DEBUG mode (Serial enabled).

CONF_RELEASE

#define CONF_RELEASE   0

Constant used to compile in RELEASE mode (Serial disabled).

DEBUG

#define DEBUG   CONF_DEBUG

Current configuration.

SENSOR

#define SENSOR   SENSOR_HCSR04

Current sensor.

SENSOR_HCSR04

#define SENSOR_HCSR04   0

Constant used to compile code for HC-SR04 ultrasonic sensor.

SENSOR_JSNSR04T

#define SENSOR_JSNSR04T   1

Constant used to compile code for JSN-SR04T ultrasonic sensor (waterproof).

VERSION

#define VERSION   "v0.13"

Software for water tank level monitoring.

This Software measures and monitors the water level in a tank using an ultrasonic distance sensor. It shows essential information (such as remaining liters and fill percentage) in a 16x2 LCD and warns about low water level using a LED.

Pinout and links:

• LCD (1602A):
  • Vss : GND
  • Vdd : +5V
  • Vo : OUT Potentiometer (for contrast regulation)
  • RS : DIGITAL 12
  • RW : GND (Write)
  • E : DIGITAL 11
  • DB4, DB5, DB6, DB7
  • 4 , 5 , 6 , 7 (DIGITAL)

Author

Giovanni Rossi

Copyright

This project is released under the GNU General Public License v3.0. Version tag