Conversation
nedseb
left a comment
nedseb
left a comment
There was a problem hiding this comment.
Bonne base — le Basic Usage est correct et la structure est claire. Cependant il manque une part significative de l'API publique.
Méthodes publiques manquantes
Le driver expose environ 40 méthodes publiques. Le README n'en documente qu'une vingtaine. Il manque notamment :
Seal/Unseal :
sealed()— check if device is sealedseal()— seal the deviceunseal()— unseal for configuration
GPOUT getters :
gpout_polarity()— lire la polarité actuellegpout_function()— lire la fonction actuelleconfigure_gpout_input()/configure_gpout_output()— configuration GPIO
Seuils getters :
soc1_set_threshold()/soc1_clear_threshold()socf_set_threshold()/socf_clear_threshold()
Flags et delta :
soc_flag()/socf_flag()— flags de statut batteriesoci_delta()/set_soci_delta()— delta pour l'interrupt SoC
Config avancée :
op_config()/write_op_config()— registre de configuration
Même si ces méthodes sont avancées, elles doivent au minimum être listées dans une section "Advanced API" pour que l'utilisateur sache qu'elles existent.
Enums non documentés
current(type), soc(type), soh(type), temperature(type) prennent des enums en paramètre. Quelles sont les valeurs possibles ? Regarde dans const.py les classes CurrentMeasureType, SocMeasureType, SohMeasureType, TempMeasureType et liste les options. Exemple :
# Current types
bq.current(BQ27441.CurrentMeasureType.AVG)
bq.current(BQ27441.CurrentMeasureType.STBY)
bq.current(BQ27441.CurrentMeasureType.MAX)Contenu manquant
- Pas de section "Sensor Specifications" — Ajoute un tableau avec le composant (BQ27441-G1A), tension supportée, précision de mesure SoC, etc.
set_capacity(mAh)— exemple manquant — Tu mentionnes que la capacité par défaut est 650 mAh mais tu ne montres pas comment la configurer. Un exemple avecenter_config/set_capacity/exit_configserait utile.
Détails
- Trailing whitespace après "Arduino Library)." (ligne 3) et "650 mAh (configurable)" (dans Notes)
- Cohérence section I²C Address — La puce
* **Default address:** \0x55`` mélange les styles. Aligne-toi sur le format des autres README.
Rappel
Ouvre device.py et vérifie que chaque méthode def qui ne commence pas par _ est documentée dans le README. C'est le critère de complétude.
There was a problem hiding this comment.
Pull request overview
Expands the bq27441 driver README from a minimal stub into a full, driver-style documentation page to match other libraries in the repository and close docs harmonization gaps.
Changes:
- Added new README sections: Features, I2C address, Basic Usage, API reference, Examples, and Notes.
- Documented the driver’s public measurement/config/power/info methods and added an example
mpremoteinvocation. - Added operational notes (battery required for I²C response, default design capacity).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| # MicroPython BQ27441 Library | ||
|
|
||
| This library is a port of the [SparkFun BQ27441-G1A LiPo Fuel Gauge Arduino Library](https://github.com/sparkfun/SparkFun_BQ27441_Arduino_Library). | ||
| This library is a port of the [SparkFun BQ27441-G1A LiPo Fuel Gauge Arduino Library](https://github.com/sparkfun/SparkFun_BQ27441_Arduino_Library). |
There was a problem hiding this comment.
Line ends with trailing whitespace, which can create unintended Markdown hard line breaks and makes diffs noisy. Please remove the trailing space.
| * power management (shutdown / wake-up) | ||
| * GPOUT interrupt configuration (SOC_INT / BAT_LOW) | ||
|
|
||
| # I2C Address |
There was a problem hiding this comment.
For consistency with other driver READMEs (e.g., ISM330DL/WSEN-HIDS), consider using the same section title spelling: “I²C Address” rather than “I2C Address”.
| # I2C Address | |
| # I²C Address |
| * `current_average()` — average current | ||
| * `current(type)` — current (AVG, STBY, MAX) | ||
|
|
There was a problem hiding this comment.
The docs for current(type) suggest passing values like “AVG/STBY/MAX”, but in code the method expects the CurrentMeasureType constants (and they are not exported from bq27441.__init__). Please document the correct import/usage (e.g., from bq27441.device import CurrentMeasureType) or export these enums from the package so the README examples match the public API.
| * `capacity(type)` — advanced capacity readings | ||
|
|
||
| ### Charge & Health | ||
|
|
||
| * `state_of_charge()` — battery level (%) | ||
| * `soc(type)` — filtered / unfiltered SoC | ||
| * `state_of_health()` — battery health (%) | ||
| * `soh(type)` — detailed SoH | ||
|
|
||
| ### Temperature | ||
|
|
||
| * `temperature(type)` — battery or internal temperature | ||
|
|
||
| ## Configuration | ||
|
|
||
| * `set_capacity(mAh)` — set battery design capacity | ||
| * `enter_config(user_control)` — enter config mode | ||
| * `exit_config(resim=True)` — exit config mode | ||
|
|
||
| ### GPOUT / Alerts | ||
|
|
||
| * `set_gpout_function(type)` — SOC_INT or BAT_LOW | ||
| * `set_gpout_polarity(active_high)` | ||
| * `set_soc1_thresholds(set, clear)` | ||
| * `set_socf_thresholds(set, clear)` | ||
| * `pulse_gpout()` |
There was a problem hiding this comment.
Similar to current(), several APIs here take typed constants (e.g., capacity(...), soc(...), soh(...), temperature(...), set_gpout_function(...)) but the README doesn’t indicate what values to pass or how to import the corresponding *MeasureType / GpoutFunctionType classes. Please update the docs to reference the actual constants and their import path, otherwise these signatures are hard to use correctly.
|
|
||
| ### Temperature | ||
|
|
||
| * `temperature(type)` — battery or internal temperature |
There was a problem hiding this comment.
temperature(type) is documented as “battery or internal temperature”, but the driver returns the raw register value directly (no °C conversion). Please clarify the returned units/format and (if needed) show how to convert it, so users don’t assume the result is already in degrees.
| # Notes | ||
|
|
||
| * The **BQ27441 requires a connected LiPo battery** to respond on I²C | ||
| * Default design capacity is **650 mAh** (configurable) |
There was a problem hiding this comment.
Trailing whitespace at end of line; please remove to avoid unintended Markdown formatting and keep diffs clean.
|
README réécrit en 86d8c1f pour traiter tous les commentaires : Revue :
Copilot :
Prête à merger. |
|
🎉 This PR is included in version 0.0.2 🎉 The release is available on GitHub release Your semantic-release bot 📦🚀 |
Closes #190
Parent issue #194
Title: Expand bq27441 README with full documentation
Description:
The
bq27441README was minimal and only contained a title and a basic mpremote command.This PR expands it to match the level of detail of other drivers like
ism330dlandwsen-hids.Changes
Added Features section (voltage, SoC, capacity, current, power, SoH, temperature)
Added I2C Address section (default
0x55)Added Basic Usage example (init + voltage + SoC reading)
Added complete API documentation:
Added Examples section with existing scripts
Added Notes about battery requirement (device only responds when battery is connected)
Notes
Checklist