ElixirForge/bom-local-card
1
0
Fork 0
mirror of https://github.com/alexhopeoconnor/bom-local-card.git synced 2026-10-03 22:22:00 +10:00
Code Releases 2 Activity

Initial commit: BOM Local Radar Card

Browse Source 
- Custom Home Assistant card for displaying BOM radar data
- Docker-based build system (no local Node.js required)
- Test environment with Home Assistant and BOM service
- TypeScript source with LitElement framework
- HACS integration ready
This commit is contained in:
alex
2025-12-16 19:51:16 +10:00
parent 1259a2e779
commit d49228d671
16 changed files with 3174 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+280
View File
@@ -0,0 +1,280 @@
# 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](https://github.com/alexhopeoconnor/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](https://github.com/alexhopeoconnor/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](https://github.com/alexhopeoconnor/bom-local-service) to be running. The service provides the cached radar data that the card displays.
See the [BOM Local Service README](https://github.com/alexhopeoconnor/bom-local-service) 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](https://github.com/alexhopeoconnor/bom-local-card/releases)
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`:
```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
```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:
```yaml
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:
```yaml
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:
```yaml
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:
```yaml
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:
```yaml
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:
```bash
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:
```bash
git clone https://github.com/alexhopeoconnor/bom-local-card.git
cd bom-local-card
```
2. Install dependencies:
```bash
npm install
```
3. Build the card:
```bash
npm run build
```
The built file will be in `dist/bom-local-radar-card.js`
4. For development with watch mode:
```bash
npm run watch
```
### Testing with Home Assistant
The repository includes Docker Compose configuration for testing with Home Assistant:
```bash
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](LICENSE) file for details
## Credits
- Built for use with [BOM Local Service](https://github.com/alexhopeoconnor/bom-local-service)
- Inspired by the original [bom-radar-card](https://github.com/Makin-Things/bom-radar-card) project
## Support
For issues, questions, or contributions, please visit the [GitHub repository](https://github.com/alexhopeoconnor/bom-local-card).