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). 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`

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

`modbee_battery_status_t`

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

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

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

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

if (modbeeMPPT.api.hasFaults()) {
  Serial.println(modbeeMPPT.api.getFaultString());
}

MPPT Charger

API reference