Owner's Manual.

1. Quick Start (first-time setup)

You'll need: the globe, its USB-C cable, and your home WiFi name + password.

1. Power it on. Plug the USB-C cable into the globe and any USB power source (a phone charger or computer port is fine). After a few seconds you'll see a short start-up sequence, then a "Set up WiFi" screen.
2. Join the globe's setup hotspot. On your phone or laptop, open WiFi settings and connect to the network named Globe-Setup (no password).
3. A setup page opens automatically. If it doesn't pop up on its own, open a browser and go to 192.168.4.1. You'll see the Globe Setup page.
4. Enter your home WiFi in the WiFi network and WiFi password boxes, then tap Save & Restart.
5. Done. The globe reboots, joins your network, syncs the time, and within a minute or two begins showing the live Earth. The first cloud image is downloaded in the background and appears shortly after.

That's it — you won't need to repeat this unless you move the globe to a new network.

2. What you're looking at

The living Earth (the default view)

• Real day & night: The globe is sun-synchronous: the sunlit half and the shadowed half are placed using the real position of the Sun for the current date and time, with a soft, natural twilight band along the day/night line. As the hours pass, the Earth turns beneath the light just as the real planet does.
• Live clouds: Cloud cover is pulled from NASA's VIIRS satellites and draped over the globe, refreshed in the background every few hours, so the weather systems you see are real and current.
• City lights: After dusk, the night side lights up with the glow of the world's cities (NASA "Black Marble" night-lights).

The other worlds

Your globe isn't limited to Earth. From the settings page you can switch it to any of ten bodies, in this order: Earth · Mercury · Venus · Mars · Jupiter · Saturn · Uranus · Neptune · Moon · Sun.

Each is rendered from real imagery with the same sunlight-and-shadow treatment, so Mars or the Moon shows a true day/night line too. (The Sun is shown glowing on its own, with no shadow side.) Live clouds and city lights are Earth-only features — the other worlds use fixed surface imagery.

The time + weather card

On a cadence you choose, the globe briefly switches to a clean, full-screen card showing the local time (12-hour, with AM/PM) and the day + date, your city, the current temperature and what it feels like, humidity and wind speed.

It uses your approximate location (derived from your internet connection) to fetch local weather, then returns to the globe automatically after about 25 seconds. This card is off by default — turn it on from the settings page.

3. Features at a glance

• 🌍 Sun-synchronous live day/night Earth with a soft twilight terminator
• ☁️ Live NASA VIIRS cloud cover, refreshed automatically every few hours
• 🌃 City lights on the night side
• 🪐 10 selectable worlds — Earth, Mercury → Neptune, the Moon, and the Sun
• 🕒 Optional time + local weather card on a schedule you set
• 🔆 Adjustable brightness, motion speed, camera tilt, and shadow framing
• 🔁 Display rotation (0/90/180/270°) for however you stand it
• ⚡ Performance mode for extra-smooth motion
• 📶 Remembers up to 3 WiFi networks; simple captive-portal setup
• 🔑 No app, no account, no API keys — everything runs on the device

4. The settings page

Open a browser on the same WiFi as the globe and go to the address shown on the globe at boot (e.g. http://192.168.1.42). During first-time setup the address is 192.168.4.1. The page is titled 🌐 Globe Setup. Change whatever you like and tap Save & Restart at the bottom. Some settings take effect instantly; others restart the globe to apply (it comes right back).

About "Motion": at Real Earth speed the globe turns once every 24 hours — true to life, but far too slow to see moving. Pick a Timelapse option to watch it spin. The motion is designed to be perfectly smooth at any speed.

The Save button is labelled Save & Restart, but the globe only actually restarts when a change requires it (anything in the "Restart" rows above). If you only touched instant settings, the page just saves and returns.

5. Buttons & resetting WiFi

The globe has one physical button — BOOT — and no power switch (it runs whenever it's plugged in). You can reconnect it to a different WiFi network in any of three ways:

• Hold the BOOT button for ~3 seconds. The globe forgets all saved networks and reopens the Globe-Setup hotspot so you can set it up again.
• Use the web page. On the settings page, tap "Forget WiFi & reopen setup" at the bottom and confirm.
• Automatic. If the globe has no saved networks (brand new, or just reset), it opens the Globe-Setup hotspot on its own.

6. What happens automatically

Once it's online, the globe takes care of itself:

• Clouds refresh in the background roughly every 3 hours (and retry within ~10 minutes if a download fails). NASA's daily worldwide image is assembled swath by swath, so a fresh day is often patchy; the globe checks how complete each day is and, if too many gaps remain, automatically steps back day by day (up to a week) to the most recent fully-assembled image. Any small leftover gaps are filled from a base Earth map so you never see a blank patch.
• Weather updates about every 20 minutes; your location is checked periodically too.
• The clock stays accurate via internet time sync, so the day/night line and the card are always right. Temperature units pick themselves — °F in the United States, °C elsewhere.
• If the internet drops, the globe keeps right on spinning with the last clouds it downloaded; it simply resumes live updates when the connection returns. It also watches the connection and reconnects on its own if your router blips.

7. Troubleshooting

• The screen is blank / nothing happens: Make sure the USB-C cable is firmly seated and the power source supplies enough current (a wall charger is more reliable than a keyboard/hub port). Try a different cable or adapter.
• I don't see the Globe-Setup network: Give it ~15 seconds after power-on. If it still doesn't appear, hold the BOOT button ~3 seconds to force the setup hotspot, then look again.
• The setup page didn't open by itself: Once you've joined Globe-Setup, open a browser to 192.168.4.1 manually.
• It says it connected, but the globe looks dim or the day/night line seems off at first: On first power-up it needs a moment to sync the clock over the internet; the lighting corrects itself within a minute. If it persists, your WiFi may be blocking time sync — try a different network.
• The clouds look plain / there are no clouds: The first satellite image downloads a little after boot — give it a few minutes. Clouds only appear on Earth with the Earth clouds setting On, and require an internet connection.
• No city lights: City lights only show on Earth, on the night side, with Earth city lights On. The daytime hemisphere never shows them.
• The time/weather card never appears: It's Off by default — switch Time & Weather to a schedule on the settings page. It also needs the internet (for time, location, and weather) to show.
• The motion looks choppy: Make sure you're on current firmware; you can also turn on Performance mode for a higher frame rate. (Smooth motion at all time-lapse speeds is expected behavior.)
• I moved it to a new house / new WiFi: Hold BOOT ~3 seconds (or use Forget WiFi) and run setup again. The globe keeps up to three networks, so it'll also reconnect automatically if you bring it back.

8. Technical specifications

• Display: 1.75" round AMOLED, 466 × 466 px (LilyGo T-Display-S3 AMOLED, CO5300 QSPI)
• Processor: Espressif ESP32-S3 (dual-core 240 MHz)
• Memory: 8 MB PSRAM · 16 MB flash
• Connectivity: WiFi 802.11 b/g/n (2.4 GHz)
• Power: USB-C, 5 V
• Controls: BOOT button (hold ~3 s to reset WiFi)
• Data sources: NASA GIBS / VIIRS (clouds & base map), ip-api.com (approx. location), Open-Meteo (weather), NTP (time) — all free, no API keys or accounts

A note on privacy

To show local weather, the globe asks ip-api.com for your approximate city based on your internet address, then sends those coordinates to Open-Meteo for the forecast. It contacts NASA for cloud imagery and a time server for the clock. It does not create an account, require a login, or send any personal data, and nothing is stored in the cloud. If you'd rather it stay fully local, set Time & Weather to Off (the live Earth itself still needs internet only for clouds).

Appendix — For the maker (build, flash & assets)

This globe is a custom ESP32-S3 / PlatformIO firmware project. The whole device program is a single file, firmware/src/main.cpp; host-side Python tools that generate textures and verify visuals live in backend/.

Build & flash:

cd firmware
pio run -e lilygo-t-display-s3-amoled -t upload      # firmware
pio run -e lilygo-t-display-s3-amoled -t uploadfs    # LittleFS assets in data/ (~11.6 MB across 12 binaries, slow)

Serial monitor: 115200 baud over USB-C (USB-CDC). A boot heartbeat prints the frame rate, time-lapse scale, and active cloud buffer.

Regenerating image assets: the planet textures, night lights, and the card font/icon atlas are produced by the backend/ generators (e.g. python backend/gen_planets.py, python backend/gen_card_assets.py). After regenerating, run uploadfs and reflash so the firmware and assets stay in sync — flashing one without the other will corrupt the card. Because the device screen can't be captured, every visual change is validated against the Python replicas in backend/ (simulate_realtime.py for the globe, verify_assets.py for the card) before flashing.