bom-local-card/README.md

BOM Local Radar Card

A Home Assistant custom card that displays Australian Bureau of Meteorology (BOM) rain radar data using the local BOM Local Service.

Background

The Australian Bureau of Meteorology's radar API endpoint stopped working in December 2024, breaking integrations like the popular bom-radar-card for Home Assistant. This card works alongside the BOM Local Service to provide a reliable local solution by consuming cached radar data from a local service.

Features

• 🌧️ Live Radar Display: View the latest BOM rain radar images for any Australian location
• 🎬 Animated Slideshow: Play through radar frames to see precipitation movement
• 📊 Historical Data: View radar history from 1 hour to 24 hours ago
• 🎯 Location-Based: Support for any Australian suburb/state combination
• 🔄 Auto-Refresh: Automatically updates radar data at configurable intervals
• 🎨 Beautiful UI: Modern, responsive design that integrates seamlessly with Home Assistant themes
• ⚙️ Visual Editor: Full GUI configuration editor (no YAML editing required)

Prerequisites

1. BOM Local Service: This card requires the BOM Local Service to be running. The service provides the cached radar data that the card displays.

   See the BOM Local Service README for installation instructions.

2. Home Assistant: Version 2024.1.0 or later

Installation

HACS (Recommended)

1. Open HACS in Home Assistant
2. Go to Frontend → Explore & Download Repositories
3. Search for BOM Local Radar Card
4. Click Download
5. Restart Home Assistant

Manual Installation

1. Download the latest bom-local-radar-card.js from the releases page

2. Copy the file to your Home Assistant www directory (usually /config/www/)

3. Add the resource reference to your Lovelace configuration:

   Option A: Via UI (Recommended)

   • Go to Settings → Dashboards → Resources (three dots menu)
   • Click Add Resource
   • Set URL to /local/bom-local-radar-card.js
   • Set Resource type to JavaScript Module
   • Click Create

   Option B: Via YAML Add to your configuration.yaml:

   lovelace:
     resources:
       - url: /local/bom-local-radar-card.js
         type: module
   

4. Restart Home Assistant

Configuration

Using the Visual Editor (Recommended)

1. Add a card to your Lovelace dashboard
2. Search for BOM Local Radar Card or select Custom: BOM Local Radar Card
3. Configure using the visual editor:
   • Service URL: Base URL of your BOM Local Service (default: http://localhost:8082)
   • Suburb: The suburb name (e.g., Pomona, Brisbane)
   • State: State abbreviation (e.g., QLD, NSW, VIC)
   • Card Title: Optional custom title for the card
   • Show Metadata: Toggle to show/hide cache status and observation time
   • Timespan: Select historical data range (Latest, 1h, 3h, 6h, 12h, 24h)
   • Frame Interval: Seconds between frames during animation (default: 2.0)
   • Auto Play: Automatically start animation when data loads
   • Refresh Interval: Seconds between automatic data refreshes (default: 30)

Using YAML

type: custom:bom-local-radar-card
service_url: http://localhost:8082
suburb: Pomona
state: QLD
card_title: Local Weather Radar
show_metadata: true
timespan: latest
frame_interval: 2.0
auto_play: true
refresh_interval: 30

Configuration Options

Option	Type	Default	Required	Description
service_url	string	http://localhost:8082	No	Base URL of the BOM Local Service
suburb	string	-	Yes	Suburb name (e.g., "Pomona", "Brisbane")
state	string	-	Yes	State abbreviation (e.g., "QLD", "NSW", "VIC")
card_title	string	-	No	Custom title displayed at the top of the card
show_metadata	boolean	true	No	Show/hide cache status, observation time, and weather station info
timespan	string	latest	No	Historical data timespan: latest, 1h, 3h, 6h, 12h, 24h, or custom
frame_interval	number	2.0	No	Seconds between frames during animation (0.5-10)
auto_play	boolean	true	No	Automatically start animation when data loads
refresh_interval	number	30	No	Seconds between automatic data refreshes (10-300)
custom_start_time	string	-	No	ISO 8601 datetime for custom timespan start (requires timespan: custom)
custom_end_time	string	-	No	ISO 8601 datetime for custom timespan end (requires timespan: custom)

Usage Examples

Basic Configuration

Display the latest radar frames for a location:

type: custom:bom-local-radar-card
suburb: Brisbane
state: QLD
service_url: http://192.168.1.100:8082

Historical Data (Last 3 Hours)

View radar history from the past 3 hours:

type: custom:bom-local-radar-card
suburb: Melbourne
state: VIC
service_url: http://192.168.1.100:8082
timespan: 3h
auto_play: true
frame_interval: 1.5

Custom Time Range

View radar data for a specific time period:

type: custom:bom-local-radar-card
suburb: Sydney
state: NSW
service_url: http://192.168.1.100:8082
timespan: custom
custom_start_time: "2024-01-15T10:00:00Z"
custom_end_time: "2024-01-15T14:00:00Z"

Manual Control (No Auto-Play)

Display radar with manual controls only:

type: custom:bom-local-radar-card
suburb: Adelaide
state: SA
service_url: http://192.168.1.100:8082
auto_play: false
frame_interval: 3.0

Different Service Location

If your BOM Local Service is running on a different machine:

type: custom:bom-local-radar-card
suburb: Perth
state: WA
service_url: http://192.168.1.50:8082
refresh_interval: 60

Controls

The card provides several controls for navigating radar frames:

• Play/Pause Button: Start or stop the animation
• Previous/Next Buttons: Navigate to the previous or next frame
• Frame Slider: Drag to jump to any frame
• Navigation Buttons:
  • ⏮ First frame
  • -10 / +10: Jump backward/forward by 10 frames
  • ⏭ Last frame

The card displays frame information including frame number, total frames, and timestamp.

Troubleshooting

Card Shows "Configuration Error"

• Ensure both suburb and state are configured
• Verify the configuration using the visual editor

Card Shows "Failed to fetch radar data" or "Cache not ready"

• Check BOM Local Service is running: Verify the service is accessible at the configured service_url
• Verify Service URL: Ensure the URL is correct and reachable from your Home Assistant instance
• Check Cache Status: The service may be generating the cache for your location. Wait a minute and refresh
• Network Access: If the service is on a different machine, ensure network connectivity and firewall rules allow access

Card Shows "Radar data not found"

• The cache may not be available for your location yet
• Trigger a cache update via the BOM Local Service API:

  curl -X POST http://your-service-url/api/cache/YourSuburb/YourState/refresh
  

Images Don't Load

• Check browser console for CORS errors (may indicate service configuration issue)
• Verify the service URL is correct and images are accessible
• If using a different machine, ensure CORS is properly configured in the service

Animation Not Playing

• Check that auto_play is set to true (default)
• Verify frames are loading (check frame count display)
• Try manually clicking the Play button

Service URL Configuration

• Local service: Use http://localhost:8082 if the service runs on the same machine as Home Assistant
• Remote service: Use the IP address or hostname of the machine running the service (e.g., http://192.168.1.100:8082)
• Docker network: If Home Assistant and the service are in the same Docker network, use the service container name (e.g., http://bom-local-service:8080)

Development

Building from Source

1. Clone the repository:

   git clone https://github.com/alexhopeoconnor/bom-local-card.git
   cd bom-local-card
   

2. Install dependencies:

   npm install
   

3. Build the card:

   npm run build
   

   The built file will be in dist/bom-local-radar-card.js

4. For development with watch mode:

   npm run watch
   

Testing with Home Assistant

The repository includes Docker Compose configuration for testing with Home Assistant:

npm run test:ha

This will:

• Start Home Assistant in a Docker container
• Build and copy the card to the Home Assistant www directory
• Allow you to test the card in a real Home Assistant environment

License

MIT License - see LICENSE file for details

Credits

• Built for use with BOM Local Service
• Inspired by the original bom-radar-card project

Support

For issues, questions, or contributions, please visit the GitHub repository.