Globe Software
Complete interactive globe visualization system with hardware control, media playback, and web interface.
Overview
Globe Software is a complete system for controlling and visualizing content on a physical rotating globe display. This package includes both the FastAPI backend server and the React web interface as static files.
WARNING: This package is designed to be used on the Globe platform hardware - use on other systems may result in unexpected behaviour like forced network disconnects.
Features
- Web Interface: React-based UI for controlling the globe (served as static files)
- FastAPI Backend: High-performance async web server with REST API
- Globe Visualization: Real-time 3D globe rendering with earth-viz
- Media Management: Upload and manage video/image content with playlist support
- Hardware Control: Interface with ESP32 (motor) and FPGA (display) hardware
- Network Management: WiFi configuration, network switching, and access point mode
- Automatic Updates: Online (PyPI) and offline (.whl) update support
- Real-time Communication: WebSocket support for live status updates
Installation
Quick Install
pip install globe-server
Initial Setup
After installation, run the setup wizard to configure the system:
globe-server-setup
This will:
- Create the
~/.globe-server/directory structure - Download required static images for visualization
- Prompt for configuration (ESP32 API key, WiFi credentials, etc.)
Production Deployment (Raspberry Pi)
For production deployment on Raspberry Pi, see the installation guide which covers:
- Creating the installation directory and virtual environment
- Installing as a systemd service
- Automatic startup and update management
Usage
Starting the Server
# Start the server
globe-server
The server will start on http://localhost:8000 and serve:
- Web interface at
http://localhost:8000/ - API documentation at
http://localhost:8000/docs - Alternative API docs at
http://localhost:8000/redoc
Accessing the Web Interface
Once the server is running, open your browser to:
http://localhost:8000(local access)http://<raspberry-pi-ip>:8000(remote access)
The web interface provides:
- Media upload and playlist management
- Globe visualization controls
- Motor speed and rotation control
- Network and WiFi configuration
- System settings and firmware updates
Command Line Options
# Start with default settings
globe-server
# Or use uvicorn directly for custom configuration
uvicorn globe_server.main:app --host 0.0.0.0 --port 8000 --reload
Configuration
The server stores configuration and data in ~/.globe-server/:
.env- Environment variables (API keys, WiFi credentials)globe.db- SQLite databasemedia/- Uploaded media filesupdates/- Software update packages (.whl files)logs/- Application logs
Key configuration settings (from globe_server.config):
GLOBE_DATA_DIR:~/.globe-server(base directory)GLOBE_MEDIA_DIRECTORY: Media storage locationUPDATE_DIRECTORY: Software update packagesMOTOR_RPM: Default motor rotation speedESP32_API_KEY: Authentication for ESP32 communication
System Architecture
┌─────────────────┐
│ Web Interface │ (React - served as static files)
│ Port 8000 │
└────────┬────────┘
│ HTTP/WebSocket
┌────────▼────────┐
│ FastAPI Server │ (Python)
│ Port 8000 │
└────┬───────┬────┘
│ │
│ └──────────┐
┌────▼────┐ ┌──────▼──────┐
│ ESP32 │ │ FPGA │
│ (Motor) │ │ (Display) │
└─────────┘ └─────────────┘
API Endpoints
The REST API provides programmatic access to all features:
/- Web interface (static files)/media/*- Media file management and playback/playlist/*- Playlist operations/motor/*- Motor control (ESP32)/status/*- Server status and WebSocket updates/settings/*- Server configuration/update/*- Software and firmware updates (server, ESP32, FPGA)/network/*- Network and WiFi management/earth-viz/*- Globe visualization rendering
Full interactive API documentation available at /docs when server is running.
Software Updates
Globe Software supports both online and offline updates:
Online Updates (PyPI)
When connected to the internet, the system automatically checks for updates on startup (when using the systemd service).
Offline Updates
For systems without internet access:
- Download the update bundle (
.whlfiles for the package and all dependencies) - Copy all
.whlfiles to~/.globe-server/updates/ - Restart the server
The startup script will automatically install from local files if PyPI is unavailable.
Development
From Source
git clone https://github.com/edcatley/Globe-Software.git
cd Globe-Software/backend
pip install -e .[dev]
Running Tests
pytest
Code Quality
# Format code
black src/
# Type checking
mypy src/
Links
- GitHub Repository: https://github.com/edcatley/Globe-Software
- Issue Tracker: https://github.com/edcatley/Globe-Software/issues
- Installation Guide: https://github.com/edcatley/Globe-Software/blob/main/INSTALL.md
Requirements
Software
- Python 3.8 or higher
- VLC media player (for video/image playback)
Hardware (Optional)
- Raspberry Pi (tested on Bookworm)
- ESP32 microcontroller (for motor control)
- FPGA (for display control)
The system can run without hardware for development and testing.
Python Dependencies
All Python dependencies are automatically installed:
- FastAPI & Uvicorn (web server)
- SQLite (database)
- VLC Python bindings (media playback)
- PyQt5 & PyQtWebEngine (visualization windows)
- earth-viz (globe rendering)
- pyserial (UART communication)
- zeroconf (network discovery)
See the pyproject.toml for the complete dependency list.
Author
Edward Catley (edward.catley@catleytech.com)
License
MIT License - see LICENSE for details
1 maintainer
Metadata
1 maintainer
Release files for globe-server 0.0.145
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| globe_server-0.0.145.tar.gz | 377.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| globe_server-0.0.145-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 781.0 kB
Release files / globe_server-0.0.145.tar.gz
| Download URL | globe_server-0.0.145.tar.gz |
|---|---|
| Size | 377.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
258f55e6baa6efb55963da838aca4eda369515728986e79ec5555557ff04fdac
|
|
BLAKE2b-256 checksum How to use checksums |
0709184982bf43a18ed98fc54ad7fc8c019d8be50e2421072d49a184dc9194ad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.
Transparency logRelease files / globe_server-0.0.145-py3-none-any.whl
| Download URL | globe_server-0.0.145-py3-none-any.whl |
|---|---|
| Size | 403.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e3e8a189cb4dc1d8e155380d169103671fa3c4509fac7959377fbf53f43cc4a5
|
|
BLAKE2b-256 checksum How to use checksums |
689a62e90c4ce2a971730c8d8f3f04dd2d8e3a7db1ebf8994ba9607ec52a79ac
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 7, 2026.
Transparency log
