Troubleshooting
Below are responses to some common problems.
Firmware Installation issues~
Unable to upload via the Web interface~
When uploading the firmware via the Web interface and you see the error "Invalid file extension or incompatible bin file", check that you are using the correct firmware binary file that matches your board and ESP32 chip set. If that is correct, it may be because the firmware is too large for the boot partition, which could be the case when moving from 3.6.5 to 3.7.0 in certain situations. The solution is to use one of the flash tools.
Web Interface shows old data or errors in browser after an update~
This is caused by the browser caching the old files. To fix this, clear the browser cache and reload the page. CTRL-R or CMD-R or F5 on most browsers.
Stability~
EMS-ESP can not connect to the WiFi~
The EMS-ESP is probably in Access Point mode. Look for a wifi SSID ems-esp
, connect to this and open a browser to 'http://192.168.4.1'. If you have configured a WiFi client your router would have appointed an IP address via DHCP. You should be able to then connect via https://ems-esp or https://ems-esp.local.
On boards with Ethernet, Ethernet will be disabled if a WiFi SSID exists. If you want to use Ethernet, set this clear this setting.
The LED is constantly flashing~
A fast pulse of the LED means the system is booting or in installation mode. Connect via the WiFi to its Access Point (ems-esp
) to complete the configuration.
A slow pulse means either there is no WiFi connection or EMS-ESP cannot read from the EMS bus. In this case go to the Web interface and try a different Tx Mode setting.
See the explanation on what the LED shows.
EMS-ESP often restarts~
A healthy gateway/interface board running EMS-ESP should run happily for long periods without spontaneous restarts so, if yours is restarting by itself at random intervals, then something's not right.
Record how often it crashes and whether there is any relation to activity on the network (e.g. wifi or mqtt reconnecting) or something incoming/outgoing to one of the EMS devices. A good way to spot this is to use Home Assistant or simple MQTT Explorer to watch the system up time.
Things to check:
It may be power related~
- Power down the gateway and check wiring connections are secure. Check that the ESP32, DC-DC converter and any jumpers on the gateway are securely seated onto their connectors.
- Try powering the gateway from the ESP32's USB socket (check the wiki for how to do this on your particular gateway model). If the restarts stop, then you've got a problem with the external power source (BUS or service jack) or the DC-DC converter inside the gateway.
- If on WiFi, try reducing the WiFi Tx Power to 10 dBm from the
Network Settings
page and see if that helps.
It may be memory related~
The ESP32 has very limited RAM, split between run-time stack and the heap. The heap can quickly become fragmented reducing the maximum size of a buffer, and we use A LOT of buffers to prepare all that lovely JSON files for sending to MQTT and populating the Web pages. When the ESP32 runs out of available it will simply restart itself. Things to check:
- If the WebUI is accessible, go to
System->System Status
and look at the Heap. If the Free memory is below 90KB or the Max allocation below 45KB then that may be an issue and you'll need to turn off services, try again and report this. Start by disabling mDNS and SysLog (if running) one by one and see if that helps. - Make sure the System Log's Max Buffer Size at
System->System Log
is at its lowest (25). - Each network protocol (Ethernet, Wifi, AP) consumes memory. If you're only using Ethernet (e.g. an BBQKees E32 Gateway) switch off WiFi and the Access Point (use a blank WiFI ssid).
- If you have many EMS entities use the Customizations page and set any unused entities (shown by having a blank value) to "remove from memory".
It could be code related~
- Go to
System->System Log
and set theLog Level
toINFO
. This will make sure you'll see the restart log at the top next time it restarts. It'll show something similar to2022-12-30 11:58:02.000 INFO 0: [emsesp] Last system reset reason Core0: Software reset CPU, Core1: Software reset CPU
. - And finally, if none of the above works then the problem is the core processing the incoming telegrams. Try and capture some logs just before it crashes (using SysLog is good for this) and post the information in a new GitHub issue.
EMS-ESP becomes unresponsive~
If EMS-ESP becomes unresponsive and you cannot access the WebUI, follow these steps:
- Check your network router to see if ems-esp is still active. If you're running a Mesh of WiFi Access Points it may have been roamed to a new location or switched WiFi channels. The work-around for this is to set a BSSID in EMS-ESP (WiFI only).
- Look at the on-board LED, if you haven't disabled it. If the LED is flashing or solid it means EMS-ESP is still running.
- Next check the EMS-ESP services. Can you Telnet to port 25 to access the Console? Are MQTT messages still being sent, if enabled?
- If you're using the Ethernet port, do you see the LED on the port flashing showing traffic in and out?
- If EMS-ESP has restarted itself check the system logs for the Reset Reason. It will be one of the first messages. See above.
- Attach the board to a computer via USB, without restarting on powering down EMS-ESP and access the Serial console to see if there are any errors.
- Lastly, log a GitHub issue with the Support Info and details of your setup.
EMS Data and Connectivity~
Not all EMS devices are recognized~
Experiment with changing the Tx Mode value in the Settings page. The default EMS works for older EMS1.0 systems, EMS2 or EMSPlus systems and HT3 for Junkers/Worcester using the Heatronics protocol.
If you have EMS devices that may not yet be supported by EMS-ESP then use scan
or scan deep
from the Console to find out their details and then post an enhancement issue on GitHub. Remember the su
password is default ems-esp-neo
unless this has been changed via the console (passwd
) or in the WebUI (Security->Security Settings
). For example:
1 + |
The thermostat needs a setting of day-of-week and daylight-saving. Bosch day-of-week is Mo-0, Su-6, unlike unix-time.
If you have enabled NTP you can just enter "NTP" and the ntp time is set to the thermostat.
With NTP enabled the thermostat clock is also automatically set by EMS-ESP if it differs from the ntp time.
Pay attention to whether or not you want to enable daylight-saving time. This should be consistent with the setting on your thermostat.