|
| 1 | +# Manual Installation Guide |
| 2 | + |
| 3 | +This guide explains how to manually install this custom Air Quality Card in your Home Assistant instance without using HACS. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +- Access to your Home Assistant configuration directory (via SSH, Samba, File Editor add-on, etc.) |
| 8 | +- The built `air-quality-card.js` file from the `dist/` folder |
| 9 | + |
| 10 | +## Installation Steps |
| 11 | + |
| 12 | +### 1. Locate your Home Assistant config directory |
| 13 | + |
| 14 | +Your HA config directory is typically at: |
| 15 | +- **Home Assistant OS / Supervised**: `/config/` |
| 16 | +- **Docker**: Wherever you mounted the config volume |
| 17 | +- **Core**: `~/.homeassistant/` |
| 18 | + |
| 19 | +### 2. Create the www directory (if it doesn't exist) |
| 20 | + |
| 21 | +```bash |
| 22 | +mkdir -p /config/www/community/air-quality-card |
| 23 | +``` |
| 24 | + |
| 25 | +### 3. Copy the card file |
| 26 | + |
| 27 | +Copy `dist/air-quality-card.js` to: |
| 28 | +``` |
| 29 | +/config/www/community/air-quality-card/air-quality-card.js |
| 30 | +``` |
| 31 | + |
| 32 | +**Via SCP (from your dev machine):** |
| 33 | +```bash |
| 34 | +scp dist/air-quality-card.js root@homeassistant.local:/config/www/community/air-quality-card/ |
| 35 | +``` |
| 36 | + |
| 37 | +**Via Samba share:** |
| 38 | +Copy the file to `\\homeassistant.local\config\www\community\air-quality-card\` |
| 39 | + |
| 40 | +### 4. Copy the rating images |
| 41 | + |
| 42 | +Copy the contents of the `img/` folder to your HA instance: |
| 43 | +```bash |
| 44 | +mkdir -p /config/www/airquality |
| 45 | +cp img/*.png /config/www/airquality/ |
| 46 | +``` |
| 47 | + |
| 48 | +### 5. Add the resource to Lovelace |
| 49 | + |
| 50 | +Go to **Settings > Dashboards > Resources** (enable Advanced Mode in your profile if you don't see it), then add: |
| 51 | + |
| 52 | +- **URL**: `/local/community/air-quality-card/air-quality-card.js` |
| 53 | +- **Type**: JavaScript Module |
| 54 | + |
| 55 | +Or add manually to your `configuration.yaml`: |
| 56 | +```yaml |
| 57 | +lovelace: |
| 58 | + resources: |
| 59 | + - url: /local/community/air-quality-card/air-quality-card.js |
| 60 | + type: module |
| 61 | +``` |
| 62 | +
|
| 63 | +### 6. Restart Home Assistant |
| 64 | +
|
| 65 | +Restart HA or reload resources for changes to take effect. |
| 66 | +
|
| 67 | +### 7. Clear browser cache |
| 68 | +
|
| 69 | +Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R) to load the new card version. |
| 70 | +
|
| 71 | +## Updating the Card |
| 72 | +
|
| 73 | +To update, simply replace the `air-quality-card.js` file and clear your browser cache. |
| 74 | + |
| 75 | +```bash |
| 76 | +# Build new version |
| 77 | +npm run build |
| 78 | +
|
| 79 | +# Copy to HA |
| 80 | +scp dist/air-quality-card.js root@homeassistant.local:/config/www/community/air-quality-card/ |
| 81 | +``` |
| 82 | + |
| 83 | +## Replacing an Existing HACS Installation |
| 84 | + |
| 85 | +If you previously installed via HACS and want to use your custom version: |
| 86 | + |
| 87 | +1. **Option A - Override HACS version:** |
| 88 | + - Copy your built file to `/config/www/community/air-quality-card/air-quality-card.js` |
| 89 | + - This overwrites the HACS-managed file (HACS updates will overwrite your changes) |
| 90 | + |
| 91 | +2. **Option B - Install alongside (recommended):** |
| 92 | + - Uninstall the HACS version first |
| 93 | + - Follow the installation steps above |
| 94 | + - Update your dashboard resource URL to point to your custom location |
| 95 | + |
| 96 | +## Troubleshooting |
| 97 | + |
| 98 | +**Card not showing up:** |
| 99 | +- Check browser console for errors (F12) |
| 100 | +- Verify the file exists at the correct path |
| 101 | +- Ensure the resource URL matches the file location |
| 102 | +- Clear browser cache |
| 103 | + |
| 104 | +**"Custom element doesn't exist" error:** |
| 105 | +- Resource not loaded - check the URL path |
| 106 | +- Try restarting Home Assistant |
| 107 | +- Check that the file isn't corrupted (should be ~28KB) |
0 commit comments