From c3e0685a7b996a817cbe04e904f323fb92f5cc18 Mon Sep 17 00:00:00 2001 From: Paul Madden Date: Wed, 24 Apr 2019 12:28:11 -0600 Subject: [PATCH] Docs for camera component of bom integration (#9166) * Add camera.bomradarcam.markdown * Rename camera.bomradarcam.markdown -> bomradarcam.markdown * Move docs for BOM camera into bom.markdown to reflect code reorg * :pencil2: Tweak * Update example using 'id' to use quoted string --- source/_components/bom.markdown | 114 +++++++++++++++++++++++++++++++- 1 file changed, 113 insertions(+), 1 deletion(-) diff --git a/source/_components/bom.markdown b/source/_components/bom.markdown index cfdafebc97c..f9265b83145 100644 --- a/source/_components/bom.markdown +++ b/source/_components/bom.markdown @@ -11,6 +11,7 @@ logo: bom.png ha_category: - Weather - Sensor + - Camera ha_release: 0.36 ha_iot_class: Cloud Polling redirect_from: @@ -22,6 +23,7 @@ The `bom` weather platform uses the [Australian Bureau of Meteorology (BOM)](htt There is currently support for the following device types within Home Assistant: +- [Camera](#camera) - [Sensor](#sensor) ## {% linkable_title Configuration %} @@ -51,6 +53,116 @@ This platform is an alternative to the [`bom`](#sensor) sensor. The weather platform is easier to configure but less customizable.

+## {% linkable_title Camera %} + +The `bom` camera platform uses the [Australian Bureau of Meteorology (BOM)](http://www.bom.gov.au) [radar web service](http://www.bom.gov.au/australia/radar/) as a source to generate an animated radar image. + +To add the BOM camera to your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +camera: + - platform: bom + location: YOUR_LOCATION +``` + +See below for a list of valid `location` values, and subsitute one for `YOUR_LOCATION`. + +{% configuration %} +location: + description: Required unless `id` is specified. See below for a list of valid locations. + required: true + type: string +name: + description: Allows you to override the Home Assistant-generated camera name. + required: false + type: string +id: + description: Allows you to manually specify a BOM Radar ID (either `location` or `id` must be defined, but not both). + required: false + type: integer +delta: + description: Time in seconds between BOM radar images available for this radar. Optional if `location` is defined; required if `id` is defined. + required: false + type: integer +frames: + description: Number of frames in the animated GIF. Optional if `location` is defined; required if `id` is defined. + required: false + type: integer +filename: + description: Periodically save the animated GIF image to this filesystem path. + required: false + type: string +{% endconfiguration %} + +### {% linkable_title Valid `location` values %} + +``` +Adelaide Albany AliceSprings Bairnsdale Bowen +Brisbane Broome Cairns Canberra Carnarvon +Ceduna Dampier Darwin Emerald Esperance +Geraldton Giles Gladstone Gove Grafton +Gympie HallsCreek Hobart Kalgoorlie Katherine +Learmonth Longreach Mackay Marburg Melbourne +Mildura Moree MorningtonIs MountIsa MtGambier +Namoi Newcastle Newdegate NorfolkIs NWTasmania +Perth PortHedland SellicksHill SouthDoodlakine Sydney +Townsville WaggaWagga Warrego Warruwi Watheroo +Weipa WillisIs Wollongong Woomera Wyndham +Yarrawonga +``` + +### {% linkable_title Examples %} + +#### {% linkable_title Using `location` and `name` %} + +Example `configuration.yaml` entry to display the `Townsville` radar with a camera named `mytowsvilleradar`: + +```yaml +camera: + - platform: bom + name: mytownsvilleradar + location: Townsville +``` + +#### {% linkable_title Using `id`, `delta` and `frames` %} + +In the event BOM creates a new radar, or a radar's ID changes, you may define a custom `id` along with corresponding `delta` and `frames` values. You may also specify custom `delta` and `frames` values, along with a valid `location`, to override the default values for an existing radar. You may not define `location` and `id` in the same entity; you must specify one or the other. If `id` is specified, then `delta` and `frames` values _must_ be provided. If `location` is specified, `delta` and `frames` _may_ be provided to override the default values. + +To find a live radar ID (e.g. for the `Townsville` radar), visit the [BOM website's radars page](http://www.bom.gov.au/australia/radar/), click the link for the radar you are interested in, and note the URL, for example: `http://www.bom.gov.au/products/IDR733.loop.shtml`. The ID is the number following `IDR` (i.e. `733`) in the URL. You can also see, at the bottom of the radar image, a rotating set of times corresponding to the frames of the BOM's JavaScript-driven animation. The number of minutes (in seconds) between these times corresponds to the camera's `delta` value, and the number of frames corresponds to the `frames` value. At the time of this writing, the `Townsville` radar loop is composed of 4 frames at 10-minute (600 second) intervals. Since these are also the default values, this configuration block + +```yaml +camera: + - platform: bom + location: Townsville +``` + +is equivalent to this one + +```yaml +camera: + - platform: bom + id: '053' + delta: 600 + frames: 4 + name: 'Carnarvon' +``` + +#### {% linkable_title Using `filename` %} + +This option can be specified to save the animated radar-imagery GIF to the given filesystem path. + +Example `configuration.yaml` entry to display the `Sydney` radar and save the animated GIF to a file named `sydneyradar.gif` to the filesystem path accessible as `/local/sydneyradar.gif` via Home Assistant's web server: + +```yaml +camera: + - platform: bom + id: Sydney + filename: /config/www/images/sydneyradar.gif +``` + +The file will be updated every `delta` seconds when the camera regenerates the animation. + ## {% linkable_title Sensor %} The `bom` sensor platform uses the [Australian Bureau of Meteorology (BOM)](http://www.bom.gov.au) as a source for current (half-hourly) meteorological data. @@ -174,4 +286,4 @@ monitored_conditions:

This sensor is an alternative to the [`bom`](#configuration) weather platform. The weather platform is easier to configure but less customisable. -

\ No newline at end of file +