---
title: "API reference"
space: "MPPT Charger"
url: "https://docs.modbee.org/mppt-charger/api-reference"
updated: "2026-10-25"
---

# API Reference

Reference for `ModbeeMpptAPI` (`lib/ModbeeMPPT/src/ModbeeMpptAPI.h`), the unit-based interface to the BQ25798. It is available as `modbeeMPPT.api`.

**Saved settings take precedence.** The firmware re-applies the saved settings (`modbeeMPPT.config`) at boot and every 5 minutes, and the fixed charger settings every 60 seconds. A value written directly through the API, such as charge voltage, charge current, MPPT or watchdog, is overwritten at the next re-apply. To change a setting permanently, change `modbeeMPPT.config.data`, validate, save and apply it (see [Common Examples](#common-examples)). Direct API writes are intended for reads, diagnostics and short-lived adjustments.

## Quick Method Reference

### Power & Energy
| Method | Returns | Description |
|--------|---------|-------------|
| `updateStats()` | void | Update peak power and total energy statistics |
| `getVbusPower()` | `modbee_power_data_t` | Solar input power (voltage × current) |
| `getBatteryPower()` | `modbee_power_data_t` | Battery power (positive=charge, negative=discharge) |
| `getSystemPower()` | `modbee_power_data_t` | System rail power from power balance equation |
| `getVAC1Power()` | `modbee_power_data_t` | VAC1 input power |
| `getVAC2Power()` | `modbee_power_data_t` | VAC2 input power |
| `getEfficiency()` | float | System efficiency (%) |

### Voltage & Current
| Method | Returns | Description |
|--------|---------|-------------|
| `getVbusVoltage()` | float | Solar input voltage (V) |
| `getIbusCurrent()` | float | Solar input current (A) |
| `getBatteryVoltage()` | float | Battery terminal voltage (V) |
| `getBatteryCurrent()` | float | Battery charging current (A) |
| `getSystemVoltage()` | float | System rail voltage (V) |
| `getSystemCurrent()` | float | System load current (A) |
| `getVAC1Voltage()` | float | VAC1 voltage (V) |
| `getVAC2Voltage()` | float | VAC2 voltage (V) |

### Battery Monitoring
| Method | Parameters | Returns | Description |
|--------|-----------|---------|-------------|
| `getBatteryChargePercent()` | - | float | Battery SOC (0-100%) |
| `getBatteryTemperature()` | - | float | Battery temperature (°C) |
| `getRawTSPercent()` | - | float | Raw TS ADC reading (0-100%) |
| `updateTrueBatteryVoltage()` | - | void | Start true voltage measurement |
| `getTrueBatteryVoltage()` | - | float | True battery voltage (no-load) |
| `getBatteryChargingVoltage()` | - | float | Terminal voltage while charging |
| `getActualBatterySOC()` | - | float | SOC based on full range (0-100%) |
| `getUsableBatterySOC()` | - | float | SOC based on operating range (0-100%) |
| `getComprehensiveBatteryStatus()` | - | `modbee_battery_status_t` | Complete battery snapshot |
| `setBatteryType()` | type, cell_count | bool | Configure battery chemistry |
| `setBatteryVoltageRange()` | min_voltage, max_voltage | bool | Set custom voltage range |

### Charging Control
| Method | Parameters | Returns | Description |
|--------|-----------|---------|-------------|
| `setChargeVoltage()` | voltage (3.0-18.8V) | bool | Set target charge voltage |
| `setChargeCurrent()` | current (A) | bool | Set charge current (board rating 3 A) |
| `getChargeVoltage()` | - | float | Get charge voltage setpoint (V) |
| `getChargeCurrent()` | - | float | Get charge current limit (A) |
| `getTerminationCurrent()` | - | float | Get end-of-charge threshold (A) |
| `setTerminationCurrent()` | current | bool | Set end-of-charge threshold |
| `getRechargeThreshold()` | - | float | Get recharge threshold offset |
| `setRechargeThreshold()` | offset | bool | Set recharge threshold |
| `getPrechargeCurrent()` | - | float | Get precharge current (A) |
| `setPrechargeCurrent()` | current | bool | Set precharge current |
| `getPrechargeVoltageThreshold()` | - | `modbee_vbat_lowv_t` | Get precharge exit voltage |
| `setPrechargeVoltageThreshold()` | threshold | bool | Set precharge exit voltage |
| `setChargeEnable()` | enable | bool | Enable/disable charging |
| `getChargeEnable()` | - | bool | Check if charging enabled |

### Input Limits
| Method | Parameters | Returns | Description |
|--------|-----------|---------|-------------|
| `setInputCurrentLimit()` | current | bool | Set max input current |
| `setInputVoltageLimit()` | voltage | bool | Set max input voltage |
| `getInputVoltageLimit()` | - | float | Get input voltage limit (V) |
| `getInputCurrentLimit()` | - | float | Get input current limit (A) |
| `setMinSystemVoltage()` | voltage | bool | Set VSYS floor |
| `getMinSystemVoltage()` | - | float | Get min system voltage (V) |
| `setVACOVP()` | voltage | bool | Set VAC overvoltage threshold (7, 12, 18 or 26 V; rounds up) |
| `getVACOVP()` | - | float | Get VAC OVP threshold (V) |
| `getCellCount()` | - | uint8_t | Get configured cell count |

### MPPT Control
| Method | Parameters | Returns | Description |
|--------|-----------|---------|-------------|
| `setMPPTEnable()` | enable | bool | Enable/disable MPPT |
| `getMPPTEnable()` | - | bool | Check if MPPT enabled |
| `setMPPTVOCPercent()` | percent | bool | Set MPPT VOC reference (%) |
| `getMPPTVOCPercent()` | - | `modbee_voc_percent_t` | Get current VOC setting |
| `setMPPTVOCDelay()` | delay | bool | Set tracking delay interval |
| `setMPPTVOCRate()` | rate | bool | Set tracking adjustment rate |

### ADC Control
| Method | Parameters | Returns | Description |
|--------|-----------|---------|-------------|
| `setADCEnable()` | enable | bool | Enable/disable ADC |
| `getADCEnable()` | - | bool | Check if ADC enabled |
| `setADCMode()` | mode | bool | Set mode (CONTINUOUS/ONE_SHOT) |
| `setADCAveraging()` | averaging | bool | Set ADC averaging (`modbee_adc_avg_t`) |
| `setADCResolution()` | resolution | bool | Set resolution (12-15 bit) |
| `configureADC()` | resolution, averaging, mode | bool | Configure all ADC settings |
| `isADCConversionDone()` | - | bool | Check if conversion complete |
| `getADCControlRegister()` | - | uint8_t | Get raw ADC control register |

### Timers
| Method | Parameters | Returns | Description |
|--------|-----------|---------|-------------|
| `setFastChargeTimer()` | timer | bool | Set fast-charge timeout |
| `setFastChargeTimerEnable()` | enable | bool | Enable/disable fast-charge timer |
| `getFastChargeTimerEnable()` | - | bool | Check if timer enabled |
| `setPrechargeTimer()` | timer | bool | Set precharge timeout |
| `setPrechargeTimerEnable()` | enable | bool | Enable/disable precharge timer |
| `getPrechargeTimerEnable()` | - | bool | Check if timer enabled |
| `getTopOffTimer()` | - | `modbee_topoff_timer_t` | Get top-off timer setting |
| `setTopOffTimer()` | timer | bool | Set top-off timer |
| `setTrickleChargeTimerEnable()` | enable | bool | Enable/disable trickle timer |
| `getTrickleChargeTimerEnable()` | - | bool | Check if trickle enabled |
| `setTimerHalfRateEnable()` | enable | bool | Enable timer half-rate mode |
| `getTimerHalfRateEnable()` | - | bool | Check if half-rate enabled |

### System Control
| Method | Parameters | Returns | Description |
|--------|-----------|---------|-------------|
| `setWatchdogEnable()` | enable | bool | Enable/disable the BQ25798 I2C watchdog (the firmware keeps it disabled) |
| `setWatchdogTimer()` | timer | bool | Set timeout (DISABLE/40s/80s/160s) |
| `resetWatchdog()` | - | bool | Reset watchdog timer |
| `getWatchdogEnable()` | - | bool | Check if watchdog enabled |
| `getWatchdogTimer()` | - | `modbee_watchdog_timer_t` | Get timer setting |
| `setPWMFrequency()` | frequency | bool | Set PWM switching frequency |
| `getPWMFrequency()` | - | `modbee_pwm_freq_t` | Get frequency setting |
| `setForwardPFM()` | enable | bool | Enable pulse frequency modulation |
| `getForwardPFM()` | - | bool | Check if PFM enabled |
| `setForwardOOA()` | enable | bool | Out-of-audio mode in forward (charging) mode |
| `getForwardOOA()` | - | bool | Read out-of-audio setting |
| `setHIZMode()` | enable | bool | Enable high-impedance mode |
| `getHIZMode()` | - | bool | Check if HIZ enabled |
| `setBackupMode()` | enable | bool | Enable backup mode |
| `getBackupMode()` | - | bool | Check if backup enabled |
| `setShippingMode()` | enable | bool | Enter ship mode (battery disconnected until QON or input) |
| `getShipMode()` | - | bool | Check if in ship mode |
| `getDieTemperature()` | - | float | Get BQ25798 die temp (°C) |
| `detectBatteryConnected()` | - | bool | Detect battery connection |
| `setBatteryDischargeSenseEnable()` | enable | bool | Enable discharge sensing |
| `getBatteryDischargeSenseEnable()` | - | bool | Check if sensing enabled |
| `setICOEnable()` | enable | bool | Enable input current optimizer |

### Status & Faults
| Method | Returns | Description |
|--------|---------|-------------|
| `getChargeStateString()` | String | Charge state name (e.g. "Fast Charge (CC)", "Charge Termination Done") |
| `isCharging()` | bool | Check if actively charging |
| `hasFaults()` | bool | Check for any fault condition |
| `getFaultString()` | String | Get fault description |
| `getAllFaultStatus()` | void | Get raw fault registers |
| `hasInputOvervoltageFault()` | bool | Check input OVP fault |
| `hasOvercurrentFault()` | bool | Check overcurrent fault |
| `hasThermalFault()` | bool | Check thermal fault |

### Utilities
| Method | Parameters | Returns | Description |
|--------|-----------|---------|-------------|
| `vocPercentToFloat()` | voc_enum | float | Convert VOC enum to % |
| `floatToVocPercent()` | percentage | `modbee_voc_percent_t` | Convert % to VOC enum |
| `update()` | - | void | Internal state machine (call via loop) |

---

## Data Structures

### `modbee_power_data_t`
```cpp
struct {
  float voltage;     // Volts
  float current;     // Amps
  float power;       // Watts
  bool valid;        // Data validity
};
```

### `modbee_battery_status_t`
```cpp
struct {
  float charging_voltage;      // Terminal voltage while charging
  float true_voltage;          // Measured no-load voltage
  float actual_soc;            // SOC 0-100% (full range)
  float usable_soc;            // SOC 0-100% (operating range)
  float current;               // Battery current (A, positive = charging)
  float temperature;           // Battery temperature (°C)
  String state;                // "Charging", "Discharging" or "Idle"
};
```

---

## Common Examples

### Change and persist settings
```cpp
auto& cfg = modbeeMPPT.config.data;
cfg.battery_type = MODBEE_BATTERY_LIFEPO4;
cfg.battery_cell_count = 4;
cfg.charge_voltage = 14.4f;   // 3.6 V/cell
cfg.charge_current = 2.0f;

if (modbeeMPPT.config.validateConfig()) {
  modbeeMPPT.config.saveConfig();
  modbeeMPPT.config.applyToMPPT(modbeeMPPT.api);
}
```

### Real-time monitoring
```cpp
void loop() {
  modbeeMPPT.loop();

  auto input = modbeeMPPT.api.getVbusPower();
  auto battery = modbeeMPPT.api.getBatteryPower();
  Serial.printf("Input: %.1f W | Battery: %.1f W | SOC: %.1f %%\n",
                input.power, battery.power, modbeeMPPT.api.getBatteryChargePercent());
}
```

### Battery status snapshot
```cpp
auto status = modbeeMPPT.api.getComprehensiveBatteryStatus();
Serial.printf("Charging: %.2f V | Rest: %.2f V | SOC: %.1f %% (usable)\n",
              status.charging_voltage, status.true_voltage, status.usable_soc);
```

### Faults
```cpp
if (modbeeMPPT.api.hasFaults()) {
  Serial.println(modbeeMPPT.api.getFaultString());
}
```