{"id":35098546,"url":"https://github.com/cosimodamianoforina/battery-range","last_synced_at":"2026-04-01T18:23:39.924Z","repository":{"id":330700568,"uuid":"1123649938","full_name":"CosimoDamianoForina/Battery-Range","owner":"CosimoDamianoForina","description":"A smart battery charging manager for Windows laptops that helps extend battery lifespan by maintaining charge within optimal State of Charge (SoC) ranges using a Tasmota-compatible smart plug.","archived":false,"fork":false,"pushed_at":"2026-01-07T10:58:18.000Z","size":95,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-08T09:53:08.870Z","etag":null,"topics":["automation","battery","battery-health","battery-management","esp32","esp8266","home-automation","iot","laptop","notebook","power-management","powershell","smart-plug","system-tray","tasmota","utility","windows"],"latest_commit_sha":null,"homepage":"","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CosimoDamianoForina.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-27T10:20:00.000Z","updated_at":"2026-01-07T10:56:32.000Z","dependencies_parsed_at":"2025-12-29T03:08:20.304Z","dependency_job_id":null,"html_url":"https://github.com/CosimoDamianoForina/Battery-Range","commit_stats":null,"previous_names":["cosimodamianoforina/battery-range"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/CosimoDamianoForina/Battery-Range","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CosimoDamianoForina%2FBattery-Range","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CosimoDamianoForina%2FBattery-Range/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CosimoDamianoForina%2FBattery-Range/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CosimoDamianoForina%2FBattery-Range/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CosimoDamianoForina","download_url":"https://codeload.github.com/CosimoDamianoForina/Battery-Range/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CosimoDamianoForina%2FBattery-Range/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31018542,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-27T03:51:26.850Z","status":"ssl_error","status_checked_at":"2026-03-27T03:51:09.693Z","response_time":164,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["automation","battery","battery-health","battery-management","esp32","esp8266","home-automation","iot","laptop","notebook","power-management","powershell","smart-plug","system-tray","tasmota","utility","windows"],"created_at":"2025-12-27T16:08:42.619Z","updated_at":"2026-03-27T04:01:56.894Z","avatar_url":"https://github.com/CosimoDamianoForina.png","language":"PowerShell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\r\n\u003cimg width=\"640\" height=\"320\" alt=\"Battery-Range\" src=\"https://github.com/user-attachments/assets/7e9f58f9-c61b-4965-aaf1-337a1bdc04f5\" /\u003e\r\n\u003c/p\u003e\r\n\r\n# Battery-Range\r\n\r\nA smart battery charging manager for Windows laptops that helps extend battery lifespan by maintaining charge within optimal State of Charge (SoC) ranges using a Tasmota-compatible smart plug.\r\n\r\n## Why?\r\n\r\nLithium-ion batteries degrade faster when kept at 100% charge or frequently deep-discharged. Research suggests maintaining batteries between 20-80% (or even narrower ranges like 40-60%) can significantly extend their lifespan. Battery Range automates this by controlling your laptop charger through a smart plug.\r\n\r\n## Features\r\n\r\n- **Automatic Battery Management** - Maintains battery within configurable SoC ranges\r\n- **Dual Range Profiles** - Normal (35-45%) and High (70-80%) modes for different needs\r\n- **One-Time Target** - Charge/discharge to a specific target once\r\n- **Manual Override** - Force charger on/off when needed\r\n- **System Tray Integration** - Unobtrusive operation with right-click context menu\r\n- **Failure Notifications** - Alerts you to manually plug/unplug if smart plug is unreachable\r\n- **Intelligent Standby Handling** - Configurable thresholds to manage charging before sleep\r\n- **Wi-Fi Hotspot Management** - Optionally manages Windows Mobile Hotspot for smart plug connectivity\r\n- **Single Instance** - Prevents multiple copies from running simultaneously\r\n\r\n## How It Works\r\n\r\n```\r\n┌─────────────────────────────────────────────────────────┐\r\n│                   Auto Mode Flowchart                   │\r\n├─────────────────────────────────────────────────────────┤\r\n│   Check Battery Level (every N seconds)                 │\r\n│              │                                          │\r\n│              ▼                                          │\r\n│   ┌─────────────────────┐                               │\r\n│   │  Battery ≤ Min%     │──Yes──► Turn ON Smart Plug    │\r\n│   │  AND discharging?   │                               │\r\n│   └─────────────────────┘                               │\r\n│              │ No                                       │\r\n│              ▼                                          │\r\n│   ┌─────────────────────┐                               │\r\n│   │  Battery ≥ Max%     │──Yes──► Turn OFF Smart Plug   │\r\n│   │  AND charging?      │                               │\r\n│   └─────────────────────┘                               │\r\n│              │ No                                       │\r\n│              ▼                                          │\r\n│        Do Nothing                                       │\r\n└─────────────────────────────────────────────────────────┘\r\n```\r\n\r\n## Requirements\r\n\r\n- Windows 10/11\r\n- PowerShell 5.1 or later\r\n- Tasmota-compatible Wi-Fi smart plug (see [Devices with Factory Flashed Tasmota](https://templates.blakadder.com/preflashed.html))\r\n- Network connectivity between laptop and smart plug (regular Wi-Fi network or Windows Mobile Hotspot)\r\n\r\n## Quick Start\r\n\r\n1. Set up your Tasmota smart plug (see [Smart Plug Setup](#tasmota-smart-plug-setup))\r\n2. Download `Battery-Range.ps1`\r\n3. Run the script:\r\n   ```powershell\r\n   .\\Battery-Range.ps1\r\n   ```\r\n4. Right-click the system tray icon to select modes\r\n\r\n## Parameters\r\n\r\n### Smart Plug Configuration\r\n\r\n| Parameter | Default | Range | Description |\r\n|-----------|---------|-------|-------------|\r\n| `-SmartplugIP` | 192.168.137.101 | - | IP address of the Tasmota smart plug |\r\n| `-SmartplugTimeoutSeconds` | 2 | 1-5 | Timeout in seconds for smart plug requests |\r\n| `-SmartplugConnectionMaxAttempts` | 10 | 2-50 | Maximum attempts to verify smart plug is reachable |\r\n| `-SmartplugCommunicationMaxAttempts` | 3 | 1-10 | Maximum attempts to send commands to the smart plug |\r\n\r\n### Battery Levels\r\n\r\n| Parameter | Default | Range | Description |\r\n|-----------|---------|-------|-------------|\r\n| `-MinBatteryLevel` | 35 | 19-99 | Minimum battery % for Auto mode |\r\n| `-MaxBatteryLevel` | 45 | 20-100 | Maximum battery % for Auto mode |\r\n| `-MinBatteryLevelHigh` | 70 | 19-99 | Minimum battery % for Auto High mode |\r\n| `-MaxBatteryLevelHigh` | 80 | 20-100 | Maximum battery % for Auto High mode |\r\n\r\n**Min values must be less than their corresponding Max values.**\r\n\r\n### Timing \u0026 Behavior\r\n\r\n| Parameter | Default | Range | Description |\r\n|-----------|---------|-------|-------------|\r\n| `-CheckIntervalSeconds` | 30 | 15-300 | How often to check battery status |\r\n| `-ConfirmationTimeoutSeconds` | 5 | 1-10 | Timeout for confirming charging state change |\r\n\r\n### Standby Thresholds\r\n\r\n| Parameter | Default | Range | Description |\r\n|-----------|---------|-------|-------------|\r\n| `-StandbyOnSoCThreshold` | 15 | -1 to 30 | Turn ON charger before standby if battery ≤ this % (set to -1 to disable) |\r\n| `-StandbyOffSoCThreshold` | 30 | 20-101 | Turn OFF charger before standby if battery ≥ this % (set to 101 to disable) |\r\n\r\n**StandbyOnSoCThreshold must be less than StandbyOffSoCThreshold.** Battery levels between these thresholds will keep the current charger state.\r\n\r\n### Wi-Fi Hotspot Management\r\n\r\n| Parameter | Default | Range | Description |\r\n|-----------|---------|-------|-------------|\r\n| `-ManageWiFiHotspot` | false | - | Enable automatic Windows Mobile Hotspot management |\r\n| `-HotspotTimeoutSeconds` | 30 | 5-120 | Timeout for activating Windows Mobile Hotspot |\r\n\r\n### Example with Custom Settings\r\n\r\n```powershell\r\n.\\Battery-Range.ps1 -SmartplugIP \"192.168.1.100\" -MinBatteryLevel 40 -MaxBatteryLevel 60\r\n```\r\n\r\n### Example with Wi-Fi Hotspot Management\r\n\r\n```powershell\r\n.\\Battery-Range.ps1 -ManageWiFiHotspot 1 -HotspotTimeoutSeconds 60\r\n```\r\n\r\n### Example with Custom Standby Behavior\r\n\r\n```powershell\r\n# Turn on charger if battery ≤ 20%, turn off if battery ≥ 50%\r\n.\\Battery-Range.ps1 -StandbyOnSoCThreshold 20 -StandbyOffSoCThreshold 50\r\n\r\n# Only turn off charger before standby (disable turn-on behavior)\r\n.\\Battery-Range.ps1 -StandbyOnSoCThreshold -1 -StandbyOffSoCThreshold 30\r\n\r\n# Only turn on charger before standby (disable turn-off behavior)\r\n.\\Battery-Range.ps1 -StandbyOnSoCThreshold 15 -StandbyOffSoCThreshold 101\r\n\r\n# Disable standby charger management entirely\r\n.\\Battery-Range.ps1 -StandbyOnSoCThreshold -1 -StandbyOffSoCThreshold 101\r\n```\r\n\r\n## Modes\r\n\r\n| Mode | Description |\r\n|------|-------------|\r\n| **Auto** | Maintains battery between `MinBatteryLevel` and `MaxBatteryLevel` (default: 35-45%) |\r\n| **Auto High** | Maintains battery between `MinBatteryLevelHigh` and `MaxBatteryLevelHigh` (default: 70-80%) |\r\n| **To X% Once...** | Brings the battery to a specific target and then returns to the previous mode |\r\n| **Charger On** | Forces charger on continuously (useful before travel) |\r\n| **Charger Off** | Forces charger off continuously |\r\n\r\n## System Tray Icon\r\n\r\nThe tray icon provides at-a-glance status:\r\n\r\n| Element | Meaning |\r\n|---------|---------|\r\n| **Number** | Current battery percentage |\r\n| **Text color: Green** | Laptop is on AC power |\r\n| **Text color: White** | Laptop is on battery |\r\n| **Border: Blue** | Auto mode |\r\n| **Border: Magenta** | Auto High mode |\r\n| **Border: Gold** | To X% Once mode |\r\n| **Border: Green** | Charger On mode |\r\n| **Border: Orange** | Charger Off mode |\r\n\r\n## Standby Behavior\r\n\r\nBattery Range intelligently handles system sleep with two configurable thresholds:\r\n\r\n- **Before Standby**:\r\n  - If battery ≤ `StandbyOnSoCThreshold` (default: 15%), charger turns ON to prevent deep discharge\r\n  - If battery ≥ `StandbyOffSoCThreshold` (default: 30%), charger turns OFF to prevent overcharging\r\n  - If battery is between thresholds, charger state is unchanged\r\n- **On Resume**: Battery check timer restarts immediately, and if Wi-Fi Hotspot management is enabled, the hotspot is re-activated\r\n\r\nThis is useful for scenarios like closing your laptop overnight → the battery won't overcharge if it's high, and won't deep discharge if it's low.\r\n\r\n## Wi-Fi Hotspot Management\r\n\r\nFor portable setups where the smart plug connects directly to your laptop's Mobile Hotspot:\r\n\r\n- Enable with `-ManageWiFiHotspot 1`\r\n- The script will automatically start the Windows Mobile Hotspot on launch\r\n- On resume from standby, the hotspot is re-activated and smart plug connectivity is verified\r\n\r\nThis feature is ideal when you don't have a shared Wi-Fi network available (e.g., traveling).\r\n\r\n## Running at Startup\r\n\r\n1. Press `Win + R`, type `shell:startup`, press Enter\r\n2. Create a shortcut to run the script:\r\n   - Right-click → New → Shortcut\r\n   - Target: `powershell -WindowStyle Hidden -ExecutionPolicy Bypass -Command \"[path to the script]\\Battery-Range.ps1 [custom parameters]\"`\r\n   - Name: `Battery-Range`\r\n\r\n## Robustness Notes\r\n\r\n- **On Exit**: The script automatically turns the charger ON when exiting to prevent accidental battery drain\r\n- **On Standby**: Charger is turned ON if battery is low, OFF if battery is high (based on configurable thresholds)\r\n- **On Resume**: Timer restarts immediately; Wi-Fi Hotspot is re-activated if managed\r\n- **Power Outages**: If the smart plug loses power, it will restore its previous state when power returns (default Tasmota behavior)\r\n- **Plug Failures**: If the smart plug is unreachable, a Windows notification prompts manual action\r\n- **Wiring Issues**: If the battery charging status is inconsistent with the smart plug status, a notification prompts the user to check the charger connection\r\n\r\n## Tasmota Smart Plug Setup\r\n\r\n### Flashing Tasmota\r\n\r\nIf your smart plug doesn't already have Tasmota, you'll need to flash it. See the [Tasmota documentation](https://tasmota.github.io/docs/) for device-specific instructions.\r\n\r\n### Configuring Static IP for Windows Mobile Hotspot\r\n\r\nIf you're using your laptop's Mobile Hotspot to connect the smart plug (useful for portable setups), configure a static IP on the plug:\r\n\r\n1. Connect to your Tasmota plug's web interface\r\n2. Go to **Console**\r\n3. Enter the following command:\r\n\r\n```\r\nBacklog IPAddress1 192.168.137.101; IPAddress2 192.168.137.1; IPAddress3 255.255.255.0; IPAddress4 192.168.137.1; Restart 1\r\n```\r\n\r\nThis sets:\r\n- **IPAddress1**: Static IP for the plug (`192.168.137.101`)\r\n- **IPAddress2**: Gateway (Windows hotspot is always `192.168.137.1`)\r\n- **IPAddress3**: Subnet mask (`255.255.255.0`)\r\n- **IPAddress4**: DNS server (using the gateway)\r\n\r\nThe plug will restart with the new network settings.\r\n\r\n### Configuring for Regular Wi-Fi Network\r\n\r\nFor a regular home network, use your router's DHCP reservation feature to assign a static IP, or configure via Tasmota console:\r\n\r\n```\r\nBacklog IPAddress1 192.168.1.101; IPAddress2 192.168.1.1; IPAddress3 255.255.255.0; IPAddress4 192.168.1.1; Restart 1\r\n```\r\n\r\nAdjust the IP addresses to match your network configuration.\r\n\r\n## Troubleshooting\r\n\r\n| Issue | Solution |\r\n|-------|----------|\r\n| Script won't start | Ensure execution policy allows scripts: `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` |\r\n| Can't connect to plug | Verify IP address and that laptop and plug are on same network |\r\n| Notifications not appearing | Check Windows notification settings for PowerShell |\r\n| Battery not detected | Ensure running on a laptop with battery installed |\r\n| Hotspot won't start | Ensure Wi-Fi adapter supports hosted networks and no other app is using it |\r\n| \"Already running\" message | Check system tray for existing instance or restart explorer.exe |\r\n\r\n## License\r\n\r\nMIT License - See [LICENSE](LICENSE) for details.\r\n\r\n## Contributing\r\n\r\nContributions are welcome! Please open an issue or submit a pull request.\r\n\r\n## Acknowledgments\r\n\r\n- [Tasmota](https://github.com/arendst/tasmota) - Open source firmware for ESP8266/ESP32 devices\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcosimodamianoforina%2Fbattery-range","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcosimodamianoforina%2Fbattery-range","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcosimodamianoforina%2Fbattery-range/lists"}