# ePaper Camera
## Overview
Build an ePaper camera display using the Adafruit MEMENTO camera and MagTag eink display so you can snap lofi pictures and transmit them over WiFi to your eInk photo frame!
A free Adafruit IO account acts as the intermediary between camera and display, through your own custom camera feed.
## Parts
Featured
### MEMENTO - Python Programmable DIY Camera - Bare Board
[MEMENTO - Python Programmable DIY Camera - Bare Board](https://www.adafruit.com/product/5420)
Make memories, or just a cool camera-based project, with **Adafruit's MEMENTO Camera Board**. It's a development board with everything you need to create programmable camera and vision projects: with a camera module, TFT preview screen, buttons, SD card slot and...
Out of Stock
[Buy Now](https://www.adafruit.com/product/5420)
[Related Guides to the Product](https://learn.adafruit.com/products/5420/guides)
Featured
### Adafruit MEMENTO Camera Enclosure & Hardware Kit
[Adafruit MEMENTO Camera Enclosure & Hardware Kit](https://www.adafruit.com/product/5843)
Once you've picked up your **MEMENTO Camera** and you're ready to take it out into the world, here is a chic and minimalist enclosure that will look great on the runways of Paris or the street photography of New York City! These front and back plates have been...
In Stock
[Buy Now](https://www.adafruit.com/product/5843)
[Related Guides to the Product](https://learn.adafruit.com/products/5843/guides)
Featured
### 256MB Micro SD Memory Card
[256MB Micro SD Memory Card](https://www.adafruit.com/product/5251)
Add storage in a jiffy using this **256MB microSD card**. Preformatted to FAT32, so it works out of the packaging with our projects. Works great with any device in the Adafruit shop that uses microSD cards. Ideal for use with Feathers, data loggers, or small Linux SBCs (not good...
In Stock
[Buy Now](https://www.adafruit.com/product/5251)
[Related Guides to the Product](https://learn.adafruit.com/products/5251/guides)
Featured
### Lithium Ion Polymer Battery with Short Cable - 3.7V 420mAh
[Lithium Ion Polymer Battery with Short Cable - 3.7V 420mAh](https://www.adafruit.com/product/4236)
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 420mAh for a total of about 1.55 Wh. If you need a larger (or smaller!) battery,
In Stock
[Buy Now](https://www.adafruit.com/product/4236)
[Related Guides to the Product](https://learn.adafruit.com/products/4236/guides)
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
### 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
### 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
### 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)
# ePaper Camera
## Get Started with Adafruit IO
Adafruit IO is integrated with your [adafruit.com account](https://accounts.adafruit.com/) so you don't need to create yet another online account! You need an Adafruit account to use Adafruit IO because we want to make sure the data you upload is available to only you (unless you decide to publish your data).
## I have an Adafruit.com Account already
**If you already have an Adafruit account, then you already have access to Adafruit IO**. It doesn't matter how you signed up, your account will make all three available.
To access Adafruit IO, simply visit [https://io.adafruit.com](https://io.adafruit.com) to start streaming, logging, and interacting with your data.
## Create an Adafruit Account (for Adafruit IO)
An Adafruit account makes Adafruit content and services available to you in one place. Your account provides access to the [Adafruit shop](https://www.adafruit.com/), the [Adafruit Learning System](https://learn.adafruit.com/), and [Adafruit IO](https://io.adafruit.com/). This means only one account, one username, and one password are necessary to engage with the content and services that Adafruit offers.
If you do not have an Adafruit account, signing up for a new Adafruit account only takes a couple of steps.
Begin by visiting [https://accounts.adafruit.com](https://accounts.adafruit.com).
**Click the Sign Up button** under the "Need An Adafruit Account?" title, below the Sign In section.
This will take you to the **Sign Up** page.
**Fill in the requested information,** and **click the Create Account button.**
This takes you to your Adafruit Account home page. From here, you can access all the features of your account.
You can also access the Adafruit content and services right from this page. Along the top of the page, you'll see a series of links beginning with "Shop". To access any of these, simply click the link.
For example, **to begin working with Adafruit IO, click the IO link** to the right of the rest of the links. This is the same for the other links as well.
That's all there is to creating a new Adafruit account, and navigating to Adafruit IO.
# ePaper Camera
## Create Adafruit IO Feed
Pink: These steps are REQUIRED to use the ePaper camera. Skipping them may result in your code raising errors!
Feeds are the core of the Adafruit IO system. A feed holds **data ** and **meta-data** that you have sent to Adafruit IO.
- **Data** is the information you want Adafruit IO to store. For example, image data from the MEMENTO's camera.
- **Meta-data** includes settings for the data such as privacy settings and data retention options.
Before using the ePaper camera, a new Adafruit IO Feed must be created to store the camera's image. Then, the feed's history must be disabled to allow larger data points to be sent to Adafruit IO, such as a large amount of data to represent an image.
To create a feed, navigate to your [Adafruit IO Feeds](https://io.adafruit.com/feeds) page. Then, click _New Feed_.
Name the feed _epapercamera_ and click Create.
The feeds list now lists an _epapercamera_ feed. Click this feed.
## Disable Feed History
On the epapercamera feed's sidebar, click _Feed History_.
Set _History_ to _OFF_ and click Save. This will change the feed's data storage from 1KB to 100KB, large enough to store image data.
# ePaper Camera
## MEMENTO Camera Setup
Here you'll assemble your MEMENTO camera and set it up with the CircuitPython installation and ePaper Camera code.
# ePaper Camera
## MEMENTO Assembly
## Film Prep
OK, not that kind of film. But still, the first step in assembling your MEMENTO camera is to remove the protective film from the four threaded standoffs.
## Lens Cover
Next, remove the protective film from the lens.
## Battery Adhesive
Peel off one side of backing from the double-sided adhesive foam, then press it onto the main board where the battery will go, as shown.
## Battery Mount
Insert the battery JST cable into the connector, then remove the other protective backing from the adhesive foam.
Press the battery into place as shown, being careful to dress the wires neatly.
## LED Faceplate
You'll mount the LED faceplate using four of the provided M3 screws.
Place the faceplate over the MEMENTO board with the white triangle pointing at the shutter button. This assures the JST connectors of both boards are on the same edge.
Screw in the four screws.
## Prep for Back Plate
Flip the MEMENTO over, then press gently on the TFT to make sure it is square and the adhesive strips are snug against the PCB.
Remove the protective film.
## Fastener Prep
Place the four remaining screws through the back panel holes from the side of the board that will face you when assembled as shown.
Thread the four nuts onto the screws -- these will act as spacers.
Place the back panel onto the back of the MEMENTO so the buttons and screen line up.
Screw the four screws into the threaded standoffs.
## JST Cable
We had a special short JST 3-pin cable made for the MEMENTO so the LED board can get power and data for the NeoPixels from the A1 port on the MEMENTO.
Plug the cable into the LED plate and MEMENTO A1 JST ports. The connectors can only go in one way.
## Insert SD Card
Orient the micro SD card as shown and press it into the SD card reader slot -- you'll press it all the way in until it clicks and stops and then as you let off the pressure it'll click a second time. \*snik snik!\*
NOTE: You can use cards with up to 32GB capacity.
Warning: The author warns that if you aren't careful about pressing the SD card all the way in before releasing your finger, it will shoot across the room just like the spring loaded missile launcher on the Micronauts Hydra vehicle he had as a kid that he can't believe his parents got rid of.
That's it, you've assembled your MEMENTO! Now, you're ready to get started taking pictures and hacking your MEMENTO camera! Flip the ON switch and the camera will boot up with the factory demo.
# ePaper Camera
## Install CircuitPython
[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.
## CircuitPython Quickstart
Follow this step-by-step to quickly get CircuitPython running on your board.
Warning: Make sure you use CircuitPython 9.0.0 final or later. CircuitPython 9.0.0-beta.1 and earlier have a bug that can corrupt the fileystem.
```auto
import storage
storage.erase_filesystem()
```
Your board will reboot after running this.
[Download the latest version of CircuitPython for this board via circuitpython.org](https://circuitpython.org/board/adafruit_esp32s3_camera/)
Warning: As of CircuitPython 9, you'll need to create a folder called "sd" on your CIRCUITPY drive to mount the microSD card, if it's not already there.
[Follow these steps to create the /sd directory](https://learn.adafruit.com/adafruit-memento-camera-board/circuitpython-memento-starter-projects)
**Click the link above to download the latest CircuitPython UF2 file.**
Save it wherever is convenient for you.
Plug your board into your computer, using a known-good data-sync cable, directly, or via an adapter if needed.
Double-click the **reset** button (highlighted in red above), and you will see the **RGB status LED(s)** turn green (highlighted in green above). If you see red, try another port, or if you're using an adapter or hub, try without the hub, or different adapter or hub.
For this board, tap reset and wait for the LED to turn purple, and as soon as it turns purple, tap reset again. The second tap needs to happen while the LED is still purple.
If you do not see the LED turning purple, you will need to reinstall the UF2 bootloader. See the **Factory Reset** page in this guide for details.
If double-clicking doesn't work the first time, try again. Sometimes it can take a few tries to get the rhythm right!
A lot of people end up using charge-only USB cables and it is very frustrating! **Make sure you have a USB cable you know is good for data sync.**
You will see a new disk drive appear called **CAMERABOOT**. Drag the **adafruit-circuitpython-adafruit\_esp32s3\_camera-etc.uf2** file to **CAMERABOOT**.
The **BOOT** drive will disappear and a new disk drive called **CIRCUITPY** will appear.
That's it!
# ePaper Camera
## Code the MEMENTO
## Download the Project Bundle
Your project will use a specific set of CircuitPython libraries, and the **code.py** file. To get everything you need, click on the **Download Project Bundle** button below, and uncompress the .zip file.
Connect your computer to the MEMENTO via a known good USB power+data cable. A new flash drive should show up on your computer named **CIRCUITPY** in the File Explorer or Finder (depending on your operating system/computer type).
Drag the **lib** directory and the **memento\_code.py** file onto your MEMENTO board's **CIRCUITPY** drive, replacing any existing files or directories with the same names, and adding any new ones that are necessary.
Once you've copied the files to the MEMENTO's CIRCUITPY drive, rename the **memento\_code.py ** file to **code.py ** otherwise the code won't run on startup.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Epaper_Camera/memento_code.py
## How It Works
The ePaper Camera system uses two Adafruit boards working together: the MEMENTO camera captures black and white photos, and the MagTag e-ink displays them. Let's walk through how the code makes this happen.
### Setup and Initialization
When the MEMENTO powers on, it first connects to your WiFi network using credentials stored in **settings.toml**. It then creates a socket pool for network communications and gets ready to talk to Adafruit IO, where images will be uploaded.
```python
wifi.radio.connect(
os.getenv("CIRCUITPY_WIFI_SSID"), os.getenv("CIRCUITPY_WIFI_PASSWORD")
)
pool = socketpool.SocketPool(wifi.radio)
```
Next, the PyCamera object initializes the camera hardware. It is configured for black and white photography (`effect = 2`) at 240x240 resolution, set the LED ring to a medium brightness, and turn on the display so you can see what you're framing:
```python
pycam = adafruit_pycamera.PyCamera()
pycam.effect = 2 # B&W
pycam.resolution = 0 # 240x240
pycam.display.brightness = 0.7
```
### The Main Loop
The camera runs in a continuous loop, always showing a live preview. This happens in the main `while True:` loop at the bottom of the code. Every 10 milliseconds, it grabs a frame from the camera and displays it:
```python
frame = pycam.continuous_capture()
if frame and hasattr(frame, "width"):
pycam.blit(frame)
```
The code also checks for button presses. If you press the shutter button, it calls `capture_send_image()` to take a photo and upload it. If you press the up button, it cycles through LED brightness levels (0-4) so you can adjust the light for different shooting conditions.
### Capturing and Processing Images
When you press the shutter button, the `capture_send_image()` function runs. Here's the journey your photo takes:
**Step 1: Capture**
First, the camera autofocuses and captures a JPEG image:
```auto
pycam.autofocus()
jpeg_data = pycam.capture_into_jpeg()
```
**Step 2: Dithering**
The JPEG is saved temporarily to the SD card, then loaded back as a bitmap. We create a second bitmap and apply Floyd-Steinberg dithering, which converts the grayscale image into a beautiful black and white pattern that looks great on e-ink displays:
```auto
bitmaptools.dither(
dithered_frame, captured_bitmap, displayio.Colorspace.RGB565_SWAPPED
)
```
**Step 3: GIF Creation**
We save the dithered bitmap as a single-frame GIF file:
```auto
with gifio.GifWriter(f, width, height, colorspace, dither=True) as g:
g.add_frame(dithered_frame, 1)
```
**Step 4: Encoding**
The GIF is read back from the SD card and encoded as base64 text to send over the internet:
```auto
encoded_data = binascii.b2a_base64(gif_data).strip().decode("ascii")
```
**Step 5: Uploading**
Finally, we create a fresh network session and send the encoded image to your Adafruit IO feed named `epapercam`:
```auto
io.send_data(feed_camera["key"], encoded_data)
```
### Memory Management
After each major step, the code explicitly frees memory and runs garbage collection to ensure we don't run out of space:
```auto
jpeg_data = None
gc.collect()
```
We also create a fresh `requests` session for each upload and delete it afterward. This prevents socket exhaustion - the ESP32 only has about 10-12 network sockets available, and if we don't clean them up properly, the camera would freeze after a few photos.
### Error Handling and Recovery
The code includes extensive error handling. If something goes wrong during capture, it plays a low error tone and always returns the camera to live preview mode in the `finally:` block:
```auto
finally:
pycam.live_preview_mode()
time.sleep(0.3)
pycam.display.refresh()
```
### LED Ring Brightness Control
The up button on the MEMENTO cycles through five LED brightness levels. Level 0 turns the LEDs off completely, while level 4 is maximum brightness:
```python
if pycam.up.rose:
pycam.led_level = (pycam.led_level + 1) % 5
```
# ePaper Camera
## MagTag Frame Setup
Here you'll assemble your MagTag, set up CircuitPython on it, and code it to act as the ePaper photo display.
# ePaper Camera
## 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.
# ePaper Camera
## 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.
# ePaper Camera
## Code the MagTag
## Download the Project Bundle
Your project will use a specific set of CircuitPython libraries, and the **code.py** file. To get everything you need, click on the **Download Project Bundle** button below, and uncompress the .zip file.
Connect your computer to the MagTag via a known good USB power+data cable. A new flash drive should show up on your computer as **CIRCUITPY**.
Drag the **lib** directory and the **magtag\_code.py** file onto your MagTag board's **CIRCUITPY** drive, replacing any existing files or directories with the same names, and adding any new ones that are necessary.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/Epaper_Camera/magtag_code.py
Once you've copied the files to the MEMENTO's **CIRCUITPY** drive, rename the **memento\_code.py ** file to **code.py ** otherwise the code won't run on startup.
## How It Works
The MagTag acts as a wireless picture frame, automatically checking Adafruit IO for new photos and displaying them on its e-ink screen. It's designed to run on battery power for weeks or even months by using deep sleep between checks.
### Configuration and Power Management
At the top of the code, you'll find the sleep interval setting:
```auto
SLEEP_INTERVAL = 300 # 5 minutes in seconds
```
This determines how often the MagTag wakes up to check for new images. Start with 300 seconds (5 minutes) for testing, then increase it to 900 (15 minutes) or 3600 (1 hour) for longer battery life. Longer intervals mean better battery life but slower image updates.
### Sleep Memory and Wake Detection
When the MagTag wakes up, it needs to know whether this is a fresh boot or a wake from deep sleep:
```auto
if alarm.wake_alarm:
print("Woke from deep sleep")
else:
print("Cold boot - clearing sleep memory")
alarm.sleep_memory[0:100] = b"\x00" * 100
```
The ESP32 has a special 256-byte "sleep memory" that persists through deep sleep but not through power loss. We use the first 100 bytes to store the timestamp of the last image we displayed. On a cold boot (like when you first plug in the battery), we clear this memory so the MagTag will display whatever image is currently in the feed.
### NeoPixel Status Indicators
The four NeoPixels on the MagTag act as status indicators, giving you visual feedback about what's happening:
- **Amber** : Power-on (brief)
- **Cyan** : Connected to WiFi
- **Green** : Checking Adafruit IO for new images
- **White** : Downloading and processing an image
- **Red** : An error occurred
- **Off** : In deep sleep (saving battery)
```auto
magtag.peripherals.neopixels.fill(0x002000) # Green while checking
```
These dim colors (`0x002000` instead of `0x00FF00`) save power while still being visible.
### Connecting and Setup
After showing the amber "power-on" indicator, the MagTag connects to WiFi using credentials from your **settings.toml** file:
```auto
wifi.radio.connect(
os.getenv("CIRCUITPY_WIFI_SSID"), os.getenv("CIRCUITPY_WIFI_PASSWORD")
)
```
It then creates a connection to Adafruit IO and gets information about the `epapercam` feed where images are stored:
```auto
io_client = IO_HTTP(aio_username, aio_key, requests)
feed_camera = io_client.get_feed("epapercam")
```
### Update Check
To help with battery life, instead of downloading every time it wakes up, the MagTag first checks if there's actually a new image:
```auto
last_timestamp = get_last_timestamp() # From sleep memory
feed_data = io_client.receive_data(feed_camera["key"])
current_timestamp = feed_data.get("updated_at")
if current_timestamp != last_timestamp:
# New image! Download and display it
else:
# Same image, skip download to save battery
```
The `get_last_timestamp()` function reads the stored timestamp from sleep memory:
```auto
stored = bytes(alarm.sleep_memory[0:100]).decode("utf-8").strip("\x00")
```
If the timestamps match, the MagTag skips the download entirely, turns off the LEDs, and goes back to sleep. This saves significant battery power since most wake cycles will find no new image.
### Image Processing Pipeline
When a new image is detected, `fetch_and_display_epaper_cam_image()` handles the download and display.
**Step 1: Download and Decode**
The image arrives as base64-encoded text (the same format the MEMENTO sent). We decode it back to binary GIF data:
```auto
gif_data = binascii.a2b_base64(base64_image)
```
**Step 2: Load the GIF**
Using `adafruit_imageload`, we convert the GIF data into a bitmap and color palette that CircuitPython can work with:
```auto
gif_stream = BytesIO(gif_data)
bitmap, palette = adafruit_imageload.load(gif_stream)
```
**Step 3: Scaling**
The MEMENTO captures 240x240 pixel images, but the MagTag display is 296x128 pixels. We need to scale and crop the image to fit. First, we calculate the scale factor to fill the width:
```auto
scale = DISPLAY_WIDTH / bitmap.width # 296 / 240 = 1.23
scaled_height = int(bitmap.height * scale) # 296 pixels tall
```
**Step 4: Centering and Cropping**
Since the scaled image (296x296) is taller than the display (296x128), we crop it vertically and center it:
```auto
src_y_offset = (scaled_height - DISPLAY_HEIGHT) // 2
```
This offset tells us how many pixels to skip from the top of the scaled image to show the center portion.
**Step 5: Pixel-by-Pixel Scaling**
The `scale_and_crop_image()` helper function does the actual scaling using nearest-neighbor interpolation. For each pixel on the display, it figures out which pixel from the source image to copy:
```auto
for y in range(DISPLAY_HEIGHT):
src_y = int((y + src_y_offset) / scale)
for x in range(DISPLAY_WIDTH):
src_x = int(x / scale)
display_bitmap[x, y] = src_bitmap[src_x, src_y]
```
**Step 6: Display**
Finally, we create a TileGrid with the scaled bitmap and display it:
```auto
tile_grid = displayio.TileGrid(display_bitmap, pixel_shader=palette, x=0, y=0)
group = displayio.Group()
group.append(tile_grid)
magtag.graphics.display.root_group = group
magtag.graphics.display.refresh()
```
The e-ink display refresh takes about 2-3 seconds and creates that characteristic "flash" as the screen updates.
### Saving the Timestamp
After successfully displaying the new image, we save its timestamp to sleep memory so we won't download it again:
```auto
timestamp_bytes = timestamp.encode("utf-8")
padded = timestamp_bytes + b"\x00" * (100 - len(timestamp_bytes))
alarm.sleep_memory[0:100] = padded[:100]
```
### Deep Sleep
The final step is entering deep sleep, which reduces power consumption from ~80mA down to ~40µA (microamps!):
```auto
time_alarm = alarm.time.TimeAlarm(monotonic_time=time.monotonic() + SLEEP_INTERVAL)
alarm.exit_and_deep_sleep_until_alarms(time_alarm)
```
When the time alarm triggers, the ESP32 wakes up and **restarts the entire program from the beginning**. This is why we check `alarm.wake_alarm` at the start - it tells us this is a wake from sleep, not a fresh boot.
### Memory Management for Stability
Just like the MEMENTO code, the MagTag explicitly frees memory after each major operation:
```auto
base64_image = None
gc.collect()
```
This ensures the device can run reliably for weeks or months without running out of RAM.
### Error Handling
If anything goes wrong (WiFi issues, corrupted image data, Adafruit IO problems), the code catches the error, shows a red LED briefly, and still goes to deep sleep. This ensures that even if one wake cycle fails, the MagTag will try again after the next sleep interval:
```auto
except Exception as main_err:
magtag.peripherals.neopixels.fill(0x200000) # Red
# Still go to sleep to preserve battery
alarm.exit_and_deep_sleep_until_alarms(time_alarm)
```
# ePaper Camera
## Use It
Here's how to take pictures with your ePaper Camera. First, turn on the MEMENTO and the MagTag -- after a moment they will connect to the WiFi based on the credentials you entered in the **settings.toml** files.
## Snap a Pic
Press the UP button on the MEMENTO to cycle between NeoPixel ring levels. Then, snap a photo.
## Auto Upload
The MEMENTO will automatically dither and then upload the photo to your Adafruit IO `epapercam` feed. After about 20-30 seconds you'll see the full frame image appear in the feed.
## Auto Download
The next time the MagTag comes out of deep sleep to check for a new image, it'll detect the new photo, download it, crop it to fit, and then display it on the eInk display.
You can use the magnetic feet to mount it on your fridge or locker or other metal surface.
## Guide Products
### MEMENTO - Python Programmable DIY Camera - Bare Board
[MEMENTO - Python Programmable DIY Camera - Bare Board](https://www.adafruit.com/product/5420)
Make memories, or just a cool camera-based project, with **Adafruit's MEMENTO Camera Board**. It's a development board with everything you need to create programmable camera and vision projects: with a camera module, TFT preview screen, buttons, SD card slot and...
Out of Stock
[Buy Now](https://www.adafruit.com/product/5420)
[Related Guides to the Product](https://learn.adafruit.com/products/5420/guides)
### Adafruit MEMENTO Camera Enclosure & Hardware Kit
[Adafruit MEMENTO Camera Enclosure & Hardware Kit](https://www.adafruit.com/product/5843)
Once you've picked up your **MEMENTO Camera** and you're ready to take it out into the world, here is a chic and minimalist enclosure that will look great on the runways of Paris or the street photography of New York City! These front and back plates have been...
In Stock
[Buy Now](https://www.adafruit.com/product/5843)
[Related Guides to the Product](https://learn.adafruit.com/products/5843/guides)
### 256MB Micro SD Memory Card
[256MB Micro SD Memory Card](https://www.adafruit.com/product/5251)
Add storage in a jiffy using this **256MB microSD card**. Preformatted to FAT32, so it works out of the packaging with our projects. Works great with any device in the Adafruit shop that uses microSD cards. Ideal for use with Feathers, data loggers, or small Linux SBCs (not good...
In Stock
[Buy Now](https://www.adafruit.com/product/5251)
[Related Guides to the Product](https://learn.adafruit.com/products/5251/guides)
### Lithium Ion Polymer Battery with Short Cable - 3.7V 420mAh
[Lithium Ion Polymer Battery with Short Cable - 3.7V 420mAh](https://www.adafruit.com/product/4236)
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 420mAh for a total of about 1.55 Wh. If you need a larger (or smaller!) battery,
In Stock
[Buy Now](https://www.adafruit.com/product/4236)
[Related Guides to the Product](https://learn.adafruit.com/products/4236/guides)
### 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)
### 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)
### 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)
### 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)
## Related Guides
- [Adafruit MagTag](https://learn.adafruit.com/adafruit-magtag.md)
- [Adafruit MEMENTO Camera Board](https://learn.adafruit.com/adafruit-memento-camera-board.md)
- [Circuit Playground Express Automatic Sunglasses](https://learn.adafruit.com/circuit-playground-express-auto-sunglasses.md)
- [Clockwork Goggles](https://learn.adafruit.com/gemma-m0-clockwork-goggles.md)
- [Guardian Robot – Zelda BOTW](https://learn.adafruit.com/guardian-robot-zelda-botw.md)
- [FunHouse Parking Assistant](https://learn.adafruit.com/funhouse-parking-assistant.md)
- [Adafruit MagTag COVID Vaccination Percent Tracker](https://learn.adafruit.com/adafruit-magtag-covid-vaccination-percent-tracker.md)
- [MagTag 3D Printed Stand Case](https://learn.adafruit.com/magtag-3d-printed-stand-case.md)
- [LED Reactive Light-Up Hockey Puck in MakeCode](https://learn.adafruit.com/led-hockey-puck.md)
- [Living Ventriloquist Dummy with MONSTER M4SK Eyes](https://learn.adafruit.com/living-ventriloquist-dummy-with-monster-m4sk-eyes.md)
- [MagTag AR Tarot Card Reading](https://learn.adafruit.com/magtag-tarot-cards.md)
- [Goose Game M4SK Controller](https://learn.adafruit.com/goose-game-m4sk-controller.md)
- [How to use the Puppet Module in the Bluefruit Playground App](https://learn.adafruit.com/how-to-use-the-puppet-module-in-the-bluefruit-playground-app.md)
- [Snap Fit Mount for Circuit Playground Express](https://learn.adafruit.com/snap-fit-mount-for-circuit-playground-express.md)
- [A NeoPixel Pomodoro Timer](https://learn.adafruit.com/a-neopixel-pomodoro-timer.md)
- [NeoPixel Infinity Mirror Coaster](https://learn.adafruit.com/infinity-mirror-coaster.md)
- [MagTag Twitter Display](https://learn.adafruit.com/magtag-twitter-display.md)