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 with the PlatformIO IDE extension, and Git.

1. Build and flash

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:

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

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.

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.

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):

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:

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

See HARDWARE.md for the electrical details and SOFTWARE.md for firmware internals.