Planetaria

Owner's Manual & Feature Guide

A desktop digital twin of Earth.

A little window onto the living Earth. Your Planetaria shows the planet exactly as it looks from space right now — the real day/night line sweeping across the continents, live cloud cover pulled straight from NASA satellites, and the warm glow of city lights spreading over the night side. It can also wander the solar system and, on a schedule you choose, flip to a full‑screen time + local weather card.

Everything runs on the globe itself. There's no app to install and no account to create — just connect it to your home WiFi once and leave it on.

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 Planetaria-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 Planetaria Setup page.
4. Enter your home WiFi in the WiFi network and WiFi password boxes, then tap Save & Restart.
5. Watch the page — it hands you the address. The globe connects to your WiFi while you're still on the setup page (about 10–30 seconds), then the page shows the globe's new settings address (like http://192.168.1.42). If the password was wrong, it says so — just go back and retype it.

   If the page just keeps spinning, don't worry: some phones hop off the globe's hotspot at this moment. Look at the globe instead — after it restarts it shows its address on screen, big and long enough to type into your browser.

6. Done. Reconnect your phone to your own WiFi. The globe restarts, syncs the time, and within a minute or two shows the live Earth (the first cloud image downloads in the background).

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

Tip: The globe shows its web address (an IP like 192.168.1.42) on screen at every start‑up. Type that into a browser on the same WiFi any time to reopen the settings page. On iPhone, Mac, and most PCs, http://planetaria.local works too (many Android phones can't open .local names — use the IP address there).

At a school or office? If your network needs a username as well as a password (an "enterprise" network), the setup page detects that automatically and shows a Username field — just fill it in along with your password. A collapsible Advanced section there lets you add a security certificate if your IT department provides one (optional). See Troubleshooting if it still won't go online.

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 downloaded daily from NASA's VIIRS satellites and draped over the globe, 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 Space Station. A small white‑and‑cyan marker rides across the globe at the ISS's real position, computed on the device from its published orbit (refreshed twice a day). In a time‑lapse it visibly orbits — a full lap every few seconds.

The other worlds

Your globe isn't limited to Earth. From the settings page you can switch it to any of eleven views, in this order:

Earth · Mercury · Venus · Mars · Jupiter · Saturn · Uranus · Neptune · Moon · Sun · Night Sky

Night Sky turns the globe into a live planisphere: the stars and constellations above your location right now, with north at the top and east on the left (hold it up toward the sky and it matches) — and the Moon drawn at its true position with its current phase, lit limb pointing toward the Sun just like the real one. The stars wheel with the clock — try a time‑lapse. The Moon view is special: like the real, tidally‑locked Moon it keeps its near side toward you, and its terminator is the Moon's actual phase tonight — new, crescent, quarter, or full, computed on the device. The other worlds are rendered from real imagery with the same sunlight‑and‑shadow treatment, so Mars 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 (the first showing after power‑on is a shorter ~8‑second hello). Out of the box it appears every 30 minutes — change the schedule, or turn it off, on the settings page (see below).

3. Features at a glance

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) — it's also displayed on the setup page right after you save your WiFi. On iPhone, Mac, and most PCs http://planetaria.local works as well (many Android phones can't open .local names — use the IP address). During first‑time setup the address is 192.168.4.1. The page is titled 🌐 Planetaria 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 only restarts the globe when a change requires it (anything in the "Restart" rows above). If you only touched instant settings — including switching the displayed world — the page just saves and returns while the globe updates live.

▶ Run the demo tour (the green button under Save) walks the globe through everything it can do — live Earth with the Space Station, all eight planets, a full month of Moon phases in a few seconds, the Sun, a complete 24‑hour wheel of the Night Sky, and the weather card — about two and a half minutes, then the globe returns to your settings on its own. Great for showing the globe off; saving any setting during the tour simply ends it early.

5. Resetting WiFi / moving to a new network

The globe has no power switch (it runs whenever it's plugged in) and one physical button, BOOT, which may be tucked inside the case. You can reopen WiFi setup in any of four ways — and the first one needs no button and no tools:

1. Power‑cycle it 3 times (no button needed). Switch the power off and on three times in a row, leaving it on only a second or two each time. On the third power‑on, the Planetaria-Setup setup screen reappears. This is the easiest way to switch networks on a globe in a sealed case — and it keeps your saved networks, so if you trigger it by accident it just reconnects on its own after a few minutes.
2. Use the web page. On the settings page, tap "Forget WiFi & reopen setup" at the bottom and confirm. (This erases saved networks.)
3. Hold the BOOT button for ~3 seconds (if it's reachable). The globe forgets all saved networks and reopens the Planetaria-Setup hotspot. (Also erases.)
4. Automatic. If a saved network ever disappears — you moved, the router or its password changed — the globe can't connect and reopens the Planetaria-Setup hotspot on its own: right away at start‑up, or after a few minutes if it drops while running.

After reaching the setup screen, follow the Quick Start steps again. On the setup page you can add the new network — tap Forget first if you also want to clear the old ones.

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 sooner if a download fails). If today's worldwide image isn't finished yet, the globe automatically falls back to the most recent complete day.
• Weather updates about every 30 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 Planetaria-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 Planetaria-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.

It connects but shows "No internet yet." The globe joined the WiFi but couldn't reach the internet. This is common on school, office, or guest networks, which often (a) need a username (see next item), (b) make you accept terms / sign in on a web page first — which a screen‑only device can't do, or (c) block the services the globe uses. A home network or a phone hotspot is the sure bet.

It won't connect at school or work. Those networks are usually enterprise (802.1X) — they need a username, not just a password. On the setup page, pick the network and a Username field appears automatically; enter your school/work username and password. (For a hidden enterprise network, tick "This network needs a username (enterprise)" to reveal the field.) If it still won't go online, the network likely requires a browser sign‑in or blocks outside services, which a headless device can't pass.

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. Check that Time & Weather isn't set to Off on the settings page (it comes set to every 30 minutes). It also needs the internet (for time, location, and weather) to show.

The motion looks choppy. Check Performance mode on the settings page — On (the out‑of‑the‑box setting) is the smoothest. Off gives the sharpest image but visibly steppier motion during a time‑lapse; that trade is expected. Slower Motion speeds also look smoother than fast.

The image looks a little soft. That's Performance mode trading a touch of sharpness for smooth motion. For the sharpest image, set it to Off (best with Motion: Real Earth, where the globe barely moves) — or Auto, which gives the sharp image at real speed and switches to smooth rendering only while a time‑lapse is spinning.

I moved it to a new house / new WiFi. If the old network is gone, the globe notices it can't connect and reopens the Planetaria-Setup setup screen on its own — just run setup again. To switch networks while the old one still works (or on a globe in a sealed case), power‑cycle it 3 times (off and on, a second or two each time) to bring setup back without the button. The globe remembers up to three networks, so it'll also reconnect automatically if you return.

The button is inside the case — how do I reset WiFi? You don't need it. Power‑cycle the globe 3 times (off and on, only a second or two each time); on the third power‑on the Planetaria-Setup setup screen reappears. This keeps your saved networks, so an accidental triple power‑cycle simply reconnects after a few minutes.

8. Technical specifications

A note on privacy

To show local weather, the globe asks geojs.io for your approximate city based on your internet address, then sends those coordinates to MET Norway 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).

Credits: weather data from MET Norway; imagery courtesy NASA GIBS/ESDIS; planet textures © Solar System Scope (CC BY 4.0); star data from the Yale Bright Star Catalogue; constellation figures © Olaf Frohn / d3-celestial (BSD-3-Clause); ISS orbital elements from CelesTrak.

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/.

Flashing a device — three ways, easiest first:

1. Web installer (no software): open https://cosnfx.store/planetaria/install.html in Chrome or Edge on a computer, plug the globe in via USB‑C, and click Install Planetaria. Writes the complete device (firmware + assets); the globe starts fresh and asks for WiFi.

   Which port? This chip (ESP32‑S3, native USB) can appear as two COM ports — one for running, one for flashing. Pick the one named "USB JTAG/serial debug unit." If in doubt, hold BOOT, tap RESET, release BOOT first — that leaves only the flashing port. Ignore any CP210x, CH340, or Bluetooth ports.

2. One‑command USB flash: plug in one board and double‑click flash/flash.bat (full image, fresh start). To update firmware on a device without losing its WiFi and settings, use flash/flash-fw-only.ps1. Rebuild the merged image after any change with flash/build-image.ps1.
3. PlatformIO (development): sh 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/ (~12 MB, slow)

Serial monitor: 115200 baud over USB‑C (USB‑CDC). A periodic heartbeat prints the frame rate, time‑lapse scale, performance mode (and whether it's active), and the cloud buffer in use — the primary measurement hook for render performance. Note: a web‑installer browser tab can hold the serial port after flashing — close the tab if a flasher or monitor reports the port busy.

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.

Planetaria — live Earth, real clouds, your weather.