homebridge-game-light
v1.0.0
Published
A Homebridge plugin that creates a switch to trigger HomeKit automations when your favorite NBA team plays.
Maintainers
tr3ap3Readme
🏀 What It Does
Game Light monitors sports schedules and creates a switch in HomeKit that automatically turns ON when your team's game starts and OFF when it ends.
You then create HomeKit automations to control your actual lights:
- Game starts → Living room turns to team color
- Game ends → Living room returns to normal
This approach lets you use any lights already in your HomeKit setup (Hue, LIFX, Nanoleaf, etc.).
Currently Supported: NBA Basketball
More sports coming soon! See Future Extensibility.
✨ Features
- 🏀 Track your favorite team
- ⏱️ Smart polling with increased frequency in final minutes
- 🔄 Automatic game detection from official schedules
- 🎮 Manual switch toggle for testing
- 📊 Robust API rate limiting and retry logic
📦 Installation
Via Homebridge UI (Recommended)
- Open the Homebridge UI
- Go to Plugins tab
- Search for
homebridge-game-light - Click Install
Via Command Line
npm install -g homebridge-game-light⚙️ Configuration
Via Homebridge UI
- Go to Plugins → Game Light → Settings
- Select your sport and team
- Save and restart Homebridge
Manual Configuration
Add to your config.json:
{
"platforms": [
{
"platform": "GameLight",
"name": "Game Light",
"sport": "NBA",
"team": "BOS",
"pollingInterval": 5,
"scheduleCheckInterval": 6
}
]
}Configuration Options
| Option | Description | Default |
|--------|-------------|---------|
| sport | Sport league (NBA) | NBA |
| team | Team abbreviation (e.g., BOS, LAL, GSW) | BOS |
| pollingInterval | Minutes between game status checks during a game | 5 |
| scheduleCheckInterval | Hours between schedule checks when idle | 6 |
NBA Teams & Colors
Use these Hue (H) and Saturation (S) values when setting up your HomeKit light automations. In the Home app color picker, set the hue angle and saturation percentage to match.
Eastern Conference
| Code | Team | Primary | H° / S% | Secondary | H° / S% |
|------|------|---------|---------|-----------|---------|
| ATL | Atlanta Hawks | 
Western Conference
| Code | Team | Primary | H° / S% | Secondary | H° / S% |
|------|------|---------|---------|-----------|---------|
| DAL | Dallas Mavericks | 
Tip: In the Home app, tap a light → tap the color wheel → use Hue (angle around the wheel) and Saturation (distance from center).
🏠 Setting Up HomeKit Automations
After installing and configuring the plugin, you'll see a switch named after your team (e.g., "Boston Celtics Game") in the Home app.
Create "Game Start" Automation
- Open the Home app
- Tap Automation → + → Add Automation
- Choose An Accessory is Controlled
- Select your team's switch → Turns On
- Add actions:
- Set your lights to your team's color
- Set Brightness to 100%
- Tap Done
Create "Game End" Automation
- Tap + → Add Automation
- Choose An Accessory is Controlled
- Select your team's switch → Turns Off
- Add actions to set your lights back to normal
- Tap Done
🛠️ Development
# Clone the repository
git clone https://github.com/adamkornafeld/homebridge-game-light.git
cd game-light
# Install dependencies
npm install
# Build
npm run build
# Link for local testing
npm link
# Run Homebridge with debug logging
homebridge -DTesting the API
# Test API connection
npx tsx scripts/testApi.ts📋 How It Works
- Schedule Check: Plugin checks schedule for your team's games
- Game Detection: When a game is found, switches to active polling
- Game Start: When game status changes to "live", turns switch ON
- Smart Polling: In final minutes, polls more frequently for accuracy
- Game End: When game ends, turns switch OFF
- Idle: Returns to infrequent schedule checks
Schedule Check (every 6h)
│
▼
Game Found? ──No──→ Wait & Retry
│
Yes
▼
Poll Game (every 5m)
│
▼
Game Started? ──No──→ Wait & Retry
│
Yes
▼
🏀 Switch ON ──→ HomeKit Automation
│
▼
Final minutes? ──Yes──→ Poll every 30s
│
▼
Game Ended?
│
Yes
▼
🏁 Switch OFF ──→ HomeKit Automation⚠️ API Rate Limiting
This plugin uses public sports APIs which may have rate limiting. The plugin includes:
- Exponential backoff with jitter
Retry-Afterheader support- Minimum request intervals
- Graceful degradation on errors
If you see 429 errors in the logs, the plugin will automatically back off and retry.
🚀 Future Extensibility
| Feature | Description | |---------|-------------| | NHL Support | Add NHL API client, team data | | NFL Support | Add ESPN/NFL API | | MLB Support | Add MLB Stats API | | Multi-team | Support multiple teams (flash alternating colors) | | Score alerts | Flash lights on scoring plays | | Win celebration | Special color effect when your team wins | | Away game colors | Option to show opponent's color for away games | | Pre-game countdown | Gradual color transition before tip-off |
Want to contribute? PRs welcome!
🙏 Acknowledgments
- Homebridge for the amazing platform
- nba_api for API documentation
⚖️ Disclaimer
This project is not affiliated with, endorsed by, or connected to the National Basketball Association (NBA) or any of its member teams.
NBA, the NBA logo, and all NBA team names, logos, and related marks are registered trademarks of NBA Properties, Inc. and the respective NBA member teams. All other trademarks are the property of their respective owners.
Team colors provided in this plugin are approximations for personal, non-commercial home automation use only. This is an independent, open-source project created for fans to enhance their game-watching experience.
Use of the NBA API is subject to the NBA's terms of service. This plugin accesses only publicly available game schedule data.