Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Surf Grid

Surf Grid Sequence.gif

Surf Grid is a Pi Frame app. It prints an abstract surf report in the style of Kōhei Sugiura to an e-ink display via Raspberry Pi.

Surf Grid relies on the WillyWeather API for location-specific wind, tide, and swell forecast data.


To run Surf Grid 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

Surf Grid 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 Surf Grid’s. Here's an example:

└── surf-grid
└── lib
    └── waveshare_epd
        └── epd5in83_V2

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 Surf Grid repository over to the main directory of your Raspberry Pi.

Set the display driver

Look for this line as the last import in

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
sudo apt-get install python3-scipy

Enter your WillyWeather credentials

Fill out an file in the Surf Grid directory with your WillyWeather API key. An example is provided in

Run the app

Run Surf Grid just like you would any other Python file on a Raspberry Pi:

cd surf-grid

Surf Grid is noisy by default. Look for the results in Terminal.


Run on a schedule

See Pi Frame for a crontab template and usage instructions.

Design options

Surf Grid contains several visual design parameters in

Option Type Description
showWindTail Boolean Shows a visual of the wind direction. Note that the wind direction is taken into account for the dotSize calculation.
hourStart Integer An hour of the day. Sets the first column of the grid.
hourEnd Integer A later hour of the day. Sets the last column of the grid.
cols Integer The amount of columns between (and including) hourStart and hourEnd.

Several more design option variables exist to affect dot size and grid composition.

Location options

Surf Grid defaults to Coolum Beach, Queensland, Australia. Given that beach on the east coast of Australia, Surf Grid determines westerly winds as favourable offshore winds and easterly winds as poor onshore winds. Here’s where that parameter is passed, amongst other location-specific parameters:

Option Type Description
locationId Integer Sets where the surf forecast is for. See the API documentation for finding your location’s ID.
locationMaxTideHeight Integer Maximum tide height for that location in metres. Affects how tall tides are drawn.
locationMaxSwellHeight Integer Maximum swell height for that location in metres. Affects dotSize.
locationWindDirRangeStart Integer Start degree (going clockwise) for optimal wind origin. Affects dotSize.
locationWindDirRangeEnd Integer End degree (going clockwise) for optimal wind origin. Affects dotSize.
locationWindDirRangeBuffer Integer A buffer range on either end for minimal dotSize scoring.

Save to folder

Surf Grid contains an exportImages boolean option in When True it saves both an image and text file to a timestamped directory within an exports directory.