Build a Smart Letter Box with Push Notifications powered by Raspberry Pi Zero

Install a Raspberry Pi Zero and a magnetic contact switch on your letterbox, and get a push notification to your phone when the postman has been!

To build this project, you’ll need the following components:

• Raspberry Pi Zero W (ideally with a pre-soldered header)
• Mini HDMI lead or adaptor
• USB Hub to plug into the Zero’s microUSB port (for keyboard/mouse)
• Magnetic contact switch (door sensor)
• Long length of bell cable
• 2x DuPont cables (female/female)
• Long USB power lead for the Pi
• A smartphone or tablet
• A Google account (free)
• An IFTTT account (free)
• Glue Gun or other method of fixing
• Adhesive velcro strip (to mount the Pi Zero)

Check them all out in my KIT at: https://kit.co/paulfp/smart-letter-box !

Have you ever been eagerly waiting for an item of post to arrive and wished you could tell straight away if it has come yet? Maybe you’re out at work when the postie comes, or your letterbox is at the end of a really long driveway? Well, this is the project for you – I’ll show you how to rig up a tiny Raspberry Pi Zero and a sensor switch to send a push notification to your phone every time the flap is opened.

If you have any other “smart” devices in your house, you could easily expand this project to talk to those too. For example, you might want to turn on a smart WiFi light bulb for a couple of minutes a few seconds after the post arrives, to make your house look occupied whilst you’re away.

@paulfp

Before we get started I’m going to assume that you already have your Raspberry Pi Zero all set up with the latest version of Raspbian installed and up-to-date, and the date and time correctly set. You’ll also need a mini HDMI cable and a USB hub with a micro-USB connector in order to plug in a keyboard and mouse for the initial setup. (See the link to my Kit above.)

With that all ready, start by connecting up the magnetic switch to the numbered GPIO pin 18 and a ground pin – see the wiring diagram below for details. If you strip a short length from the ends of your bell wire, this should easily slot into the female DuPont cables for easy connecting to the GPIO pins. The other end is wired into the sensor switch. Wiring-wise, that’s all there is to it – it’s a very simple setup.

Connect the Pi to your home network either via WiFi or with a network cable, then enable SSH access (Pi menu – Preferences – Raspberry Pi configuration – interfaces – SSH) so you can access the Pi from another computer on your network later. Determine the Pi’s IP address on your home network by opening a Terminal and typing the following command:

 hostname -I 

It’s a good idea to set a static IP on your network (outside your router’s DHCP range) so that weeks later and after several reboots, your Pi will still be accessible via the same IP address.

@paulfp

Now that’s all set up you can start configuring the vital services required to make things work and talk to each other. This project works by adding a new row to a Google spreadsheet each time the magnetic switch is activated (ie. the letterbox is opened) along with the date and times that it was opened and closed. Another service then monitors this sheet and sends the alert to your phone whenever it sees that a new row’s been added.

Create a new Google Sheet and call it Letterbox Activations. Set up three columns as headings, then delete ALL OTHER CELLS so that your sheet looks like the picture above. This is important, as the Python script adds a brand new row to the bottom each time the letterbox is opened.

If This, Then That…

To monitor the Google spreadsheet and send push notifications to your phone, you will use a free service called If This Then That, at http://www.ifttt.com

If This, Then That is a free online platform that lets you join together your various apps and IoT devices. It can talk to lots of online services and smart devices as both trigger and action, and as the name suggests it allows you to specify that “if this happens, then do that…” Have a play and let your imagination run wild at http://www.ifttt.com

@paulfp

Sign up for If This Then That, if you don’t already have an account. Click on New Applet, then click on the big “+this” to add your “this…” scenario/trigger, which will be that new row getting added to your spreadsheet. Under services, search for Google Sheets and then select “New row added to spreadsheet” as the trigger.

After authorising access to your Google Drive, paste the full URL of your Google Sheet into the box and press Create Trigger (above). Now that the trigger is set up, you need to add the action. Click on the “+that” and search for the “Notifications” action service. Under “Choose action” select “Send a notification from the IFTTT app”.

The action fields allow you to customise the message that’s sent to your phone with each push notification. The message needs to say something like this, using the values which have been added to the spreadsheet:

The post arrived on {{ColumnA}} at {{ColumnB}}!

Click Create action, then review and Finish.

In order to receive the push notification you must have the IFTTT app installed on your phone, so open up the Google Play Store, install the IFTTT app and login with same account that you used to create the applet.

You can test it out by manually adding a new row to the spreadsheet, wait around a minute and a push notification should pop up on your phone!

Now that’s working, it’s time to make that happen automatically each time the letterbox opens.

Empower Your Python

The project uses a Python script which detects the letterbox activations and then uses the Google Sheets API to add a row to the spreadsheet. It needs to be authorised to edit the spreadsheet in your Google account, and to do this you first need to create an App on the Google Cloud Platform at https://console.cloud.google.com

Create a new app and give it a name. Next you need to enable both the Sheets and Drive APIs for your app: from your app’s dashboard, click “APIs & Services” in the left menu bar, and select “Library”. Search first for Drive and enable it and then do the same for Sheets. 

Next, click back to go to the APIs & Services dashboard and click the Credentials item on the left-hand menu. Here, click the “Create credentials” button and select “Service account key”. On the next screen “New service account” will be selected; give it a name such as “postman-log”. Under “role” select Project, then “Owner”, leave the key type as JSON and click Create.

This will create and download a credentials file to your computer. Save this to the Pi user’s home directory as service_file.json, or if you are doing this from another computer, use something like WinSCP to copy this JSON file to the Pi.

WinSCP and PuTTY are two very useful utilities for connecting to your Raspberry Pi (or any Linux machine). WinSCP for Windows gives you an easy tool for transferring files between your Windows machine and the Pi, and PuTTY allows you to run commands on it remotely, as if you were connected to the machine directly with a screen and keyboard. You can install the latest version of each from ninite.com – look under Developer Tools.

@paulfp

Now that your app on the Google Cloud Platform has the ability to work with Sheets in your Drive, it needs to be granted specific permission to the Letterbox Activations spreadsheet. Open up the JSON credentials file and look for the line which starts “client_email”: – after that will be a long email address. Copy the email address (without the quotes), return to your Google Spreadsheet and click the SHARE button in the top-right of the browser window. Paste the email address from before into the “People” field, ensure “Can edit” is selected and press the Send button. Press Yes to any “are you sure?” style warnings – this enables the app we’ve just created to make changes to the spreadsheet, which is what we want.

Next, use PuTTY to connect to your Pi from another computer on your network, using the IP address we determined earlier which will usually be something similar to 192.168.0.xxx.

By default the username:password combination to login to your Pi is pi:raspberry but you ought to change that to something else for security reasons, especially with SSH enabled.

@paulfp

The project uses the pygsheets library to make working with Google Sheets easier. Install pygsheets with the following command:

pip install https://github.com/nithinmurali/pygsheets/archive/master.zip

To authenticate with the Google Sheets API the script uses OAuth 2, so be sure the oauth2client is installed on your system by typing:

pip install --upgrade oauth2client 

Once that’s done you’re ready to install the main Python script from my GitHub:

git clone https://github.com/paulfp/Letterbox-Push-Notification.git

This will download the script into a new directory called “Letterbox-Push-Notification” within the pi user’s home directory. Make sure the magnetic sensor is in the “closed” state, and you can now run this Python script like this:

cd ~/Letterbox-Push-Notification
python letterbox.py

When you first run the script there will be a brief pause whilst it connects to Google; once done you’ll see “Letterbox is closed” printed to the terminal. Test it out by moving the magnet away from the switch and back again. When you do this, you will see “Letterbox has been opened!” and “Letterbox is closed.” printed to the terminal window along with the date and time of each action, and if you watch your Google Sheet whilst you do it you’ll also see a new row being added and then populated.

Due to the IFTTT applet you made, within about a minute a push notification from the IFTTT app should pop up on your phone. You can even press the notification to open up the spreadsheet and see full details, including when the letterbox was closed again.

Depending on how Sherlock-Holmes you want to get, you could determine that more than a second or two between open and close might signify that either more letters were being delivered, or something larger was being stuffed through your postbox.

@paulfp

Finally, set the script to auto-run each time the Pi loads so that it’ll work once installed on your letterbox without needing to hook up a display keyboard. To do this, edit the Pi’s autostart configuration file:

 sudo nano ~/.config/lxsession/LXDE-pi/autostart 

Add this line at the end of the file:

 @python /home/pi/Letterbox-Push-Notification/letterbox.py 

You could install this on anything which has an open/close mechanism – a cat flap, for example, to track your feline’s movements, or maybe a child’s bedroom door if they have a habit of sleepwalking…

@paulfp

Now that everything’s working it’s time to install the system on your letterbox. Depending on the exact design of your letterbox you may need to adjust how you fit yours, and experiment a bit with the placement of the magnet to ensure that the system correctly registers as open/closed when the letterbox is in either of these states. A nice long length of bell wire as well as a long USB power lead should ensure that you can locate the Pi Zero nicely out of the way and keep the whole installation neat and tidy.

Now you know how to hack your letterbox, what are you going to set to happen when your post arrives? I’d love to see what this inspires you to make – get in touch via Twitter (I’m @paulfp) or Instagram (I’m @paulfp there too) to show off your creations!

HackSpace Magazine

This tutorial was originally published in Issue #10 of HackSpace magazine. You can download a FREE PDF of the magazine here: https://hackspace.raspberrypi.org/issues/10