A Home Assistant (HASS) integration to show tide information for stations provided by the UK Hydrographic Office (UKHO).
It provides an entity for each station that you follow, showing whether the tide is currently rising or falling, and how long until the next high and low tides.
Height chart displayed via the ApexCharts Lovelace UI card. See below for details.
This integration plugs into the Admiralty Tidal API via the ukhotides PyPI package, which I also wrote for this project.
I've only recently fallen into the rabbit hole that is home automation, and this is my first attempt at a custom integration for HASS. Admittedly, I can think of very few use cases for such an integration. Maybe it would be useful for someone living on a house boat... Either way, this project has mostly been an opportunity to learn more about how HASS works, as well as is my first foray into Python.
First up, you will need an API key from the Admiralty Maritime Data Solutions developer portal. Follow their guide on how to do so and select one of the UK Tidal API products - the Discovery tier is free (the paid APIs are untested for this integration, but should in theory work fine).
Note that the "Products" section expands over several pages, with the "UK Tidal API - Discovery" option a bit harder to find on the second page. Alternatively you can also use the search function at the top right to find the string "discovery" and it should show up in the results list.
I am still working on submitting this as a HACS integration, however in the meantime you can still use the "Custom Repository" feature of HACS to download it. Alternatively, the manual download steps are in the next section.
custom_components
directoryFor manual installation, simply copy/download the ukho_tides
directory from this repo directly into your custom_components
directory.
Once the files are in your custom_components
directory, it can then be configured via either the User Interface, or the configuration.yaml
file.
In HASS, navigate to Configuration --> Integrations --> Add Integration and then search for UKHO Tides.
Follow the prompts to select the API level you are using and paste your API key.
Use the dropdown menu to select which station(s) you would like to follow.
Enter a custom name for each station, as well as any offset (in minutes) from which to adjust the tide data. Unfortunately, due to a limitation in the UI configuration, this section has no labels. The order of fields, from top to bottom, is 'Station Name', 'High Tide Offset', 'Low Tide Offset'.
The above steps make use of the UI to configure the component. The legacy way is via the configuration.yaml
file. Simply add the following entry, and then restart your HASS:
sensor:
- platform: ukho_tides
api_key: <api_key>
stations:
- station_id: '0001'
- station_id: '0113'
station_name: 'London Bridge'
station_offset_high: -45
station_offset_low: 60
To find the id of the station(s) you would like to follow, you can use the Easytide service on the UKHO website to look up a station, either on the map or via the search tab. Once a port is selected, check the URL for the PortID
parameter and make note of its value.
For example, the station Id for St Mary's is 0001
and can be seen in its URL below:
http://www.ukho.gov.uk/easytide/easytide/ShowPrediction.aspx?PortID=0001&PredictionLength=7
You can display a height chart on the dashboard via the ApexCharts Lovelace UI card.
See their docs for how to install it - this example is using the following configuration:
type: 'custom:apexcharts-card'
graph_span: 2d
span:
start: hour
offset: '-5h'
now:
show: true
label: now
series:
- entity: sensor.london_bridge_tower_pier_tide
unit: m
data_generator: |
return entity.attributes.predictions.map((event) => {
return [moment.utc(event[0]).local(), event[1]];
});
There are a number of attributes that can be displayed:
Attribute | Example |
---|---|
next_high_tide_in |
11h 25m |
next_low_tide_in |
6h 57m |
next_high_tide_at |
7 January 2022, 01:02:14 |
next_low_tide_at |
7 January 2022, 05:30:26 |
next_high_tide_height |
5.4m |
next_low_tide_height |
0.2m |
predictions |
Contains a list of upcoming predictions for internal use |
You can use an Entities Card to display them on your Lovelace Dashboard:
type: entities
entities:
- entity: sensor.hammersmith_bridge_tide
name: Tide State
- type: attribute
entity: sensor.hammersmith_bridge_tide
attribute: next_high_tide_in
name: Next High Tide In
icon: mdi:waves
- type: attribute
entity: sensor.hammersmith_bridge_tide
attribute: next_high_tide_height
name: Next High Tide Height
icon: mdi:waves
- type: attribute
entity: sensor.hammersmith_bridge_tide
attribute: next_low_tide_in
name: Next Low High Tide In
icon: mdi:wave
- type: attribute
entity: sensor.hammersmith_bridge_tide
attribute: next_low_tide_height
name: Next Low High Tide Height
icon: mdi:wave
title: Local Tides
Note that a full list of icons can be found at the Material Design Icons site.
Contains ADMIRALTY® Tidal Data: © Crown copyright and database right