Make a Tide Tracker with APIs and an e-ink display

Surf’s up, or is it? Save yourself a wasted trip to the beach with The MagPi’s handy tide tracker.

Tides are predictable, but it’s still easy to lose track of the times for high and low water. As a result, you might pull up at high tide to find the beach has disappeared… or at low tide, and found your boat grounded. Put an end to that once and for all with our handy tide tracker, which uses an API to download tidal forecasts for more than 600 monitoring stations around the UK. The results shouldn’t be used for navigation or other water-borne activities, but they may be just what you need to save yourself a wasted journey, or to keep an eye on the tide cycles however far you live from the coast.

01. Attach a header

We’re using a Raspberry Pi Zero 2 W for this project. If you’re using the same and don’t already have a GPIO header in place, you’ll need to solder one using the two rows of connectors at the top edge of the board. If you’re not comfortable soldering, instead use a GPIO Hammer Header, which you can knock into position using a hammer and installation jig. Once your headers are fixed, attach the e-ink display, then connect your Raspberry Pi to a USB power source and allow it to boot

02. Install display libraries

Whatever display you’re using, you’ll first have to install the libraries that Python needs when it wants to communicate with it. We’re using an Inky pHAT, for which Pimoroni has published an excellent getting started guide. Follow the instructions there for installing the necessary software, by opening a new Terminal window (click the icon on the taskbar) and typing:

curl https://get.pimoroni.com/inky | bash

When the process has finished, reboot your Raspberry Pi.

03. Register for an Admiralty account

We’re going to use data compiled by the UK Hydrographic Office. Although it charges for much of its data, its free Discovery tier gives access to data for 607 tidal stations around the UK. Open a browser window at magpi.cc/uktidalapi, check the Terms of Use and, if you’re happy to be bound by them, set up an account by subscribing to the service. When your account is up and running, log in, then click your name at the top right of the page, followed by Profile. Click Show on the line beside ‘Primary key’, and copy the subscription key this reveals into a plain text document for later use.

04. Find your tidal station

You now need to find the numeric identifier of the tidal station whose data you want to retrieve. While still logged in, point your browser at magpi.cc/tidalstations and type the name of a coastal location in the box labelled ‘name’. Leave everything else on the page as it is, and click the Send button. Assuming you entered a valid location, the query’s output will appear in the ‘Response content’ box. Copy the variable beside Id in the Properties section. We searched for Broadstairs, for which the ‘Id’ variable reads 0102A. You’ll need to include the station identifier in your query.

05. Understand how tides work

Our gauge will illustrate the tide’s rise and fall at any station, always showing how far it is from its maximum or minimum height. We don’t need live height data to produce the graph if we apply the rule of twelfths, which governs how tides move and gives a good approximation of the current position based on the interval between the most recent and next low or high tide. If you break down the interval into six equal periods, the tide height will change by 1/12th of its total range in the first and last periods, by 2/12th (a sixth) of its range in the second and fifth periods, and by 3/12th (a quarter) of its range in the third and fourth periods. You’ll apply these ratios in the code.

06. Get coding

Type out or download the tides.py code and amend it to your requirements, changing lines 3 to 14 as appropriate if you’re using a different e-ink display. Replace on line 19 with the ID of the tidal station you’re monitoring, and with your subscription key. Lines 23 to 33 are worth closer examination. Because the query pulls down every low or high tide event for 48 hours, you need to find when the next one is due. So, the code first cycles through each event in the returned data and converts its time stamp to its UNIX equivalent, which counts the number of seconds since 1 January 1970.

07. Deal with the unexpected

Notice how line 26 reads:

at = at[:19]

The variable at holds the time stamp associated with each high or low tide event. Usually this takes the 19-character form YYYY-MM-DDTHH:MM:SS (as you’ll see, there’s a T in the middle, which marks the transition from date to time). However, occasionally the time stamp returned by the query is more specific, and includes an additional half second. We need to discard this in our calculations, so line 26 trims the contents of the at variable to 19 characters before moving on. If there was no additional half second, this would have no effect, but also wouldn’t throw up an error.

08. Calculate the tidal cycle

As the code continues cycling through the data, it stores the time of each tidal event until it reaches the first one that hasn’t yet happened, then quits the loop. It now has two time stamps stored in variables: one for the previous event, and one for the next. Subtracting the former from the latter tells us how long, in minutes, the transition from low to high or high to low tide takes. We divide 100 by that number to work out what proportion, in percentage terms, is represented by a single minute. Then, in lines 54 to 71, we set a multiplier, based on our rule of twelfths, that will allow us to plot a fair approximation of the tide’s position within its cycle on our display.

09. Define the bar chart

The tide’s progress will be tracked using a bar chart, the length of which is calculated on lines 82 to 84. However, it wouldn’t be clear from just a glance at the bar whether the tide was rising or falling. So, it’s accompanied by a line of text indicating what the next event is (high or low tide) and when it will occur. For the latter part of the text (the bit dealing with the time), we’ll extract a subsection of the data held in the variable at. On line 86, we assign the 11th to 16th characters of at, which contains the two hour digits, a colon, and two minute digits, to a new variable called event_time.

10. Refresh the display

Now that our code has constructed the display’s contents in memory, we need to transfer it to the e-ink panel. This task is handled by lines 106 and 107, which send the constructed image to the screen when we run the code in step 11. If you’re using a colour display, you may notice that it will take a few seconds to refresh. This is normal. However, if you want to speed it up, go back into your code and change line 9 to:

inky_display = InkyPHAT("black")

11. Run your code

If necessary, move the code into the root of your user folder and save it as tides.py. Now, open a Terminal window by clicking the icon on the taskbar. At the prompt, type:

python3 tides.py

…and press RETURN. The Python interpreter will run your code and, after a few seconds, you should see the display refresh to show the current tidal position, with details of the next tidal event on the line below.

12. Run your code automatically

Assuming your code did what you expected, you can set it to run automatically and refresh at set intervals. Type:

crontab -e

If you’ve never edited crontab before, you’ll be asked which tool you want to use. Select 1 for Nano. When Nano opens, key down to the bottom of the file, create a new line, and type:

@reboot python3 /home/pi/tides.py &

*/10 * * * * python3 /home/pi/tides.py

The first line tells Raspberry Pi OS to run your code as soon as it starts, with the & at the end telling it to run the process in the background. The second line tells it to run the code every 10 minutes thereafter. Press CTRL+X to quit Nano, confirm that you want to save your edit, then reboot your Raspberry Pi.