# Perouz' Secret Santa Present Instructions

Belated hohoho! :smiley:

Here's everything you need to know about your secret santa present.

It's a little thingy that checks your Gmail every half hour or so and simply turns on a light if there's new mails. If you press the big top button (the envelop), the light turns off - basically, you can shush it.

I've built the whole thing from scratch (code, electronics, box) and everything is open-source. If you have privacy concerns, I'm linking the code and materials at the end.

## 0 - Preamble

- You can theoretically open the box (by removing the top) but I'd advise not to do that since there's some glue on it to hold it in place. I'm including the wiring diagram and source code below so you can check what's in the box without breaking anything
- The box is not particularly waterproof. It can be submersed only once.
- The lil box needs power from a microUSB power outlet. Literally any one will do. This can be a computer or a wall plug. 5V at 500mA are great but 5V/100mA will work too. I didn't include a cable because I'm sure you have a million of these at home.
- You can put this lil box anywhere you feel, as long as it's in reach of your wifi network.
- And speaking of which, it only works with a 2.4GHz network and WPA1/2 security. Most modern routers have both a 2.4 and 5GHz net, so see if you can enable that if it's not already turned on.
- It currently only works in wifi networks with WPA2-Private security. If you want to use it in an WPA2-Enterprise environment, let me know and I can probably modify the code. Could be a bit finicky though.
- Don't push the LED inwards. The only button this has is the big thing with the envelope at the top.
- Don't shake the lil box too much. I didn't glue the wires inside and stuff might get rearranged if shaken too harshly.

## 1 - Create an application-specific password for Gmail

In order for the lil box to fetch your mails (corporate or private), it needs to know your Gmail credentials. I assume that you have 2-factor authentication turned on, so you need to create an application-specific password. There's a nice visual tutorial over here: https://www.lifewire.com/get-a-password-to-access-gmail-by-pop-imap-2-1171882

Here's the gist of it:
1. Go to https://myaccount.google.com/security and click on **"App passwords"** in the section **"Signing in to Google"**
2. The page should look something like this. At the bottom, first select **"Mail"** and then **"Other"** and call it whatever you like (e.g. "lil-box"). Finally click on **"GENERATE"**.


3. Now you should see a popup with your shiny new password. The next step is to convert that password into a hash that we can enter on the Gmail notifier
4. On a terminal issue the following command `echo -n "YOUR_GMAIL_ADDRESS:YOUR_NEW_PASSWORD" | base64` (important: don't forget the colon between email and password) and note the output. That's going to be your **Gmail login**

## 2 - Initial Setup

There are a few steps to setting this up but bear with me - you only have to do this once.

1. Power up the lil box via MicroUSB
2. The LED should light up once for half a second to indicate powering up.
2. After 2-3 seconds, a new wifi network appears that's called **`Gmail-Notifier Setup`**
3. Connect to this network. The password is **`ladeeda123%`**


4. Your phone/laptop will probably tell you that this network needs signing in or something (like in the screenshot). If you get a notification like this, click on it to go to the configuration website. If it doesn't say anything like that, open your browser and go to `http://192.168.4.1`
5. The configuration website should look like this and you should click/tap "Configure WiFi"


6. On the next page, you will see all wifi networks in your area (after a second or two of scannig). Should look like this (safe for the fact that you probably have different networks around you):


7. First, click on your home network (A).
8. Now the name of your home network should appear in the SSID field at (B). Enter the wifi password below in the corresponding box.
9. Enter the Gmail login from the previous section into the corresponding field (C).
10. Leave the other two fields (D) and (E) as-is for now.
11. Hit "Save"/"Submit" and you should be good to go.
12. If the lil box successfully connected to your wifi, then the LED should blink twice and the `Gmail-Notifier Setup` network should disappear. If it didn't work, then the network should pop up again after a few seconds.

## 3 - How to use

- When the lil box is powered on, it blinks once.
- When it connects to your wifi successfully, it blinks twice (this only happens 5-15s after powering on).
- If you receive a new email, the LED permanently turns on (to let you know).
- If you press & release the big top button, the LED turns off it was on.

That's all there is to it :grin:.

## 4 - Troubleshooting

> How do I **factory-reset** this, i.e. how do I get back to this setup screen after I've set it up once?

Unplug the lil box, press and hold the big button, plug the power back in. Continue holding the button until the LED flashes 3 times quickly. Now it's reset and your should see the `Gmail-Notifier Setup` wifi network again.

> You input your wifi network's credentials but it can't connect to it.

Make sure you spelled the password correctly and make sure the wifi network indeed uses WPA1 or WPA2-Private security, not WPA2-Enterprise or 802.1x. Worst case try with your phone as hotspot with a really simple password.

> You input your gmail credentials and the lil box connected to wifi (double-blinks after powerin on but the light never turns on despite having new emails).

You probably made some mistake entering the gmail credentials. I'd recommend factory reset and entering your gmail credentials again.

> I wanna change the refresh rate to [every second | every minute | every hour | ...]. How do I do that?

Start by doing a factory reset and then in the setup screen where you insert your Gmail credentials, in the field labeled (E) in the screenshot above, input a number. This number is the refresh timer in seconds. The default is 30min, which is 1800 seconds.

> It worked for a bit but now it doesn't work anymore. What do?

2 options: (a) the LED burned out... shit happens. I can replace it no probs. Or, more likely, (b) the Gmail login server changed its SHA-1 fingerprint. This happens maybe once a year or two but it can happen more often than that if they do a lot of maintenance. We need the fingerprint of the Gmail server to ensure a secure connection and not fall victim to some man-in-the-middle attack. In order to check this, issue this command on a terminal: `openssl s_client -connect mail.google.com:443 < /dev/null 2>/dev/null | openssl x509 -fingerprint -noout -in /dev/stdin | sed 's/:/ /g'`. This should print out the current fingerprint. Here's the default one that I'm using for comparison:

D1 AF BF FE 4D D7 E0 F6 A8 38 A6 49 05 8F E9 82 07 FE 19 A0

If this is different from what you're getting, you might want to update the fingerprint that the lil box is using. To do that, factory-reset the box, then on the setup screen where you insert the Gmail credentials, in the field labeled (D) in the screenshot above, change the fingerprint to whatever you're currently getting. It should have the same length and the same format.

## 5 - Source Code

The github repo is here:

https://github.com/fgolemo/gmail-notifier

The source code is here: https://github.com/fgolemo/gmail-notifier/blob/main/src/main.cpp

The electronics are here: https://github.com/fgolemo/gmail-notifier/tree/main/_hardware/_wiring

The 3D models are here: https://github.com/fgolemo/gmail-notifier/tree/main/_hardware/_3dmodels