Skip to content

Commit 2bb4fb3

Browse files
arturo-ojedaclaude
andcommitted
feat: Match Awair color scheme and thresholds, fix overflow
- Update sensor thresholds to match Awair app values - CO2: 0-600 good, scale to 5000 - VOC: 0-300 good, scale to 25000 - PM2.5: 0-12 good, scale to 150 - Temperature: 20-25°C good (U-shaped gradient) - Humidity: 40-50% good (U-shaped gradient) - Implement Awair color gradient (green→yellow→orange→red→purple) - Add U-shaped gradients for temp/humidity (both extremes bad) - Replace fill-bar with position marker showing current value - Fix horizontal/vertical overflow by removing absolute positioning - Add GitHub Actions workflow for automatic releases on push to main - Add CUSTOM.md with manual installation instructions - Add CLAUDE.md for Claude Code guidance - Bump version to 1.1.0 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 994705f commit 2bb4fb3

9 files changed

Lines changed: 659 additions & 49 deletions

File tree

.github/workflow

Lines changed: 0 additions & 1 deletion
This file was deleted.

.github/workflows/release.yml

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
name: Build and Release
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
permissions:
9+
contents: write
10+
11+
jobs:
12+
build-and-release:
13+
runs-on: ubuntu-latest
14+
15+
steps:
16+
- name: Checkout code
17+
uses: actions/checkout@v4
18+
with:
19+
fetch-depth: 0
20+
21+
- name: Setup Node.js
22+
uses: actions/setup-node@v4
23+
with:
24+
node-version: '20'
25+
cache: 'npm'
26+
27+
- name: Install dependencies
28+
run: npm ci
29+
30+
- name: Build
31+
run: npm run build
32+
33+
- name: Get version from package.json
34+
id: package_version
35+
run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT
36+
37+
- name: Generate release tag
38+
id: tag
39+
run: |
40+
VERSION="v${{ steps.package_version.outputs.version }}"
41+
TIMESTAMP=$(date +%Y%m%d%H%M%S)
42+
# Check if version tag exists, if so append timestamp
43+
if git rev-parse "$VERSION" >/dev/null 2>&1; then
44+
TAG="${VERSION}-${TIMESTAMP}"
45+
else
46+
TAG="$VERSION"
47+
fi
48+
echo "tag=$TAG" >> $GITHUB_OUTPUT
49+
50+
- name: Create Release
51+
uses: softprops/action-gh-release@v2
52+
with:
53+
tag_name: ${{ steps.tag.outputs.tag }}
54+
name: Release ${{ steps.tag.outputs.tag }}
55+
body: |
56+
Automated release from push to main branch.
57+
58+
## Installation
59+
60+
Download `air-quality-card.js` and copy it to your Home Assistant:
61+
```
62+
/config/www/community/air-quality-card/air-quality-card.js
63+
```
64+
65+
See [CUSTOM.md](https://github.com/${{ github.repository }}/blob/main/CUSTOM.md) for detailed installation instructions.
66+
files: |
67+
dist/air-quality-card.js
68+
draft: false
69+
prerelease: false
70+
generate_release_notes: true

.gitignore

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
node_modules/
2+
.DS_Store
3+
temp/
4+
*.log

CLAUDE.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
This is a Home Assistant custom Lovelace card for displaying air quality sensor data with visual health range indicators. It's designed for HACS (Home Assistant Community Store) installation.
8+
9+
## Build Commands
10+
11+
```bash
12+
npm install # Install dependencies
13+
npm run build # Build production bundle (outputs to dist/)
14+
```
15+
16+
The build uses Webpack to bundle TypeScript source files into a single JavaScript file for Home Assistant.
17+
18+
## Architecture
19+
20+
**Main Components:**
21+
- `src/air-quality-card.ts` - Main card component using LitElement. Renders sensor bars with gradient visualization and rating badge
22+
- `src/air-quality-card-editor.ts` - Visual config editor for the card (uses `@customElement` decorator)
23+
24+
**Key Patterns:**
25+
- Uses Lit 3 with decorators (`experimentalDecorators` enabled in tsconfig)
26+
- `custom-card-helpers` for Home Assistant integration (`HomeAssistant` type, `fireEvent`)
27+
- Sensor thresholds defined in `SENSOR_THRESHOLDS` constant with min/max/unit/icon per sensor type
28+
- Rating images mapped in `RATING_IMAGES` (excellent/good/moderate/poor/unhealthy)
29+
30+
**Supported Sensors:**
31+
- CO2, VOC, PM2.5, Temperature, Humidity (with visual bars)
32+
- Rating (determines badge image)
33+
- Recommendation (optional text sensor)
34+
35+
**Distribution:**
36+
- `hacs.json` configures HACS with filename pointing to versioned JS in dist/
37+
- Update `hacs.json` filename when releasing new versions

CUSTOM.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
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)

dist/air-quality-card.js

Lines changed: 301 additions & 0 deletions
Large diffs are not rendered by default.

hacs.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{
22
"name": "Air Quality Card",
33
"description": "A custom Lovelace card to visualize air quality sensors with healthy range indicators",
4-
"filename": "air-quality-card.v1.0.1.js",
4+
"filename": "air-quality-card.js",
55
"type": "module",
66
"render_readme": true,
77
"domains": ["lovelace"],

package.json

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "air-quality-card",
3-
"version": "1.0.0",
3+
"version": "1.1.0",
44
"main": "webpack.config.js",
55
"scripts": {
66
"build": "webpack --config webpack.config.js",

0 commit comments

Comments
 (0)