{"id":19867,"name":"BatterySense","description":"A simple Arduino library to monitor battery consumption of your battery powered projects, being LiPo, LiIon, NiCd or any other battery type, single or multiple cells: if it can power your Arduino you can monitor it.","url":"https://github.com/rlogiacco/BatterySense","last_synced_at":"2026-06-01T17:30:38.172Z","repository":{"id":28128208,"uuid":"31627347","full_name":"rlogiacco/BatterySense","owner":"rlogiacco","description":"Arduino library to monitor battery consumption","archived":false,"fork":false,"pushed_at":"2024-01-27T14:35:44.000Z","size":538,"stargazers_count":444,"open_issues_count":2,"forks_count":77,"subscribers_count":24,"default_branch":"master","last_synced_at":"2026-04-08T15:03:55.574Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rlogiacco.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["rlogiacco"],"custom":["https://www.paypal.me/rlogiacco"]}},"created_at":"2015-03-03T23:32:50.000Z","updated_at":"2026-03-27T09:22:34.000Z","dependencies_parsed_at":"2024-03-17T04:07:06.144Z","dependency_job_id":"44e08ed9-26c4-4f0c-bdbb-a8462bdd1f80","html_url":"https://github.com/rlogiacco/BatterySense","commit_stats":{"total_commits":101,"total_committers":9,"mean_commits":"11.222222222222221","dds":"0.25742574257425743","last_synced_commit":"f43f782be47c3b6b7fd8a9ae4dfee7981aec4627"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/rlogiacco/BatterySense","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlogiacco%2FBatterySense","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlogiacco%2FBatterySense/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlogiacco%2FBatterySense/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlogiacco%2FBatterySense/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rlogiacco","download_url":"https://codeload.github.com/rlogiacco/BatterySense/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlogiacco%2FBatterySense/sbom","scorecard":{"id":778655,"data":{"date":"2025-08-11","repo":{"name":"github.com/rlogiacco/BatterySense","commit":"f43f782be47c3b6b7fd8a9ae4dfee7981aec4627"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3.5,"checks":[{"name":"Code-Review","score":1,"reason":"Found 2/19 approved changesets -- score normalized to 1","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/docs.yml:1","Warn: no topLevel permission defined: .github/workflows/main.yml:1","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/docs.yml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/rlogiacco/BatterySense/docs.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/docs.yml:18: update your workflow using https://app.stepsecurity.io/secureworkflow/rlogiacco/BatterySense/docs.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/docs.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/rlogiacco/BatterySense/docs.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/main.yml:23: update your workflow using https://app.stepsecurity.io/secureworkflow/rlogiacco/BatterySense/main.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/main.yml:24: update your workflow using https://app.stepsecurity.io/secureworkflow/rlogiacco/BatterySense/main.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/main.yml:44: update your workflow using https://app.stepsecurity.io/secureworkflow/rlogiacco/BatterySense/main.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/main.yml:45: update your workflow using https://app.stepsecurity.io/secureworkflow/rlogiacco/BatterySense/main.yml/master?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/main.yml:65: update your workflow using https://app.stepsecurity.io/secureworkflow/rlogiacco/BatterySense/main.yml/master?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/main.yml:66: update your workflow using https://app.stepsecurity.io/secureworkflow/rlogiacco/BatterySense/main.yml/master?enable=pin","Info:   0 out of   4 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   5 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: GNU Lesser General Public License v3.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 14 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-23T04:19:39.442Z","repository_id":28128208,"created_at":"2025-08-23T04:19:39.442Z","updated_at":"2025-08-23T04:19:39.442Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31808518,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-14T11:13:53.975Z","status":"ssl_error","status_checked_at":"2026-04-14T11:13:53.299Z","response_time":153,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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"}},"owner":{"login":"rlogiacco","name":"Roberto Lo Giacco","uuid":"199473","kind":"user","description":null,"email":"rlogiacco@gmail.com","website":"http://rlogiacco.wordpress.com","location":"Rome","twitter":null,"company":null,"icon_url":"https://avatars.githubusercontent.com/u/199473?v=4","repositories_count":49,"last_synced_at":"2026-02-06T03:41:07.363Z","metadata":{"has_sponsors_listing":true},"html_url":"https://github.com/rlogiacco","funding_links":["https://github.com/sponsors/rlogiacco"],"total_stars":1102,"followers":82,"following":4,"created_at":"2022-11-03T04:29:33.577Z","updated_at":"2026-02-06T03:41:07.363Z","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rlogiacco","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rlogiacco/repositories"},"packages":[],"commits":{"id":1253949,"full_name":"rlogiacco/BatterySense","default_branch":"master","total_commits":101,"total_committers":9,"total_bot_commits":0,"total_bot_committers":0,"mean_commits":11.222222222222221,"dds":0.25742574257425743,"past_year_total_commits":0,"past_year_total_committers":0,"past_year_total_bot_commits":0,"past_year_total_bot_committers":0,"past_year_mean_commits":0.0,"past_year_dds":0.0,"last_synced_at":"2026-04-08T15:10:32.756Z","last_synced_commit":"f43f782be47c3b6b7fd8a9ae4dfee7981aec4627","created_at":"2023-03-27T10:48:56.972Z","updated_at":"2026-04-08T15:10:32.733Z","committers":[{"name":"Roberto Lo Giacco","email":"rlogiacco@gmail.com","login":"rlogiacco","count":75},{"name":"mesmerise","email":"and-fis@gmx.de","login":"mesmerise","count":12},{"name":"Nuno Nunes (air)","email":"nuno@nunonunes.org","login":"nunonunes","count":8},{"name":"per1234","email":"accounts@perglass.com","login":"per1234","count":1},{"name":"VOIPMINIC","email":"joan@voipminic.com","login":"voipminic","count":1},{"name":"Torsten Blindert","email":"info@by-torsten.com","login":"Torsten85","count":1},{"name":"Peter Murray","email":"jester@dltj.org","login":"dltj","count":1},{"name":"Michaël Lhomme","email":"papylhomme@gmail.com","login":"papylhomme","count":1},{"name":"JimJJewett","email":"JimJJewett+github@gmail.com","login":"JimJJewett","count":1}],"past_year_committers":[],"commits_url":"https://commits.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlogiacco%2FBatterySense/commits","host":{"name":"GitHub","url":"https://github.com","kind":"github","last_synced_at":"2026-04-14T00:00:07.982Z","repositories_count":6213305,"commits_count":903405131,"contributors_count":34927098,"owners_count":1144355,"icon_url":"https://github.com/github.png","host_url":"https://commits.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://commits.ecosyste.ms/api/v1/hosts/GitHub/repositories"}},"issues_stats":{"full_name":"rlogiacco/BatterySense","html_url":"https://github.com/rlogiacco/BatterySense","last_synced_at":"2025-09-01T03:05:52.367Z","status":"error","issues_count":14,"pull_requests_count":10,"avg_time_to_close_issue":9269760.0,"avg_time_to_close_pull_request":595297.0,"issues_closed_count":12,"pull_requests_closed_count":10,"pull_request_authors_count":10,"issue_authors_count":13,"avg_comments_per_issue":3.2142857142857144,"avg_comments_per_pull_request":1.1,"merged_pull_requests_count":9,"bot_issues_count":0,"bot_pull_requests_count":0,"past_year_issues_count":1,"past_year_pull_requests_count":0,"past_year_avg_time_to_close_issue":null,"past_year_avg_time_to_close_pull_request":null,"past_year_issues_closed_count":0,"past_year_pull_requests_closed_count":0,"past_year_pull_request_authors_count":0,"past_year_issue_authors_count":1,"past_year_avg_comments_per_issue":1.0,"past_year_avg_comments_per_pull_request":null,"past_year_bot_issues_count":0,"past_year_bot_pull_requests_count":0,"past_year_merged_pull_requests_count":0,"created_at":"2023-05-09T10:39:29.385Z","updated_at":"2025-09-02T11:52:01.307Z","repository_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlogiacco%2FBatterySense","issues_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories/rlogiacco%2FBatterySense/issues","issue_labels_count":{"enhancement":3,"bug":2,"waiting feedback":2,"invalid":1},"pull_request_labels_count":{"bug":1},"issue_author_associations_count":{"NONE":10,"OWNER":2,"CONTRIBUTOR":2},"pull_request_author_associations_count":{"CONTRIBUTOR":8,"OWNER":2,"NONE":1},"issue_authors":{"rlogiacco":2,"philipdbrown":1,"fyrus7":1,"nandakrpp":1,"sohelmomeni":1,"mesmerise":1,"Dans-Droids":1,"entozoon":1,"jeremy-meier":1,"ghost":1,"TThack":1,"diogoribeiro09":1,"papylhomme":1},"pull_request_authors":{"rlogiacco":2,"JimJJewett":1,"per1234":1,"dltj":1,"mesmerise":1,"nunonunes":1,"papylhomme":1,"voipminic":1,"Torsten85":1,"Duckle29":1},"host":{"name":"GitHub","url":"https://github.com","kind":"github","last_synced_at":"2026-04-14T00:00:07.923Z","repositories_count":14260526,"issues_count":34617559,"pull_requests_count":113192383,"authors_count":11234464,"icon_url":"https://github.com/github.png","host_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/repositories","owners_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/owners","authors_url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/authors"},"past_year_issue_labels_count":{},"past_year_pull_request_labels_count":{},"past_year_issue_author_associations_count":{},"past_year_pull_request_author_associations_count":{},"past_year_issue_authors":{},"past_year_pull_request_authors":{},"maintainers":[{"login":"rlogiacco","count":4,"url":"https://issues.ecosyste.ms/api/v1/hosts/GitHub/authors/rlogiacco"}],"active_maintainers":[]},"events":{"total":{"ForkEvent":3,"WatchEvent":36},"last_year":{"ForkEvent":2,"WatchEvent":16}},"keywords":[],"dependencies":[{"ecosystem":"actions","filepath":".github/workflows/docs.yml","sha":null,"kind":"manifest","created_at":"2024-03-17T04:07:01.471Z","updated_at":"2024-03-17T04:07:01.471Z","repository_link":"https://github.com/rlogiacco/BatterySense/blob/master/.github/workflows/docs.yml","dependencies":[{"id":16864002624,"package_name":"actions/checkout","ecosystem":"actions","requirements":"v3","direct":true,"kind":"composite","optional":false},{"id":16864002940,"package_name":"mattnotmitt/doxygen-action","ecosystem":"actions","requirements":"1.9.2","direct":true,"kind":"composite","optional":false},{"id":16864003179,"package_name":"peaceiris/actions-gh-pages","ecosystem":"actions","requirements":"v3.7.3","direct":true,"kind":"composite","optional":false}]},{"ecosystem":"actions","filepath":".github/workflows/main.yml","sha":null,"kind":"manifest","created_at":"2024-03-17T04:07:04.500Z","updated_at":"2024-03-17T04:07:04.500Z","repository_link":"https://github.com/rlogiacco/BatterySense/blob/master/.github/workflows/main.yml","dependencies":[{"id":16864003209,"package_name":"actions/checkout","ecosystem":"actions","requirements":"v4","direct":true,"kind":"composite","optional":false},{"id":16864003210,"package_name":"arduino/compile-sketches","ecosystem":"actions","requirements":"v1","direct":true,"kind":"composite","optional":false},{"id":16864003462,"package_name":"arduino/arduino-lint-action","ecosystem":"actions","requirements":"v1","direct":true,"kind":"composite","optional":false}]}],"score":8.297543529356284,"created_at":"2023-09-11T14:52:07.690Z","updated_at":"2026-06-01T17:30:38.175Z","avatar_url":"https://github.com/rlogiacco.png","language":"C++","category":"Energy Storage","sub_category":"Battery","monthly_downloads":0,"total_dependent_repos":0,"total_dependent_packages":0,"readme":"### ⚠ **IMPORTANT**\n \n\u003e Please, before submitting a support request read carefully this README and check if an answer already exists among [previously answered questions](https://github.com/rlogiacco/BatterySense/discussions): do not abuse of the Github issue tracker.\n\n\u003c!-- omit in toc --\u003e\n\u003ch1\u003e\n  Battery Sense\n  \u003ca href=https://github.com/rlogiacco/BatterySense/stargazers\u003e\u003cimg alt=\"GitHub stars\" src=https://img.shields.io/github/stars/rlogiacco/BatterySense.svg?style=social\u0026label=Star /\u003e\u003c/a\u003e\n  \u003ca href=https://github.com/rlogiacco/BatterySense/network\u003e\u003cimg alt=\"GitHub forks\" src=https://img.shields.io/github/forks/rlogiacco/BatterySense.svg?style=social\u0026label=Fork /\u003e\u003c/a\u003e\n  \u003ca href=https://twitter.com/intent/tweet?text=Sense%20your%20battery%20on%20embedded%20devices%20easily!\u0026url=https://github.com/rlogiacco/BatterySense\u0026hashtags=IoT,Arduino,ESP8266,ESP32\u003e\u003cimg alt=\"Tweet\" src=https://img.shields.io/twitter/url/http/shields.io.svg?style=social /\u003e\u003c/a\u003e\n\u003c/h1\u003e\n\n[![GitHub version](https://img.shields.io/github/release/rlogiacco/BatterySense.svg)](https://github.com/rlogiacco/BatterySense/releases)\n[![GitHub download](https://img.shields.io/github/downloads/rlogiacco/BatterySense/total.svg)](https://github.com/rlogiacco/BatterySense/releases/latest)\n[![GitHub stars](https://img.shields.io/github/stars/rlogiacco/BatterySense.svg)](https://github.com/rlogiacco/BatterySense/stargazers)\n[![GitHub issues](https://img.shields.io/github/issues/rlogiacco/BatterySense.svg)](https://github.com/rlogiacco/BatterySense/issues)\n[![Build Status](https://github.com/rlogiacco/BatterySense/actions/workflows/main.yml/badge.svg)](https://github.com/rlogiacco/BatterySense/actions/workflows/main.yml)\n[![License](https://img.shields.io/badge/license-LGPL%203-blue.svg)](https://github.com/rlogiacco/BatterySense/blob/master/LICENSE)\n\n\nThis is a simple Arduino library to monitor the battery consumption of your battery-powered projects, being LiPo, LiIon, NiCd or any other battery type, single or multiple cells: if it can power your Arduino you can monitor it!\n\nThe principle is simple: we are going to measure our battery capacity by measuring the voltage across the battery terminals.\n\nThe big assumption here is that battery capacity is linearly correlated to its voltage: the assumption itself is wrong, but in most cases, it's *close enough* to reality, especially when it comes to the battery's higher capacity side.\n\nIn reality, the relation between battery capacity and its voltage is better represented by a curve and there are many factors affecting it: current drawn, temperature, age, etc...\n\n![Battery discharge curves at 750 mA](http://www.philohome.com/batteries/discharge-750.gif)\n\n\u003c!-- toc --\u003e\n- [How to](#how-to)\n  - [Lesser than 5V, with voltage booster](#lesser-than-5v-with-voltage-booster)\n  - [Higher than 5V, with internal voltage regulator](#higher-than-5v-with-internal-voltage-regulator)\n  - [Higher than 5V, with external voltage regulator](#higher-than-5v-with-external-voltage-regulator)\n  - [Higher than 5V, activated on demand](#higher-than-5v-activated-on-demand)\n- [Voltage divider ratio](#voltage-divider-ratio)\n- [ADC Resolution](#adc-resolution)\n- [Remaining capacity approximation](#remaining-capacity-approximation)\n  - [Improvable](#improvable)\n  - [Good enough](#good-enough)\n- [Examples](#examples)\n  - [Single-cell Li-Ion on 3.3V MCU](#single-cell-li-ion-on-33v-mcu)\n  - [Double cell Li-Ion (2S) on 5V MCU](#double-cell-li-ion-2s-on-5v-mcu)\n  - [9V Alkaline on 5V MCU](#9v-alkaline-on-5v-mcu)\n  - [Double cell Li-Ion (2P) on demand for 3.3V MCU with 12 bits ADC](#double-cell-li-ion-2p-on-demand-for-33v-mcu-with-12-bits-adc)\n\u003c!-- tocstop --\u003e\n\n## How to\nThe library requires at least 1 analog pin (we will call this the `sense pin`) and no less than 2 pieces of info on your battery: the voltage you will consider the minimum acceptable level, below which your project/product becomes unreliable and should be shut down, and the maximum voltage you can expect when the battery is fully charged.\n\nAdditionally, you can provide a second pin (either analog or digital) to activate the battery measurement circuit (we call it the `activation pin`), useful in all those situations where you can sacrifice a pin to further increase your battery duration.\n\nIf you want your readings to be more accurate we _strongly suggest_ calibrating the library by providing your board reference voltage: most of the time you assume your board has exactly 5V between `Vcc` and `GND`, but this is rarely the case. To improve this we suggest using the [VoltageReference](https://github.com/rlogiacco/VoltageReference) library to obtain a better calibration value for all analog readings.\n\nThe `sense pin` wiring can vary depending on your battery configuration, but here are a few examples based on the assumption you are using a 5V board: in the case of a 3.3V board you should be performing the necessary adjustments.\n\n### Lesser than 5V, with voltage booster\nVoltage sources made of single-cell LiPo or LiIon, along with some single or multi-cell NiCd configurations (like up to 3 AA or AAA), are not able to provide the *suggested* `5.0 volts input` to your board and a voltage booster can solve your problem.\nWhat does that mean when it comes to measuring your battery level? We need to measure the battery voltage *before* it gets boosted, which means your `sense pin` must be connected between the battery positive terminal and the booster positive input and we don't need any additional components as the voltage is already in the acceptable range:\n\n```\n                                               +---------+\n          +----------------------------- SENSE |         |\n          |        +---------+                 |         |\n          |        |         |                 |         |\n  BAT+ ---+--- IN+ |   5V    | OUT+ ------- 5V | Arduino |\n                   | BOOSTER |                 |         |\n  BAT- ------- IN- |         | OUT- ------ GND |         |\n                   +---------+                 |         |\n                                               +---------+\n```\n\n### Higher than 5V, with internal voltage regulator\nVoltage sources made of multiple cells LiPo or LiIon, along with some single or multi-cell NiCd configurations (like up the classic 9V battery or 4+ AA or AAA), provide voltages above the `5.0 volts input`: most of the Arduino boards are equipped with voltage regulators able to dissipate into heat all the excess.\nTo measure such batteries we need to hook our `sense pin` *before* it gets regulated, between the battery positive terminal and the Arduino unregulated input `VIN` or `RAW`, but we require two resistors to reduce the voltage to acceptable values:\n\n```\n                         +---------+\n  BAT+ ---+--------- VIN |         |\n          |              |         |\n         R1              |         |\n          |              |         |\n          +------- SENSE | Arduino |\n          |              |         |\n         R2              |         |\n          |              |         |\n  BAT- ------------- GND |         |\n                         +---------+\n```\n\nThe values of R1 and R2 determine the `voltage ratio` parameter for this library: for information about this value refer to the section below.\n\nBecause the resistors in this configuration will constantly draw power out of your battery, you shouldn't pick values under `1k Ohm`, or you'll deplete your batteries much faster than normal. On the other end, going too high on the resistor values will impede the library from getting accurate readings.\n\n### Higher than 5V, with external voltage regulator\nWhenever your battery's maximum voltage exceeds the onboard regulator (if there is any) an external voltage regulator is required.\nOnce again, to measure such batteries we need to hook our `sense pin` *before* it gets regulated, between the battery positive terminal and the voltage regulator positive input `VIN` or `RAW` and, as before, we require two resistors to reduce the voltage to acceptable values:\n\n```\n+---------------------------------+\n|                  +---------+    |         +---------+\n| BAT+ ---+--- IN+ |         |    +-- SENSE |         |\n|         |        |         |              |         |\n|        R1        |         |              |         |\n|         |        |         |              |         |\n+---------+        |   REG   | OUT+ ---- 5V | Arduino |\n          |        |         |              |         |\n         R2        |         |              |         |\n          |        |         |              |         |\n  BAT- ---+--- IN- |         | OUT- --- GND |         |\n                   +---------+              +---------+\n```\n\nThe values of R1 and R2 determine the `voltage ratio` parameter for this library: for information about this value refer to the section below.\n\n### Higher than 5V, activated on demand\nBatteries are a precious resource and you want to prolong their life as much as you can so, deplete your battery to determine its capacity is not desirable.\n\nAs a consequence of connecting the battery terminals through two resistors we are drawing some energy out of the battery: for a 9V battery and 1k Ohm for R1 and R2, you will be adding a constant 4.5mA current consumption to your circuit. Not a huge amount, but definitely not desirable.\n\nIf you have an unused pin on your Arduino it will be easy to limit this additional current consumption to be drawn only when needed: during battery measurement. We will be turning the `activation pin` HIGH during battery measurement so that the voltage divider will be disconnected most of the time:\n\n```\n                         +---------+\n  BAT+ ---+--------- VIN |         |\n          |              |         |\n         SW--------- ACT |         |\n          |              |         |\n         R1              |         |\n          |              | Arduino |\n          +------- SENSE |         |\n          |              |         |\n         R2              |         |\n          |              |         |\n  BAT- ------------- GND |         |\n                         +---------+\n```\n\nIn the above schematics, **SW** is a circuit that can connect or disconnect the sensing circuit depending on the voltage on `ACT`: the most common and cheap circuit is made of an NPN transistor *Q1*, a p-channel MOSFET *Q2*, a 1k-4.7k Ohm resistor *R3* and a 5k-20k Ohm resistor *R4*:\n\n```\n                       BAT+\n                        |\n                  +-----+\n                  |     |\n                  R4    |\n                  |\\    |\n   ACT --- R3 ---Q1 \\-- Q2\n                  |     |\n                  |     |\n                 GND   VDIV\n                       to R1/R2/SENSE\n\n```\n\nFeel free to refer to this [circuit simulation](http://tinyurl.com/ydbjfk67) to better understand how the circuit works and how much current draws when in operation.\n\n![Simulated Circuit](https://image.ibb.co/iob7AV/sense.gif)\n\n## Voltage divider ratio\nWhenever your battery voltage is above your board voltage you need a voltage divider to constrain your readings within the 0-5V range allowed by your Arduino and you will have to provide this library with its *ratio*.\n\n```\n\n  BAT+ ---+\n          |\n         R1\n          |\n          +------- SENSE\n          |\n         R2\n          |\n  BAT- ----\n```\n\nThe `voltage divider ratio` is determined by the formula `(R1 + R2) / R2`: if you use two resistors of the same value the ratio will be **2**, which can be interpreted as *whatever value we read it will be **half** of the actual value*. This allows us to sense batteries up to 10V. \nIf you use a 22k Ohm resistor for R1 and a 10k Ohm for R2 then your `voltage` ratio` will be **3.2** and you will be able to safely monitor a 12-15V battery.\n\nYou **must** select the resistors in order to get a ratio that will produce values between the 0-5V range (or 0-3.3V for 3.3V devices) **at all times** and to obtain that the process is quite simple: divide your battery maximum voltage by 5V and you'll get the *absolute minimum value* for the `voltage ratio`, then pick any two resistors values whose combination produce a ratio *equal or higher* than the absolute minimum. For a 12V battery, the _absolute_ minimum voltage ratio* is **12/5=2.4**, meaning you can't use a *split supply divider* made of two equal resistors: you need R1 to be a higher value than R2! Get this wrong and you will probably burn your `sense pin`.\n\nYou can use [this nice website](http://www.ohmslawcalculator.com/voltage-divider-calculator) to find some appropriate values for the resistors setting your battery maximum voltage as _Voltage source_ and aiming at obtaining an _Output voltage_ value lesser than your board voltage (`5V` or `3.3V`) but as close as possible.\n\nThe *voltage divider total resistance*, made of `R1 + R2`, will determine the current drawn from your battery by the sensing circuit: the lower is the total resistance and the more accurate your readings, the higher the resistance and the less current is drawn from your battery ([Ohm's law](http://www.ohmslawcalculator.com/ohms-law-calculator) rulez!). My suggestion is to keep this value within 20k-22k Ohm when using an *always-connected* circuit and under 10k Ohm if you use an *on-demand* configuration.\n\nWhen determining the *ratio* don't stick with the resistors' nominal values, instead, if possible, use a multimeter to actually measure their resistance so to improve your results: a `4.7kΩ` resistor could easily be a `4.75kΩ` in reality!\n\n## ADC Resolution\nStarting from version `1.2.0` the library supports ADC resolutions other than the standard `10bits` of classic Arduino boards through an additional, but optional, constructor parameter named `adcBits` which obviously defaults to `10`.\n\nSo, in case your board ADC provides an ADC with a resolution higher than 10 bits, you should provide the additional parameter with the number of bits your ADC provides. In case the board has the ability to change the ADC resolution at runtime, it is your responsibility to ensure the ADC resolution is properly set before each call to any of the measuring functions: `voltage` or `level`.\n\n```cpp\n#include \u003cBattery.h\u003e\n\nBattery batt = Battery(3000, 4200, SENSE_PIN, 12);\n```\n\n\u003e ⚠ **IMPORTANT** ⚠\n\u003e \n\u003e The currently maximum supported value for the ADC resolution is `15`: specifying a value greater than that will break the library behaviour.\n\n## Remaining capacity approximation\nThe `level` available functions aim at providing an approximation of the remaining battery capacity in percentage. This is not an easy task when you want to achieve reliable values and it is something the industry of mobile devices invests a decent amount of resources.\nWhen an accurate estimate is desirable the battery voltage is not the sole parameter you want to take into consideration:\n * cell **chemistry** has a very high influence, obviously\n * cells based on the same chemistry might produce pretty different results depending on the **production process**\n * each chemistry has a different ideal operating **cell temperature**\n * the rate you **draw current** from the battery influences the remaining capacity\n * batteries are not everlasting: as the cell **age**s, the battery capacity gets reduced\n * _and more_ \n\nThe library itself doesn't aim at providing accurate estimates, but what I consider _an improvable but good enough_ estimate.\n\n### Improvable\nThe library can be configured to use a mapping function of your choice, given the function complies with the `mapFn_t` interface:\n\n```cpp\nuint8_t mapFunction(uint16_t voltage, uint16_t minVoltage, uint16_t maxVoltage)\n```\n\nTo configure your personalized function you only have to provide a pointer to it during initialization:\n\n```cpp\nBattery batt = Battery(3000, 4200, SENSE_PIN);\n\nuint8_t myMapFunction(uint16_t voltage, uint16_t minVoltage, uint16_t maxVoltage) {\n  // your code here\n}\n\n\nvoid setup() {\n  batt.begin(3300, 1.47, \u0026myMapFunction);\n}\n```\n\n\u003e You are not limited in considering only the parameters listed in the function interface, meaning you can take into consideration the cell(s) temperature, current consumption or age: that's open to your requirements and circuitry.\n\n### Good enough\nAfter collecting a few data points on battery voltage vs. battery capacity, I've used the https://mycurvefit.com/ and https://www.desmos.com online tools to calculate the math functions best representing the data I've collected.\n\n![Mapping functions](https://github.com/rlogiacco/BatterySense/blob/master/map-fn.png?raw=true)\n\n\u003e In the above plot I represent the battery percentage (Y axis) as a function of the difference between the current battery voltage and the minimum value (X axis): the graph represents a battery with a voltage swing of 1200mV from full to empty, but the functions scale accordingly to the `minVoltage` and `maxVoltage` parameters.\n\nThe library ships with three different implementations of the mapping function: \n\n * _linear_ is the default one (dashed red), probably the least accurate but the easiest to understand. Its main drawback is, for most chemistries, it will very quickly go from 25-20% to 0%, meaning you have to select the `minVoltage` parameter for your battery accordingly. As an example, for a typical Li-Ion battery having a 3V to 4.2V range, you want to specify a 3.3V configuration value as the _minimum__ voltage_.\n * _sigmoidal_ (in blue) is a good compromise between computational effort and approximation, modeled after the typical discharge curve of Li-Ion and Li-Poly chemistries. It's more representative of the remaining charge on the lower end of the spectrum, meaning you can set the minimum voltage according to the battery-safe discharge limit (typically 3V for a Li-Ion or Li-Poly).\n * _asymmetric sigmoidal_ (in green) is probably the best approximation when you only look at battery voltage, but it's more computationally expensive compared to _sigmoidal_ function and, in most cases, it doesn't provide a great advantage over its symmetric counterpart.\n\nI strongly encourage you to determine the function that best matches your particular battery chemistry/producer when you want to use this library in your product.\n\n## Examples\nHere follow a few real case scenarios that can guide you in using this library.\n\n### Single-cell Li-Ion on 3.3V MCU\nAs an example, for a single-cell Li-Ion battery (4.2V - 3.7V) powering a `3.3V` MCU, you'll need to use a voltage divider with a ratio of no less than `1.3`. Considering only E6 resistors, you can use a `4.7kΩ` (R1) and a `10kΩ` (R2) to set a ratio of `1.47`: this allows you to measure batteries with a maximum voltage of `4.85V`, well within the swing of a Li-Ion. It's a little too current-hungry for my tastes in an *always-connected* configuration, but still ok. Considering the chemistry maps pretty well to our sigmoidal approximation function I'm going to set it accordingly along with the minimum voltage whose lowest safe value clearly is 3.0V (if a Li-Ion is drained below `3.0V` the risk of permanent damage is high), so your code should look like:\n\n```cpp\n#define SENSE_PIN A0\n\nBattery batt = Battery(3000, 4200, SENSE_PIN);\n\nvoid setup() {\n  // specify an activationPin \u0026 activationMode for on-demand configurations\n  //batt.onDemand(3, HIGH);\n  batt.begin(3300, 1.47, \u0026sigmoidal);\n}\n```\n\nAnd here you can find the [relative circuit](https://www.falstad.com/circuit/circuitjs.html?ctz=CQAgjCAMB0l3BWcMBMcUHYMGZIA4UA2ATmIxAUgpABZsKBTAWjDACgAnETFEbNbhl4oUNKMnhsAbuGK9+VMHPAo84qjQ3ReVXdASdBvMKqPdR4mhjhsA7rPkCefAZDtmFfbIRdUU7pWNTZxM1dnsQ02xvFTV-CKFzMWifETF-NHJA2PBCRVMxACEAQQAVAB0ABzZMh19cqk8isqYayHIUnO8wgpAANQBLADs2jpjPbvqxAHEAOQARUa9Ui0m02hBitwB7cUIxDUhSahg4bBMkP3FsNmwwkAAxCEbochptEBZ+7YAbABcAIYAcwYbCAA).\n\n### Double cell Li-Ion (2S) on 5V MCU\nFor a double-cell Li-Ion battery (8.4V - 7.4V) powering a `5V MCU`, you'll need to use a voltage divider with a ratio no less than `1.68`: you can use a `6.8kΩ` (R1) and a `10kΩ` (R2) to set the ratio *precisely* at `1.68`, perfect for our `8.4V` battery pack. The circuit will continuously draw `0.5mA` in an _always-connected_ configuration, if you can live with that. As we don't want to ruin our battery pack and we don't want to rush from 20% to empty in a few seconds, we'll have to set the minimum voltage to `6.8V` (with a _linear_ mapping) to avoid the risk of permanent damage, meaning your code should look like:\n\n```cpp\n#define SENSE_PIN A0\n\nBattery batt = Battery(6800, 8400, SENSE_PIN); \n\nvoid setup() {\n  // specify an activationPin \u0026 activationMode for on-demand configurations\n  //batt.onDemand(3, HIGH);\n  batt.begin(5000, 1.68);\n}\n```\n\nIn terms of electrical circuit, [here is a simulation](https://www.falstad.com/circuit/circuitjs.html?ctz=CQAgjCAMB0l3BWcMBMcUHYMGZIA4UA2ATmIxAUgpABZsKBTAWjDACgAnETFEbNbhl4oUNKMnhsAbuGK9+VMHO6jxVGuujZSO3XrVRoCToN5gUeUyrFVCeOGwDus+QJ58BkJ1YV9shDyoUbyUzCytzS3Znd0i-ALjgmKFreNTgtHJQ8HCwQkVwsQAhAEEAFQAdAAc2TJdA8HyG4vKmWshybH8cy38owpAANQBLADt2zu7fPuaQAHEAOQARCbSRMRn12hASrxlsrey4qnVNRAMYYwB7cUIbWkhSbhPYSGxzJCDxbDZsSyoAGIQRTICAsEAAJQYAGdhtCAC4AQ1GAGMGL8ovQgd9oOQaNBeODBlcADZIgDm6L+4BA2KoTDcIIqXiAA).\n\n\u003e **NOTE**: I could have used the _sigmoidal_ approximation, as the chemistry fits pretty well on the curve, in which case a `6V` minimum voltage would have been a better configuration value.\n\n### 9V Alkaline on 5V MCU\nAnother classic example might be a single 9V Alkaline battery (9V - 6V) powering a `5V MCU`. In this case, you'll need to use a voltage divider with a ratio no less than `1.8` and, for the sake of simplicity, we'll go for a nice round `2` ratio. Using a nice `10kΩ` both for R1 and R2 we'll be able to measure batteries with a maximum voltage of `10V` consuming only 0.45mA. The trick here is to determine when our battery should be considered empty: a 9V Alkaline, being a non-rechargeable one, can potentially go down to 0V, but it's hard for our board can still be alive when this occurs. Assuming we are using a linear regulator to step down the battery voltage to power our board we'll have to account for the regulator voltage drop: assuming it's a `1.2V` drop, we might safely consider our battery empty when it reaches `6.2V` (5V + 1.2V), leading to the following code:\n\n```cpp\n#define SENSE_PIN A0\n\nBattery batt = Battery(6200, 9000, SENSE_PIN);\n\nvoid setup() {\n  // specify an activationPin \u0026 activationMode for on-demand configurations\n  //batt.onDemand(3, HIGH);\n  batt.begin(5000, 2.0);\n}\n```\n\nExcluding resistors and battery values, [the circuit is the same](https://www.falstad.com/circuit/circuitjs.html?ctz=CQAgjCAMB0l3BWcMBMcUHYMGZIA4UA2ATmIxAUgpABZsKBTAWjDACgAnETFEbNbhl4oUNKMnhsAbuGK9+VMHPAo84qjSrF1UaAk6DeYVYe6jxYeJDYB3WfIE8+A63acK+2Qs6opb9lTUnYzV2NyFAz28Q7n8nETFsLzMxPzRyJSMTMEJFEzEAIQBBABUAHQAHNnSAjxyqD0LSpmrIciToky9Q-JAANQBLADtW9uSPbp9aEABxADkAEVGolL5CIPMxIusAe3FCMQ1IUmRdOGxjJF9xbDZsUJAAMQgG6HIaaF4Wfp2AGwAXACGAHMGGwgA) as in the first example.\n\n\u003e **NOTE**: Most `5V MCU` can actually continue to operate when receiving `4.8V` or even less: if you want to squeeze out as much energy as you can you can fine tune the low end, but also consider there is not much juice left when a battery voltage drops that much.\n\n### Double cell Li-Ion (2P) on demand for 3.3V MCU with 12 bits ADC\nHaving two batteries in parallel doesn't change anything in terms of provided voltage, but doubles the capacity (among other things). In this example, we also wish to increase our measurement precision and extend our battery life as much as possible. In terms of resistor values, we will be using `330Ω` for R1 and `1kΩ` for R2, giving a ratio of `1.33`, but we'll use an on-demand configuration to minimize battery consumption. Also, we want maximum precision, thus we will use the more complex and more accurate `asigmoidal` approximation function, leveraging the increased precision given by the 12 bits ADC provided by the MCU we are going to use, in contrast to the more common 10bits resolution usually available. This is the code we suggest:\n\n```cpp\n#define SENSE_PIN A0\n#define ACTIVATION_PIN 3\n#define ADC_RESOLUTION 12\n\n\nBattery batt = Battery(4200, 3300, SENSE_PIN, ADC_RESOLUTION);\n\nvoid setup() {\n \tanalogReadResolution(ADC_RESOLUTION);\n  batt.onDemand(ACTIVATION_PIN, HIGH);\n  batt.begin(3300, 1.47, \u0026asigmoidal);\n}\n```\n\nAnd [this is the reference circuit](https://www.falstad.com/circuit/circuitjs.html?ctz=CQAgjCAMB0l3BWcAmWDLMgZgBxmcgCxg4CcS6IFkVApgLRhgBQA7iFgsiAYR1+ADsANnDMAZj0HciNTjMI0IYaEhgZmAJykKayaUNF7MkNjsP9uYEVGYAZcKRkJRYYXpdRwIcQEMANgDOtFS2AC48ijye+s5G3jDC+ISkkGBYaYQ4CIRJUNDCioI4kKRM0lxOrnAgACa0fgCu-mFakR6uTtHxBHBmseYD8rbaw8iewxl8chltk5B8kwJK8GbzfIRZHAs8zABuVMg4lofH1vE0UYTQ3DR3qmsC5yBZSjamAB7ghDKcQsfIXAvcDHACCAGEACrML5YLpYI4vBBYDhYCB8EggADKAFEAHK4mFUQhIfQQBDFKQbEEgABCoOh7CGAiWt0e3GGrxOLAOXM5JQsdxelxuXnuCDMfIEXGOw1M2i5zxlgvADFIzAA9t5Cl5FKRSPlhON8nAjWoeN4sMwgZiAGIQOQvUWMEAANQ1LV8AHNaNazhB7V4UddbiAADqmIA) we would implement.\n","funding_links":["https://github.com/sponsors/rlogiacco","https://www.paypal.me/rlogiacco"],"readme_doi_urls":[],"works":{},"citation_counts":{},"total_citations":0,"keywords_from_contributors":[],"project_url":"https://ost.ecosyste.ms/api/v1/projects/19867","html_url":"https://ost.ecosyste.ms/projects/19867"}