search

tomitan100 / org.openhab.binding.bom

OH2 binding for Australian weather forecast and images from Bureau of Meteorology (BOM)
4 stars 3 forks source link

readme

Australian Bureau of Meteorology Weather Forecast and Image Binding

This binding retrieves Australian weather forecast and meteorological images from Bureau of Meteorology for use in openHaB/Eclipse Smarthome.

Contents

Features

Observation and Forecast Features

This binding maps most fields from BOM data-feed. For today's observation and forecast these are available:

For future forecasts the following fields are available:

BOM Images Features

BOM images, like rain radar, rainfall and satellite images, can retrieved and processed. You have the option of:

See below for more details.

Prerequisite

For openHAB 2

For openHAB 3

Installation

Via Eclipse IoT Market - for openHAB 2 only

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.

Manual installation - for openHAB 2 and openHAB 3

Download the latest jar below for your openHAB version and copy to the openHAB addons directory.

openHAB 3.2.x

Version 3.2.x Download

openHAB 3.0.x

Version 3.0.0 Download

Version 3.0.3 Download

openHAB 2

Version 2.5.9 Download

Version 2.5.0 Download

Weather observation and forecast configuration

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":

  1. 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.
  2. Locate City Forecast - {your-city} ({your-state}) for city forecasts OR Town Forecast - {your-town} ({your-state}) for town forecasts OR District 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.

Weather Forecast Icons

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

BOM Weather Items mapping and sitemap files

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 Weather Images Generation

Background Information

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.

BOM Images Configuration

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:

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.

Image sources configuration fields

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.

Image generation configuration fields

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.

Image Layers Configuration

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:

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
## Image Manipulation and Processing 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` #### Local timestamp configuration 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.
### Rain radar images configuration example _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. ### Doppler wind images configuration example _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` ### Rainfall images configuration example _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` ### Satellite images configuration example Click [here](https://github.com/tomitan100/org.openhab.binding.bom/raw/master/doc/satellite.gif) 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. #### Other satellite view variations
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}.*
### High-definition Himawari-8 satellite images configuration example Click [here](https://github.com/tomitan100/org.openhab.binding.bom/raw/master/doc/himwari.gif) 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. ### Mean sea-level pressure images configuration example _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.*.pdf` in the FTP directory. ## Using the images #### If you want to use generated PNG's or animated GIF Use an Image widget and link to the generated image `/static/.gif` or link to the image in your custom template. For PNG images the sequence number is appended to the image name. i.e. `..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. #### If you choose NOT to use generate PNG's or animated GIF 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. ## Unsupported Charts - 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. ## Example Screenshots in openHAB HABPanel 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. ## Change log __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-timestamp` property 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.