Water Tap Technical Documentation - setup & troubleshooting

Summary

This README is a compehensive setup that will guide you through cloning and troubleshooting this project. The guide should be followed in order.

Hardware prerequisites:

• Raspberry Pi 3B or higher. (Tested with both 3B @ 2GB and 4B+ @ 8GB)
• I2C 2004 20x4 LCD Display
• RFID RC522 Module
• Ultrasonic Sensor HC-SR04
• Two * HL52S V1.0 Dual Relay Module
• Three * DS18B20 Waterproof Thermometer Probe
• Bredboard Button
• RGB LED
• Red LED
• Blue LED
• USB Microphone

Hardware Preparation

Connect the hardware modules to the GPIO pins as follows:

Legend: 🟢 = used; 🔴 = unused;

OS-Level Dependencies

We need to install a few packages from apt.

Maria DB: sudo apt install mariadb-server

Sox: sudo apt-get install sox

Git: sudo apt-get install git

NodeJS > 14.0: will be automatically installed by the script below

Node-RED: bash <(curl -sL https://raw.githubusercontent.com/node-red/linux-installers/master/deb/update-nodejs-and-nodered) While running the above script, you will be prompted about some options. Answer as follows:

MYSQL Setup

Start by creating the database for the project.

Create the databse:

CREATE DATABASE IF NOT EXISTS capstone;

Create the tables:

CREATE TABLE `RFID` (
  `UID` varchar(20) NOT NULL,
  `Quantity` int(5) NOT NULL,
  `Temperature` int(11) DEFAULT NULL,
  `Alias` varchar(20) DEFAULT NULL,
  PRIMARY KEY (`UID`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `systemSettings` (
  `settings` varchar(255) NOT NULL,
  `ColdWaterFlowRate` decimal(10,2) NOT NULL DEFAULT 0,
  `HotWaterFlowRate` decimal(10,2) NOT NULL DEFAULT 0,
  `RFID` tinyint(1) NOT NULL DEFAULT 0,
  `UD` tinyint(1) NOT NULL DEFAULT 0,
  `PID` tinyint(1) NOT NULL DEFAULT 0,
  `DISPLAY` tinyint(1) NOT NULL DEFAULT 0,
  `scheduler` longtext CHARACTER SET utf8mb4 COLLATE utf8mb4_bin DEFAULT NULL CHECK (json_valid(`scheduler`)),
  `waterPrice` FLOAT NOT NULL DEFAULT 0,
  PRIMARY KEY (`settings`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

CREATE TABLE `waterUsage` (
  `epochTime` bigint(20) DEFAULT NULL,
  `usage` decimal(6,0) DEFAULT NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

Populate the systemSettings table with the default settings:

INSERT INTO systemSettings (settings, ColdWaterFlowRate, HotWaterFlowRate, RFID, UD, scheduler)
VALUES ('default', 21, 45, 1, 1, {"timers":[],"settings":{}});

Then create the user for the project: CREATE USER 'pi'@'localhost' IDENTIFIED BY 'capstonepass';

Grant privileges to the user: GRANT ALL PRIVILEGES ON capstone.* TO 'pi'@'localhost';

Flush the privileges: FLUSH PRIVILEGES;

Setup

We will not be using the GUI, therefore you should flash the light version of Raspberry Pi OS to a Micro SD card using the official download page for Raspberry PI OS. Once flashed, install the dependencies listed above.

Move to the projects folder of Node-RED: cd /home/pi/.node-red/projects

Clone the project repository: git clone {url}.

Configure I2C and 1-Wire

Since our project uses a 1-wire temperature sensor and a i2c display, we need to enable them. To do so, run sudo raspi-config and select Interfacing Options -> 1-Wire -> Yes Then, select Interfacing Options -> I2C -> Yes. Choose to not reboot the system.

Configure config.txt

Change the directory to the boot folder: cd /boot and edit the config file: sudo nano config.txt by appending the following.

dtoverlay=w1-gpio,resolution=9,gpiopin=04
dtoverlay=w1-gpio,resolution=9,gpiopin=17
dtoverlay=w1-gpio,resolution=9,gpiopin=27

Reboot the Raspberry Pi: sudo reboot

Temperature Probe Device ID

In order to be able to configure the temperature sensor we need to gather the device id from cd /sys/bus/w1/devices. You should be seeing some folders whose names start with 28-something. These are the device ids and you should be seeing three of them, save the names of the folders as they will be needed later.

Start Node-RED

Start Node-RED with node-red-start

Once Node-RED has started, head to {localhost}:1880 using any browser. Click on the 3 sandwich menu, and select Projects -> New.

Within the next window, select Open existing project. Fill an username and email address, and select the folder that contains the repository we cloned earlier.

Node-RED Dependencies

In order to install the Node-RED dependencies, head to 'Info', select the three dots on the top right corner, then head to Dependencies. There you will see a list of dependencies that need to be installed. Install them one by one by clicking on the Install button.

The dependencies that should be listed are:

Temperature Sensor Configuration

Once opened, the debug console will show a few errors in regards to the 1-wire temperature sensors. This is because we need to configure them. To do so, head to the Data Flow, and select the temperatureGather subflow, there, modify the three read file nodes to point to the correct device id we noted earlier as follows:

Thermometer01 should be the combined temperature of the hot and cold water.

Thermometer02 should be the hot water temperature.

Thermometer03 should be the cold water temperature.

Troubleshooting

Wake word node is not being initialised:

If the configuration points to the proper path for the wake-word training files, then the issue is most likely caused by the Listen node within the NLP Flow. Make sure the USB Microphone is plugged into the Raspberry Pi and the correct audio card is selected in the Listen node. The most likely configuration is: card 1: Microphone, device 0: USB Audio (hw:1,0) In the case the audio card is not (hw:1,0), run sudo aplay -l to find the correct audio card path.

Changing the resolution is not permitted:

Permission to modify the resolution of the temperature probes is not granted by default. Although an attempt to grant the permission is made within the Gather Temperatures sub-flow, it may not be successful due to different OS configurations. To fix this issue, run sudo chmod o+w /sys/bus/w1/devices/ID/resolution where "ID" is the device ID of the thermometer. A way to identify that this issue exists is to either run the temperature resolution check or to check the debug console for errors related to permissions when the temperature probe parameters are modified. In the case of the temperature resolution check, the latency should not be higher than 200MS.

The device delivers incorrect quantities of water:

This issue can be caused by multiple factors such as variable flow rates, or an incorrect calibration of the flow rate. When improper quantities are delivered, the user should re-initiate the calibration process.

Actuation requests have significant lag:

When the actuation requests take longer than 0.5-1 second to start, this may signify that the Raspberry Pi might be overloaded. To fix this issue, the user should add a cooling fan to the Raspberry Pi, this will ensure that the CPU temperature does not force the CPU to enter the thermal-throttle state. If this is not possible, disabling features from the web interface should reduce the load on the Raspberry Pi.