Commissioning ESPhome sensors

This guide takes you step by step through everything you need after unpacking a sensor:

1. Set up WiFi – the sensor logs in to your network
2. Open the web interface – view readings and identify the sensor
3. Register the sensor – so that the data appears in your dashboard
4. Update the firmware – even when the sensor has long been at its place of use

What you need

• the sensor, connected to its power supply (or mounted at the place of use, see the device documentation)
• a 2.4 GHz WiFi with internet access – the sensors do not support 5 GHz WiFi. If your router offers both bands under a common name, this is usually not a problem
• name and password of this WiFi
• a smartphone, tablet or notebook with WiFi and a web browser

Set up WiFi

A brand-new sensor does not know your WiFi yet. It solves this by opening a small WiFi of its own (the so-called hot spot or captive portal), through which you tell it the credentials of your WiFi.

Step by step

1. Power the sensor. If the sensor finds no known WiFi, it opens its own hot spot after about a minute. Its name (SSID) starts with eco… and ends with an identifier, e.g. ecopvgx-431512.

2. Connect to the hot spot. Open the WiFi settings on your smartphone or notebook and connect to the sensor's hot spot. The password is:

   Password: 12345678

3. Open the configuration page. On many smartphones the page opens automatically. Otherwise open the address http://192.168.4.1 in a web browser. If you are asked for credentials:

   User: admin
   Password: 12345678

   

4. Note the sensor ID. In the upper part of the page you will find the sensor's identifier in the form eco…-<ID> (marked in the picture). Note it down – you need it later for registration. It can also be looked up again later in the web interface.

5. Enter your WiFi credentials. Select your WiFi from the list (or type the name under SSID), enter the Password and tap Save.

   

6. Wait. The sensor restarts, the hot spot disappears, and after a short time the sensor is logged in to your WiFi. Your smartphone automatically reconnects to your normal WiFi.

If your sensor has a status LED, you can see there how it is doing (see Troubleshooting).

Web interface

Every sensor has a small web page that it provides in your WiFi. There you see the current readings, a log for troubleshooting and the option to update the firmware. All you need is a web browser in the same WiFi as the sensor.

Find the sensor

Open the address in your browser

http://eco…-<ID>

e.g. http://ecopvgx-431512. In some networks you have to append .local: http://ecopvgx-431512.local.

If neither works (some routers and home networks do not resolve device names), look in the device list of your WiFi router to see which IP address was assigned to the sensor, and then open http://<IP address>, e.g. http://192.168.1.95.

Login

On the web page you log in with:

User: admin
Password: 12345678

What you see there

1. Sensor data
2. A "click" on a sensor value shows details (history)
3. A "double click" on a heading enlarges the area
4. Log output – in case of an error it says here what does not work
5. Uptime since the last restart
6. Name and type of the sensor
7. Light/dark mode
8. Heartbeat: green = active, grey = offline

Further down the page you find the details about the sensor itself:

1. EcoSensor ID – needed to register the sensor
2. Network details and operating parameters, among others the IP address of the web interface and the installed firmware version
3. Firmware update (depending on the sensor as a Firmware update button or as a OTA Update file selection, see Firmware update)

Register the sensor

For the readings of your sensor to appear in your dashboard, it has to be assigned to your account once. For this you need the EcoSensor ID (eco…-<ID>) from the hot spot or the web interface. How registration works is described in the documentation Register a device.

Integration in Home Assistant (optional)

With some versions of the sensors an interface to the home automation software Home Assistant can be activated. It is part of a separate firmware variant (marked -ha, see Firmware update). If you do not use Home Assistant, you do not need this chapter.

Add the sensor in Home Assistant as follows:

Settings (1) → Devices & services (2)

→ + Add integration

Now select "ESPHome" and enter the sensor's host name (eco…-<ID>). Sometimes .local has to be appended, e.g. ecopvgx-431512.local.

You will then be asked for an encryption key. It is included with each sensor or will be sent to you by email.

Firmware update

The firmware is the software that runs on the sensor. We improve it continuously; an update brings bug fixes and new features. How you update it depends on how you can reach the sensor and what the sensor can do. The sensors of the Eco series are usually at a fixed location and are often only reachable via WiFi there – that is why the ways here are sorted by effort. Take the simplest one that works for your sensor.

Which way applies to my sensor?

Open the web interface and scroll down (point 3 in the picture above):

• Does ecosensors.cloud offer an update for your sensor directly in the dashboard? → Way A. (Still in development, see below.)
• Is there a "Firmware update" button in the sensor's web interface? → Way B.
• Is there an "OTA Update" section with Choose file and UPDATE? → Way C.
• Can you no longer reach the sensor in WiFi at all, or does an update fail permanently? → Way D.

The device documentation also states which way your sensor supports.

Before every update

• Check the installed version: In the web interface, EcoSensor FW Version shows the currently installed version. In the dashboard under Firmware (login required) you can see for each of your devices whether an update is available.
• Ensure power supply: Do not disconnect the sensor from power during the update and let it restart undisturbed afterwards (about a minute). For inverter sticks such as the EcoPVGX this means: only update in daylight.
• Choose the right variant: Some sensors are available with and without Home Assistant interface (-ha). Always install the variant that is already running on the sensor – otherwise you unintentionally change its behaviour (see also Home Assistant).

Way A: Update via ecosensors.cloud

Sensors that can update themselves are to be updatable directly via ecosensors.cloud in the future: you trigger the update on the website, the sensor installs the new firmware on its own. You need neither access to the sensor's web interface nor to be in the same WiFi – the sensor only has to be online. This is particularly practical for sensors in exposed places.

Where you find an available update notice and how you trigger it will be added here as soon as the function is enabled. Even now the Firmware page shows you the installed and the current version for each of your devices.

Way B: Update at the push of a button

The sensor downloads the latest firmware itself from the internet and installs it. You do not have to download a file.

1. Open the sensor's web interface.
2. Press the "Firmware update" button.
3. Wait one to two minutes. The sensor downloads the firmware, installs it and restarts. The web page is briefly unreachable during this.
4. Reload the page and check under EcoSensor FW Version whether the new version is running.

If the latest version is already installed, nothing bad happens when you press it again – the sensor then simply installs it once more.

Way C: Upload an update file

Some sensors (e.g. EcoPVGX, EcoSPM) cannot update themselves. Here you download the update file yourself and hand it to the sensor via its web interface. For this you also need no USB connection, you only have to be in the same WiFi as the sensor.

1. Download the update file

1. Log in to ecosensors.cloud and open the Firmware page.
2. There you see the products of your devices, the installed and the current version. In the Downloads section, download the update file (file extension .ota.bin) for the right variant.

2. Transfer the file to the sensor

1. Open the sensor's web interface (from the same WiFi) and scroll to OTA Update.
2. Click Choose file and select the downloaded .ota.bin.
3. Click UPDATE and wait until the transfer is complete and the sensor has restarted (approx. 1–2 minutes). Do not close the browser tab before that.
4. Reload the page and check under EcoSensor FW Version whether the new version is running.

You can also do this update with your smartphone: the web interface (and the hot spot's configuration page, also there as OTA Update) works in the mobile browser.

Way D: Update via USB

Only necessary if the sensor can no longer be reached via WiFi, an update via the web interface fails permanently, or an existing device is to be switched to our firmware for the first time. For this the sensor must be physically accessible, i.e. connected to a computer. For sensors that have been permanently mounted, this means: remove them.

How you connect the sensor to the computer and whether a housing has to be opened or a jumper set for this is device-specific – see the device documentation.

1. On Firmware, download the complete image (initial installation) for your sensor and the right variant.

2. Connect the sensor to your computer via USB.

3. Open the ESP Web Tool in a Chromium-based browser (Chrome, Edge, Brave …). The tool runs entirely in the browser, you do not have to install anything.

4. Click CONNECT and select the sensor's USB port.

   

5. Use SELECT to choose the downloaded file. The address (field 0x) stays at 0. Then click PROGRAM.

   

6. Wait until the progress reaches 100 %.

   

7. As soon as the tool reports Done!, disconnect the sensor from the computer and reconnect it to its normal power supply ("reset your device").

   

The sensor starts with the new firmware. Depending on its state it connects to your WiFi or opens its hot spot again – then start at Set up WiFi.

Troubleshooting

LED messages

Some sensors have status LEDs, of which usually the red one serves as the status LED. Normally the red LED does not light up at all.

• Red
  • slow blinking: A warning is active. This is the case, for example, when reading a sensor value temporarily fails, when the WiFi or MQTT connection is interrupted (e.g. at startup) or when the Home Assistant interface is active but not connected.
  • fast blinking: The sensor found an error during setup. In most cases it still tries to recover and carry on.

The hot spot does not appear

• After switching on, wait up to two minutes.
• The hot spot only appears if the sensor finds no known WiFi. If your old WiFi is still in range, it may keep connecting to it – switch it off briefly for the setup.
• Search for WiFis in the 2.4 GHz band; some smartphones hide networks without internet access or switch back to your home WiFi on their own. If necessary, temporarily disable mobile data and connect again.

The web interface cannot be reached

• Are you connected to the same WiFi as the sensor (not the guest WiFi, not via mobile data)?
• If http://eco…-<ID> does not work, try http://eco…-<ID>.local, and if that does not work either, the IP address from your router (see Find the sensor).
• Restart the sensor (disconnect and reconnect the power, or Restart in the web interface).

The sensor does not report to the dashboard

• Is the sensor registered?
• Does the web interface show the heartbeat green, but the sensor is offline in the dashboard? Check the internet access of your WiFi.
• If the Home Assistant variant runs without pairing, the sensor restarts every 15 minutes (see Home Assistant).

The firmware update does not work

• Way B: Does the sensor have internet access? If not, use Way C.
• Way C: Is it really the update file (.ota.bin) and the variant that matches the sensor?
• If the transfer breaks off, move closer to the sensor with your device or improve reception and try again.
• If none of this helps: Way D.

Device documentation

The following pages contain everything that applies only to the respective device – e.g. connection, compatibility, technical data and special features of the firmware update via USB:

• EcoPVGX – for Growatt inverters
• EcoMBR1 – for ModBus RTU devices
• EcoSPM – for Shelly PM Mini Gen3