Webserver guide - dalathegreat/Battery-Emulator GitHub Wiki

Webserver

You can interact with the Battery-Emulator via the built in Webserver. Here you can check battery status, change battery settings, update the software over-the-air, check active events, monitor cellvoltages plus much more! It is the preffered way to monitor a newly setup battery system.

[!IMPORTANT]
Never expose the Battery-Emulator to the internet. If cybersecurity is a concern, you can remove the entire #define WEBSERVER. This disables everything related to Webserver/Wifi/OTA etc.

Prerequisites

ℹ️ To be able to use the Webserver, make sure that #define WEBSERVER is enabled in the USER_SETTINGS.h file. This is enabled by default, but incase you made changes to the file it is always good to verify that it is set!

Next up, you need to connect to the Battery-Emulator to either your home Wifi, or connect directly to the access point that the Battery-Emulator itself is broadcasting.

A: Connect to your home network

To have the Battery-Emulator accessible in your home network, you need to enter your home wifi credentials into the USER_SETTINGS.cpp file. The lines ssid and password will have placeholders, REPLACE_ME..., this is where you enter your home network credentials. After the file has been modified, flash it onto the hardware via USB.

When the board boots, it will attempt to connect to the wifi network you specified. Your router will give it a unique IP, so next up is figuring out what the actual address is. There are a few options you can do

  • Connect via USB and read out the serial print via Arduino serial montitor. When the board boots, it will post which IP address it got assigned to. If you only see ????? in the serial monitor, change the baud rate from 9600 to 115200
  • Check your router info. Incase your home router has a login page (typically 192.168.1.1), you can via this see what devices are connected to your home network. The board will show up as esp32-xxxxx here in your router table.
  • Bruteforce guessing. If your PC has the IP 192.168.1.10 , you can typically just replace the last number with a few numbers up/down and this way get a connection. For instance if your PC is 192.168.1.10 and the only other device on the network, the emulator might get the next available address, 192.168.1.11

Once the IP of the board has been determined, open a webbrowser on a device that is connected to the same home network, and type in the IP. This will open the Webserver user interface

[!NOTE]
After v7.0.0, the board saves which Wifi it should connect to in persistent memory. Incase you later on change network, you can disable the LOAD_SAVED_SETTINGS_ON_BOOT option to allow your new network to function

B: Connect to the Access Point

By default, there is an access point broadcasted by the board, called "Battery Emulator". The default password is "123456789". This can be changed in the USER_SETTINGS.cpp file incase you want to improve cyber-security.

After connecting your laptop/phone to this network, you can open a webbrowser and access the interface. To login , browse to the page 192.168.4.1 , this will open the Webserver user interface

Using the Webserver

The front page will contain some quick information about the system. What software version the system has, Inverter protocol, Battery type, Livedata from the battery transmitted to the Inverter, along with some buttons to go to other pages. The page will be green incase all is well, go yellow incase there is an active warning, and go red incase an error is active and blocking operation. Incase there is a warning/error active, you can click the Events button to go to this view.

image

Events

This page contains information about events that have occured while the system has been running. All events are timestamped, and have an occurance counter so you know if many events of the same type has triggered.

image

Each event also has a description field with more info. The events are grouped into three categories:

Info ℹ️

Info events contain useful information like when battery has been charged full, completely discharged, reset reason etc. Having info events present does not warranty any user action

Warning 🟡

Warning events contain info that users might want to act upon. The system will try to mitigate certain warnings, like incase the battery is reaching too high voltage, the system will raise a warning event and prevent further charging (only discharging will be possible). Warning events should be analyzed when spotted. The front page of the webserver, plus the LED on the board will also turn yellow when a warning event is active.

Error 🔴

Critical error events contain info about why the system has stopped operation. Incase it is no longer safe to continue using the battery, an error event will be generated and charging/discharging is set to 0W allowed. Check the Error event description for information on how to proceed or what to check. The front page of the webserver, plus the LED on the board will also turn red when an error event is active.

Settings

This page contains settings for how the battery should be used. They are the same settings you can put in via the 'USER_SETTINGS.h' file. All settings can be changed on the fly.

image

Battery Capacity

How much energy can your battery store? Some batteries autodetect this via CAN communication, but for some battery types that do not have this it is good to manually define the value so that your inverter knows how large the battery is.

Rescale SOC%

Increases battery life. If enabled, the system will rescale SOC% between the configured min/max-percentage. By not using the entire battery, the amount of cycles the battery can last increases. Good practice is to use this feature, and restrict SOC% between 20-80%.

image

[!NOTE] For some battery types, it is good to periodically let the battery charge to 100%, to allow for the BMS to re-calibrate. This can be performed once per month/half year. Check your batteries wiki for more info if this procedure is required.

Battery charge/discharge limit

  • Max charge speed (A)
  • Max discharge speed (A)

This setting artifically limits the amount of power that can go in/out of the battery. Even though most EV packs can push out hundreds of ampere, most inverters cannot handle large amounts of current. Some inverters even stop funcitoning incase they see a large value allowed. By default this is set to 30A on charge and discharge. You can decrease this value if the wiring or any fuses in your system cannot handle the amount of power. You can also increase this value if you have a high power inverter that becomes limited by the setting.

Manual charge voltage limits

Disabled by default. This option can be enabled to manually limit min/max voltage in the system. Note that not all inverters support voltage based limits, the setting was primarily developed for BYD_CAN. If left disabled, the system will automatically use the entire voltage range of your battery (unless Rescale SOC% is enabled)

image

Cellmonitor

Via this page you can keep track of all the cells in your battery. At the top of the page there is a quick readout of Min/Max/Deviation inside the battery. The view also has a grid view of all cells and their values, along with a graph at the bottom for quick visualization on how balanced the battery is. The two cells that are lowest and highest will be highlighted red for quicker identification where they are.

image

Interpreting the values

In general, the lower the voltage deviation in mV, the better. A battery with 10mV deviation is considerably healthier than one with 100mV deviation. Individual cells that are lower than the rest can be a sign of early stages of cellfailures/degradation/overheating, however, this depends heavily on the chemistry of the battery. Some chemistries like LMO can have way larger deviations at lower SOC% compared to NCM chemistries.

Deviations can also grow under heavy load. If you pull tens of kW out of the battery, the mV deviation usually increases. This is completely normal.

The system will automatically go into a warning state incase a cellvoltage goes too high or too low. If this happens, an Event will be raised (see the event page), and further charging/discharging will be halted.

Perform OTA Update

Via this page you can update the software. See the page OTA Update for more info how

Reboot Emulator

This button will restart the emulator. Can be useful to get out of a latched error message blocking operation (critical cell condition, etc.). Pressing the button will prompt you, "Are you sure you want to reboot?"

ℹ️ Rebooting the Emulator might open contactors! If you have configured the hardware to control contactors via GPIO (see Automatic Contactor Control), they will open during a reboot!

CAN logging

See the page about CAN logging for more information about the CAN logging function.

Web Server Authentication

This protection level is not particularly robust (Digest access authentication), however, it is sufficient to prevent non-malicious usage within the internal network on which it operates and the username and password are not sent in clear text. To force web server authentication, you need to configure WEBSERVER_AUTH_REQUIRED to true in USER_SETTINGS.h and specify http_username and http_password in USER_SETTINGS.cpp