initial commit

2026-10-03 22:22:00 +10:00 · 2025-12-16 20:28:37 +10:00
parent d49228d671
commit ec69629165
4 changed files with 287 additions and 92 deletions
@@ -4,7 +4,7 @@ A Home Assistant custom card that displays Australian Bureau of Meteorology (BOM

 ## 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.
+The Australian Bureau of Meteorology's radar API endpoint stopped working in December 2024, breaking integrations like the popular [bom-radar-card](https://github.com/Makin-Things/bom-radar-card) for Home Assistant. This card provides a replacement solution that displays BOM radar data by connecting to the [BOM Local Service](https://github.com/alexhopeoconnor/bom-local-service), which caches radar data locally and provides it via a REST API.

 ## Features

@@ -18,15 +18,93 @@ The Australian Bureau of Meteorology's radar API endpoint stopped working in Dec

 ## 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
+- **Home Assistant**: Version 2024.1.0 or later
+- **Docker**: Required to run the BOM Local Service (Docker Engine 20.10+ or Docker Desktop)
+- **BOM Local Service**: Must be installed and running (covered in installation steps below)

 ## Installation

-### HACS (Recommended)
+This card requires the [BOM Local Service](https://github.com/alexhopeoconnor/bom-local-service) to be running. Follow these steps to set up both the service and the card.
+
+### Step 1: Install BOM Local Service
+
+The service must be running and accessible to Home Assistant before you can use this card.
+
+#### Option A: Docker Run (Quick Start)
+
+Run the service using Docker:
+
+```bash
+docker run -d \
+  --name bom-local-service \
+  -p 8082:8080 \
+  -v $(pwd)/cache:/app/cache \
+  --shm-size=1gb \
+  --ipc=host \
+  -e CORS__ALLOWEDORIGINS="http://homeassistant.local:8123" \
+  ghcr.io/alexhopeoconnor/bom-local-service:latest
+```
+
+**CORS Configuration**: Replace `http://homeassistant.local:8123` with your actual Home Assistant URL. Since this service is intended to run locally, you can use `"*"` to allow all origins for simplicity. See the [CORS Configuration Explained](#cors-configuration-explained) section below for detailed options.
+
+#### Option B: Docker Compose (Recommended for Production)
+
+Create a `docker-compose.yml` file:
+
+```yaml
+services:
+  bom-local-service:
+    image: ghcr.io/alexhopeoconnor/bom-local-service:latest
+    container_name: bom-local-service
+    ports:
+      - "8082:8080"
+    volumes:
+      - ./cache:/app/cache
+    environment:
+      # CORS Configuration - Set to your Home Assistant URL(s)
+      # Replace with your actual Home Assistant URL, or use "*" for local development
+      # Multiple origins can be comma-separated: "http://homeassistant.local:8123,http://192.168.1.100:8123"
+      - CORS__ALLOWEDORIGINS=http://homeassistant.local:8123
+      - CORS__ALLOWEDMETHODS=GET,POST,OPTIONS
+      - CORS__ALLOWEDHEADERS=*
+      - CORS__ALLOWCREDENTIALS=false
+    shm_size: 1gb
+    ipc: host
+    restart: unless-stopped
+```
+
+Then run:
+```bash
+docker-compose up -d
+```
+
+#### CORS Configuration Explained
+
+**Why CORS matters**: Home Assistant runs in a browser, which enforces Cross-Origin Resource Sharing (CORS) policies. The service must explicitly allow requests from your Home Assistant origin.
+
+**Important gotcha**: The origin is determined by how you **access** Home Assistant in your browser, not by how the service is configured. If you access HA via `http://localhost:8123` one time and `http://192.168.1.100:8123` another time, you need to include both origins in the CORS configuration. The origin must **exactly match** the URL in your browser's address bar.
+
+**Quick Setup Options**:
+
+- **Simplest (recommended for local use)**: Use `"*"` to allow all origins. Since this service runs locally, this is fine and avoids configuration issues.
+- **Specific origin**: Use your exact Home Assistant URL, e.g., `"http://192.168.1.100:8123"` or `"http://localhost:8123"`
+- **Multiple origins**: Use comma-separated values: `"http://localhost:8123,http://192.168.1.100:8123,http://homeassistant.local:8123"`
+
+**Common scenarios**:
+- Accessing via localhost: Use `"http://localhost:8123"` (note: `localhost` and `127.0.0.1` are different origins - include both if you use both)
+- Accessing via IP: Use `"http://192.168.1.100:8123"` (replace with your HA's IP)
+- Accessing via hostname: Use `"http://homeassistant.local:8123"` (use exact hostname)
+- Using HTTPS: Include the `https://` version: `"https://homeassistant.local:8123"`
+
+**Troubleshooting**: If you get CORS errors, check the browser console - it shows the exact origin that was rejected. Ensure that origin exactly matches one in your `CORS__ALLOWEDORIGINS` configuration.
+
+**Verify the service is running**:
+- Open `http://localhost:8082/radar/Brisbane/QLD` in your browser (replace with your suburb/state) - you should see the demo app
+- Or check the API: `curl http://localhost:8082/api/radar/Brisbane/QLD/metadata`
+
+For more detailed service setup and configuration options, see the [BOM Local Service README](https://github.com/alexhopeoconnor/bom-local-service).
+
+### Step 2: Install the Card via HACS

 1. Open HACS in Home Assistant
 2. Go to **Frontend** → **Explore & Download Repositories**
@@ -34,28 +112,13 @@ The Australian Bureau of Meteorology's radar API endpoint stopped working in Dec
 4. Click **Download**
 5. Restart Home Assistant

-### Manual Installation
+### Step 3: Add the Card to Your Dashboard

-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
+1. Edit your Lovelace dashboard
+2. Click **Add Card**
+3. Search for **BOM Local Radar Card** or select **Custom: BOM Local Radar Card**
+4. Configure the card (see [Configuration](#configuration) section below)
+5. Set the **Service URL** to match your service installation (e.g., `http://localhost:8082` or `http://192.168.1.50:8082`)

 ## Configuration

@@ -64,15 +127,25 @@ The Australian Bureau of Meteorology's radar API endpoint stopped working in Dec
 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 Configuration**:
   - **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`)
+   - **Suburb**: The suburb name (e.g., `Pomona`, `Brisbane`) - **Required**
+   - **State**: State abbreviation (e.g., `QLD`, `NSW`, `VIC`) - **Required**
+   
+   **Display**:
   - **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)
+   - **Show Metadata**: Toggle to show/hide cache status, observation time, and weather station info (default: `true`)
+   
+   **Slideshow**:
+   - **Timespan**: Select historical data range - `latest` (Latest 7 frames), `1h`, `3h`, `6h`, `12h`, or `24h` (default: `latest`)
+   - **Frame Interval**: Seconds between frames during animation (default: `2.0`, range: 0.5-10)
+   - **Auto Play**: Automatically start animation when data loads (default: `true`)
+   
+   **Auto Refresh**:
+   - **Refresh Interval**: Seconds between automatic data refreshes (default: `30`, range: 10-300)
+
+**Note**: For custom time ranges (using `timespan: custom`), you'll need to configure `custom_start_time` and `custom_end_time` via YAML as these options are not available in the visual editor.

 ### Using YAML

@@ -89,6 +162,18 @@ auto_play: true
 refresh_interval: 30
 ```

+For custom time ranges:
+
+```yaml
+type: custom:bom-local-radar-card
+service_url: http://localhost:8082
+suburb: Brisbane
+state: QLD
+timespan: custom
+custom_start_time: "2024-01-15T10:00:00Z"
+custom_end_time: "2024-01-15T14:00:00Z"
+```
+
 ### Configuration Options

 | Option | Type | Default | Required | Description |
@@ -99,9 +184,9 @@ refresh_interval: 30
 | `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) |
+| `frame_interval` | number | `2.0` | No | Seconds between frames during animation (range: 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) |
+| `refresh_interval` | number | `30` | No | Seconds between automatic data refreshes (range: 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`) |

@@ -185,7 +270,150 @@ The card provides several controls for navigating radar frames:

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

-## Troubleshooting
+## Development
+
+### Quick Start for Local Development
+
+The easiest way to start developing is to use the included test environment script:
+
+```bash
+./run.sh test
+```
+
+This single command will:
+1. Build the card (auto-detects Docker or npm)
+2. Start Home Assistant in a Docker container (port 8124)
+3. Start the BOM Local Service (port 8082)
+4. Copy the built card to Home Assistant's `www` directory
+5. Configure CORS properly for local testing
+
+**Access your test environment:**
+- Home Assistant: http://localhost:8124
+- BOM Local Service: http://localhost:8082
+
+**Default test credentials:** Username: `testuser`, Password: `testpass123`
+
+### Available Scripts
+
+The repository includes several helper scripts for development:
+
+#### Main Entry Point: `./run.sh`
+
+The main script that handles building, testing, and cleaning:
+
+```bash
+./run.sh [COMMAND] [BUILD_METHOD]
+```
+
+**Commands:**
+- `build [docker|npm]` - Build the card (auto-detects method if not specified)
+- `test` - Build and start the test Home Assistant environment
+- `update [docker|npm]` - Rebuild card and update running test environment (preserves HA state)
+- `clean` - Clean test environment (stops containers, removes data)
+
+**Build Methods:**
+- `docker` - Use Docker to build (isolated, no local Node.js needed)
+- `npm` - Use local npm/Node.js to build
+
+**Examples:**
+```bash
+./run.sh build          # Auto-detect: Docker (preferred) or npm
+./run.sh build docker   # Force Docker build
+./run.sh test           # Build and start test environment
+./run.sh update         # Rebuild and update running environment (no data loss)
+./run.sh clean          # Clean test environment completely
+```
+
+#### Detailed Test Script: `./scripts/test.sh`
+
+For more advanced testing options:
+
+```bash
+./scripts/test.sh [OPTIONS]
+```
+
+**Options:**
+- `--skip-build` - Skip building the card (use existing dist file)
+- `--force-build` - Force rebuild of the card (no cache)
+- `--docker-build` - Use Docker to build the card
+- `--npm-build` - Use npm to build the card (requires local Node.js)
+- `--service-path PATH` - Build service from local source at PATH instead of using pre-built image
+
+**Examples:**
+```bash
+./scripts/test.sh                                    # Auto-detect build method
+./scripts/test.sh --force-build                      # Force rebuild card
+./scripts/test.sh --docker-build                     # Build card with Docker
+./scripts/test.sh --service-path ../bom-local-service  # Test with local service changes
+```
+
+**Note:** If containers are already running, the script automatically updates the card and restarts Home Assistant (preserves HA state).
+
+#### Building from Source (Manual)
+
+If you prefer to build manually:
+
+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. **Development with watch mode:**
+   ```bash
+   npm run watch
+   ```
+
+### Test Environment Details
+
+The test environment includes:
+
+- **Home Assistant**: Running in Docker on port 8124
+- **BOM Local Service**: Pre-configured service running on port 8082
+- **CORS**: Automatically configured to allow requests from Home Assistant
+- **Card Pre-installed**: The built card is automatically added to Home Assistant's resources
+
+**Updating the Card During Development:**
+
+When you make changes to the card code, you can update the running test environment without losing your Home Assistant state:
+
+```bash
+./run.sh update
+```
+
+This rebuilds the card and updates it in the running Home Assistant container, preserving all your dashboard configurations and test data.
+
+**Testing with Local Service Changes:**
+
+To test the card against a local version of the BOM Local Service (instead of the pre-built image):
+
+```bash
+./scripts/test.sh --service-path ../bom-local-service
+```
+
+This builds the service from your local source and uses it in the test 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
+
+## Troubleshooting & Support

 ### Card Shows "Configuration Error"

@@ -225,56 +453,16 @@ The card displays frame information including frame number, total frames, and ti
 - **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
+### Getting Additional Help

-### Building from Source
+If you're still experiencing issues:

-1. Clone the repository:
-   ```bash
-   git clone https://github.com/alexhopeoconnor/bom-local-card.git
-   cd bom-local-card
-   ```
+- **Review the [BOM Local Service documentation](https://github.com/alexhopeoconnor/bom-local-service)** - If the issue relates to the service (cache not ready, CORS errors, etc.)
+- **Test with the development environment** - Use `./run.sh test` to verify your setup works correctly
+- **Open an [issue on GitHub](https://github.com/alexhopeoconnor/bom-local-card/issues)** - For bug reports or feature requests

-2. Install dependencies:
-   ```bash
-   npm install
-   ```
+## Disclaimer

-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).
+This card displays radar data provided by the [BOM Local Service](https://github.com/alexhopeoconnor/bom-local-service), which caches data from the Australian Bureau of Meteorology (BOM). 

+This project is not affiliated with or endorsed by the Australian Bureau of Meteorology. For official BOM data and services, visit [bom.gov.au](https://www.bom.gov.au/).
@@ -1,12 +1,12 @@
 {
  "name": "bom-local-radar-card",
-  "version": "1.0.0",
+  "version": "0.0.1",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "bom-local-radar-card",
-      "version": "1.0.0",
+      "version": "0.0.1",
      "license": "MIT",
      "dependencies": {
        "custom-card-helpers": "^1.9.0",
@@ -1,7 +1,7 @@
 {
  "name": "bom-local-radar-card",
-  "version": "1.0.0",
-  "description": "A rain radar card using the local BOM service",
+  "version": "0.0.1",
+  "description": "Home Assistant custom card for displaying Australian Bureau of Meteorology (BOM) rain radar data with animated slideshow and historical data support",
  "module": "bom-local-radar-card.js",
  "keywords": [
    "home-assistant",
@@ -11,8 +11,14 @@
    "lovelace",
    "custom-cards",
    "bom",
+    "bureau-of-meteorology",
    "radar",
-    "weather"
+    "weather",
+    "australia",
+    "rain",
+    "precipitation",
+    "meteorology",
+    "hacs"
  ],
  "repository": {
    "type": "git",
@@ -1,4 +1,4 @@
-export const CARD_VERSION = '1.0.0';
+export const CARD_VERSION = '0.0.1';
 export const DEFAULT_SERVICE_URL = 'http://localhost:8082';
 export const DEFAULT_FRAME_INTERVAL = 2.0;  // seconds
 export const DEFAULT_RESTART_DELAY = 2000;  // ms (pause before looping)
@@ -13,3 +13,4 @@ export const DEFAULT_REFRESH_INTERVAL = 30;  // seconds



+