Go to file
Marvin Johanning 38dcfb2786 Add license text 2018-07-12 11:37:08 +02:00
lib Initial commit 2018-07-10 22:27:15 +02:00
src Add license text 2018-07-12 11:37:08 +02:00
.gitignore Add license text 2018-07-12 11:37:08 +02:00
.travis.yml Initial commit 2018-07-10 22:27:15 +02:00
LICENSE Add LICENSE 2018-07-10 20:31:39 +00:00
README.md Update README, remove comment from start file 2018-07-12 11:21:29 +02:00
platformio.ini Initial commit 2018-07-10 22:27:15 +02:00
start Add license text 2018-07-12 11:37:08 +02:00


Gmail Notifier


DISCLAIMER: I cannot made responsible for any damage caused to your Arduino, yourself or any other of your possessions. I have tested this program myself, however, I cannot guarantee that it will work with you and I also cannot guarantee that it will not break. Use at your own risk!

What is this?

Gmail Notifier is a simple little program that you can use with your Arduino, an LCD and an active buzzer that will notify you of a new email and will display the email's subject on the LCD connected to the Arduino.

Prerequisites and Installation

The very first thing you should do is downloading this repository which you can simply do by clicking the Download button at the top of this repository's page. Save and extract it into a folder of your liking.


In this section I will be talking about what software components you will be needing and how to install them properly. NOTE: The only supported operating systems are those based on Linux and trying to run it on a different operating system will almost definitely not work.


Firstly, you need to install Ruby. Ruby is an easy to use programming language that might already be installed on your computer. To check whether it is installed, type ruby -v into your Terminal upon which you should get information about the version of your current Ruby installation.
If, however, you get an error, please install Ruby — preferably the version that I am using myself, 2.5.1. For further information on how to install Ruby on your operating system, please refer to the official website: https://www.ruby-lang.org/en/documentation/installation/

Ruby gems

Secondly, running this program requires you to install a few so-called gems. These are basically the extensions of Ruby and add a lot of functionality. In this case, the gems that you need to install are the following:

  • serialport (for sending data to the serial port in order for the Arduino to read it)
  • gmail (for receiving email from your Gmail account)
  • colorize (for displaying coloured text in the terminal — used only for error messages)
  • socket (for testing your internet connection)

Installing gems is fairly easy and straightforward. Simply type (sudo) gem install gem_name_here into your terminal and the gem should start installing. Please note that some Ruby installations require you to be root to install gems. If that is the case, please add the sudo before the command.


Thirdly, you need an IDE that is capable of uploading code to your Arduino. The most commonly used one being the official Arduino IDE that can be downloaded from their website. I personally used the PlatformIO IDE which is however more difficult to install for beginners. Therefore, I recommend by starting with the official Arduino IDE.

Arduino Library

Fourthly and lastly, you also need to download the LiquidCrystal library from here. The main purpose of this library is to be able to easily control LCDs. For further information on how to install libraries for your Arduino, please visit refer to the official guide.

Uploading to the Arduino

After having downloaded and installed the library and the IDE, first you need to connect the Arduino to your computer. After having done so, please open the Arduino IDE. Afterwards, click the Tools tab. A small window should open in which there are two options you need to be concerned about: Board and Port. In the Board section, please select the board that you are using and in the Port section you need to select the port that the Arduino is connected to (usually it tell you which one that is). Thereafter you need to upload the sketch (the program) located in src/main.cpp to your Arduino. To do so, press Ctrl-O and find the folder you extracted the repository into and open it. Once the sketch can be seen in the IDE's window, press Ctrl-U to upload it to your Arduino.


As mentioned previously, you also require some hardware to be able to run this program properly. In the following section I will explain what hardware you need, what specific hardware I use and how to connect said hardware correctly to your Arduino. Please note that your hardware will most likely not be the exact same as mine and therefore you might experience unintended issues. Should you be certain to have connected everything correctly without the program working, please file an Issue on this repository.


The most important hardware component you will be needing is obviously an Arduino. I believe that most Arduinos should work with this program, but I cannot be entirely sure. Therefore, the only officially supported Arduino for this is the Arduino Uno. If you tried this program on any other Arduino and it worked, please contact me and I will add it to the list of supported devices. However, I am not sure you will be able to connect the hardware with an Arduino that only supports 3.3V.


Another important component is obviously the LCD. In order for this program to function properly, please use an LCD with 16 columns and 2 rows. Using an LCD with fewer or more columns and rows will most likely result in weird glitches or it might not work at all. These generally have 14 or 16 pins — The latter is back-lit, the former is not — of which you only need to worry about 10 (or 12 in case of an LCD with back-light). I am using the LCD 1602 Module. Please connect the pins as follows:

LCD Arduino
V0 10kΩ potentiometer (which itself still needs to be connected to 5V and GND)
RS Pin 7
E Pin 8
D4 - D7 Pin 9 - 12

If you have a back-lit screen, you might also have to connect two more pins to GND and 5V (these are named A for 5V and K for GND in my case). Furthermore, your LCDs pins might be named differently. In that case, please refer to your LCDs data sheet (just looking for the model number on your preferred search engine should yield results pretty quickly). The back-light also might have to be connected to a 220Ω resistor through 5V instead of going directly to 5V.

Active buzzer

Another component is the active buzzer. It will make a sound whenever you receive an emails to notify you. The one I am using is the TMB12A05. Connected the negative side of the buzzer to GND and the positive side (which is usually marked by having a longer lead) to your Arduino's Pin 2.

Setting up the software to work with your Gmail account

Having done everything mentioned in the previous sections, it is now time to set up the program to work with your Gmail account. To do so, open the src/gmail_login_information.rb file with your preferred text editor and enter your Gmail username and your password into the appropriate variables.

NOTE: If you're using two-factor authentication (which I highly recommend you do), you will need to create an app password which you can then use as your password for GmailNotifier.

Starting the program

After completing all the steps listed above, it is time to start the Ruby program on your computer. Firstly, please check whether your Arduino is correctly connected to your computer (if the buzzer beeps and the LCD displays some text upon connecting it to your PC, don't be alarmed. I'm not quite sure why this happens, but it goes away after a few seconds and it doesn't seem to impact the program at all).
After you ensured that the Arduino is connected properly to your computer, open the directory you've extracted this repository into and start the start file by typing ./start or ruby start into your Terminal while being in the directory. The program now checks for an active internet connection, checks whether it can connect to your Gmail account and it will automatically determine what serial port your Arduino is connected to.