YaSolR Manual

Quick Start

When everything is wired and installed properly, you can:

  1. Flash the downloaded firmware (see Firmware First Time Installation)
  2. Power on the system to start the application
  3. Connect to the WiFI: YaSolR-xxxxxx
  4. Connect to the Captive Portal to setup your WiFi (see: Captive Portal (Access Point) and WiFi)
  5. Go to the GPIO page to verify or change your GPIO settings
  6. Go to the Hardware page to activate the hardware you have
  7. Go to the Hardware Config page to configure your hardware settings and resistance values. Resistance Calibration is really important to do otherwise the router will not work.
  8. Go to the MQTT page to configure your MQTT settings if needed.
  9. Go to the Relays page to configure your relay loads if needed.
  10. Go to Output 1 & 2 pages to configure your bypass options and dimmer settings if needed.
  11. Restart to activate everything.
  12. Enjoy your YaSolR!

Firmware First Time Installation

The firmware file which must be used for a first installation is the one ending with .FACTORY.bin.

Firmware can be downloaded here : Download

With esptool.py (Linux / MacOS):

First erase the memory (including the user data):

esptool.py erase_flash

The flash the complete FACTORY firmware file:

esptool.py write_flash 0x0 YaSolR-VERSION-MODEL-BOARD.FACTORY.bin

With Espressif Flash Tool (Windows):

IMPORTANT

Be careful to not forget the 0

Espressif Flash Tool

Firmware Update

Considering that YaSolR supports many features, this is a big application that is taking a lot of space on the ESP32. So YaSolR is using a SafeBoot image to allow updating the firmware through the Web OTA.

To update the firmware through OTA, please follow these steps:

  1. First download the new firmware. The firmware file which must be used is the one ending with .OTA.bin (YaSolR-<VERSION>-<MODEL>-<BOARD>.OTA.bin)

  2. Go to the management page to restart the device in SafeBoot mode:

  1. Once in SafeBoot mode, the device will open an Access Point with the name SafeBoot-xxxxxx. You need to connect to this Access Point.

  1. Once connected, open a browser and go to http://192.168.4.1 and you will see the ElegantOTA page allowing you to update the firmware.

  1. After the update is successful, the device will reboot in the updated YaSolR.

Captive Portal (Access Point) and WiFi

TIP

Captive Portal and Access Point address: http://192.168.4.1/

A captive portal (Access Point) is started for the first time to configure the WiFi network, or when the application starts and cannot join an already configured WiFi network fro 15 seconds.

The captive portal is only started for 3 minutes, to allow configuring a (new) WiFi network. After this delay, the portal will close, and the application will try to connect again to the WiFi. And again, if the WiFi cannot be reached, connected to, or is not configured, the portal will be started again.

This behavior allows to still have access to the application in case of a WiFi network change, or after a power failure, when the application restarts. If the application restarts before the WiFi is available, it will launch the portal for 3 minutes, then restart and try to join the network again.

In case of WiFi disruption (WiFi temporary down), the application will keep trying to reconnect. If it is restarted and the WiFi is still not available, the Captive Portal will be launched.

Access Point Mode

You can also chose to not connect to your Home WiFi and keep the AP mode active. In this case, you will need to connect to the router WiFi each time you want to access it.

In AP mode, all the features depending on Internet access and time are not available (MQTT, NTP). You will have to manually sync the time from your browser to activate the auto bypass feature.

Dashboard

Here are the main links to know about in the application:

(replace yasolr.local with the IP address of the router)

/config page

This page is accessible at: http://<esp-ip>/config. It allows to see the raw current configuration of the router and edit it.

WARNING

This page should not normally be used, except for debugging purposes.

/console page

A Web Console is accessible at: http://<esp-ip>/console. You can see more logs if you activate Debug logging (but it will make the router react a bit more slowly).

Overview section

The overview section shows some global information about the router:

IMPORTANT

The resistance value that you see in the overview page is an estimation of the global resistance value corresponding to output 1 and output 2 combined together, and this value is measured by a JSY or PZEM when routing.

This is not the resistance value calibrated for each output in the Hardware Config section.

Output sections

The output sections show the state of the outputs and the possibility to control them.

Energy:

IMPORTANT

A PZEM is required to see the measurements of each outputs.

Dimmer Control:

Bypass Control:

The following settings are visible if Bypass Automatic Control is activated.

TIP

All these settings are applied immediately and do not require a restart

Relays section

Management section

Logging

If you need to record the logs during a long period of time to troubleshoot an issue, you can activate Debug and then stream the logs into a file using websocat from another computer. Make sure the computer won’t g oto sleep!

> websocat ws://192.168.125.123/wserial > logs.txt
NOTE

The special characters (like ??f??OO) at the beginning of each line are normal.

Network section

WARNING

The password MUST be more than 8 characters long otherwise the ESP will fail to start AP mode or the Captive Portal for recovery if it needs to.

Time settings:

WiFi settings:

Static IP address:

When setting a static IP, the router will try to connect to the WiFi with the static IP and won’t use DHCP anymore.

IMPORTANT

When using a board with Ethernet adapter, the static IP setting only applies to the Ethernet adapter, not the WiFi. So if a WiFi SSID is configured to connect to, YaSolR will connect to the WiFi and will use DHCP to get an IP address.

The ESP32 must be restarted to apply the changes.

MQTT section

IMPORTANT

MQTT as a Grid Source

IMPORTANT

The ESP32 must be restarted to apply the changes.

MQTT topics are less accurate because depend on the refresh rate of this topic, and an expiration delay of a few seconds is set in order to stop any routing if no update is received in time. Also, there is 1 minute expiration delay after which the values will be considered as invalid.

As a general rule, do not use MQTT as a grid power source if you have a JSY or Remote JSY.

MQTT as a Temperature Source

MQTT can be used to receive temperature data instead of relying on a connected sensor. There is 1 minute expiration delay after which the temperature will be considered as invalid. So this is important to make sure that the topic will be refreshed, otherwise features based on temperature won’t work.

IMPORTANT

The ESP32 must be restarted to apply the changes.

Home Assistant Discovery

YaSolR supports Home Assistant Discovery: if configured, it will automatically create a device for the Solar Router in Home Assistant under the MQTT integration.
IMPORTANT

MQTT must be restarted to apply the changes.

The complete reference of the published data in MQTT is available here. The published data can be explored with MQTT Explorer.

Activating MQTT Discovery in Home Assistant

You can read more about Home Assistant Discovery and how to configure it here.

Here is a configuration example for Home Assistant to move the published state topics under the homeassistant/states:

# https://www.home-assistant.io/integrations/mqtt_statestream
mqtt_statestream:
  base_topic: homeassistant/states
  publish_attributes: true
  publish_timestamps: true
  exclude:
    domains:
      - persistent_notification
      - automation
      - calendar
      - device_tracker
      - event
      - geo_location
      - media_player
      - script
      - update

To configure the discovery topic, you need to go to http://homeassistant.local:8123/config/integrations/integration/mqtt, then click on configure, then reconfigure then next, then you can enter the discovery prefix homeassistant/discovery.

Once done on Home Assistant side and YaSolR side, you should see the Solar Router device appear in Home Assistant in the list of MQTT devices.

GPIO section

This section allows to configure the pinout for the connected hardware and get some validation feedback.

If you see a warning with (Input Only), it means that this configured pin can only be used to read data. It perfectly OK for a ZCD, but you cannot use a pin that can only be read for a relay, DS18 sensor, etc.

IMPORTANT

If you change one of these settings, please stop and restart the corresponding Hardware.

Hardware section

This section allows to enable / disable some features of the router, and get some feedback in case some activated features cannot be activated.

All these components are activated live without the need to restart the router.

NOTE

Hardware Config section

This section allows to further configure some hardware settings and calibrate the resistance values of the loads.

IMPORTANT

If you change one of these settings in the hardware section, please restart the corresponding hardware or the YaSolR device.

Grid Frequency

Auto-detect will automatically detect the grid frequency based on the connected measurement devices, or remote ones, or thanks to the pulse analyzer. It is recommended to leave the setting to Auto-detect unless you have a good reason to force it. The reason is that the grid utility frequency can change for example from 50Hz to 51Hz after a power failure in case a generator is installed.

Dimmer Range Remapping

DANGER

For advanced users only.

This feature allows to remap where the 0% power is set (Min) and where the 100% power is set (Max). When remapped, the new duty range (0-100%) will match values from Min to Max instead of 0 to 100%.

This can be used for example to limit the power output of a dimmer, or to remap the pwm signal sent to a voltage regulator.

For example, if you set the range to `10-80%, then the new 0 will match a duty cycle of 10% and the new full power (100%) will match a duty cycle of 80%.

Read more about how to calibrate a voltage regulator in the Voltage Regulators section.

Display

Supported displays are any I2C OLED Display of type SSD1307, SH1106, SH1107.

SH1106 is recommended and has been extensively tested.

The display will look like a carousel with a maximum of 5 pages:

Relay Types

Relay Automatic Control

YaSolR supports 2 additional relays (Electromechanical or SSR, controlled with 3.3V DC) to control external loads, or to be connected to the A1 and A2 terminals of a power contactor. Relays can also be connected to the other resistance of the water tank (three-phase resistance) as described in the recommendations to reduce harmonics and flickering, in order to improve the routing and reduce harmonics. You must use a SSR for that, because the relay will be switched on and off frequently.

NOTE

Remember that the voltage is not dimmed: these are 2 normal relays

WARNING

Pay attention that there is little to no hysteresis on the relays. So do not use the automatic feature to switch non-resistive loads such as pumps, electric vehicle chargers, etc. If you need to switch other types of load in a more complex way with some hysteresis or other complex conditions, you can use the MQTT, REST API, Home Assistant or Jeedom to query the Virtual Power metric and execute an automation based on this value. The automation can then control the router relays remotely. The relays need to be set in Manual Control. Remember that these relays are not power contactors and should not be used to directly control high power loads like an Electric Vehicle charge, a pump, etc.

TIP

Rules of Automatic Switching

Grid Virtual Power is calculated by the router as Grid Power - Routed Power. This is the power that would be sent to the grid if the router was not routing any power to the resistive loads.

Grid Virtual Power is negative on export and positive on import.

For a 3000W three-phase resistance, 3% means 30W per relay because there is 3x 1000W resistances. For a 2100W three-phase resistance, 3% means 21W per relay because there is 3x 700W resistances.

Resistance Calibration

The router needs to know the resistance value of the load to correctly calculate the dimmer values.

Be careful to put a value that you have correctly measured with a multimeter, or calculated (see formula below). An approximation will cause the router to not properly work because it won’t be able to adjust the exact amount of power to send.

Remember the equation:

R = U * U / P

where:

Reading the resistance value from a PZEM or JSY

If you have a PZEM or JSY device attached, they can help you. You can set the dimmer in manual mode and set it to 50% and 100% and read the resistance value. Then you just have to report it in the Hardware Config page.

Using the automatic detection feature

This is the easiest way to calibrate the resistance values: when a PZEM or JSY is installed, the router will be able to automatically calculate the resistance. For that, click on the corresponding buttons and wait about 10-15 seconds. You can at the same time check the statistics on the Output or Overview sections, and the logs in the Web console for a more detailed output. Once done, the resistance value will be put in the corresponding field. Any previously set value will be erased.

To use this feature, make sure that the resistance will really draw some current. It won’t work if the water heater has already reached its threshold temperature.

PZEM Pairing

Each output supports the addition of a PZEM-004T v3 sensor to monitor the power sent to the resistive load specifically for this output. Thanks to the PZEM per output, it is also possible to get some more precise information like the dimmed RMS voltage, resistance value, etc.

The PZEM-004T v3 devices has a special installation mode: you can install 2x PZEM-004T v3 devices on the same Serial TX/RX. To communicate with the right one, each output will use a different slave address. The initial setup requires to pair each PZEM-004T v3 with the corresponding output.

  1. Connect the 2x PZEM-004T v3 devices to the grid (L/N) and install the clamp around the wire at the exit of the dimmer of first output
  2. Only connect the terminal wire (+5V, GND, RX, TX) of the first PZEM-004T v3 to pair to Output 1
  3. Boot the device and open the console (http://yasolr.local/console)
  4. Got to the Hardware section to activate Output 1 PZEM. It should be yellow if it has no electricity or if it is not paired.
  5. Press the Output 1 PZEM Pairing button.
  6. Verify that the pairing is successful in the console. Output 1 PZEM should also be green in the Hardware section.
  7. Disconnect this first PZEM-004T v3 from the ESP32
  8. Connect the second PZEM (which has its clamp at the exit of the dimmer of the second output) to the ESP32
  9. Press the Output 2 PZEM Pairing button.
  10. Verify that the pairing is successful in the console. Output 2 PZEM should also be green in the Hardware section.
  11. Now that the 2 devices have an address, you can connect them all to the ESP32

You can verify that the pairing is successful by trying to activate the dimmer in the overview page, and see if you get the output power.

This complex pairing procedure is not specific to this router project but is common to any PZEM-004T device when using several PZEM-004T v3 devices on the same Serial TX/RX. You can read more at:

PID Controller section

DANGER

For advanced users only.

This page allows to tune the PID algorithm used to control the automatic routing. Use only if you know what you are doing and know how to tweak a PID controller.

You can change the PID settings at runtime and the effect will appear immediately.

Default Settings

To reset the other values to their default value, just click on the validate / enter green button.

TIP

If you find better settings, please do not hesitate to share them with the community.

If you are using a slower measurement device like MQTT, you might want to try with Ki = 0.3

IMPORTANT

Here are some basic links to start with, which talks about the code used under the hood:

PID Tuning through WebSocket

When Real-time Data is activated, a WebSocket endpoint is available at /ws/pid/csv and will stream all the PID data in real time in a CSV format when automatic dimmer control is activated. You can quickly show then and process then in bash with websocat by typing for example:

❯  websocat ws://192.168.125.123/ws/pid/csv
pMode,dMode,icMode,rev,setpoint,kp,ki,kd,outMin,outMax,input,output,error,sum,pTerm,iTerm,dTerm
2,1,2,0,800,0.300,0.400,0.200,-10000,10000,780.645,1109.700,19.355,1104.889,7.217,7.742,4.811
2,1,2,0,800,0.300,0.400,0.200,-10000,10000,778.620,1114.453,21.380,1114.048,0.607,8.552,0.405
2,1,2,0,800,0.300,0.400,0.200,-10000,10000,774.128,1126.643,25.872,1125.745,1.347,10.349,0.898
2,1,2,0,800,0.300,0.400,0.200,-10000,10000,786.127,1125.294,13.873,1127.694,-3.600,5.549,-2.400
2,1,2,0,800,0.300,0.400,0.200,-10000,10000,804.696,1116.531,-4.696,1120.245,-5.571,-1.878,-3.714
2,1,2,0,800,0.300,0.400,0.200,-10000,10000,820.285,1104.337,-20.285,1107.455,-4.677,-8.114,-3.118
2,1,2,0,800,0.300,0.400,0.200,-10000,10000,822.300,1097.527,-22.300,1097.930,-0.605,-8.920,-0.403
2,1,2,0,800,0.300,0.400,0.200,-10000,10000,808.928,1101.045,-8.928,1098.370,4.012,-3.571,2.674
2,1,2,0,800,0.300,0.400,0.200,-10000,10000,798.264,1104.396,1.736,1102.264,3.199,0.694,2.133
2,1,2,0,800,0.300,0.400,0.200,-10000,10000,793.393,1107.342,6.607,1106.368,1.461,2.643,0.974
2,1,2,0,800,0.300,0.400,0.200,-10000,10000,785.225,1116.361,14.775,1114.728,2.450,5.910,1.634
2,1,2,0,800,0.300,0.400,0.200,-10000,10000,821.839,1087.686,-21.839,1095.008,-10.984,-8.736,-7.323

You can also stream this data directly to a command-line tool that will plot in real time the graphs. Example of such tools:

Demo

Here is a demo of the real-time PID tuning in action:

PID Tuning in YaSolR (Yet Another Solar Router)

Statistics section

This page shows a lot of statistics and information on the router.

Important Hardware Information

Bypass Relay

Installing a relay for bypass is optional: if installed, the relay will be used to power the heater, and the dimmer will be set to 0.

If not installed, when activating bypass mode, the dimmer will be used and set to 100%. The advantage is a simple setup, the drawbacks are:

In the Hardware section, Output 1 Relay (Bypass) and Output 2 Relay (Bypass) both specify if a relay is installed for the output, on top of the dimmer of course, and if it should be used when bypass is activated. If no relay is installed, the dimmer will be used and will be set to 100%.

In the Hardware Config section, Output 1 Relay Type (Bypass) and Output 2 Relay Type (Bypass) are used to specify the type of the relay: Normally Open or Normally Closed.

JSY (local)

The JSY is used to measure:

  1. the total routed power of the outputs combined (optional) with the channel 1 (tore or clamp depending on the model)
  2. the grid power and voltage with the clamp of channel 2

The JSY can be replaced by MQTT, reading the power and voltage from MQTT topics. See MQTT as a Grid Source.

JSY (remote)

JSY can also be replaced with a remote JSY without any impact on routing speed. You can install the Sender .ino file on a ESP32 and connect it to the JSY. This is a standalone application that looks looks like this and will show all your JSY data, help you manage it, and also send the data through UDP at a rate of 20 messages per second.

You can look in the JSY project to find more information about how to setup remote JSY and the supported protocols.

When using a remote JSY with the router, the following rules apply:

TIP

JSY Remote app is automatically detected on the same network: you don’t need to configure anything. As soon as the Sender app will start sending data, YaSolR will receive it and display it.

LEDs

The LEDs are used to notify the user of some events like reset, restarts, router ready, routing, etc.

LIGHTS SOUNDS STATES
🟢 🟡 🔴 BEEP BEEP STARTED + POWER + OFFLINE
🟢 🟡 ⚫   STARTED + POWER
🟢 ⚫ 🔴 BEEP BEEP STARTED + OFFLINE
🟢 ⚫ ⚫ BEEP STARTED
⚫ 🟡 🔴 BEEP BEEP BEEP RESET
⚫ 🟡 ⚫    
⚫ ⚫ 🔴 BEEP BEEP RESTART
⚫ ⚫ ⚫   OFF

Temperature Sensor

The temperature sensors are used to monitor the water tank in order:

Supported temperature sensor: DS18B20

A temperature sensor can also be used to monitor the router box itself (Overview section).

Virtual Grid Power / Compatibility with EV box

The router exposes through API and MQTT the Virtual Grid Power, which is the value of Grid Power you would have if the router was not routing.

You can use this value to inject in the EV box in order to prioritize EV charging over routing to the water tank.

This is usually acceptable to give the EV box a priority over the water tank, because the water tank only need a small amount of routed energy to start heating, while the EV usually requires a threshold to start charging. So the router will take whatever is not used by the EV box.

IMPORTANT

Virtual Grid Power requires a PZEM or JSY in place to measure the routed power.

Voltage Regulators (LSA, LCTC, etc)

Using voltage regulators such as LSA or LCTC is possible with the help of a conversion board like the one listed in the hardware page.

How it works:

  1. The conversion board will transform the 100Hz 3.3V dimmer PWM signal to an analog output, which is a voltage in the range 0-10V
  2. The LSA reads this voltage and based on its level it knows how much power he has to let go to the load

Calibration:

TIP

If you use the conversion board listed, you won’t need to calibrate: it works out of the box.

  1. Use the Dimmer Range Remapping feature to remap the dimmer range if needed to increase the base voltage or decrease the duty cycle
  2. Eventually calibrate the conversion board (potentiometer) as described in the manual of the conversion board
  3. Adjust the input voltage of the conversion board (HDR-15-12 potentiometer)

Oscilloscope views:

Here is what happens when you change the dimmer slider at 10%, 50% and 50%:

10% 50% 90%

We can see that updating the slider in YasolR will change the current going out from the LSA to the load, and the lines are close enough so that the PID algorithm of the router will be able to still work properly.

This could even be tweaked further: ideally, the pink line should match the blue line.

Here, the pink line triggers AFTER the blue line at 10%, which means that the voltage going to the LSA input is not high enough when teh duty cycle is low. The pink line triggers BEFORE the blue line at 90%, which means that the voltage going to the LSA input is too high when the duty cycle in YaSolR is at 90%.

Note: using the Dimmer Range Remapping feature won’t fix that: this is a calibration that has to be done on conversion board and or by adjusting the HDR-15-12 voltage.

Zero-Cross Detection

The Zero-Cross Detection (ZCD) module is used to detect the zero-crossing of the grid voltage. It is required, whether you use a Robodyn or SSR or any routing algorithm (phase control or burst mode).

When activating Zero-Cross Detection in the hardware page, YaSolR will first start a pulse analyzer to grab some statistics about the pulse characteristics: period and length. This characteristics are used to fine-tune the TRIAC firing and they can be viewed in the dashboard, in the statistics section:

Once the pulse analysis if finished (it should last around 1 second), the ZCD module will be activated and the router will start routing.

Note that if the electricity is not available when YaSolR starts, the pulse analyser will wait until the electricity is back to start the pulse analysis and then activate the ZCD module.

TIP

The Robodyn includes a ZCD (its ZC pin). Do not forget to activate the ZCD module in the Hardware section.

IMPORTANT

Robodyn has a very bad ZCD circuit. I strongly suggest you use a dedicated ZCD module instead. Please have a look at these blog articles on YaSolR website for more information:

Help and support