Where ISS

Where ISS is a Pi Frame app. It prints what the International Space Station sees of Earth to an e-ink/e-Paper display via Raspberry Pi.

Where ISS relies on the Open Notify International Space Station Current Location API for tracking the whereabouts of the space station and the Mapbox Raster Tiles API for rendering subsequent map tiles.

Prerequisites

To run Where ISS you need to first:

1. Join a Wi-Fi network on your Raspberry Pi
2. Enable SSH on your Raspberry Pi
3. Plug in a Waveshare e-Paper or similar display to your Raspberry Pi

Where ISS works great with Pi Frame, which includes the Waveshare drivers amongst other things like a scheduling template. If you’d prefer not to use Pi Frame, you’ll need to upload the Waveshare e-Paper display drivers (or similar) to your Raspberry Pi in a lib directory that is a sibling of Where ISS’. Here's an example:

.
└── where-iss
└── lib
    └── waveshare_epd
        ├── __init__.py
        ├── epdconfig.py
        └── epd5in83_V2.py

Either way, Waveshare displays require some additional setup. See the Hardware Connection and Python sections of your model’s manual.

Get started

If you haven’t already, copy all the contents of this Where ISS repository over to the main directory of your Raspberry Pi.

Set the display driver

Look for this line as the last import in app.py:

from waveshare_epd import epd5in83_V2 as display

Swap out the epd5in83_V2 for your Waveshare e-Paper display driver, which should be in the lib directory. Non-Waveshare displays should be imported here too, although you’ll need to make display-specific adjustments in the handful of places display is called further on.

Install required packages

See requirements.txt for a short list of required packages. Install each package on your Raspberry Pi using sudo apt-get. Here’s an example:

sudo apt-get update
sudo apt-get install python3-pil
sudo apt-get install python3-requests

Enter your Mapbox credentials

Fill out an env.py file in the Where ISS directory with your Mapbox access token. An example is provided in env.example.py.

Run the app

Run Where ISS just like you would any other Python file on a Raspberry Pi:

cd where-iss
python3 app.py

Where ISS is noisy by default. Look for the results in Terminal.

---

Usage

Run on a schedule

See Pi Frame for a crontab template and usage instructions.

Design options

Where ISS contains several visual design parameters in app.py.

Option	Type	Description
minForegroundPercentage	Integer	The minimum percentage for the foreground colour. A map tile with less than this will not be printed.
maxZoomLevel	Integer	The maximum (and starting) zoom level for the map tile.
minZoomLevel	Integer	The minimum zoom level for the map tile. A map tile that doesn’t pass minForegroundPercentage rules and is at minZoomLevel will not be printed.
invertZoomLevel	Integer	At what zoom level to invert the colours. Can make for better legibility of coastlines.
contrast	Integer	A Pillow .enhance value for ImageEnhance.Contrast.

Save to folder

Where ISS contains an exportImages boolean option in app.py. When True it saves both the original colour image, a processed image, and text file to a timestamped directory within an exports directory.