{"id":28713444,"url":"https://github.com/drarox/enphasy","last_synced_at":"2026-05-17T00:10:25.478Z","repository":{"id":298881646,"uuid":"1001386279","full_name":"Drarox/Enphasy","owner":"Drarox","description":"Enphasy: A lightweight Enphase data sync tool using the cloud API. Fetches and stores solar production, consumption, import/export data automatically.","archived":false,"fork":false,"pushed_at":"2025-06-13T11:01:02.000Z","size":10,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-06-13T12:18:59.609Z","etag":null,"topics":["api","bun","cloud","enphase","enphase-api","enphase-envoy","enphase-gateway","solar"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/drarox/enphasy","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Drarox.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-13T09:39:22.000Z","updated_at":"2025-06-13T11:55:50.000Z","dependencies_parsed_at":"2025-06-13T12:29:03.486Z","dependency_job_id":null,"html_url":"https://github.com/Drarox/Enphasy","commit_stats":null,"previous_names":["drarox/enphasy"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Drarox/Enphasy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Drarox%2FEnphasy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Drarox%2FEnphasy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Drarox%2FEnphasy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Drarox%2FEnphasy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Drarox","download_url":"https://codeload.github.com/Drarox/Enphasy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Drarox%2FEnphasy/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259901390,"owners_count":22929227,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","bun","cloud","enphase","enphase-api","enphase-envoy","enphase-gateway","solar"],"created_at":"2025-06-15T00:10:20.214Z","updated_at":"2025-10-08T01:29:43.057Z","avatar_url":"https://github.com/Drarox.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ☀️ Enphasy - Enphase Monitoring Server\n[![Docker Pulls](https://badgen.net/docker/pulls/drarox/enphasy?icon=docker\u0026label=pulls)](https://hub.docker.com/r/drarox/enphasy/)\n[![Docker Image Size](https://badgen.net/docker/size/drarox/enphasy?icon=docker\u0026label=image%20size)](https://hub.docker.com/r/drarox/enphasy/)\n[![Github issues](https://img.shields.io/github/issues/drarox/enphasy?logo=github)](https://github.com/Drarox/Enphasy/issues)\n[![Github Pull Requests](https://img.shields.io/github/issues-pr/drarox/enphasy?logo=github)](https://github.com/Drarox/Enphasy/pulls)\n[![Github License](https://img.shields.io/github/license/drarox/enphasy)](https://github.com/Drarox/Enphasy/blob/master/LICENSE)\n\nA lightweight API server for fetching, storing, and serving solar energy data from the external Enphase Monitoring API, using SQLite as a local database. The app minimizes API usage by caching responses and scheduling smart fetches.\n\n---\n\n## ❓ Why this project?\n\nEnphasy exists because **local access to the Enphase device is not possible** in my setup.\n\nAlthough Enphase systems typically allow for local data access (e.g., via the Envoy gateway), my Enphase device is connected to a **separate, isolated network**—one that the main network running this server cannot reach. That means I can't pull data directly from the device over LAN.\n\nTo overcome this limitation, **Enphasy uses Enphase’s official cloud API** to fetch production, consumption, import/export, and system summary data. This allows me to gather and archive solar data remotely and reliably, even without direct device access.\n\n---\n\n## 🚀 Features\n\n- Fetches **current system summary** and caches it\n- Pulls **lifetime data daily at 3 AM** (production, consumption, import, export)\n- Stores all data in a local **SQLite** database\n- Refreshes **access token daily at midnight**\n- Includes Docker support with volume binding for database persistence\n\n\n---\n\n## 🖥️ Web Interface and API Docs\n\nOnce the service is running, you can access:\n\n- A small **Dashboard** (minimal status view) on `/`\n- The **Full API documentation** (made via Scalar) on `/docs`\n\n---\n\n## 🌐 API Endpoints\n\n- `GET /current`  \n  Returns cached current system summary (to avoid API limitations)\n\n- `GET /daily/:date`  \n  Returns stored lifetime data for a specific date (`YYYY-MM-DD`)\n\n- `GET /lifetime`  \n  Returns all the stored lifetime data\n\n- `GET /health`  \n  Returns simple \"Server is running\" health check response\n---\n\n## 🔐 Environment Variables\n\nCreate a `.env` file or use environment injection via Docker:\n\n```env\nENPHASE_API_KEY=your_api_key_here\nENPHASE_INITIAL_REFRESH_TOKEN=your_initial_refresh_token\nENPHASE_BASIC_AUTH=base64encoded(client_id:secret)\nSYSTEM_ID=your_enphase_system_id (can be found in the Enphase dashboard or mobile app)\nREQ_CACHE_MINUTES=60 (optional)\n````\n\nSee the How to get your Enphase API credentials section for details on how to obtain these values.\n\n---\n\n## 🐳 Docker Usage\n\n### Run with Compose\n\nUse this `docker-compose.yml`:\n\n```yaml\nversion: \"3.9\"\n\nservices:\n  enphase-monitor:\n    image: drarox/enphasy:latest\n    container_name: enphasy\n    restart: unless-stopped\n    ports:\n      - \"3000:3000\"\n    volumes:\n      - db:/usr/src/app/db\n    environment:\n      ENPHASE_API_KEY: your_api_key\n      ENPHASE_INITIAL_REFRESH_TOKEN: your_refresh_token\n      ENPHASE_BASIC_AUTH: xxxxx= #base64encoded(client_id:secret)\n      SYSTEM_ID: 00000000 #can be found in the Enphase dashboard or mobile app\n    #OR use env_file:\n    #env_file:\n    #  - .env\nvolumes:\n  db:\n```\n\nStart:\n\n```bash\ndocker-compose up -d\n```\n\n---\n\n## 📥 How to get your Enphase API credentials (click to expand)\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🛠️ Step-by-step guide (Enphase API setup using Watt plan)\u003c/strong\u003e\u003c/summary\u003e\n\n### ✅ Using the free tier from Enphase (plan named \u003ckbd\u003eWatt\u003c/kbd\u003e)\n\n---\n\n#### 1. Create an Enphase Developer Account\n\nSign up for free at:\n\n🔗 [https://developer-v4.enphase.com/signup](https://developer-v4.enphase.com/signup)\n\n---\n\n#### 2. Create a new app\n\n* Go to the **Applications** tab.\n* Click **Create Application**.\n* Select the **Watt** free plan.\n* Choose a name (e.g. `Enphasy`).\n* Under **Access Control**, select **all the permissions**.\n\n---\n\n#### 3. Gather credentials\n\n* Copy your **API Key** → Set as `ENPHASE_API_KEY` in your environment.\n* Copy your **Client ID** and **Client Secret**.\n* Create your `ENPHASE_BASIC_AUTH` value like this:\n\n```bash\n# Replace below with your actual client ID and secret\necho -n \"your_client_id:your_client_secret\" | base64\n```\n\nUse the result in your `.env` or `docker-compose.yml`:\n\n```env\nENPHASE_BASIC_AUTH=\u003cbase64_encoded_credentials\u003e\n```\n\n---\n\n#### 4. Get the initial refresh token\n\nYou’ll only need this **once**—afterward, Enphasy will auto-refresh it.\n\n##### 🔐 Authorize your app with an Enphase consumer account:\n\nTake the **Authorization URL** and append the required redirect URI:\n\nJust add `redirect_uri=https://api.enphaseenergy.com/oauth/redirect_uri` to the end of the URL:\n\n```text\nBase: https://api.enphaseenergy.com/oauth/authorize?response_type=code\u0026client_id=YOUR_CLIENT_ID\nFinal: https://api.enphaseenergy.com/oauth/authorize?response_type=code\u0026client_id=YOUR_CLIENT_ID\u0026redirect_uri=https://api.enphaseenergy.com/oauth/redirect_uri\n```\n\n* Open the final URL in your browser (or share it with the Enphase account holder).\n* Log in and authorize the app.\n* You’ll see something like:\n\n  \u003e **Authorization code (XXX) is generated**\n\n* Copy the code and paste it into the `curl` request below.\n---\n\n#### 5. Exchange the code for a refresh token\n\nMake this `curl` request to retrieve your first token:\n\n```bash\ncurl --location --request POST 'https://api.enphaseenergy.com/oauth/token?grant_type=authorization_code\u0026redirect_uri=https://api.enphaseenergy.com/oauth/redirect_uri\u0026code=XXX' \\\n--header 'Authorization: Basic XXXXXX='\n```\n\n* Replace the code `XXX` with the authorization code from the previous step.\n* Replace the basic authorization header `XXXXXX=` with your `ENPHASE_BASIC_AUTH` value from earlier.\n\nThis will return a JSON like:\n\n```json\n{\n  \"refresh_token\": \"your-refresh-token\",\n  ...\n}\n```\n\n---\n\n#### 6. Add it to your environment\n\nSet it in your `.env` or `docker-compose.yml`:\n\n```env\nENPHASE_INITIAL_REFRESH_TOKEN=your-refresh-token\n```\n\n---\n\n🎉 You're done! Enphasy will now handle data syncing and token refreshing automatically.\n\n---\n\n📚 **Further Documentation:**\n\n* [Quick Start Guide](https://developer-v4.enphase.com/docs/quickstart.html#step_1)\n* [Full API Reference](https://developer-v4.enphase.com/docs.html)\n\n\u003c/details\u003e\n\n---\n\n## 🕰️ Scheduled Tasks\n\n| Task                  | Schedule               |\n| --------------------- |------------------------|\n| Refresh access token  | Daily @ 00:00          |\n| Sync lifetime data    | Daily @ 03:00          |\n| Cache current summary | Every hour (on demand) |\n\n---\n\n## 🧪 Dev Server\n\nNote: This project uses [Bun](https://bun.sh). Install it with `curl -fsSL https://bun.sh/install | bash`\n\n```bash\nbun install\nbun run src/index.ts\n```\n\n---\n\n## 📌 Notes\n\n* SQLite writes must have write permissions. When running in Docker, always bind the DB to a host directory.\n* The Enphase free tier (Watt) limits API calls to 1000 per month — make sure to set `REQ_CACHE_MINUTES` to a sensible value to avoid hitting rate limits.\n* All critical errors are logged in the container console.\n\n---\n\n\u003cdetails\u003e\n\u003csummary\u003e📺 How to add Enphasy as a \u003ca href=\"https://gethomepage.dev/\" target=\"_blank\"\u003eHomepage\u003c/a\u003e widget\u003c/summary\u003e\n\nTo show Enphasy data in your Homepage dashboard, you can use the built-in `customapi` widget. Below is an example configuration that shows:\n\n- Real-time power data\n- Lifetime energy metrics\n- Yesterday's solar, consumption, import/export data\n\nAdd this block to your `homepage/config/services.yaml` file:\n\n```yaml\n    - Enphase Enlighten:\n        icon: /img/enphase.png\n        href: https://enlighten.enphaseenergy.com/web/\n        description: Solar Power\n        widgets:\n          - type: customapi\n            url: http://enphasy:3000/current\n            method: GET\n            mappings:\n              - field: current_power\n                label: Current Power\n                format: number\n                suffix: \"W\"\n              - field: energy_today\n                label: Energy Today\n                format: number\n                suffix: \"Wh\"\n              - field: energy_lifetime\n                label: Energy Lifetime\n                format: number\n                scale: 0.001\n                suffix: \"kWh\"\n          - type: customapi\n            url: http://enphasy:3000/daily/yesterday\n            method: GET\n            mappings:\n              - field: production\n                label: Prod Yest\n                format: number\n                suffix: \"Wh\"\n              - field: consumption\n                label: Cons Yest\n                format: number\n                suffix: \"Wh\"\n              - field: import\n                label: Import Yest\n                format: number\n                suffix: \"Wh\"\n              - field: export\n                label: Export Yest\n                format: number\n                suffix: \"Wh\"\n```\n\nPreview:\n\n![Enphasy widget](https://raw.githubusercontent.com/Drarox/Enphasy/master/img/homepage.png)\n\u003c/details\u003e\n\n---\n\n## 📃 License\n\n[GPL-3.0 license](https://github.com/Drarox/Enphasy/blob/master/LICENSE)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrarox%2Fenphasy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrarox%2Fenphasy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrarox%2Fenphasy/lists"}