Merge pull request #26 from Teslemetry/claude/plan-homebridge-integration-9ym5y

Add HomeBridge integration

Author: Bre77

packages/homebridge-teslemetry/README.md

@@ -0,0 +1,224 @@
+# @teslemetry/homebridge-teslemetry
+
+[![npm version](https://badge.fury.io/js/%40teslemetry%2Fhomebridge-teslemetry.svg)](https://badge.fury.io/js/%40teslemetry%2Fhomebridge-teslemetry)
+[![verified-by-homebridge](https://badgen.net/badge/homebridge/verified/purple)](https://github.com/homebridge/homebridge/wiki/Verified-Plugins)
+
+Teslemetry platform plugin for Homebridge with **real-time streaming support** for Tesla vehicles and energy sites.
+
+## Features
+
+🚗 **Tesla Vehicle Control**
+- Real-time status updates via Server-Sent Events (SSE)
+- Lock/unlock doors
+- Climate control (heat/cool)
+- Charge management
+- Sentry mode control
+- Window control
+- And more...
+
+⚡ **Energy Site Support** *(Coming Soon)*
+- Powerwall monitoring
+- Solar production tracking
+- Grid control
+
+🔄 **Real-time Streaming**
+- Instant updates when vehicle state changes
+- No polling - efficient and responsive
+- Built on Teslemetry's Fleet Telemetry API
+
+## Requirements
+
+- **Active Teslemetry Subscription**: Create an account and get an access token at [teslemetry.com](https://teslemetry.com)
+- **Node.js**: Version 18 or higher
+- **Homebridge**: Version 1.8.0 or higher
+- **Fleet Telemetry Support**: Your vehicle must support Fleet Telemetry (most recent Tesla vehicles)
+
+## Installation
+
+### Via Homebridge Config UI X (Recommended)
+
+1. Search for "Teslemetry" in the Homebridge Config UI X plugin search
+2. Click **Install**
+3. Configure the plugin with your Teslemetry access token
+
+### Via Command Line
+
+```bash
+npm install -g @teslemetry/homebridge-teslemetry
+```
+
+Or if using pnpm:
+
+```bash
+pnpm add -g @teslemetry/homebridge-teslemetry
+```
+
+## Configuration
+
+### Via Homebridge Config UI X
+
+The easiest way to configure this plugin is through the Homebridge Config UI X interface. All options are available through the visual interface.
+
+### Manual Configuration
+
+Add the following to your Homebridge `config.json`:
+
+```json
+{
+  "platforms": [
+    {
+      "platform": "Teslemetry",
+      "name": "Teslemetry",
+      "accessToken": "your_teslemetry_access_token_here",
+      "prefixName": true,
+      "latitude": 37.7749,
+      "longitude": -122.4194,
+      "ignoreVehicles": [],
+      "ignoreEnergySites": []
+    }
+  ]
+}
+```
+
+### Configuration Options
+
+| Option | Type | Required | Default | Description |
+|--------|------|----------|---------|-------------|
+| `platform` | string | **Yes** | - | Must be `"Teslemetry"` |
+| `accessToken` | string | **Yes** | - | Your Teslemetry API access token from [teslemetry.com](https://teslemetry.com) |
+| `name` | string | No | `"Teslemetry"` | Display name for the platform |
+| `prefixName` | boolean | No | `true` | Whether to prefix accessory names with the vehicle name |
+| `latitude` | number | No | - | Latitude for Homelink activation (required if using Homelink) |
+| `longitude` | number | No | - | Longitude for Homelink activation (required if using Homelink) |
+| `ignoreVehicles` | string[] | No | `[]` | Array of vehicle VINs to ignore |
+| `ignoreEnergySites` | number[] | No | `[]` | Array of energy site IDs to ignore |
+
+## Getting a Teslemetry Access Token
+
+1. Go to [teslemetry.com](https://teslemetry.com)
+2. Create an account or log in
+3. Navigate to your account settings
+4. Generate a new API access token
+5. Copy the token and paste it into your Homebridge configuration
+
+## Supported Vehicles
+
+This plugin supports all Tesla vehicles that have Fleet Telemetry capability:
+
+- Model 3 (2017+)
+- Model Y (2020+)
+- Model S (2021+ refresh)
+- Model X (2021+ refresh)
+- Cybertruck (2023+)
+
+Older Model S and Model X vehicles may have limited support.
+
+## HomeKit Accessories
+
+Each Tesla vehicle will appear as multiple accessories in HomeKit:
+
+### Current Implementation (Phase 1)
+- **Vehicle Discovery** - Automatic discovery and registration of vehicles
+- **Real-time Streaming** - Connection to Teslemetry's streaming API
+
+### Coming Soon (Phase 2)
+- **Battery Service** - Battery level and charging status
+- **Lock Service** - Lock/unlock doors
+- **Climate Service** - Temperature control and HVAC
+- **Charge Port** - Open/close charge port
+- **Charge Switch** - Start/stop charging
+- **Charge Limit** - Set charge limit percentage
+- **Defrost Service** - Activate max defrost
+- **Door Sensors** - Individual door status
+- **Window Control** - Vent/close windows
+- **Sentry Mode** - Enable/disable sentry mode
+- **Homelink** - Trigger Homelink (requires location config)
+
+## Troubleshooting
+
+### Plugin Not Discovering Vehicles
+
+1. Verify your access token is correct
+2. Check that you have an active Teslemetry subscription
+3. Ensure your vehicle supports Fleet Telemetry
+4. Check Homebridge logs for error messages
+
+### Streaming Connection Issues
+
+1. Verify network connectivity
+2. Check that Teslemetry streaming is enabled for your account
+3. Restart Homebridge
+4. Check firewall settings (SSE requires persistent connections)
+
+### Accessories Not Responding
+
+1. Check if vehicle is asleep (may take a moment to wake)
+2. Verify streaming connection status in logs
+3. Try restarting the Homebridge service
+
+## Development
+
+This package is part of the [Teslemetry TypeScript monorepo](https://github.com/Teslemetry/typescript-teslemetry).
+
+### Local Development
+
+```bash
+# Clone the repository
+git clone https://github.com/Teslemetry/typescript-teslemetry.git
+cd typescript-teslemetry
+
+# Install dependencies
+pnpm install
+
+# Build the package
+pnpm --filter @teslemetry/homebridge-teslemetry build
+
+# Watch mode for development
+pnpm --filter @teslemetry/homebridge-teslemetry watch
+```
+
+### Testing Locally
+
+```bash
+# Link globally for testing
+cd packages/homebridge-teslemetry
+pnpm link --global
+
+# In your Homebridge directory
+cd ~/.homebridge
+pnpm link --global @teslemetry/homebridge-teslemetry
+
+# Run Homebridge in debug mode
+homebridge -D
+```
+
+## Contributing
+
+Contributions are welcome! Please read the [contributing guidelines](../../CONTRIBUTING.md) before submitting pull requests.
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/Teslemetry/typescript-teslemetry/issues)
+- **Documentation**: [Teslemetry Docs](https://teslemetry.com/docs)
+- **Community**: [Teslemetry Discord](https://discord.gg/teslemetry)
+
+## License
+
+Apache-2.0 - see [LICENSE](../../LICENSE) for details.
+
+## Credits
+
+- Built with [@teslemetry/api](https://www.npmjs.com/package/@teslemetry/api)
+- Powered by [Teslemetry](https://teslemetry.com)
+- Part of the [Homebridge](https://homebridge.io) ecosystem
+
+## Related Projects
+
+- [@teslemetry/api](../api) - Core TypeScript SDK
+- [node-red-contrib-teslemetry](../node-red-contrib-teslemetry) - Node-RED integration
+- [n8n-nodes-teslemetry](../n8n-nodes-teslemetry) - n8n workflow integration
+- [homey](../homey) - Homey smart home app
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md) for release history.

packages/homebridge-teslemetry/config.schema.json

@@ -0,0 +1,98 @@
+{
+  "pluginAlias": "Teslemetry",
+  "pluginType": "platform",
+  "singular": true,
+  "headerDisplay": "Teslemetry platform plugin for Homebridge with real-time streaming support. Create an access token at [teslemetry.com](https://teslemetry.com).",
+  "footerDisplay": "For support and documentation, visit [GitHub](https://github.com/Teslemetry/typescript-teslemetry/tree/main/packages/homebridge-teslemetry).",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "name": {
+        "title": "Platform Name",
+        "type": "string",
+        "default": "Teslemetry",
+        "required": false,
+        "description": "The name for this platform instance"
+      },
+      "accessToken": {
+        "title": "Teslemetry Access Token",
+        "type": "string",
+        "required": true,
+        "description": "Your Teslemetry API access token from teslemetry.com"
+      },
+      "prefixName": {
+        "title": "Prefix Accessory Names",
+        "type": "boolean",
+        "default": true,
+        "required": false,
+        "description": "Prefix accessory names with vehicle/site name for easier identification"
+      },
+      "latitude": {
+        "title": "Latitude",
+        "type": "number",
+        "required": false,
+        "description": "Latitude for Homelink activation (required for Homelink service)"
+      },
+      "longitude": {
+        "title": "Longitude",
+        "type": "number",
+        "required": false,
+        "description": "Longitude for Homelink activation (required for Homelink service)"
+      },
+      "ignoreVehicles": {
+        "title": "Ignore Vehicles",
+        "type": "array",
+        "required": false,
+        "description": "List of vehicle VINs to ignore",
+        "items": {
+          "type": "string",
+          "title": "VIN",
+          "description": "Vehicle Identification Number"
+        }
+      },
+      "ignoreEnergySites": {
+        "title": "Ignore Energy Sites",
+        "type": "array",
+        "required": false,
+        "description": "List of energy site IDs to ignore",
+        "items": {
+          "type": "number",
+          "title": "Site ID",
+          "description": "Energy site identifier"
+        }
+      }
+    },
+    "required": ["accessToken"]
+  },
+  "layout": [
+    {
+      "type": "fieldset",
+      "title": "Authentication",
+      "expandable": false,
+      "items": ["accessToken"]
+    },
+    {
+      "type": "fieldset",
+      "title": "General Settings",
+      "expandable": true,
+      "expanded": false,
+      "items": ["name", "prefixName"]
+    },
+    {
+      "type": "fieldset",
+      "title": "Homelink Location",
+      "expandable": true,
+      "expanded": false,
+      "description": "Configure location for Homelink activation",
+      "items": ["latitude", "longitude"]
+    },
+    {
+      "type": "fieldset",
+      "title": "Filters",
+      "expandable": true,
+      "expanded": false,
+      "description": "Optionally ignore specific vehicles or energy sites",
+      "items": ["ignoreVehicles", "ignoreEnergySites"]
+    }
+  ]
+}

packages/homebridge-teslemetry/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@teslemetry/homebridge-teslemetry",
+  "displayName": "Homebridge Teslemetry",
+  "version": "0.1.0",
+  "description": "Teslemetry integration for Homebridge with real-time streaming support",
+  "author": "Teslemetry",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Teslemetry/typescript-teslemetry.git",
+    "directory": "packages/homebridge-teslemetry"
+  },
+  "bugs": {
+    "url": "https://github.com/Teslemetry/typescript-teslemetry/issues"
+  },
+  "main": "dist/index.cjs",
+  "type": "module",
+  "engines": {
+    "node": ">=18.0.0",
+    "homebridge": "^1.8.0 || ^2.0.0-beta.0"
+  },
+  "scripts": {
+    "build": "tsdown --format cjs",
+    "watch": "tsdown --format cjs --watch",
+    "tsc": "tsc --noEmit",
+    "prepublishOnly": "pnpm build"
+  },
+  "keywords": [
+    "homebridge-plugin",
+    "tesla",
+    "teslemetry",
+    "streaming",
+    "vehicle",
+    "smart-home",
+    "iot"
+  ],
+  "dependencies": {
+    "@teslemetry/api": "workspace:*"
+  },
+  "devDependencies": {
+    "homebridge": "^1.8.0",
+    "tsdown": "^0.16.7",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "homebridge": "^1.8.0 || ^2.0.0-beta.0"
+  },
+  "files": [
+    "dist",
+    "config.schema.json"
+  ]
+}