# MagTag IoT Menorah
## Overview
Every year for Hanukkah, you light a candle every night for 8 days. Often about halfway through the holiday though, you may find yourself losing count of the nights. You may also live in a space where you can't light a candle, like a dorm room or an apartment. This project helps you with all of these problems by making the menorah digital and keeping time with the internet.
Every day, the MagTag fetches the date and time, compares it to the start date of Hanukkah and updates the menorah graphic accordingly. It's also a low power project, taking advantage of deep sleep on the ESP32-S2, so you can keep it battery powered on your desk throughout the season.
The menorah graphic was designed by [Noe Ruiz](https://learn.adafruit.com/u/pixil3d). Each flame on the candles is covered by a circle in the CircuitPython code. As the candles are "lit", the circles are made transparent to reveal the flames.
## 3D Printed Case
You can [3D print](https://learn.adafruit.com/magtag-case/cad-files) or [purchase the Adafruit MagTag case](https://www.adafruit.com/product/6433) from the shop. The case features a kick stand and space for a battery inside.
### MagTag Case - CAD Files
[MagTag Case](https://learn.adafruit.com/magtag-case)
[CAD Files](https://learn.adafruit.com/magtag-case/cad-files)
## Parts
Featured
### Adafruit MagTag - 2.9" Grayscale E-Ink WiFi Display
[Adafruit MagTag - 2.9" Grayscale E-Ink WiFi Display](https://www.adafruit.com/product/4800)
The Adafruit MagTag combines the ESP32-S2 wireless module and a 2.9" grayscale E-Ink display to make a low-power IoT display that can show data on its screen even when power is removed! The ESP32-S2 is great because it builds on the years of code and support for the ESP32 and also adds...
In Stock
[Buy Now](https://www.adafruit.com/product/4800)
[Related Guides to the Product](https://learn.adafruit.com/products/4800/guides)
Featured
### Lithium Ion Polymer Battery - 3.7v 500mAh
[Lithium Ion Polymer Battery - 3.7v 500mAh](https://www.adafruit.com/product/1578)
Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery has a capacity of 500mAh for a total of about 1.9 Wh. If you need a larger (or smaller!) battery,
In Stock
[Buy Now](https://www.adafruit.com/product/1578)
[Related Guides to the Product](https://learn.adafruit.com/products/1578/guides)
Featured
### Adafruit MagTag Enclosure & Buttons Kit
[Adafruit MagTag Enclosure & Buttons Kit](https://www.adafruit.com/product/6433)
Here is a cool and minimal enclosure for your [MagTag](https://www.adafruit.com/product/4800) to keep it safe during use and transport. This case has been custom-designed and 3D printed to accommodate all connection ports of the MagTag. No screws or...
In Stock
[Buy Now](https://www.adafruit.com/product/6433)
[Related Guides to the Product](https://learn.adafruit.com/products/6433/guides)
Featured
### Mini Magnet Feet for RGB LED Matrices (Pack of 4)
[Mini Magnet Feet for RGB LED Matrices (Pack of 4)](https://www.adafruit.com/product/4631)
Got a glorious RGB Matrix project you want to mount and display in your workspace or home? If you have one of the matrix panels listed below, you'll need a pack of these **Mini-Magnet Feet.** We got these specifically for our RGB LED Matrices, which no longer...
In Stock
[Buy Now](https://www.adafruit.com/product/4631)
[Related Guides to the Product](https://learn.adafruit.com/products/4631/guides)
Featured
### Black Nylon Machine Screw and Stand-off Set – M3 Thread
[Black Nylon Machine Screw and Stand-off Set – M3 Thread](https://www.adafruit.com/product/4685)
Totaling **420 pieces** , this **M3 Screw Set** is a must-have for your workstation. You'll have enough screws, nuts, and hex standoffs to fuel your maker tendencies for days on end! M3 size screws fit a number of Adafruit breakout/dev board...
In Stock
[Buy Now](https://www.adafruit.com/product/4685)
[Related Guides to the Product](https://learn.adafruit.com/products/4685/guides)
Featured
### USB Type A to Type C Cable - approx 1 meter / 3 ft long
[USB Type A to Type C Cable - approx 1 meter / 3 ft long](https://www.adafruit.com/product/4474)
As technology changes and adapts, so does Adafruit. This **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop.
USB C is the latest industry-standard connector for...
In Stock
[Buy Now](https://www.adafruit.com/product/4474)
[Related Guides to the Product](https://learn.adafruit.com/products/4474/guides)
# MagTag IoT Menorah
## Install CircuitPython
Danger: Make sure that you [update the TinyUF2 Bootloader](https://learn.adafruit.com/adafruit-magtag/update-tinyuf2-bootloader-for-circuitpython-10-4mb-boards-only) before installing CircuitPython!
### Adafruit MagTag - Update TinyUF2 Bootloader for CircuitPython 10 and Later
[Adafruit MagTag](https://learn.adafruit.com/adafruit-magtag)
[Update TinyUF2 Bootloader for CircuitPython 10 and Later](https://learn.adafruit.com/adafruit-magtag/update-tinyuf2-bootloader-for-circuitpython-10-4mb-boards-only)
[CircuitPython](https://github.com/adafruit/circuitpython) is a derivative of [MicroPython](https://micropython.org) designed to simplify experimentation and education on low-cost microcontrollers. It makes it easier than ever to get prototyping by requiring no upfront desktop software downloads. Simply copy and edit files on the **CIRCUITPY** drive to iterate.
## Set Up CircuitPython
Follow the steps to get CircuitPython installed on your MagTag.
[CircuitPython Download for MagTag](https://circuitpython.org/board/adafruit_magtag_2.9_grayscale/)
Warning: WARNING: The updated Adafruit MagTag 2025 Edition will not work with CircuitPython 9.2.x or earlier. Make sure you install 10.x.x or later!
**Click the link above and download the latest .BIN and .UF2 file**
You can use a 9.x.x release for a pre-2025 MagTag. You **must** use a 10.x.x release for the updated MagTag 2025 Edition.
(depending on how you program the ESP32S2 board you may need one or the other, might as well get both)
Download and save it to your desktop (or wherever is handy).
Plug your MagTag into your computer using a known-good USB cable.
**A lot of people end up using charge-only USB cables and it is very frustrating! So make sure you have a USB cable you know is good for data sync.**
# Option 1 - Load with UF2 Bootloader
This is by far the easiest way to load CircuitPython. **However it requires your board has the UF2 bootloader installed. Some early boards do not (we hadn't written UF2 yet!) - in which case you can load using the built in ROM bootloader.**
Still, try this first!
Warning: Make sure that you [update the TinyUF2 Bootloader](https://learn.adafruit.com/adafruit-magtag/update-tinyuf2-bootloader-for-circuitpython-10-4mb-boards-only) before following these steps for the UF2 bootloader!
## Try Launching UF2 Bootloader
Loading CircuitPython by drag-n-drop UF2 bootloader is the easier way and we recommend it. If you have a MagTag where the front of the board is black, your MagTag came with UF2 already on it.
Launch UF2 by **double-clicking** the Reset button (the one next to the USB C port). You may have to try a few times to get the timing right.
If the UF2 bootloader is installed, you will see a new disk drive appear called **MAGTAGBOOT**
Copy the **UF2** file you downloaded at the first step of this tutorial onto the **MAGTAGBOOT** drive
If you're using Windows and you get an error at the end of the file copy that says **Error from the file copy, Error 0x800701B1: A device which does not exist was specified.** You can ignore this error, the bootloader sometimes disconnects without telling Windows, the install completed just fine and you can continue.[If its really annoying, you can also upgrade the bootloader (the latest version of the UF2 bootloader fixes this warning)](https://learn.adafruit.com/adafruit-magtag/install-uf2-bootloader)
Your board should auto-reset into CircuitPython, or you may need to press reset. A **CIRCUITPY** drive will appear. You're done! Go to the next pages.
# Option 2 - Use esptool to load BIN file
If you have an original MagTag with while soldermask on the front, we didn't have UF2 written for the ESP32S2 yet so it will not come with the UF2 bootloader.
You can upload with **esptool** to the ROM (hardware) bootloader instead!
Follow the initial steps found in the [Run esptool and check connection section of the ROM Bootloader page](https://learn.adafruit.com/adafruit-magtag/rom-bootloader#run-esptool-and-check-connection-3076823-5) to verify your environment is set up, your board is successfully connected, and which port it's using.
**In the final command to write a binary file to the board, replace the port with your port, and replace "firmware.bin" with the the file you downloaded above.**
The output should look something like the output in the image.
Press reset to exit the bootloader.
Your **CIRCUITPY** drive should appear!
You're all set! Go to the next pages.
# Option 3 - Use Chrome Browser To Upload BIN file
If for some reason you cannot get esptool to run, you can always try using the Chrome-browser version of esptool we have written. This is handy if you don't have Python on your computer, or something is really weird with your setup that makes esptool not run (which happens sometimes and isn't worth debugging!) You can follow along on the [Web Serial ESPTool](https://learn.adafruit.com/adafruit-magtag/web-serial-esptool) page and either load the UF2 bootloader and then come back to Option 1 on this page, or you can download the CircuitPython BIN file directly using the tool in the same manner as the bootloader.
# MagTag IoT Menorah
## Create Your settings.toml File
CircuitPython works with WiFi-capable boards to enable you to make projects that have network connectivity. This means working with various passwords and API keys. As of [CircuitPython 8](https://circuitpython.org/downloads), there is support for a **settings.toml** file. This is a file that is stored on your **CIRCUITPY** drive, that contains all of your secret network information, such as your SSID, SSID password and any API keys for IoT services. It is designed to separate your sensitive information from your **code.py** file so you are able to share your code without sharing your credentials.
CircuitPython previously used a **secrets.py** file for this purpose. The **settings.toml** file is quite similar.
Warning: Your **settings.toml** file should be stored in the main directory of your **CIRCUITPY** drive. It should not be in a folder.
## CircuitPython **settings.toml** File
This section will provide a couple of examples of what your **settings.toml** file should look like, specifically for CircuitPython WiFi projects in general.
The most minimal **settings.toml** file must contain your WiFi SSID and password, as that is the minimum required to connect to WiFi. Copy this example, paste it into your **settings.toml** , and update:
- `your_wifi_ssid`
- `your_wifi_password`
```auto
CIRCUITPY_WIFI_SSID = "your_wifi_ssid"
CIRCUITPY_WIFI_PASSWORD = "your_wifi_password"
```
Many CircuitPython network-connected projects on the Adafruit Learn System involve using Adafruit IO. For these projects, you must _also_ include your Adafruit IO username and key. Copy the following example, paste it into your settings.toml file, and update:
- `your_wifi_ssid`
- `your_wifi_password`
- `your_aio_username`
- `your_aio_key`
```auto
CIRCUITPY_WIFI_SSID = "your_wifi_ssid"
CIRCUITPY_WIFI_PASSWORD = "your_wifi_password"
ADAFRUIT_AIO_USERNAME = "your_aio_username"
ADAFRUIT_AIO_KEY = "your_aio_key"
```
Some projects use different variable names for the entries in the **settings.toml** file. For example, a project might use `ADAFRUIT_AIO_ID` in the place of `ADAFRUIT_AIO_USERNAME`. **If you run into connectivity issues, one of the first things to check is that the names in the settings.toml file match the names in the code.**
Warning: Not every project uses the same variable name for each entry in the **settings.toml** file! Always verify it matches the code.
## **settings.toml** File Tips
Here is an example **settings.toml** file.
```auto
# Comments are supported
CIRCUITPY_WIFI_SSID = "guest wifi"
CIRCUITPY_WIFI_PASSWORD = "guessable"
CIRCUITPY_WEB_API_PORT = 80
CIRCUITPY_WEB_API_PASSWORD = "passw0rd"
test_variable = "this is a test"
thumbs_up = "\U0001f44d"
```
In a **settings.toml** file, it's important to keep these factors in mind:
- Strings are wrapped in double quotes; ex: `"your-string-here"`
- Integers are _ **not** _ quoted and may be written in decimal with optional sign (`+1`, `-1`, `1000`) or hexadecimal (`0xabcd`).
- Floats (decimal numbers), octal (`0o567`) and binary (`0b11011`) are not supported.
- Use `\u` escapes for weird characters, `\x` and `\ooo` escapes are not available in **.toml** files
- Example: `\U0001f44d` for 👍 (thumbs up emoji) and `\u20ac` for € (EUR sign)
- Unicode emoji, and non-ASCII characters, stand for themselves as long as you're careful to save in "UTF-8 without BOM" format
When your **settings.toml ** file is ready, you can save it in your text editor with the **.toml** extension.
## Accessing Your **settings.toml** Information in **code.py**
In your **code.py** file, you'll need to `import` the `os` library to access the **settings.toml** file. Your settings are accessed with the `os.getenv()` function. You'll pass your settings entry to the function to import it into the **code.py** file.
```python
import os
print(os.getenv("test_variable"))
```
In the upcoming CircuitPython WiFi examples, you'll see how the **settings.toml ** file is used for connecting to your SSID and accessing your API keys.
# MagTag IoT Menorah
## Code the Menorah
Once you've finished setting up your MagTag with CircuitPython, you can access the code and necessary libraries by downloading the Project Bundle.
To do this, click on the **Download Project Bundle** button in the window below. It will download to your computer as a zipped folder.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/MagTag/MagTag_IoT_Menorah/code.py
## Upload the Code and Libraries to the MagTag
After downloading the Project Bundle, plug your MagTag into the computer's USB port with a known good USB data+power cable. You should see a new flash drive appear in the computer's File Explorer or Finder (depending on your operating system) called **CIRCUITPY**. Unzip the folder and copy the following items to the MagTag's **CIRCUITPY** drive.
- **lib** folder
- **code.py**
- **magtag\_menorah.bmp**
Your MagTag **CIRCUITPY** drive should look like this after copying the **lib** folder, bitmap image file and the **code.py** file.
## Add Your **settings.toml** File
As of CircuitPython 8.0.0, there is support for [Environment Variables](https://docs.circuitpython.org/en/latest/docs/environment.html). Environment variables are stored in a **settings.toml** file. Similar to **secrets.py** , the **settings.toml** file separates your sensitive information from your main **code.py** file. Add your **settings.toml** file as described in the [Create Your settings.toml File page](https://learn.adafruit.com/moon-phase-guide/create-your-settings-toml-file) earlier in this guide. You'll need to include values for your `CIRCUITPY_WIFI_SSID` and `CIRCUITPY_WIFI_PASSWORD`.
```python
CIRCUITPY_WIFI_SSID = "your-ssid-here"
CIRCUITPY_WIFI_PASSWORD = "your-ssid-password-here"
```
# MagTag IoT Menorah
## Assembly
## Install Buttons
Hold the top half of the enclosure face side down and place the four buttons into the holes. Then set it aside.
## Install Battery (Optional)
Connect the optional 500mAh lipo battery to the MagTag. Use a piece of double-sided tap or mounting tack to keep the battery adhered to the MagTag's PCB.
## Install MagTag
Get the bottom half of the enclosure and four M3 x 6mm long nylon screws.
Orient the MagTag with the bottom half of the enclosure. Place the MagTag into the bottom with the mounting holes lined up.
## Secure MagTag
Flip the MagTag and bottom part and fasten the M3 screws into the four mounting holes.
## Install Switch
Place the switch into the slot near the MagTag's on/off switch. The actuator of the on/off switch should fit in between the two nubs.
## Join Top and Bottom
Orient the top and bottom half of the enclosure parts so they orient. While holding the switch in place, begin joining the two halves together making sure the four buttons stay in place.
Firmly join the two halves together until they snap fit closed.
## Kickstand
To use the kickstand, locate the notch on the back side. To pop out the stand, fit your fingernail under the ridge of the stand and pull it out.
The stand can be stowed away by snaping it into the back side of the enclosure.
## Assembled Case
The assembled case is ready to prop on your desk, or stick to your refrigerator or other metal surface using the magnetic feet.
# MagTag IoT Menorah
## Use
At the top of the code are a few user parameters you'll want to update. `lat` and `long` are for your latitude and longitude location. This is used with the Open-Meteo API to fetch the sunset time for your location. `tz_offset` is your GMT timezone offset as an integer (examples: -5 for New York, 9 for Tokyo, Japan). Finally, `hanukkah_date` carries the month and date for the first day of Hanukkah.
```python
# latitude
lat = 42.36
# longitude
long = -71.06
# timezone offset from GMT
tz_offset = -5
hanukkah_date = [12, 14] # month, date
```
After updating these values, you can run the code on your MagTag. The project utilizes deep sleep, so you can power it with a battery.
On wake, the MagTag fetches the date and time from the internet. It checks if the date is coinciding with Hanukkah based on the date at the top of the code. This determines how many candles will be lit. The sunset time is fetched and compared to the current time. If it's after sunset, the next candle is lit. Then, the MagTag goes back into deep sleep until sunset the next day.
## Guide Products
### Adafruit MagTag - 2.9" Grayscale E-Ink WiFi Display
[Adafruit MagTag - 2.9" Grayscale E-Ink WiFi Display](https://www.adafruit.com/product/4800)
The Adafruit MagTag combines the ESP32-S2 wireless module and a 2.9" grayscale E-Ink display to make a low-power IoT display that can show data on its screen even when power is removed! The ESP32-S2 is great because it builds on the years of code and support for the ESP32 and also adds...
In Stock
[Buy Now](https://www.adafruit.com/product/4800)
[Related Guides to the Product](https://learn.adafruit.com/products/4800/guides)
### Lithium Ion Polymer Battery - 3.7v 500mAh
[Lithium Ion Polymer Battery - 3.7v 500mAh](https://www.adafruit.com/product/1578)
Lithium-ion polymer (also known as 'lipo' or 'lipoly') batteries are thin, light, and powerful. The output ranges from 4.2V when completely charged to 3.7V. This battery has a capacity of 500mAh for a total of about 1.9 Wh. If you need a larger (or smaller!) battery,
In Stock
[Buy Now](https://www.adafruit.com/product/1578)
[Related Guides to the Product](https://learn.adafruit.com/products/1578/guides)
### Adafruit MagTag Enclosure & Buttons Kit
[Adafruit MagTag Enclosure & Buttons Kit](https://www.adafruit.com/product/6433)
Here is a cool and minimal enclosure for your [MagTag](https://www.adafruit.com/product/4800) to keep it safe during use and transport. This case has been custom-designed and 3D printed to accommodate all connection ports of the MagTag. No screws or...
In Stock
[Buy Now](https://www.adafruit.com/product/6433)
[Related Guides to the Product](https://learn.adafruit.com/products/6433/guides)
### Mini Magnet Feet for RGB LED Matrices (Pack of 4)
[Mini Magnet Feet for RGB LED Matrices (Pack of 4)](https://www.adafruit.com/product/4631)
Got a glorious RGB Matrix project you want to mount and display in your workspace or home? If you have one of the matrix panels listed below, you'll need a pack of these **Mini-Magnet Feet.** We got these specifically for our RGB LED Matrices, which no longer...
In Stock
[Buy Now](https://www.adafruit.com/product/4631)
[Related Guides to the Product](https://learn.adafruit.com/products/4631/guides)
### Black Nylon Machine Screw and Stand-off Set – M3 Thread
[Black Nylon Machine Screw and Stand-off Set – M3 Thread](https://www.adafruit.com/product/4685)
Totaling **420 pieces** , this **M3 Screw Set** is a must-have for your workstation. You'll have enough screws, nuts, and hex standoffs to fuel your maker tendencies for days on end! M3 size screws fit a number of Adafruit breakout/dev board...
In Stock
[Buy Now](https://www.adafruit.com/product/4685)
[Related Guides to the Product](https://learn.adafruit.com/products/4685/guides)
### USB Type A to Type C Cable - approx 1 meter / 3 ft long
[USB Type A to Type C Cable - approx 1 meter / 3 ft long](https://www.adafruit.com/product/4474)
As technology changes and adapts, so does Adafruit. This **USB Type A to Type C** cable will help you with the transition to USB C, even if you're still totin' around a USB Type A hub, computer or laptop.
USB C is the latest industry-standard connector for...
In Stock
[Buy Now](https://www.adafruit.com/product/4474)
[Related Guides to the Product](https://learn.adafruit.com/products/4474/guides)
## Related Guides
- [Adafruit MagTag](https://learn.adafruit.com/adafruit-magtag.md)
- [Glowy Message Crown](https://learn.adafruit.com/glowy-message-crown.md)
- [IOT IR Remote using Raspberry Pi Zero W and QtPy Hat](https://learn.adafruit.com/iot-ir-remote-using-raspberry-pi-zero-w-and-qtpy-hat.md)
- [CircuitPython USB VID/PID Reporter](https://learn.adafruit.com/circuitpython-usb-vid-pid-reporter.md)
- [Circle of Fifths Euclidean Synth with synthio and CircuitPython](https://learn.adafruit.com/circle-of-fifths-euclidean-synth-with-synthio-and-circuitpython.md)
- [MIDI Foot Pedal](https://learn.adafruit.com/midi-foot-pedal.md)
- [Light-Up Costumes in Harsh Environments](https://learn.adafruit.com/light-up-costumes-in-harsh-environments.md)
- [No-Code DS18B20 Temperature Sensor with WipperSnapper](https://learn.adafruit.com/using-ds18b20-temperature-sensor-with-wippersnapper.md)
- [Capturing Camera Images with CircuitPython](https://learn.adafruit.com/capturing-camera-images-with-circuitpython.md)
- [Track a Turtle with WipperSnapper](https://learn.adafruit.com/track-a-turtle-with-wippersnapper.md)
- [Retroreflective Greenscreen Light Ring QT Py Controller ](https://learn.adafruit.com/retroreflective-green-screen-light-ring-controller.md)
- [Clockwork Goggles](https://learn.adafruit.com/gemma-m0-clockwork-goggles.md)
- [4x4 Rotary Encoder MIDI Messenger](https://learn.adafruit.com/4x4-rotary-encoder-midi-messenger.md)
- [MCUME Emulators on Fruit Jam](https://learn.adafruit.com/mcume-emulators-on-fruit-jam.md)
- [CircuitPython on the Xteink X4 eReader](https://learn.adafruit.com/circuitpython-on-the-xteink-x4-ereader.md)
- [No-Code, No-Solder Monitoring For Perfect Bread](https://learn.adafruit.com/no-code-no-solder-temperature-monitoring-with-wippersnapper-offline.md)