---
title: "Getting started"
space: "MPPT Charger"
url: "https://docs.modbee.org/mppt-charger/getting-started"
updated: "2026-10-25"
---

# Getting Started

Build and flash the firmware, wire the board in the right order, and set it up for your battery.

## You will need

- **Board.** A ModBee MPPT Charger.
- **USB-C data cable.** For flashing and the serial console.
- **Battery.** A 2S to 4S Li-ion, Li-Po or LiFePO4 pack, with a fuse close to the battery.
- **Solar panel and/or DC supply.**
  - PV input: a 12 V nominal panel with **Voc of 24 V or less** at the coldest expected temperature.
  - POWER input: 5 V to 24 V.
- **Battery thermistor.** A 10 kΩ NTC (103AT type) taped to the battery. Without one, bridge the **NTC BYPASS** jumper (JP2).
- **Software.** [Visual Studio Code](https://code.visualstudio.com/) with the [PlatformIO IDE](https://platformio.org/install/ide?install=vscode) extension, and Git.

## 1. Build and flash

```bash
git clone https://github.com/mod-bee/modbee-mppt-ti-c3.git
cd modbee-mppt-ti-c3
```

Open the folder in VS Code. PlatformIO picks up `platformio.ini` (environment `lolin_c3_mini`). All libraries are included in `lib/`, so no downloads are needed beyond the PlatformIO ESP32 platform.

With only USB connected, upload both the firmware and the web interface:

```bash
pio run -t upload     # firmware
pio run -t uploadfs   # web interface (LittleFS image from data/)
```

Without the filesystem upload, the charger still works, but the web interface has no pages to serve.

**Uploading the filesystem image erases the saved settings and statistics.** After an update, re-enter your battery settings before connecting a charging source.

If the board does not enter upload mode on its own, hold **BOOT**, press and release **RESET**, then release **BOOT**.

### Serial console

```bash
pio device monitor     # 115200 baud
```

The console uses the ESP32-C3 native USB. It prints a short status summary every 2 seconds. With only USB connected, the charger IC has no power, so the readings are not meaningful. That is expected.

## 2. Connect the hardware

Follow this order every time. The reasons are explained in [HARDWARE.md](/mppt-charger/hardware#connection-and-disconnection-order).

**Connect:**

1. **Battery** (BATT+ / GND-). Wait for the SYS status LED to light.
2. **PV and/or POWER input.**
3. **Load** (L+ / GND-).

**Disconnect** in reverse:

1. **Load.**
2. **PV and/or POWER input.**
3. **Battery** last.

**The firmware ships set for a 3S Li-Po pack (12.6 V, 1.0 A).** For any other pack, configure it before connecting a charging source: connect the battery only, set it up in the web interface (step 4), and then connect the input.

## 3. Open the web interface

1. **Join the access point.** The board starts a Wi-Fi access point called **`ModbeeMPPT`**. It is an open network with no password.
2. **Open the dashboard.** Browse to **http://192.168.4.1/**. A captive DNS redirects other addresses there too.
3. **If the network does not appear, press the WIFI button.** The access point is not started at boot when the battery reads below 5 % or is not detected.
4. **The access point turns off after 5 minutes** to save power. Press **WIFI** to turn it on for another 5 minutes.

| Page | Address | Use |
|------|---------|-----|
| Dashboard | `/` | Live power flow, battery, inputs, system rail, energy totals |
| Settings | `/settings` | Battery, charging, input, timer and MPPT settings |
| Debug | `/debug` | Charger status registers and configuration readback |

The access point is open, and anyone in range can change the charger settings while it is on. Keep that in mind for public installations.

## 4. Configure the battery

On the **Settings** page, set the battery type, cell count, charge voltage and charge current, then **Save Settings**.

- **Saving.** Settings are written to `/config/mppt_config.json` and applied to the charger immediately.
- **Re-applying.** The firmware re-applies the full settings every 5 minutes, and at every boot.
- **Validation.** The firmware rejects a charge voltage that does not suit the selected cell count and chemistry. When that happens, the previous settings stay in force.

Typical settings (always check your cell datasheet):

| Pack | Battery type | Cells | Charge voltage | Charge current |
|------|--------------|-------|----------------|----------------|
| 2S Li-ion / Li-Po | Li-Po | 2 | 8.4 V | up to 3 A |
| 3S Li-ion / Li-Po (default) | Li-Po | 3 | 12.6 V | 1.0 A default |
| 4S Li-ion / Li-Po | Li-Po | 4 | 16.8 V | up to 3 A |
| 2S LiFePO4 | LiFePO4 | 2 | 7.2-7.3 V | up to 3 A |
| 3S LiFePO4 | LiFePO4 | 3 | 10.8-10.95 V | up to 3 A |
| 4S LiFePO4 | LiFePO4 | 4 | 14.4-14.6 V | up to 3 A |

**Other settings:**

- **Charge current.** A common choice is 0.2C to 0.5C of the pack capacity, and no more than 3 A on this board.
- **MPPT.**
  - Leave **MPPT enabled** for solar.
  - **VOC %** sets the panel operating point as a fraction of its open-circuit voltage. The default is 87.5 %; most panels have their maximum power point at 70-90 % of Voc.
  - **VOC rate** sets how often the panel is sampled.
- **Factory reset.** **Reset to Defaults** restores the 3S Li-Po defaults.

## Charging behaviour

The BQ25798 runs a standard Li-ion charge cycle:

| CHG_STAT state | What happens |
|----------------|--------------|
| Trickle / Pre-charge | Deeply discharged pack: low current until the pre-charge threshold |
| Fast charge (CC) | Constant current at the charge-current setting |
| Taper (CV) | Constant voltage at the charge voltage; current falls |
| Top-off | Optional extra time after taper (top-off timer) |
| Termination done | Current fell below the termination threshold; charging stops |

Charging restarts when the battery falls by the recharge threshold (default 0.4 V) below the charge voltage. Li-ion chemistries have no float stage.

The green **CHG** LED is on while charging and blinks on a charger fault. The **SYS** RGB LED shows the firmware state: yellow while charging, green when done, blue when idle, red on a fault.

## Troubleshooting

| Symptom | Check |
|---------|-------|
| No charging | Input above 3.6 V and below the VAC OVP setting; NTC fitted or JP2 bridged; battery voltage inside the configured cell-count range; fault bits on the Debug page |
| Panel connected but input reads 0 V | Polarity on PV+/GND-; panel Voc above 24 V triggers input over-voltage protection |
| Access point not visible | Press WIFI; it turns off after 5 minutes |
| Web page blank or 404 | Filesystem not uploaded: run `pio run -t uploadfs` |
| Settings rejected | Charge voltage outside the range for the selected cell count and battery type |
| Serial readings are zero or meaningless | Normal with USB only: the charger IC is unpowered until a battery or input is connected |

See [HARDWARE.md](/mppt-charger/hardware) for the electrical details and [SOFTWARE.md](/mppt-charger/software) for firmware internals.