{"id":27072514,"url":"https://github.com/cyberdns/energy-ai","last_synced_at":"2026-05-09T04:32:17.674Z","repository":{"id":286233750,"uuid":"933244389","full_name":"CyberDNS/energy-ai","owner":"CyberDNS","description":"This project provides an API for optimizing battery schedules using MQTT-based forecasts and a linear optimization algorithm.","archived":false,"fork":false,"pushed_at":"2025-04-05T05:12:39.000Z","size":2666,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-05T06:20:19.643Z","etag":null,"topics":["battery","home-assistant","iobroker","mqtt","photovoltaic","tibber","zendure"],"latest_commit_sha":null,"homepage":"","language":"Python","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/CyberDNS.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}},"created_at":"2025-02-15T13:59:46.000Z","updated_at":"2025-04-05T05:12:42.000Z","dependencies_parsed_at":"2025-04-05T06:20:42.463Z","dependency_job_id":null,"html_url":"https://github.com/CyberDNS/energy-ai","commit_stats":null,"previous_names":["cyberdns/energy-ai"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyberDNS%2Fenergy-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyberDNS%2Fenergy-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyberDNS%2Fenergy-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CyberDNS%2Fenergy-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CyberDNS","download_url":"https://codeload.github.com/CyberDNS/energy-ai/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247411377,"owners_count":20934674,"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":["battery","home-assistant","iobroker","mqtt","photovoltaic","tibber","zendure"],"created_at":"2025-04-05T23:18:08.382Z","updated_at":"2026-05-09T04:32:17.636Z","avatar_url":"https://github.com/CyberDNS.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"assets/CozyPowerBear.png\" alt=\"Energy AI Logo\" width=\"200\"\u003e\n\n# Energy AI API\n\nThis project provides an API for optimizing battery schedules using MQTT-based forecasts and a linear optimization algorithm.\n\n## API Usage\n\n### Endpoint: `/optimize`\n\n- **Method**: `POST`\n- **Content-Type**: `application/json`\n- **Description**: Optimizes the battery schedule based on the provided current state of charge and forecast data fetched via MQTT.\n\n#### Request Body\n```json\n{\n  \"current_soc_percent\": 50,  // Current state of charge in percentage\n  \"current_time_index\": 12,   // Current time index (e.g., hour of the day)\n  \"battery_params\": {         // Optional: Custom battery parameters\n    \"capacity_kwh\": 7.4,\n    \"max_rate_kw\": 0.8,\n    \"min_soc_percent\": 10,\n    \"efficiency_roundtrip\": 0.90\n  }\n}\n```\n\n#### Response\n- **200 OK**: Optimization successful, returns the next action and estimated savings.\n- **400 Bad Request**: Missing or invalid input fields.\n- **503 Service Unavailable**: Failed to fetch forecast data.\n- **500 Internal Server Error**: Optimization or MQTT publishing error.\n\nExample Response:\n```json\n{\n  \"solver_status\": \"Optimal\",\n  \"action_next_hour\": 0.5,\n  \"estimated_total_savings\": 12.34,\n  \"mqtt_publish_status\": \"Success\"\n}\n```\n\n---\n\n## Environment Variables\n\nThe application uses the following environment variables for configuration:\n\n| Variable               | Default Value                     | Description                                      |\n|------------------------|-----------------------------------|--------------------------------------------------|\n| `MQTT_BROKER`          | `localhost`                      | MQTT broker hostname or IP address.             |\n| `MQTT_PORT`            | `1883`                           | MQTT broker port.                               |\n| `MQTT_TOPIC_FORECAST`  | `forecast/topic`                 | MQTT topic for receiving forecast data.         |\n| `MQTT_TOPIC`           | `battery/schedule/optimal`       | MQTT topic for publishing optimized schedules.  |\n| `MQTT_USERNAME`        | None                             | MQTT username for authentication (optional).    |\n| `MQTT_PASSWORD`        | None                             | MQTT password for authentication (optional).    |\n\n\n### Example `.env` File\n```env\nMQTT_BROKER=192.168.1.100\nMQTT_PORT=1883\nMQTT_TOPIC_FORECAST=forecast/topic\nMQTT_TOPIC=battery/schedule/optimal\nMQTT_USERNAME=user\nMQTT_PASSWORD=pass\n```\n\n---\n\n## Building and Publishing the Docker Image\n\n### Build the Docker Image\nTo build the Docker image, use the following command:\n```bash\ndocker buildx build --platform linux/amd64 -t registry.example.com/energy-ai:latest .\n```\n\n### Push the Docker Image\nTo push the image to a Docker registry:\n```bash\ndocker push registry.example.com/energy-ai:latest\n```\n\nReplace `registry.example.com` with your Docker registry URL.\n\n---\n\n## Running the Application\n\n1. Ensure the required environment variables are set (e.g., via `.env` file).\n2. Run the application using Docker:\n   ```bash\n   docker run --env-file .env -p 5001:5001 registry.example.com/energy-ai:latest\n   ```\n3. Access the API at `http://localhost:5001/optimize`.\n\n---\n\n## Logging\n\nLogs are output to the console in the following format:\n```\n[Timestamp] [LogLevel] Message\n```\nAdjust the logging level by modifying the `logging.basicConfig` configuration in `app.py`.\n\n---\n\n## Integration with Smart Home Systems\n\nThis project can be integrated into smart home systems to optimize energy usage and visualize data. In my setup, I integrated the system using ioBroker, Tibber, PVForecast, and a Zendure battery. The data is processed and pushed into MQTT, which is then consumed by Home Assistant to display charts.\n\n### Components Used:\n1. **ioBroker**: For managing states and integrating with Tibber and PVForecast.\n2. **Tibber**: Provides electricity price data.\n3. **PVForecast**: Supplies solar production forecasts.\n4. **Zendure Battery**: Used for energy storage and control.\n5. **MQTT**: Acts as a communication layer for optimized schedules.\n6. **Home Assistant**: Displays the data using custom charts.\n\n### Code Disclaimer:\nThe provided code is heavily adapted for my specific use case. You may need to modify it to suit your own setup and requirements.\n\n#### Relevant Files:\n- `tibber-prices.js`: Processes Tibber prices and solar forecasts to calculate adjusted prices.\n- `zendure-control-ai.js`: Controls the Zendure battery based on AI-optimized schedules.\n- `hass-apexcharts-pricegraph.yml`: Displays Tibber prices and adjusted prices in Home Assistant.\n- `hass-apexcharts-actionschart.yml`: Visualizes battery actions in Home Assistant.\n\n---\n\n## Example Charts in Home Assistant\n\n### Tibber Prices Adjusted by Solar Production\nThe `hass-apexcharts-pricegraph.yml` file configures a chart to display Tibber prices and adjusted prices based on solar production.\n\n\u003cimg src=\"assets/hass-integration-1.png\" alt=\"Energy AI Logo\" width=\"400\"\u003e\n\n### Battery Actions\nThe `hass-apexcharts-actionschart.yml` file configures a chart to show battery charge and discharge actions.\n\n\u003cimg src=\"assets/hass-integration-2.png\" alt=\"Energy AI Logo\" width=\"400\"\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyberdns%2Fenergy-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcyberdns%2Fenergy-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcyberdns%2Fenergy-ai/lists"}