Raspi-Sump Frequently Asked Questions
Project Related
1 - What is Raspi-Sump?
2 - What problem does Raspi-Sump solve?
3 - How much does it cost?
4 - Looks complicated, how can I do this?
5 - How can I get help to do this?
6 - Sounds good, but what's the catch?
7 - Will it always be free?
8 - I have a good idea for the application, can you add it?
9 - What Python and OS versions are supported?
10 - I would like to re-use your code to make a different program?
11 - How can I Donate to the Raspi-Sump Project
Technical Questions
1 - Why am I missing files after doing a pip3 install?
2 - Why do you pin raspisump to a specific version of RPi.GPIO?
3 - Why are my email alerts not working?
4 - I am not getting any depth readings?
5 - Why are the dates on my charts not formatting properly?
6 - Why am I getting multiple readings of 0 on my charts?
7 - I use the JSN-SR04T sensor and get bad readings when the water gets up high?
8 - I want to use the program to send me alerts when the water level gets too low.
9 - I can't start the lighttpd web server on Raspbian Buster.
10 - How do I set the heartbeat alert to always text me at the same time.
11 - What about power outages? How will I receive alerts if there is no power?
12 - Is there a way to make the pi control the pump directly?
13 - My charts are no longer being generated but resolved itself inexplicably the next day.
14 - Is there an easy way to test that emails are working?
Project Related Questions
Raspi-Sump is a waterlevel monitoring system that uses an ultrasonic sound sensor (such as the HCSR04) connected to the GPIO pins of a Raspberry Pi.
It passively monitors the waterlevel and sends you a SMS text alert to your phone if the water exceeds a pre-defined level.
The program is written in Python and the source code is available on Github.
Monitoring the waterlevel of a sump pit or any other container requires you to be at that location. Raspi-Sump allows you to monitor
the level from any location that has an internet connection and actively alerts you if there is a problem, which allows you to address it before there is a disaster.
Raspi-Sump if free to use under the MIT License. The source code is freely available to use, modify and distribute as you see fit.
Raspi-Sump is a community driven “do-it-yourself” type of project. That being said it is not that difficult. There are very detailed instructions available for anyone who feels this may be a potential solution for them.
See the Raspi-Sump website for all information you need on materials required and instructions. The project will consist of acquiring the necessary items, making a cable to connect to your sound sensor and installing the software.
Finally you will need to properly mount the project in the environment you want to monitor.
Help is available if you get stuck or have questions.
a - Report problems or find solutions on the GitHub issue tracker (requires a Github Account)
b - Subscribe to the Raspi-Sump email list
c - Join our Discord group to ask questions. Email me for an invite link.
There is no catch. Don’t think of the program as “Free Beer”. Think of it as “Free Speech”. When I say you can use it as you wish that is exactly what I mean. The MIT License is very permissive in this regards.
Raspi-Sump will always remain free to use.
Raspi-Sump is open source. I welcome contributions to the program. If you are interested in contributing I have setup
contribution guidelines that you can follow.
I make no promises on what will be added to Raspi-Sump. Please read the guidelines, if you do not follow these then I can assure you it will not be added or even considered.
Be clear with what you are proposing and why. Make sure your code works and is readable before submitting pull requests. If you are not sure let's discuss it in the issue tracker
before you invest any time at all writing code.
Raspi-Sump is supported on Python3. Python2 is no longer supported.
It works on any version of the Raspberry Pi that can run Raspberry Pi OS 11 (Bullseye) or Raspbian 10 (Buster). Support for Raspi-Sump will target in support versions of Raspberry Pi OS or Raspbian only.
For example, it may work great on Raspbian Jessie or Stretch, but if new functionality is added that uses updated libraries that are not supported on these versions,
the fix will be to upgrade the OS to Bullseye or Buster. If you are just starting with Raspi-Sump then I highly recommend starting with the most current version of Raspberry Pi OS.
It also may work on ARM based Operating Systems other than Raspbian (such as Ubuntu for ARM) or on other boards (such as Orange Pi)
but it will require tweaking on your end and I will not be supporting that in the official version of Raspi-Sump.
You are encouraged to fork the project and release under a different name if you want to go in another direction.
The MIT License allows you to do this. There are only two restrictions;
1 - You cannot name your application Raspi-Sump.
2 - You must include a copy of the original license in any program or documentation related to the program that you redistribute.
In practice this simply means a copy and paste of the Raspi-Sump MIT license. Your new program can be released under any license you wish, even a closed source binary release.
This step simply provides attribution to the original project in your release.
Technical Questions
Earlier versions of pip allowed doing scripted installs with setup.py. You could copy all kinds of files where you needed them on install. At some point pip started
using wheels to install and a lot of the stuff in setup.py was getting ignored on install. As a work around you can force pip to install the
old way by passing --no-binary :all: in the install command. I have not found an elegant way to go to back the way it used to be. I am sure there
is a good way, but I have not found it. I am open to ideas.
In the meantime, always install as follows;
sudo pip3 install --no-binary :all: raspisump
and to upgrade;
sudo pip3 install -U --no-binary :all: raspisump
Actually I pin my versions to the latest version of hcsr04sensor, which is the sensor library I wrote.
That version is what is pinned to a specific version of RPi.GPIO. I have had the library just die when RPi.GPIO
went from version 5.10 to 5.11 due to changes. Since many of us use these systems for things we rely on,
I want to make sure nothing unexpectedly dies if you upgrade. As soon as I have tested that the newest version of RPi.GPIO works
with the hcsr04sensor library, I pin to the next version. It is simply a failsafe. I've been burned once and this seems like a good compromize.
This can be caused for different reasons;
a - Are your server configuration details properly entered in raspisump.conf?
b - If using Gmail, have you setup an app password? Google uses Oauth for authentication and forces you to use app passwords. See Signing In With App Passwords for instructions on how to do this.
c - Can you receive sms emails to your phone, have you tested with a regular email client?
d - Login to your pi and run the command emailtest . What error do you see?
If problems persist enter an issue in the Github Tracker or join our Discord group and ask a question.
This could be because the signal is not being received from the sensor. In the /home/username/raspi-sump/logs folder check the error_log file.
If you see the following error this could be indicative of a cable or sensor problem.
**ERROR - Signal not received. Possible cable or sensor problem.
Check that your cable is well attached and that each pin on the sensor is going to the right GPIO pin you have identified in raspisump.conf.
Finally look at the sensor itself, is there corrosion on it? Try testing with the following command;
hcsr04.py -t trigpin -e echopin ---'trigpin' and 'echopin' should match the GPIO pins you are using
This is due to matplotlib. If your dates are not formatting properly create a file called 'matplotlibrc' in the
/home/username/.config/matplotlib directory.
Enter the following lines in the file, save it and regenerate a chart;
date.autoformatter.minute : %H:%M:%S
date.autoformatter.hour : %H:%M:%S
This will be fixed in version 1.7.1 and no longer be required.
This is almost always due to a sensor that is starting to fail. If a sensor starts throwing high negative values the problem may start getting worse.
The reason that it shows 0 on the chart is that Raspi-Sump corrects negative values to 0, so that a high negative number doesn't make the chart unreadable.
Check for corrosion on the sensor. Replace the sensor.
The JSN-SR04T is a good sensor that works in more humid/wet conditions compared to the HCSR04 sensor. However it has a different range. The sensor specification says that it has an effective range
of 20cm-600cm (8in to about 19ft). If your water level is getting within 8 inches of the sensor it will start throwing bad readings. Try positioning the sensor a little higher away if
possible. Don't forget to adjust the pit_depth value in raspisump.conf if you do that. That value should be from the sensor to the bottom of the pit.
Not everyone wants to use this program to monitor a sump pit. You may want to monitor a liquid level in a tank for low volumes, like a drinking water cistern for example.
No problem, Raspi-Sump can be configured to monitor for low water levels as well.
In raspisump.conf look for the following value;
alert_when = high
change it to;
alert_when = low
Make sure to adjust your critical_water_level value accordingly. Alerts will be customized to warn you of low water/liquid levels.
The lighttpd web server software that ships on Raspbian Buster made a change to the naming of a file for mime.types. There are two ways you can address this issue, only select one of them;
1. Create a softlink to the new file with the old naming convention;
cd /usr/share/lighttpd
sudo ln -s create-mime.conf.pl create-mime.assign.pl
sudo /etc/init.d/lighttpd stop
sudo /etc/init.d/lighttpd start
2. Modify the lighttpd.conf file with the proper entry and restart the webserver.
sudo nano /etc/lighttpd/lighttpd.conf
replace the following line;
include_shell "/usr/share/lighttpd/create-mime.assign.pl"
with this line;
include_shell "/usr/share/lighttpd/create-mime.conf.pl"
Save the file and restart the webserver
sudo /etc/init.d/lighttpd stop
sudo /etc/init.d/lighttpd start
To set the heartbeat alert to always text you at the same time do as follows;
a) edit the raspisump.conf file as follows for heartbeat
# daily = 1439 minutes
# weekly = 10079 minutes
# Monthly = 43199 minutes
heartbeat_interval = 1439
Open the /home/username/raspi-sump/logs/heartbeat_log with nano and edit the time on the last alert to match the exact time you want to receive alerts going forward.
nano /home/username/raspi-sump/logs/heartbeat_log
Change the time on the last line to your preferred time and save the file;
2020-03-31 09:00:00,Heartbeat Email Sent
A Back-UPS or similar battery backup is essential for both your pi and your internet modem/router. With a UPS,
internet should continue to work fine for a while during a power outage. There is also the option to use a data plan through the cell
network and simply have the pi plugged into a UPS. I have seen some USB key monthly plans that could potentially be used. I have not
tried this and they would of course incur some monthly charges. This would take some configuration and testing on your part and is beyond the scope of Raspi-Sump.
As long as you have internet, alerts should work.
Remember that Raspi-Sump is one line of defense only. It cannot revive a dead pump or supply electrical power. Once you have addressed
these important infrastructure issues (backup pump, gas or solar generator) then Raspi-Sump is another layer to add piece of mind.
Possibly, but I highly recommend against this. Mechanical float devices are used for a reason, they mostly just work. I am a huge fan of Raspberry Pi, I own several of them.
However, I would not trust them to replace the float ball in my pit. There are too many things that
can go wrong and I would not want to depend on a dead pi or a corrupted flash memory card to cause my pump to not start.
Raspi-Sump is and will always be a passive monitoring system.
If your Raspberry pi had the power cut without a graceful shutdown you may have a corrupted depth reading in your waterlevel csv file for that day.
Login to the console and open the csv file for that day located in /home/username/raspisump/csv
Find the reading that looks like this and remove all the symbols before the 1;
^@^@^@^@^@^@^@^@^@^@^@^@^@16:01:10,4.6
Save the file and rerun your chart.
As of version 1.4 you can run an on-demand email test from the command prompt on your pi.
Login to your pi with ssh and run the following command
emailtest
A test email will be sent to you based on the email you entered in your raspisump.conf file.
