# World Clock
## Overview
Create a world clock to show a satellite photo of the earth with the current midday at the center of the display. The map slowly scrolls across doing a complete loop every 24 hours.
This clock tracks solar time so the middle of the display is the point where the sun in highest in the sky. Solar time is usually quite close to the time our clocks show, but doesn't take into account daylight savings or timezones that are ahead or behind solar time.
In the above photo, it's solar noon in England, so the time is 8am in New York and 5am in Los Angeles. Slightly confusingly, it's 1pm in London (because of daylight savings time).
## Parts:
Featured
### Adafruit QT Py S3 with 2MB PSRAM WiFi Dev Board with STEMMA QT
[Adafruit QT Py S3 with 2MB PSRAM WiFi Dev Board with STEMMA QT](https://www.adafruit.com/product/5700)
The ESP32-S3 has arrived in QT Py format - and what a great way to get started with this powerful new chip from Espressif! With dual 240 MHz cores, WiFi and BLE support, and native USB, this QT Py is great for powering your IoT projects. Now we even have this powerhouse of a board with built...
In Stock
[Buy Now](https://www.adafruit.com/product/5700)
[Related Guides to the Product](https://learn.adafruit.com/products/5700/guides)
Featured
### Adafruit EYESPI BFF for QT Py or Xiao - 18 Pin FPC Connector
[Adafruit EYESPI BFF for QT Py or Xiao - 18 Pin FPC Connector](https://www.adafruit.com/product/5772)
Our QT Py boards are a great way to make very small microcontroller projects that pack a ton of power - and now we have a way for you to add a small, colorful, and bright display to any project.
Our most recent [display...](https://www.adafruit.com/?q=eyespi&sort=BestMatch)
In Stock
[Buy Now](https://www.adafruit.com/product/5772)
[Related Guides to the Product](https://learn.adafruit.com/products/5772/guides)
Featured
### EYESPI Cable - 18-pin 50mm long Flex PCB (FPC) A-B Type
[EYESPI Cable - 18-pin 50mm long Flex PCB (FPC) A-B Type](https://www.adafruit.com/product/5462)
Connect this to that when an 18-pin FPC connector is needed. This 50mm long cable is made of a flexible PCB. It's A-B style which means that pin one on one side will match with pin one on the other side. How handy!
In Stock
[Buy Now](https://www.adafruit.com/product/5462)
[Related Guides to the Product](https://learn.adafruit.com/products/5462/guides)
Featured
### Adafruit 1.28" 240x240 Round TFT LCD Display with MicroSD
[Adafruit 1.28" 240x240 Round TFT LCD Display with MicroSD](https://www.adafruit.com/product/6178)
'Round these parts we enjoy unusually-shaped displays. And this one certainly fits the description - it's a 1.28" diagonal TFT that comes in a round shape and contains a high density 220 ppi, 240x240 pixel RGB display with full-angle viewing. It _looks_ a lot like our
In Stock
[Buy Now](https://www.adafruit.com/product/6178)
[Related Guides to the Product](https://learn.adafruit.com/products/6178/guides)
## You might also need:
You'll need something like the following to power and program your clock.
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)
Featured
### 5V 2A Switching Power Supply w/ USB-A Connector
[5V 2A Switching Power Supply w/ USB-A Connector](https://www.adafruit.com/product/1994)
Our 5V 2A USB power adapter is the perfect choice for powering single-board computers like Raspberry Pi, BeagleBone, or anything else that's power-hungry!
This adapter was specifically designed to provide 5.25V, not 5V, but we still call it a 5V USB adapter. We did this on purpose to...
In Stock
[Buy Now](https://www.adafruit.com/product/1994)
[Related Guides to the Product](https://learn.adafruit.com/products/1994/guides)
If you have access to a 3D printer, you can print out your support for the clock. Alternatively, you can fabricate a support out of whatever you like. It would be fairly straightforward to make one out of wood or foam board. The mounting points on the LCD take M2 machine screws (or other screws that will fit through a 0.1 inch hole).
# World Clock
## Connecting the Hardware
The Adafruit EYESPI BFF for QT Py comes with header pins that you can use to solder this board to the Adafruit QT Py S3, but you need to break them into two segments each 7 pins long.
Before powering up your soldering iron, do a dry fit to ensure you know what you're connecting to where. Make sure that you've connected the two boards the right way around (the flex cable port and the USB C port should be at the same end and each be on the outside of the sandwich. You can confirm that everything's as it should be because the 5V and A0 pins should be against their equivalent number on both boards. The plastic part of the pins should be between the two boards preventing any components from touching.
Keep everything together like this and solder each pin to make the connection permanent. It should look like the image below.
## Connect the Screen to the BFF
The EYESPI Cable connects the Adafruit 1.28" 240x240 Round TFT LCD Display to the Adafruit EYESPI BFF for QT Py. On both boards, there is a connector for flat cables. Gently lever up the darker plastic clip gently using your fingernail (or something similar) – it should rotate 90 degrees and expose some contact underneath. On either end of the cable there are exposed metal contacts. The metal contacts on one end of the cable should be placed on top of the metal contacts on the connector, then push the cable as far into the connector as it will go. Once in place, the dark plastic clip can be pressed back down to secure the cable. When it's connected properly, it should withstand a gentle tug – if it comes out, repeat the process being sure to push the cable as far into the connector as possible.
Repeat the process on the LCD side so that cable joins the Adafruit EYESPI BFF and the LCD.
That's the hardware connected, it's time to move onto the software.
# World Clock
## 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.
There are two versions of this board: one with 8MB Flash/No PSRAM and one with 4MB Flash/2MB PSRAM. Each version has their own UF2 build for CircuitPython. There isn't an easy way to identify which version of the board you have by looking at the board silk. If you aren't sure which version you have, try either build to see which one works.
Warning:
[Download the latest version of CircuitPython for the 8MB/No PSRAM version of this board via circuitpython.org](https://circuitpython.org/board/adafruit_qtpy_esp32s3_nopsram/)
[Download the latest version of CircuitPython for the 4MB/2MB PSRAM version of this board via circuitpython.org](https://circuitpython.org/board/adafruit_qtpy_esp32s3_4mbflash_2mbpsram/)
**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.
Click the **reset** button once (highlighted in red above), and then click it again when you see the **RGB status LED(s)** (highlighted in green above) turn purple (approximately half a second later). Sometimes it helps to think of it as a "slow double-click" of the reset button.
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.
On some very old versions of the UF2 bootloader, the status LED turns red instead of purple.
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.
Once successful, you will see the **RGB status LED(s)** turn green (highlighted in green above), and a disk drive ending in " **...BOOT**" should appear on your host computer. 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.
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.**
Info:
You will see a new disk drive appear called **QTPYS3**** BOOT**.
Drag the **adafruit\_circuitpython\_etc.uf2** file to **QTPYS3BOOT**.
Copy or drag the UF2 file you downloaded to the **BOOT** drive.
The **BOOT** drive will disappear and a new disk drive called **CIRCUITPY** will appear.
That's it!
# World Clock
## Code
Are you new to using CircuitPython? No worries, [there is a full getting started guide here](https://learn.adafruit.com/welcome-to-circuitpython "Welcome to CircuitPython").
Adafruit suggests using the Mu editor to edit your code and have an interactive REPL in CircuitPython. [You can learn about Mu and installation in this tutorial](https://learn.adafruit.com/welcome-to-circuitpython/installing-mu-editor "Mu tutorial").
## Getting the image
The clock is going to display an image of the earth, so the first thing to do is get this image. NASA makes all their images free to use, and has a full earth image made from multiple satellite photos stitched together. This has been converted into the right format and resized. The resulting image is available below. Save this image by clicking on it, then selecting the original resolution (in the right-hand panel). Give it the file name **world.bmp** and place it in root directory of your QT Py.
## Set your environmental variables
The clock will get the current time from the internet, so it needs the details to log into your WiFi network. Open the **settings.toml** file on your QT Py (or create one if it doesn't already exist), and enter the following:
`CIRCUITPY_WIFI_SSID = "YOUR-WIFI-SSID"`
`CIRCUITPY_WIFI_PASSWORD = "YOUR-WIFI-PASSWORD"`
With the correct Wifi password and network name. Ensure the values on the right are in double quotes (`"`)
## Get the libraries and code
You'll need the following libraries.
- adafruit\_connection\_manager.mpy
- adafruit\_gc9a01a.mpy
- adafruit\_ntp.mpy
The easiest way to get these is to click 'Download Project Bundle' below. This will give you a ZIP file containing the code and libraries you need for this project. Save this file somewhere on your computer and open it up. You should see folders for each of the current versions of CircuitPython. Take the **code.py** file and **lib** folder from the folder for your version of CircuitPython and copy them onto your QT Py.
https://github.com/adafruit/Adafruit_Learning_System_Guides/blob/main/World_Clock_Round_Display/code.py
As soon as this is all saved, the QT Py should reboot and after a few seconds, display an image of the world with the current mid-day point in the middle. If it doesn't then check that you have all the required files on the device, and that you are in an area with Wifi coverage.
### Map projection
There is a bit of a rendering error in this clock. The Earth is obviously a sphere, and the image we're using is a flat rectangle. There are various ways of squishing an image of a sphere onto a rectangle, but they all introduce errors.
Our clock doesn't account for the curvature of the earth. To us, this doesn't matter because it makes it easier to recognize the part of the Earth that's currently showing. If you'd prefer to render it in a different way, you can update the code however you'd like.
### Do I need to change the code to my time zone?
No, the map will scroll with the sun reflecting GMT per design.
That's the electronics setup. Now to look at the physical setup.
# World Clock
## Finishing Touches
Our clock holder needs to fulfill two basic tasks:
1. Keep the clock face upright.
2. Stop the pins on the QT Py touching the back of the LCD.
As long as you manage those things, you can set it up however you like. There is an STL file you can use if you want to, but be as creative as you like with your housing.
You can download the clock holder STL file from [https://www.printables.com/model/1281120-clock-holder](https://www.printables.com/model/1281120-clock-holder) or via the green button below. It should print on its side without supports. Two machine screws hold the LCD in place. There are no mounting holes on the QT Py, so you'll need to use a dollop of something sticky to hold it in place. I used White Tack, but hot glue would also work (but might be harder to remove). Whatever you use, just be careful to keep it away from the USB or STEMMA QT ports.
[Clock Holder STL File](https://cdn-learn.adafruit.com/assets/assets/000/136/766/original/clock-holderv2.stl?1747077583)
Once everything's together, plug it into a power source and enjoy your world clock.
## Guide Products
### Adafruit QT Py S3 with 2MB PSRAM WiFi Dev Board with STEMMA QT
[Adafruit QT Py S3 with 2MB PSRAM WiFi Dev Board with STEMMA QT](https://www.adafruit.com/product/5700)
The ESP32-S3 has arrived in QT Py format - and what a great way to get started with this powerful new chip from Espressif! With dual 240 MHz cores, WiFi and BLE support, and native USB, this QT Py is great for powering your IoT projects. Now we even have this powerhouse of a board with built...
In Stock
[Buy Now](https://www.adafruit.com/product/5700)
[Related Guides to the Product](https://learn.adafruit.com/products/5700/guides)
### Adafruit EYESPI BFF for QT Py or Xiao - 18 Pin FPC Connector
[Adafruit EYESPI BFF for QT Py or Xiao - 18 Pin FPC Connector](https://www.adafruit.com/product/5772)
Our QT Py boards are a great way to make very small microcontroller projects that pack a ton of power - and now we have a way for you to add a small, colorful, and bright display to any project.
Our most recent [display...](https://www.adafruit.com/?q=eyespi&sort=BestMatch)
In Stock
[Buy Now](https://www.adafruit.com/product/5772)
[Related Guides to the Product](https://learn.adafruit.com/products/5772/guides)
### EYESPI Cable - 18-pin 50mm long Flex PCB (FPC) A-B Type
[EYESPI Cable - 18-pin 50mm long Flex PCB (FPC) A-B Type](https://www.adafruit.com/product/5462)
Connect this to that when an 18-pin FPC connector is needed. This 50mm long cable is made of a flexible PCB. It's A-B style which means that pin one on one side will match with pin one on the other side. How handy!
In Stock
[Buy Now](https://www.adafruit.com/product/5462)
[Related Guides to the Product](https://learn.adafruit.com/products/5462/guides)
### Adafruit 1.28" 240x240 Round TFT LCD Display with MicroSD
[Adafruit 1.28" 240x240 Round TFT LCD Display with MicroSD](https://www.adafruit.com/product/6178)
'Round these parts we enjoy unusually-shaped displays. And this one certainly fits the description - it's a 1.28" diagonal TFT that comes in a round shape and contains a high density 220 ppi, 240x240 pixel RGB display with full-angle viewing. It _looks_ a lot like our
In Stock
[Buy Now](https://www.adafruit.com/product/6178)
[Related Guides to the Product](https://learn.adafruit.com/products/6178/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)
### 5V 2A Switching Power Supply w/ USB-A Connector
[5V 2A Switching Power Supply w/ USB-A Connector](https://www.adafruit.com/product/1994)
Our 5V 2A USB power adapter is the perfect choice for powering single-board computers like Raspberry Pi, BeagleBone, or anything else that's power-hungry!
This adapter was specifically designed to provide 5.25V, not 5V, but we still call it a 5V USB adapter. We did this on purpose to...
In Stock
[Buy Now](https://www.adafruit.com/product/1994)
[Related Guides to the Product](https://learn.adafruit.com/products/1994/guides)
## Related Guides
- [Adafruit QT Py ESP32-S3](https://learn.adafruit.com/adafruit-qt-py-esp32-s3.md)
- [Adafruit EYESPI BFF](https://learn.adafruit.com/adafruit-eyespi-bff.md)
- [Adafruit 1.28" 240x240 Round TFT LCD](https://learn.adafruit.com/adafruit-1-28-240x240-round-tft-lcd.md)
- [No-Code Room Occupancy Status ](https://learn.adafruit.com/no-code-room-occupancy-status.md)
- [LED Matrix Alarm Clock](https://learn.adafruit.com/led-matrix-alarm-clock.md)
- [Ahsoka Lightsaber Prop-Maker RP2040 retrofit](https://learn.adafruit.com/lightsaber-retrofit.md)
- [No-Code WipperSnapper Action Counter](https://learn.adafruit.com/no-code-wippersnapper-action-counter.md)
- [WiFi Jellyfish Lantern with WLED](https://learn.adafruit.com/wifi-jellyfish-lantern-with-wled.md)
- [No-Code IoT Pool Monitor](https://learn.adafruit.com/iot-pool.md)
- [Adafruit MagTag Kitchen Timer](https://learn.adafruit.com/adafruit-magtag-kitchen-timer.md)
- [Wirelessly Program a Circuit Playground Bluefruit Using the File Glider App ](https://learn.adafruit.com/how-to-transfer-files-to-a-circuit-playground-bluefruit-using-the-fileglider-app.md)
- [CircuitPython USB VID/PID Reporter](https://learn.adafruit.com/circuitpython-usb-vid-pid-reporter.md)
- [I2S Microphones with CircuitPython](https://learn.adafruit.com/i2s-microphones-with-circuitpython.md)
- [No-Code Indoor Air Quality Monitor with Separate Display](https://learn.adafruit.com/no-code-indoor-air-quality-monitor-with-separate-display.md)
- [Laser-Cut Layered LED Art Panel (Wood + Acrylic) with WLED](https://learn.adafruit.com/laser-cut-layered-led-art-panel-wood-acrylic-with-wled.md)
- [Hacking the Teenage Engineering EP-2350 Ting](https://learn.adafruit.com/hacking-the-teenage-engineering-ep-2350-ting.md)
- [Tiny Wiki for CircuitPython](https://learn.adafruit.com/tiny-wiki-for-circuitpython.md)
- [MCUME Emulators on Fruit Jam](https://learn.adafruit.com/mcume-emulators-on-fruit-jam.md)