Midnight Sun Firmware
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Modules Pages
max17261_fuel_gauge.h
1#pragma once
2#include <stdint.h>
3
4#include "i2c.h"
5#include "max17261_fuel_gauge_defs.h"
6
7/* Notes:
8 * 3 things are required for configuring the max17261:
9 * - Design Capacity (in milliamp hours)
10 * - Empty Voltage
11 * - Charge Termination Current
12 *
13 * Some of the units of the registers (like capacity and current) depend on RSense,
14 * it looks like max17261 automatically determines this value, it should be provided
15 * to the driver for conversions from register values to actual units
16 *
17 * See data sheet P.15 for more info on how registers are formatted
18 * Datasheet: https://www.analog.com/media/en/technical-documentation/data-sheets/max17261.pdf
19 */
20
21typedef struct {
22 I2CPort i2c_port;
23 I2CAddress i2c_address;
24
25 uint32_t pack_design_cap_mah;
26 uint16_t cell_empty_voltage_v;
27 uint16_t charge_term_current_ma; // ref end-of-charge detection
28 // https://web.archive.org/web/20220121025712mp_/https://pdfserv.maximintegrated.com/en/an/user-guide-6597-max1726x-m5-ez-rev3-p4.pdf
29
30 uint16_t i_thresh_max_a;
31 int16_t i_thresh_min_a;
32 uint16_t temp_thresh_max_c;
33
34 float sense_resistor_mohms;
36
37typedef struct {
38 Max17261Settings *settings;
40
41// Storage for parameters learned by fuel guage
42// Must be stored in flash to keep up to date after power cycle
43typedef struct Max27261Params {
44 uint16_t rcomp0;
45 uint16_t tempco;
46 uint16_t fullcaprep;
47 uint16_t cycles;
48 uint16_t fullcapnom;
50
51/* @brief Gets the current state of charge given by the max17261 in percentage
52 * @param storage - a pointer to an already initialized Max17261Storage struct
53 * @param soc_pct - state of charge in percentage will be returned in this var
54 * @return STATUS_CODE_OK on success
55 */
56StatusCode max17261_state_of_charge(Max17261Storage *storage, uint16_t *soc_pct);
57
58/* @brief Gets the current remaining capactity in micro amp hours
59 * @param storage - a pointer to an already initialized Max17261Storage struct
60 * @param soc_pct - remaining capactity in micro amp hours returned in this var
61 * @return STATUS_CODE_OK on success
62 */
63StatusCode max17261_remaining_capacity(Max17261Storage *storage, uint32_t *rem_cap_mAh);
64
65/* @brief Gets the full charge capacity of the battery in micro amp hours
66 * @param storage - a pointer to an already initialized Max17261Storage struct
67 * @param soc_pct - full charge capacitry in micro amp hours returned in this var
68 * @return STATUS_CODE_OK on success
69 */
70StatusCode max17261_full_capacity(Max17261Storage *storage, uint32_t *full_cap_mAh);
71
72/* @brief Gets the time to empty in milliseconds
73 * @param storage - a pointer to an already initialized Max17261Storage struct
74 * @param soc_pct - time to empty in milliseconds returned in this var
75 * @return STATUS_CODE_OK on success
76 */
77StatusCode max17261_time_to_empty(Max17261Storage *storage, uint16_t *tte_ms);
78
79/* @brief Gets the time to full in milliseconds
80 * @param storage - a pointer to an already initialized Max17261Storage struct
81 * @param soc_pct - time to full in milliseconds returned in this var
82 * @return STATUS_CODE_OK on success
83 */
84StatusCode max17261_time_to_full(Max17261Storage *storage, uint16_t *ttf_ms);
85
86/* @brief Gets a current reading in amps
87 * @param storage - a pointer to an already initialized Max17261Storage struct
88 * @param soc_pct - current in amps returned in this var
89 * @return STATUS_CODE_OK on success
90 */
91StatusCode max17261_current(Max17261Storage *storage, int32_t *current_a);
92
93/* @brief Gets a single cell's voltage in mV
94 * @param storage - a pointer to an already initialized Max17261Storage struct
95 * @param soc_pct - voltage in mV returned in this var
96 * @return STATUS_CODE_OK on success
97 */
98StatusCode max17261_voltage(Max17261Storage *storage, uint16_t *vcell_mv);
99
100/* @brief Gets a temperature reading in celcius
101 * @param storage - a pointer to an already initialized Max17261Storage struct
102 * @param soc_pct - temperature in celcius returned in this var
103 * @return STATUS_CODE_OK on success
104 */
105StatusCode max17261_temp(Max17261Storage *storage, uint16_t *temp_c);
106
107/* @brief Gets the time to full in milliseconds
108 * @param storage - a pointer to an uninitialized Max17261Storage struct
109 * @param settings - populated settings struct
110 * @return STATUS_CODE_OK on success
111 */
112StatusCode max17261_init(Max17261Storage *storage, Max17261Settings *settings, Max27261Params *params);
113
114StatusCode max17261_set_learned_params(Max17261Storage *storage, Max27261Params *params);
115StatusCode max17261_get_learned_params(Max17261Storage *storage, Max27261Params *params);
uint8_t I2CAddress
I2C address type.
Definition: i2c.h:34
I2CPort
I2C Port selection.
Definition: i2c.h:37
StatusCode
StatusCodes for various errors.
Definition: status.h:27
Definition: max17261_fuel_gauge.h:21
Definition: max17261_fuel_gauge.h:37
Definition: max17261_fuel_gauge.h:43