This project uses an ESP32 wifi development board connected to a DS18B20 temperature sensor to constantly send temperature readings to a syslog server on the wireless network. The syslog server runs a cron script to monitor the termperature and send alerts if sensors have been exceeded the temperature threshold for too long a time period as defined by the user.
This project is designed to help animal shelters monitor the temperature of various kennels they have to ensure the animals are safe. You can use this for other reasons but you may need to make some additional adjustments not mentioned here. There are commerical products that can accomplish the same objective, but none are as affordable as they need to be, especially for animal shelters that have very little money to spare.
For example, the best temperature monitor I could find on amazon that could do everything in this project was ~$80 for one unit. Our shelter has 9 locations to monitor, so already that's several hundred dollars for a non-profit, low-budget animal shelter. This project reduces costs to ~$20 per location plus the cost of a raspberry pi, or you could use free tier on AWS to skip the raspberry pi.
Usage and build instructions are below. I have written these instructions for people that are not tech savvy. If you know a tech person, I would recommend getting assistance from that person. worst case, you can google "hackerspace" or "makerspace" and your city name to locate any possible nearby hackerspace/makerspace. you can reach out to them to locate someone that can help you with this project. The hardest part in this project is soldering, so if you can handle that you should be fine. There are lots of tutorials on youtube to help you learn.
I welcome others to assist me with this project to improve wherever possible, so if you would like to collboarte and contribute, please drop me a line.
- All the advice and instruction given is for EDUCATIONAL PURPOSES ONLY. While I shouldn't have to say this, I am not responsible for anything you do or destroy or anything else that happens as a result of your efforts. Nothing is fool-proof so do not trust this or anything as a perfect solution for monitoring temperatures. If you want a guaranteed solution, you should buy one. I am making this project because I have zero solutions that will do the same thing at an affordable price which is what this project accomplishes.
- this project involves some soldering which is recommended to install a physical switch. I am not responsible for you hurting anyone or burning something to the ground or worse. If you are not comfortable soldering, you can reach out to your local hackerspace/makerspace for help. Ultimately it is YOUR RESPONSIBILITY to do all the proper research of all the subjects discussed here before attempting anything yourself.
- this project requires Wi-Fi is available at all of the locations you need to monitor. So that is something else you will need to ensure is ready before you attempt to start this project.
- The equipemnt required for this project only produces a max of 5vdc. This is less than 9v battery and it's technically safe for most people to put that directly on their toungue (just an example, not recommrnding it). Once the USB power adapter ( aka cell phone charger ) converts the electricity from the wall socket into lower voltage current, any danger of electrocultion is removed. HOWEVER, it is not impossible depending on your exact setup.
For example, if you were to use an extention cord to bring the usb power adapter to a different place in the room as needed, it would technically be safe if the animals were to chew on the USB cable or ESP device and not get electrocuted. BUT if they were to chew on the extension cord itself, that could easily kill an animal or human as that is unconverted high voltage current. Expect your animals to chew the wires at some point so be sure not to provide any high voltage wires. It is STRONGLY recommended that you consult with an electrician if you don't know anything about electrical safety. - On that note, an animal swallowing any part of the sensors would be very bad, so be sure to devise a way to keep them out of reach from the animals.
1 - Raspberry Pi or alternative, (potentially optional) see below for more info and cheaper alternatives
(make sure it comes with a PROPER power supply or buy one with it)
?? - DS18B20 Temperature Sensor (one for each area you need to monitor)
?? - ESP-32 WiFi Development Board (one for each area you need to monitor)
?? - Breakout board for ESP32 (one for each area you need to monitor)
?? - USB chargers (one for each area you need to monitor)
??- Low voltage wires (cat5 cable works great)
1 - (optional) lighted toggle switch 3-pole any style is ok as long as its an 3-pole
1 - (optional) solderable breadboard hat
1 - 200ohm resistor (optional) (have to buy a pack, but you may be able to locate a someone that has a few to spare)
1 - basic LED (optional)
1 - tiny flat head screwdriver
1 - micro SD card (16gb or larger). Don't go cheap here. Recommend you buy SanDisk brand. 16gb is plenty of space, you don't need space for this project. The card should come with an micro to standard size adapter. If it doesn't you will need to get one.
1 - Soldering Iron kit (an iron with an iron stand and some solder, micro cutters, maybe something like this)
1 - helping hands see this search for examples. You will need something to hold your items while soldering.
Optional hardware:
You may need a USB-SD card adapter so you can read/write to the card. Some laptops have this already so check before ordering.
Optional alternative hardware:
If you've never done a project like this and don't have any of the items listed above, here is a starter kit that has the M-F cables, low-voltage wires, a temporary breadbaoard, LEDs and resistors.
ELEGOO Electronic Fun Kit for Arduino, Respberry Pi https://a.co/d/bWZt9zZ
Respberry Pi notes & alternatives:
A pi is optional, you can run this on a desktop or server because everything is handled over the Wi-Fi network. Just edit shelterMon.py and edit useSwitch = 1 to useSwitch = 0. The pi is very useful to create a physical switch to disable alerts.
Right now, rPi's are more expensive than they used to be. You DO NOT NEED to get the latest rPi. We bought a rPi version 2 for cheap while the version 4 (latest) was ~$150. You need version 2 or greater.
there are some alternatives you can try to use instead of an actual Pi. I recommend googling "Raspberry Pi Alternatives" but here are a few that look like they may wor. Overall, you must find somethign that has the same set of GPIO pins that the rPi has. Below are some options found on google but I HAVE NOT TESTED THEM AND CANNOT RECOMMEND THESE.
A pi is optional, you can run this on a desktop or server because everything is handled over the Wi-Fi network. But this script requires a LINUX operating system with python3 installed. Just edit shelterMon.py and edit useSwitch = 1 to useSwitch = 0. Otherwise, follow these steps to setup the pi.
- go to https://www.raspberrypi.com/software/ and download the latest Raspbery Pi system imager tool.
- run the EXE file and install the tool, then run the tool.
- for operating system, choose Raspberry Pi OS (should be the top option). Click STORAGE and locate your USB drive and make sure it's the correct size. Dont click WRITE just yet
- Click the cog wheel icon to set additional options.
- Set the hostname if you prefer, enable SSH and use password authenticaiton.
- Scroll down and set the initial username and password
- Set the wireless LAN (wifi) information
- Click SAVE
- Now click WRITE
- After it's finished writing the data, you can eject the card and place it in the Raspberry Pi. Don't power on the pi just yet.
- First go find your router. If you don't already know the admin password, you can check on the router as most modern routers will have that printed somewhere.
- you will need to find your router's IP address
- Once you have the address, put that IP in a browser window to connect to the router. Login using the admin password. If you can't find the router password and can't login, you will need to reset the router. This can be problematic and requires a network cable so make sure you know what you're doing first.
- Once logged in, go to the LOGS section (you may need to click ADVANCED if your router has a basic/advanced option) and you should have a log file to watch as it assigns IP addresses to your devices. Once you have that, power on the rpi.
- Watch the log and look for the IP address given to the rpi. Write down the IP address AND the MAC address for that device, you will need both (example MAC: ab:00:ef:01:23:45).
- Now you will need to locate the DHCP area and find where you can reserve the DHCP address for your rpi. Check this link for an example using a netgead router but you may have to google "dhcp reservation" and your router name/model to find the right guide.
- Once your router has the IP reserved, you are done with the router. REMEMBER how to get back here because you will need to reserve the IPs for each ESP32 device as well. More on that later.
- Now that you have the IP address, you can SSH into the rpi.
- if you dont know how to SSH to a device, you can download putty. Click here for a guide on how to use putty for SSH.
- After logging in run these commands: (you can paste copied text into the putty window clicking the putty window with the right mouse button):
sudo apt-get -y install rsyslog git && sudo cd /home && sudo git clone https://github.com/bramuno/shelterMon.git && sudo cd shelterMon && sudo cp shelter.conf /etc/rsyslog.d/ && nano /etc/rsyslog.d/shelter.conf - Edit the file and use the provided examples and replicate as needed to have one line for each ESP32 sensor you have. The first section defines the log file location, and the second section ties the log file to the IP address of the sensors. Update the IP addresses to match the IPs you got earlier for each ESP32 device. Each line has to be unique so change the 1's and 2's as needed. If you dont have that many devices, don't worry about the extra lines. hit CTRL-O and ENTER to save, then CTRL-X to exit.
- now run this command to edit the rsyslog.conf file
sudo nano /etc/rsyslog.conf
locate module(load="imudp") and remove the # before it. Do the same for next line. Then change port="514" to port="3333" and use CTRL-O to save and CTRL-X to exit. - now run this command to check your conf file is correct:
rsyslogd -f /etc/rsyslog.conf -N1
- now run this command to restart rsyslog:
sudo systemctl restart syslog.socket
If the command returns nothing, especially no errors, then you are fine. Otherwise, go back into the file and try to find where the problem is. syslog won't run if that file isn't perfect. - Now that syslog is listening we can setup the sensors.
- Pop the ESP32 boards into the breakout boards. Make sure the pins line up by matching the labels.
- The sensors should have come with 3 cables with a header that conects to the sensor board. Connect the white header plugs into the sensor boards.
- Now the other end of the cables go to the breakout baord. The red cable goes to the 3V3 pin, the black cable goes to the GND pin, and the yellow cable goes to P14.
- To power on, connect a micro-usb cable to the ESP32 and connect the other end to a usb charger port (like a cell phone charger) or for now you can use the USB port on your computer.
- read this guide on getting to know the basics on the ESP32, follow the instructions to setup arduino IDE and pay attention on how to upload code to the board. It requires you press the reset button just before the board begins uploading, so it may take some practice.
- Now that you are familiar with the ES32, you can upload the code to the board. See the project repo and look for the file "ESP32.ino". Open that file and copy the code into the arduino IDE. Now look for the areas you need to edit. Look for the comments "user changes here". Update the SSIDname and SSIDpassword to your wifi SSID name and password, update the "locationName" to describe the location the sensor has been placed, and update the udpAddress to the IP address of the rpi. Leave the rest unless you know what you are doing.
- Now you need the additional libraries before you upload. Click SKETCH menu and select INCLUDE LIBRARY and then select MANAGE LIBRARIES. It should open a window to allow you to search for new libraries. Search for dallas and install DallasTemp by Miles Burton. Choose the option to INSTALL ALL DEPENDENCIES (otherwise search for OneWire by Jim Studt and install that as well). You should be good to upload now.
- Make sure your Arduino IDE settings are as instructed by the ESP32 guide, then click the UPLOAD button. remember uploading is not that simple for ESP32 so refer back to the previous ESP32 guide and remember you need to hold the reset button on the ESP32 then wait for the arduino output to say "uploading..." and then release the button. it may take a few tries to get it right.
- Repeat the upload process as needed if you have more sensors.
- Once all the sensors are have the wifi code uploaded, you need to reserve the IP address for each device. Go back to the router's DHCP reservation area and then restart the ESP32 devices. When the devices restart, they should ask the router for an IP address and the router will respond. Once you have the IP and MAC addresses, go back to the DHCP reservation area in the router to reserve each device. Then be sure to label each ESP32 (use the bottom side of the breakout board).
- Dont place them in the path of the sun. The sun will heat them up and either freeze them or make them read at higher temperatures than they are.
- Dont place them underneath another object. The sensor needs the smae air as the animals
- Don't place them in a quiet corner with no air flow. You want to ensure the A/C is moving air around so the sensor gets a new temperature every so often. The temperatures are to the nearest hundredth degree so even if it remains the same temperature, the sensor should still see a tiny change in the hundretdth degree.
- Assume the animanls will chew on them so try to keep them out of reach or somehwat protected.
- Avoid placing directly in the path of the A/C vent.
- If you are using your gmail/google account, you can follow this guide to setup your google account information. Don't use your normal gmail password.
- If you are using something else, then you will need to locate your mail server inforamtion. You can ask your IT person if you have one, or you can google "smtp server" and the name of your mail provider (eg "smtp server yahoo). But you will have to check their documentation if it doesnt work as you may need to create an app password similar to the gmail procedure.
- save the username, password and server address and server port as you will need that later. The breadboard hat provides a physical switch to enable/disable the monitor and also an LED that indicates the position of the switch.
- On the rPi, run this command:
sudo nano /home/shelterMon/config.json - When nano opens the file, use the information below to configure your devices:
- "enable":"1", <-- use 1 to enable, 0 to disable checks for this location
- "logfileName":"sensor1.log", <-- Make sure the logfileName matches the file name as mentioned in the syslog.conf file you created earlier
- "locationName":"Kennels", <-- Change this value to the name of the Shelter or the location name where the sensor has been placed
- "maxTemp":"95", <-- Change this to your maximum allowed temperature
- "minTemp":"50", <-- Change this to your minimum required temperature
- "maxDuration":"20" <-- Set this value to the longest time a bad result is tolerable until it should send a notification alert
- "tempUnit":"F", <-- Change this to either C for Celcius or F for Farenheit
- "emailDestination":"[email protected]", <-- Change this to your desired email destination where alerts should be sent. Use commas to separate multiple email addresses.
- "destSMS":"+15551234567" <-- set this value to the destination phone number to receive SMS alerts. Use a comma to separate multiple numbers. If not using SMS alerts, leave the value blank. (empty quotes "" ).
- "throttle":"20" <-- set the number of minutes to wait between sending alert notifications
- "checkASM":" no" <-- enable/disable the use of ASM (see further instructions below)
- "locationID":"1" <-- set the locationID as found in ASM
- "locationUnit":"nameHere" <-- set the locationUnit name as found in ASM
- Repeat the above process for all the sensors your have installed. Name each file to describe it's location and follow with .json (eg. kennels.json)
- Now edit the email.json file to update your SMTP server settings
- "SMTPuser":"SMTPuserNameHere", <-- Change this to your SMTP username from the email section
- "SMTPpass":"SMTPpasswordHere", <-- Change this to your SMTP password from the email section
- "SMTPserver":"smtp.gmail.com", <-- Chnage this to your SMTP server address from the email section
- "SMTPport":"465", <-- Change this to your< SMTP server's destination port from the email section
- hit CTRL-O and ENTER to save, then CTRL-X to exit.
- The sms.json is remaining but that is optional and will be addressed later in this guide.
- Now test each config by running the command:
python3 /home/shelterMon/shelterMon.py -C CONFIGFOLDER
where CONFIGFOLDER is the full path of the folder that contains the json config files you just created. It should be /home/shelterMon
Example:
python /home/shelterMon/shelterMon.py -C /home/shelterMon/ -d yes - If the test is successful you will not get any errors. If the breadboard hat is working correctly, you should get a message that states the switch is OFF and the script will quit. When in the ON position, the script should finish without errors. Refer to the video for a demonstration.
- Now we need to tell the server to run that command by itself every minute.
Run this command: (if it prompts for an editor, choose NANO)
crontab -e - Now paste the following line into the nano editor:
* * * * * sudo python /home/shelterMon/shelterMon.py -C /home/shelterMon/ > /dev/null 2>&1 - Use CTRL-O & ENTER to save then CTRL-X to quit
- Now you are ready to start testing the system is doing what it should be doing. Use whatever you can to test the sensor's temperature readings (hairdryer, freezer, etc).
Turn off the sensor's power supply but leave the Raspberry Pi running. It should notify you the sensor is offline.
Keep the ESP32 powered on but disconenct the sensor from the ESP32, you should get a notification the sensor is not reading correctly within 5 minutes.
- Now you just need to place the sensor(s) where they need to go and use a USB charge adapter to power the sensor unit. the unit needs to be in a place where it can communicate with the WiFi. Also keep in mind the sensor should not be too high up since warm air rises. so a more accurate temperature reading that reflects what the animals will be feeling is going to be when the sensor is closer to their level.
DONT FORGET PLACEMENT IS IMPORTANT! where you place the sensor and the ESP32 wifi module will matter. To avoid false/unreliable readings:
Please refer to the images for the soldering connections and the video for help with the soldering details. Otherwise, I suggest you locate someone that knows how to solder or you can reach our to your local hackerspace/makerspace. If this is your only project you plan to make, then it would be better to lean on some help instead of buying a soldering station.
Again, this step is optional as you don't NEED a switch to allow this to read temperatures and send alerts. However, if there is a problem and the tech person isn't available to disable the alerts, then you could end up sending a lot of emails and SMS messages, which as mentioned in the SMS section below could lead to an expensive scenario.
There are also other ways to make this switch that are more simple and less shiny. It really doesn't matter as long as it works. The LED design allows for non-techy people to flip the switch and show an indicator that the switch is on the OFF position.
As an alternative you send text to a specific mobile carrier's desginated domain like "vtext.com". Here is an example article. HOWEVER be warned as I tested this thoroughly for this project before going with Twilio. I can only speak for Verizon as thats all i could test since that's ny carrier, so maybe the other carriers are better in some areas.
But Verizon SERIOUSLY THROTTLES the messages sent to vtext.com. In my testing on several different days, I sent more than ~10 mesages in a short amount of time, and Verizon stopped delivering those messages. I later got some emails saying the message I sent hours ago has been delayed and not delivered yet. That was a very reliable problem and it's why I don't recommend using it as a permanent solution.
Use the below steps to create and use a Twilio account. These instructions are likely to get depreacted as their website and protocols mentioned below may change over time. So you will have to do your best to do what is needed to get the necessary information. At the time this was written, you can rent a phone number from Twilio for ~$2/month.
- "twilioServiceID":"ABC123" <-- this is your Service ID
- "twilioAcctID":"DEF123" <-- This is your Account ID
- "twilioFromNumber":"+15551234567" <-- This is your twilio phone number
- "twilioToken":"AAABBBCCC" <-- This is your Auth Token
python3 /home/shelterMon/shelterMon.py -C /home/shelterMon -t yes
to run rsyslog in debug mode, stop the syslog service with:
systemctl stop rsyslog.socket
then run the service in the foreground with:
/sbin/rsyslogd -dn
IndexError: list index out of range
These two above lines typically indicate a problem loading the log file created by the syslog service. Check the config.json file(s) to make sure the file name matches the file created by the syslog service. Also make sure the file exists and the syslog service is writing to the file.
this message typically means there is a parsing error on the config.json file, or the json files does not exist. This will happen if there is an extra comma, or unbalanced quotes, etc. the JSON format must be perfect , so if you can't figure it out just go back to the default config.json file provided in the github repo and paste it into your file again. you can also google for an online json validator to help you find the error in the json code.
So the script contacts ASM and grabs some data that holds the occupancy data for those outdoor locations. with that, the script can enable/disable the checks on those locations. Thus if the temperature is too high/low for that location but there is no animal using it, then there is no need to send an alert. This makes things much easier for us so we don't have to worry about enabling/disabling the checks.
If you are using ASM, you can follow these steps to use it with the script.
- In ASM, first create a new USER ROLE. ONLY give that new role permissions to VIEW REPORTS, nothing else.
- Next create a new USER ACCOUNT and grant that user the new role you just created.
- Now you need to create a new REPORT. Go to SETTINGS > REPORTS and creata a new report. Name it whatever you want but place it in a container that you are sure no one will accidently delete or mess with. I advise not using spaces in the title.
Grant the new role to the new report. Paste the below text into the SQL box:select ID, ANIMALNAME, SHELTERLOCATIONUNIT, SHELTERLOCATION from animal a WHERE SHELTERLOCATION = '' and a.Archived = 0 and ActiveMovementID = '0'
and replace with the ID of the location as found in your location table. - NOTE that the above SQL may not work. You will need to ensure you have the correct column names as needed to locate your data. the above code is just an example and not guaranteed to work.
- Here you need to figure out the numerical location ID of the location found in ASM. If you click on SHELTER VIEW and then click on that specifc location, it will bring up the animals in that location. in the URL address bar, you will see the numerical value of that location ID after "shelterlocation". (eg. https://us000.sheltermanager.com/animal_find_results?logicallocation=onshelter&shelterlocation=123456)
- Take that number of your location and replace with the number found in the above SQL query a.ShelterLocation = 18. Replace the "1111" with your number.
- If you have more than one location that needs to be included in the report, then you are going to have to figure out how to get the report to include all the locationd and units you require.
- Now hit the SQL check button and then hit the button to generate the HTML. If no errors, click SAVE
- Check the report is working using the REPORTS menu. When the report opens in the browser, look at the URL address bar. the report ID number will be in the address. You will need that below. (eg. https://us000.sheltermanager.com/report?id=1234567890)
- Now on your pi or server, run this command:
nano /home/shelterMon/asm.json - Add the information the file is asking for and save then exit.
Account - your ASM account number
Username - the new user account you created above
Password - the passwrd for the new user account you created above
Title - the title of the report you created above. If the name has any spaces, replace the space character with + (eg "Spaces+are+Fun) - Now edit the .json config file for the location(s) you need to check against ASM.
nano /home/shelterMon/config.json - Towards the end of the file you will see these three fields. Edit them as needed, then save and exit.
checkASM -set this option to "yes" to enable checks against ASM
locationID - this is the numeric report ID of the report you created earlier.
locationUnit - this is the label/name of that unit found within the location in ASM. This is custom to what your org has labeled it in ASM, so be sure it matches exactly including whitespace characters. We use numbers for our units, but some are words. - Now you can do a test run of the script and check for errors. As long as the location's config file has the checkASM value enabled and the asm.json file has all the required info, it should run the check against ASM to look for occupancy.
Once you have that server running you may need to do some additional work on your network but if you're using a basic home router setup you should be fine. in this case I would recommend getting help from an IT nerd so you do it correctly. the ESP sensors will just use your local WIFI to send the temperature readings to an internet address instead of a local address. You would also have to open up the firewall to accept traffic from your source IP using the destination port 3333 or whatever you set that port to use.
Below is the example output of what the script does at our location. Quarantine shed #2 is occupied, but the others are not. All the sheds are checking against ASM for occupancy but the other locations are not because they are never empty.
root@server# python3 /home/shelterMon/shelterMon.py -C /home/shelterMon/
{"lastSeen":"1678240977","OKstatus":"1","duration":"0","lastTemp":"71.8","minsSinceLastLog":"0.1","locationName":"Cats Area","notifyMin":"0","diffChange":"0" }
{"lastSeen":"1678240980","OKstatus":"1","duration":"0","lastTemp":"70.2","minsSinceLastLog":"0.0","locationName":"Clinic room","notifyMin":"0","diffChange":"0" }
{"lastSeen":"1678240976","OKstatus":"1","duration":"0","lastTemp":"74.1","minsSinceLastLog":"0.1","locationName":"Clean Room","notifyMin":"0","diffChange":"0" }
{"lastSeen":"1678240979","OKstatus":"1","duration":"0","lastTemp":"77.2","minsSinceLastLog":"0.0","locationName":"Foster Room","notifyMin":"0","diffChange":"0" }
{"lastSeen":"1678240976","OKstatus":"1","duration":"0","lastTemp":"74.0","minsSinceLastLog":"0.1","locationName":"Dog Kennels","notifyMin":"0","diffChange":"0" }
Quarantine Room 1 is NOT occupied. Disabling.
config: /home/shelterMon/quaran1.json is disabled, skipping.
Quarantine Room 2 is occupied. Enabling.
{"lastSeen":"1678240979","OKstatus":"1","duration":"0","lastTemp":"73.2","minsSinceLastLog":"0.0","locationName":"Quarantine Room 2","notifyMin":"0","diffChange":"0" }
Quarantine Room 3 is NOT occupied. Disabling.
config: /home/shelterMon/quaran3.json is disabled, skipping.
Quarantine Room 4 is NOT occupied. Disabling.
config: /home/shelterMon/quaran4.json is disabled, skipping.