Multi-module distance monitor utilising HC-SR04 sonar modules, Arduino, RaspberryPi, MQTT, and Node-RED

What does this do?

This project allows remote monitoring of one or more HC-SR04 sonar modules.

The modules plug into an Arduino, the Arduino is controlled by a Raspberry Pi, and the Raspberry Pi sends the data to a NodeRed dashboard via the MQTT protocol.

---

What should I know before starting this project?

• How to set up a Raspberry Pi
• How to wire up Arduino pins and upload code via the IDE.
• How to install Python3 and run a script.
• How to install Node-RED and import a flow
• Basic familiarity of the Firmata controller protocol.
• Basic familiarity of the MQTT messaging protocol.

---

What hardware is needed?

This project as it's currently configured requires the following:

• Raspberry Pi (3B or better)
• Arduino (MEGA2560 used but any modern board will probably work)
• One or more HC-SR04 sonar modules (project uses 4)

---

What code is needed?

This project uses the following software / libraries:

Arduino

• FirmataExpress - Accepts control commands via USB

Raspberry Pi

• Python3 - Runs the script
• pymata4 - Sends control commands to the Arduino via USB
• paho-mqtt - Sends readings via MQTT

Raspberry Pi or network connected PC

• Mosquitto MQTT Broker - Receives readings sent via MQTT and allow other devices to subscribe to those readings
• Node-RED - Displays readings received via MQTT on a dashboard

---

Project steps

Step 1: Setup the Arduino pins

Wire the HC-SR04 modules to the Arduino as follows:

red: 5v power - powers the module
black: ground - completes the circuit
green: trigger - receives read command from Arduino
yellow: echo - sends distance signal to Arduino

You may use whichever pins on the Arduino you like, just make sure you update the script as required.

Step 2: Upload FirmataExpress onto the Arduino

The easiest way is to use the official Arduino IDE

1. Go to Tools > Manage Libraries to download and install the FirmataExpress library
2. Go to File > Examples > FirmataExpress > FirmataExpress to open the FirmataExpress code.
3. Upload onto the Arduino

Step 3: Setup the Raspberry Pi

1. Set up the Pi with the latest Raspberry Pi OS
2. Update Pi and install dependencies

   $ sudo apt update && sudo apt -y dist-upgrade
   $ sudo apt install python3

3. Connect Raspberry Pi to the Arduino with a USB cable (any port is fine)

Step 4: Download and install python script

Either clone or download this repo and move the distance_monitor directory containing distance_monitor.py into a directory of your choice.
For this example we'll be using /opt/distance_monitor. Note you'll need to use sudo to move files into /opt.

1. Copy scrip directory to /opt:

   $ cd ~/distance_monitor-main  # or wherever you downloaded this repo
   $ sudo cp distance_monitor/ /opt

2. Check files were moved correctly

   $ ls /opt/distance_monitor

   You should see the following files listed:

   distance_monitor.py
   requirements.txt

Do the next steps once you've finished step 7 and installed an MQTT broker

3. Open distance_monitor.py with your favourite editor

   $ nano /opt/distance_monitor/distance_monitor.py 

4. Replace mqtt-broker with the url of your mqtt broker. No need to include the port.

   MQTT_BROKER = '<mqtt-broker-ip-address>'

Step 5: Install Python dependencies

1. Create and activate virtual environment (optional but recommended)

   $ cd /opt/distance_monitor
   $ python3 -m venv venv 
   $ source venv/bin/activate

2. Use pip to install dependencies listed in requirements.txt

   $ pip3 install -r requirements.txt

The code can now be run via this command (if you get USB permission issues run as sudo):

$ /opt/distance_monitor/venv/bin/python3 /opt/distance_monitor/distance_monitor.py

CMD + C will stop the programme

Step 6: Make the script run at startup using systemd (optional)

If you're happy to run this script manually or have some other way to running it you can skip this step.
This example assumes you'll be running the script as root, but your needs may vary.

1. Copy distance_monitor.service to the systemd directory

   $ cd ~/distance_monitor-main  # or wherever you downloaded this repo
   $ sudo cp raspberrypi/distance_monitor.service /etc/systemd/system/

2. Ensure Python and script paths are correct

   $ sudo nano /etc/systemd/system/distance_monitor.service

3. Check that ExecStart and WorkingDirectory point to the right files. Change these to match wherever you put the script.

   [Service]  
   ExecStart=/opt/distance_monitor/venv/bin/python3 /opt/distance_monitor/distance_monitor.py  
   WorkingDirectory=/opt/distance_monitor/

4. Save the file with CMD + O and close the editor with CMD + X

5. Reload the daemon to ensure systemd sees the new file

   $ sudo systemctl daemon-reload

6. Set the service to run at boot

   $ sudo systemctl enable distance_monitor

7. Check service was enabled successfully

   $ sudo systemctl status distance_monitor

   Second line should read something like:

   Loaded: loaded (/etc/systemd/system/distance_monitor.service; enabled; vendor preset: enabled)

8. Start the service manually (optional)

   $ sudo systemctl start distance_monitor 

Step 7: Setup MQTT broker

Head to the mosquitto download page and follow the instructions relevant to the OS you'll be using.

If you're installing both mosquitto and Node-RED on the Raspberry Pi, you can skip the next steps.

If you're using a separate machine, you'll need to configure mosquitto to allow remote connections as by default it only works locally.

1. Create and open a new mosquitto config file

   $ sudo nano /etc/mosquitto/conf.d/custom.conf

2. Add the following text to the file.

   allow_anonymous true
   listener 1883
   

   Save & close with CMD + O and CMD + X

Note this opens up the mosquitto service to all machines connected to the network and has no security or authentication enabled. Steps for securing mosquitto are available but are outside the scope of this guide.

Step 8: Setup Node-RED

Head to the Node-RED getting started page and follow the instructions. If you're installing onto the Raspberry Pi or another Debian / Ubuntu machine then you can follow the Raspberry Pi section.

1. Install dependencies

   $ sudo apt install curl

2. Run Node-RED install script

   $ bash <(curl -sL https://raw.githubusercontent.com/node-red/linux-installers/master/deb/update-nodejs-and-nodered)

   If the install was successful you should get an All done message on the screen and be provided with some options on how to start the Node-RED programme. Easiest is just to enter node-red-start in the terminal.

3. Run Node-RED as a service on startup (optional)
   If you want to set Node-RED to run every time the machine boots up, just do the following.

   $ sudo systemctl enable nodered.service

Step 9: Run Node-RED and connect to MQTT broker

1. Start Node-RED however you prefer

2. In a web browser enter http://localhost:1880 if accessing locally or http://<ip-address>:1880 if accessing remotely.

3. Install the node-red-dashboard node module to your palette using the guide on the Node-RED website.
   The easiest way is via the Manage Pallet option in the main menu of the Palette Manager.
   

4. Open the Import nodes dialogue in the main menu, press select a file to import.
   

5. Navigate to ~/distance_monitor-main/node_red/mqtt_dashboard.json, select Open, then Import. A new editor tab named mqtt distance dashboard should appear at the top.

6. Double-click each mqtt input node and enter the correct address for the mqtt broker. If you're running everything on the same machine this will be localhost:1833, otherwise it will be <ip-address>:1833. If successful you'll see a green square and a connected message beneath each mqtt input node.
   

7. Press the red Deploy button to save changes.

8. In a new browser window enter http://localhost:1880/ui if accessing locally or http://<ip-address>:1880/ui if accessing remotely to open the dashboard.
   

Step 10: Play around!

The options are limitless!
Check out Node-RED's documentation for some guided help.