This binding retrieves Australian weather forecast and meteorological images from Bureau of Meteorology for use in openHaB/Eclipse Smarthome.
- Features
- Prerequisite
- Installation
- Weather observation and forecast configuration
- Weather forecast icons
- BOM weather items mapping and sitemap files
- BOM weather images generation
-
- BOM images background information
- BOM images configuration
- Image sources configuration fields
- Image generation configuration fields
- Image layers configuration
- Image manipulation and processing
- Local timestamp configuration
- Rain radar images configuration example
- Doppler wind images configuration example
- Rainfall images configuration example
- Satellite images configuration example
- High-definition Himawari-8 satellite images configuration example
- Mean sea-level pressure images configuration example
- Using the images
- Unsupported charts
- Example screenshots in openHAB HABPanel
- Change log
This binding maps most fields from BOM data-feed. For today's observation and forecast these are available:
- Weather station
- Observation time
- Date and time of forecast
- Forecast icon name
- Precis
- Forecast text
- Minimum temperature
- Maximum temperature
- Possibility of precipitation
- UV alert text
- Apparent temperature
- Air temperature
- Dew point
- Relative humidity
- Atmospheric pressure
- Wind direction
- Wind direction in degrees
- Wind speed in km/h
- Wind speed in Knots
- Rainfall
- 24 Hour rainfall
For future forecasts the following fields are available:
- Date and time of forecast
- Forecast icon name
- Precis
- Forecast text
- Minimum temperature
- Maximum temperature
- Probability of precipitation
- Minimum precipitation
- Maximum precipitation
- UV alert text
BOM images, like rain radar, rainfall and satellite images, can retrieved and processed. You have the option of:
- Retrieve the image sequence filenames for use in custom template with custom AngularJS animation code.
- Generate animated GIF from a sequence images.
- Generate individual PNG images from a sequence of images.
See below for more details.
- openHAB 2.4 to 2.5.x
- Java 1.8 and above.
- Fonts installed if local timestamp is enabled for BOM Image.
- openHAB 3.0.0 and above
- Java 11 and above.
- Fonts installed if local timestamp is enabled for BOM Image.
For openHAB install Eclipse IoT Market add-on under MISC tab in openHAB Paper UI. Then install Australian BOM Weather Forecast Binding from the Bindings page.
For Eclipse SmartHome install from https://marketplace.eclipse.org/content/australian-bom-weather-forecast-binding.
Download the latest jar below for your openHAB version and copy to the openHAB addons directory.
Version 3.2.x Download
Version 3.0.0 Download
Version 3.0.3 Download
Version 2.5.9 Download
Version 2.5.0 Download
Unfortunately, it can be quite daunting to configure this binding due to the lack of index of all the data files available from BOM. Hopefully the details below is sufficient to get the binding up and running on your openHAB. In the future an external tool might be coded to make this binding less difficult to configure.
At minimum there are five values required to process the data-feed from BOM. The observation product ID, the weather station ID of observation, the precis product ID, the city/town product ID and finally the area code.
Observation product ID and weather station enables you show the relevant current weather information in your area. Precis forecast data provides brief forecast information for the next 5-8 days. City/town/district forecast data provides the detailed forecast description.
Listed below is the observation product ID's for the states. Enter the ID you need into the Observation product ID field in Things configuration in openHAB.
| State | Observation Product ID |
|---|---|
| NSW | IDN60920 |
| ACT | IDN60920 |
| NT | IDD60920 |
| QLD | IDQ60920 |
| SA | IDS60920 |
| TAS | IDT60920 |
| VIC | IDV60920 |
| WA | IDW60920 |
The next step is to open the product XML by loading ftp://ftp.bom.gov.au/anon/gen/fwo/{product-id}.xml in your browser. Replace {product-id} with the ID of your state from the table above. Locate the weather station of interest. Copy the wmo-id number and use this as the Weather station ID.
For example: PERTH METRO station ID in the file ftp://ftp.bom.gov.au/anon/gen/fwo/IDW60920.xml is 94608.
Next you will need to provide the precis forecast product ID and city/town/district forecast product ID.
Below is a list of the forecast product ID's for Australian major cities. If you do not live in the cities listed below then follow the instruction to locate your city, town or district.
| City | Precis Forecast Product ID | City Forecast Product ID |
|---|---|---|
| Darwin (NT) | IDD10207 | IDD10150 |
| Canberra (ACT) | IDN11060 | IDN10035 |
| Sydney (NSW) | IDN11060 | IDN10064 |
| Newcastle (NSW) | IDN11060 | IDN11051 |
| Central Coast (NSW) | IDN11060 | IDN11052 |
| Wollongong (NSW) | IDN11060 | IDN11053 |
| Alpine Centres (NSW) | IDN11055 | IDN11055 |
| Brisbane (QLD) | IDQ11295 | IDQ10095 |
| Gold Coast (QLD) | IDQ11295 | IDQ10610 |
| Sunshine Coast (QLD) | IDQ11295 | IDQ10611 |
| Adelaide (SA) | IDS10044 | IDS10034 |
| Hobart (TAS) | IDT16710 | IDT13600 |
| Launceston (TAS) | IDT16710 | IDT13610 |
| Melbourne (VIC) | IDV10753 | IDV10450 |
| Geelong (VIC) | IDV10753 | IDV10701 |
| Mornington Peninsula (VIC) | IDV10753 | IDV10702 |
| Perth (WA) | IDW14199 | IDW12300 |
NOTE: If the forecast product ID's you are after are not in the list go to this catalogue page http://reg.bom.gov.au/catalogue/anon-ftp.shtml and search for the products. The type must be "Forecast". Use the Search box on the page by entering, e.g "(WA)", or something more specific like "City Forecast":
- Locate
Precis Forecast XML Package ({your-state})from the search results and enter the product ID into the field Precis forecast product ID back in Thing configuration. - Locate
City Forecast - {your-city} ({your-state})for city forecasts ORTown Forecast - {your-town} ({your-state})for town forecasts ORDistrict Forecast - {your-district} ({your-state})for district forecasts from the search results. Enter the product ID into the configuration field City/town/district forecast product ID in openHAB configuration.
Now open either the precis or the city/town/district forecast XML (ftp://ftp.bom.gov.au/anon/gen/fwo/{product-id}.xml) and locate the area code (aac code).
For example: Perth's aac code in ftp://ftp.bom.gov.au/anon/gen/fwo/IDW12300.xml is WA_PT053.
Save your configuration. openHAB will begin to download all the required weather information in a few seconds and made available to you to display.
For more information about data-feeds, please go to http://reg.bom.gov.au/catalogue/data-feeds.shtml
Screenshot below shows an example configuration in Paper UI.
The following table shows all the possible icon names returned by the channel. You may use these to determine which forecast icon to show in the mobile app/browser. Setting this up is beyond the scope of this document. Discussion about this is available in the openHAB community forum.
| Forecast | Icon name |
|---|---|
| Sunny | sunny |
| Clear | clear |
| Mostly sunny | mostly-sunny |
| Cloudy | cloudy |
| Hazy | hazy |
| Light rain | light-rain |
| Windy | windy |
| Fog | fog |
| Shower | shower |
| Rain | rain |
| Dusty | dusty |
| Frost | frost |
| Snow | snow |
| Storm | storm |
| Light shower | light-shower |
| Heavy shower | heavy-shower |
| Cyclone | cyclone |
Creating items and linking them for eight days of forecasts can be tedious. Provided below is the items mapping file that you can drop into the "items" folder, typically in /etc/openhab2/items under Linux or C:\openHAB2\conf\items under Windows. The prerequisite is to name the BOM Thing ID "default". If you would like name your BOM Thing ID as something else, edit the file and rename accordingly.
https://github.com/tomitan100/org.openhab.binding.bom/raw/master/doc/bom.items
Also provided below is the site map where you can modify and drop into /etc/openhab2/sitemaps.
https://github.com/tomitan100/org.openhab.binding.bom/raw/master/doc/bom.sitemap
BOM images, like rain radar loop, are made up of a series of transparent PNG files, which get updated frequently as data is made available. These images contain only the transparent radar/satellite scans and do not include static overlays like the the background, topography, locations, borders, etc. The final image is built by overlaying all the images in the correct order.
BOM Image binding can create final image(s) of each radar or satellite image sequence or series as PNG images or a single animated GIF or both. This makes it easier for you to display radar loops in the browser/viewer without having to code Javascript to assemble the image overlays.
By default, BOM Image binding retrieves rainfall radar sequence of images from ftp://ftp.bom.gov.au/anon/gen/radar/ and static overlay images from ftp://ftp.bom.gov.au/anon/gen/radar_transparencies/.
You have the option to use images from different paths to generate other kinds of weather images. Please look at example configurations for other images here.
Configuring weather images does look daunting at first but it is not. If you read through the instruction below you should have no problems.
For rainfal radar images, the first step is to determine the product ID of the images you are after. You can do this easily by searching "IDR" in BOM's catalogue page http://reg.bom.gov.au/catalogue/anon-ftp.shtml. Another way is to note the product ID in the "Rainfall Radars" URL itself. e.g http://www.bom.gov.au/products/IDR701.loop.shtml.
Note that each radar range is under different product ID.
Examples for Perth radar loop:
- IDR701 - 512 km
- IDR702 - 256 km
- IDR703 - 128 km
- IDR704 - 64 km
In the configuration screen typically you would only care about changing the Product ID to the rainfall radar you would like to show, and turning on Generate animated GIF. For other products please see example configurations in this document.
On this screen you also have the option to modify the layer ordering, add additional layer, generate PNG images, generate animated GIF, change the delay between GIF images in the animated gif, enable GIF looping, enable local timestamp, configure local timestamp properties, apply post processing to the image, change image output path and output filename.
FTP server: This is the BOM's FTP server.
Images directory path: The location of the images sequences relative to the root directory of the FTP server.
Image product ID: The product ID as described above.
Transparencies directory path: The location of the static background and foreground images relative to the root directory of the FTP server.
Regular expression for image file filter: Under some scenarios it is necessary to provide more specific filter by the use of regular expression. This is an optional field.
Date range to search:
The date range to search. Valid values are: last_#d (last # days), last_#h (last # hours), last_#m (last # minutes), last_#s (last # seconds), today and yesterday. e.g last_15m to include files only from the last 15 minutes. Specific start/end date is not yet supported.
Image layers configuration: The list of layers to merge. See below for details.
Monitoring interval in minutes: The interval to check for new files.
Generate PNG images: Generate individual images from series.
Generate animaged GIF: Generated animated GIF from series.
GIF image delay time in ms: The number of milliseconds to pause before showing the next image sequence/frame.
Enable GIF loop: If enabled GIF will restart when the last frame is reached.
Embed local timestamp: Embed local timestamp in each image.
Local timestamp properties: The timestamp's font face, font size, font weight, font decoration, font style, font colour and position configuration.
TIFF image index: High-definition images, like from Himawari-8 satellite, are stored in a single TIFF image file. There are five images in the file and each image is of varying resolution; zero being the highest resolution (6111x4167), four being lowest resolution (510x350). The default image index is 3. The use of image index 0 or 1 is not recommended unless your system can handle it.
Image post-processing: Post processing applied to the final image. See below for details.
Image output path: The path to output the generated images.
Image output filename:
The name to give to the filename. This field can also accept bind variable ${pid}, which is the ID entered in the Product ID field.
Each layer is separated by a semicolon and each setting for the layer is separated by a comma. The order of the layer determines the layer merge order.
Each layer at minimum must contain the full image file name. The layer where each of the series/sequence image to be merged must be named ${series}.
For example (taken from default configuration):
image=IDR.legend.0.png; image=${pid}.background.png; image=${pid}.topography.png; image=${series}; image=${pid}.locations.png; image=${pid}.range.png
Explanation:
- There are six layers of images that make up the final image: legend, background, topography overlay, ${series} image, locations transparency overlay and range transparency overlay. You can re-order the the layers to your liking.
${pid}is the placeholder for product ID and gets replaced by the product ID you entered in the product ID field. If your product ID is IDR701 then it is equivalent to enteringimage=IDR701.background.png.- Layer 1 non-transparent part of the image will be obscured by layer 2, layer 2 will be obscured by layer 3, and so on.
- Layer 3,
image=${series}, is the placeholder for the image series. ie. the radar scan image. - The images, except for the series images, are sourced from ftp://ftp.bom.gov.au/anon/gen/radar_transparencies/ by default (as defined in the Transparencies directory path). You can specify a URL instead to include images from external sources. See table below.
- Other transparancies available from the BOM ftp site are:
${pid}.wthrDistricts.png,${pid}.waterways.png,${pid}.roads.png,${pid}.rail.png,${pid}.catchments.png. Including/excluding these transparencies is equivalent to toggling these feature on/off on the BOM website. - It is possible to add image manipulation operations to each layer. See below for more details.
Below is a list of supported external image sources:
| URL Type | Description | Example |
|---|---|---|
| http | HTTP protocol | image=http://www.openhab.org/openhab-logo.png |
| https | Secure HTTP protocol | image=https://www.openhab.org/openhab-logo.png |
| ftp | FTP protocol | image=ftp://ftp.bom.gov.au/anon/gen/radar_transparencies/IDR.legend.0.png |
| file | Local file | image=file:///etc/openhab2/html/location_24.png |
There are five image manipulation operations available to each layer and the final image:
- Opacity - changes the opacity (transparency level) of the image.
- Resize - resizes the image.
- Crop - crops the image.
- Position - repositions image in the layer.
- Resize canvas - reizes the canvas.
| Operation | Parameters | Example | Notes |
|---|---|---|---|
| opacity | opacity | opacity=0.5 | Valid values are 0.0 to 1.0. 0 = completely transparent (invisible), 1 = complete opaque. |
| resize | width height | resize=600 600 | width and height in pixels, must be positive numbers. |
| crop | x y width height | crop=0 12 512 500 | x and y are the starting coordinate relative to top-left of the canvas. width the number of pixels from x to include. height is the number of pixels from y to include. |
| position | x y | position=200 148 | reposition top-left corner of the image to the provided x and y coordinate. |
| canvas | width height x y background-colour | canvas=512 700 0 0 #606060 | x and y are the starting coordinate relative to top-left of the canvas. If no background-colour provided the background will remain transparent. |
Example usage in a layer:
image=${pid}.range.png, opacity=0.5;
image=file:///C:/openhab2/html/location_24.png, opacity=0.5, position=218 148;
Example usage in Image post-processing field:
crop=0 12 512 500, resize=600 600
When "Embed local timestamp" is enabled, each PNG/GIF frame will include the local timestamp in the image. You have the option to override the default timestamp format, text properties and positioning.
By default the following properties are used:
format=dd/MM/yyyy HH:mm:ss z, font-face=Arial, font-size=16, font-color=#080808, font-weight=bold, position=256 20
This binding does not attempt to read the timestamp overlay in the image. Instead the timestamp on the filename itself is used. For some images (e.g rain radar) the timestamp on the filename does not actually match the timestamp overlay. In the case of rain radar, there is a constant 5 minute delay. You can fix this by using adjust-timestamp attribute.
Available configuration properties:
| Attribute | Description |
|---|---|
| format | The date format in Java. |
| adjust-timestamp | Adjust the timestamp. Valid values: [-]#d, [-]#h, [-]#m or [-]#s. e.g adjust-timestamp=-5m |
| font-face | The font face to use. Default is Arial. Fonts availability is system dependent. |
| font-size | The point size of the font. |
| font-color | The colour of the font in hexadecimal. |
| font-weight | The thickness of the font. Valid values: normal, bold. |
| font-style | The posture of the font. Valid values: normal, italic. |
| font-decoration | The decoration for the font. Valid values: none, underline. |
| position | The position of the timestamp in x and y coordinate. |
Image directory path: /anon/gen/radar/
Image product ID: IDR701
Image layers configuration: image=IDR.legend.0.png; image=${pid}.background.png; image=${pid}.topography.png; image=${series}; image=${pid}.locations.png; image=${pid}.range.png, opacity=0.6; image=file:///etc/openhab2/html/location_24.png, opacity=0.8, position=248 212
Embed local timestamp: On
Local timestamp properties: format=dd/MM/yyyy HH:mm:ss z, adjust-timestamp=-5m font-face=Arial, font-size=16, font-color=#000000, font-weight=bold, position=250 485
Note:
- Timestamp is adjusted to minus 5 minutes to match the UTC time overlay.
- Opacity is added to range image overlay.
- The use of location marker with its opacity set to 0.8 and positioned to the desired location.
Image directory path: /anon/gen/radar/
Image product ID: IDR70I
Date range to search: last_24h
Image layers configuration: image=IDR.legend.2.png; image=IDR703.background.png; image=IDR703.topography.png; image=${series}; image=IDR703.locations.png; image=IDR703.range.png
Image directory path: /anon/gen/radar/
Image product ID: IDR70D
Image layers configuration: image=IDR.legend.1.png; image=IDR703.background.png; image=${series}; image=IDR703.locations.png; image=IDR703.range.png
Embed local timestamp: On
Local timestamp properties: format=dd/MM/yyyy HH:mm:ss z, font-face=Arial, font-size=16, font-color=#080808, font-weight=bold, position=226 490
Click here for animated GIF version.
Image directory path: /anon/gen/gms/
Image product ID: IDE00135
Regular expression for image filter: IDE00135.\d{12}.*
Date range to search: last_6h
Image layers configuration: image=${series}
Embed local timestamp: On
Local timestamp properties: format=dd/MM/yyyy HH:mm:ss z, font-face=Arial, font-size=16, font-color=#FFFFFF, font-weight=bold, position=316 458
Note:
- Regular expression is required because the product ID used to search for the image files also matches unrelated files
IDE00135.radar.*.jpg. - Date range is set to the past 6 hours as there are a large number of files spanning ~20 days.
| Region | Satellite View | Product ID | Regular expression |
|---|---|---|---|
| Australia | False colour temperatures | IDE00134 | IDE00134.\d{12}.* |
| Australia | Infrared, greyscale | IDE00105 | IDE00105.\d{12}.* |
| Australia | Visible, greyscale | IDE00106 | IDE00106.\d{12}.* |
| Australia | Infrared, Zehr enhanced | IDE00133 | IDE00133.\d{12}.* |
| Australia West | False colour temperatures | IDE00124 | IDE00124.\d{12}.* |
| Australia West | Infrared, greyscale | IDE00125 | IDE00125.\d{12}.* |
| Australia West | Visible, greyscale | IDE00126 | IDE00126.\d{12}.* |
| Australia West | Infrared, Zehr enhanced | IDE00123 | IDE00123.\d{12}.* |
| Australia East | False colour temperatures | IDE00144 | IDE00144.\d{12}.* |
| Australia East | Infrared, greyscale | IDE00145 | IDE00145.\d{12}.* |
| Australia East | Visible, greyscale | IDE00146 | IDE00146.\d{12}.* |
| Australia East | Infrared, Zehr enhanced | IDE00143 | IDE00143.\d{12}.* |
| Full Disk | False colour temperatures | IDE00154 | IDE00154.\d{12}.* |
| Full Disk | Infrared, greyscale | IDE00155 | IDE00155.\d{12}.* |
| Full Disk | Visible, greyscale | IDE00156 | IDE00156.\d{12}.* |
| Full Disk | Infrared, Zehr enhanced | IDE00153 | IDE00153.\d{12}.* |
Click here for animated GIF version.
Image directory path: /anon/gen/gms/
Image product ID: IDE00436
Date range to search: last_3h
Image layers configuration: image=${series}
Embed local timestamp: On
Local timestamp properties: format=dd/MM/yyyy HH:mm:ss z, font-face=Arial, font-size=16, font-color=#FFFFFF, font-weight=bold, position=510 510
TIFF image index: 3
Note:
- Himawari-8 satellite images are in TIFF format and each file has 5 images of different resolution, from high (index 0) to low (index 4). In this example index 3 is used as it provides good-enough resolution without too much overhead. Image index 0 or 1 is not recommended unless your system can handle it.
Image directory path: /anon/gen/fwo/
Image product ID: IDY00030
Regular expression for image filter: IIDY00030.\d{12}.png
Date range to search: last_7d
Image layers configuration: image=${series}
Embed local timestamp: On
Local timestamp properties: format=dd/MM/yyyy HH:mm:ss z, font-face=Arial, font-size=16, font-color=#F76623, font-weight=bold, position=380 420
Note:
- Regular expression is required because product ID also matches PDF files
IDY00030.*.pdfin the FTP directory.
Use an Image widget and link to the generated image /static/<output-filename>.gif or link to the image in your custom template.
For PNG images the sequence number is appended to the image name. i.e. <output-filename>.<sequence>.png. e.g IDR701.0.png, IDR701.1.png and so on. The list of PNG's is available in the Generated PNG's channel.
In your custom template you will have to write AngularJS/Javascript to handle the display of the image layers and animating the radar images. The benefit of this method is you can make it user interactive and frame rate, etc is not baked in. This is similar to what BOM site does and it is beyond the scope of this documentation.
The list of radar image sequences are available as a channel (Source Images). Unfortunately it is represented as a comma-separated string due to framework shortcoming. You will have to split the values into an array to be useful.
- National Radar Loop - this is made up of two series of images. Possible to support in the future if there is demand.
- Weather and Wave Forecast Maps - this is a single file of around 154MB needs to be downloaded and processed.
- Latest Colour MSLP and Infrared Greyscale Satellite - this is a single image that can be linked directly.
- Short-term forecast - this is a single image that can be linked directly.
- Colour Forecast map for next 4 days - this is a single image that can be linked directly.
- UV Forecast - this is a single image that can be linked directly.
- Asia MSL Pressure Analysis - this is a single image that can be linked directly.
- Southern Hemisphere MSLP Aanalysis - this is a PDF file.
- Pacific Ocean MSLP Analyses - this is a single image that can be linked directly.
- Indian Ocean MSLP Analyses - this is a single image that can be linked directly.
The screenshots below are examples of the binding in operation. The screens use custom theme called "Matrix Theme" by Patrick (@pmpkk). For more information about the theme please go to https://community.openhab.org/t/matrix-theme-for-habpanel/31100.
16/02/2022
- openHAB version 3.2.x compatibility update
13/12/2021
- openHAB version 3.0.3 update
- Add option to save XML data file from BOM
- Replace dashes with underscores in icon names (version 3.0.3 only)
18/12/2020
- openHAB version 3.0.0 update
20/10/2020
- Changed FTP client to not verify remote site.
25/09/2020
- openHAB version 2.5.9 compatibility update.
03/01/2020
- Fixed retry of image generation if images are missing on the FTP site.
23/04/2019
- Added support for high-definition Himawari-8 satellite images (TIFF files).
20/04/2019
- Read timestamp from image filename instead of file.
- Added optional
adjust-timestampproperty to local timestamp configuration. - Removed hard-coded timestamp adjustment as this is not applicable to other image products.
18/04/2019
- Fixed chaining of image manipulation operation.
17/04/2019
- Added regular expression file matching.
- Added date time range filter.
15/04/2019
- Added timestamp option.
- Fixed sourcing of images from external sources.
14/04/2019
- Added retain min/max temperatures for today.
- Added BOM radar/rainfall image generation support.
08/03/2019
- Fixed icon mapping for light rain.
03/03/2019
- Fixed apparent vs air temperature mix up.
- Fixed today's min/max temperature.
26/02/2019
- Added 24 hour rainfall channel.
- Added minimum and maximum precipitation.
18/02/2019
- Added weather station channel and additional logging.
17/02/2019
- Updated channel label names.
16/02/2019
- Added apparent temperature from observation.
14/02/2019
- Added support for city/town and district forecast data.
- Handled NaN values from data.
13/02/2019
- Updated forecast date and time label.
12/02/2019
- Initial release.