YaSolR Manual

Quick Start

When everything is wired and installed properly, you can:

  1. Flash the downloaded firmware (see Initial Firmware 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!

Initial Firmware 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

Flash with esptool.py (Linux / MacOS):

# Erase the memory (including the user data)
esptool.py \
  --port /dev/ttyUSB0 \
  erase_flash

# Flash initial firmware and partitions
esptool.py \
  --port /dev/ttyUSB0 \
  --chip esp32 \
  --before default_reset \
  --after hard_reset \
  write_flash \
  --flash_mode dout \
  --flash_freq 40m \
  --flash_size detect \
  0x0 YaSolR-VERSION-MODEL-CHIP.FACTORY.bin

Do not forget to change the port /dev/ttyUSB0 to the one matching your system. For example on Mac, it is often /dev/cu.usbserial-0001 instead of /dev/ttyUSB0.

With Espressif Flash Tool (Windows):

IMPORTANT

Be careful to not forget the 0

Espressif Flash Tool

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

/update page

Go to the Web OTA at http://<esp-ip>/update to update the firmware over the air:

The firmware file which must be used is the one ending with .OTA.bin:

YaSolR-<VERSION>-<MODEL>-<BOARD>.OTA.bin

Overview section

The overview section shows some global information about the router:

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

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 (tri-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 tri-phase resistance, 3% means 30W per relay because there is 3x 1000W resistances. For a 2100W tri-phase resistance, 3% means 21W per relay because there is 3x 700W resistances.

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

Time settings:

WiFi settings:

The ESP32 must be restarted to apply the changes.

MQTT section

IMPORTANT

MQTT must be restarted to apply the changes.

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

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 is especially useful when using a module converting the PWM signal to an analog voltage range between 0-10V for a voltage regulator. But voltage regulators like LSA do work on a voltage range which is closer to 1-8V, 1 being 0% on the voltage regulator and 8V matching 100%.

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%.

TIP

If you use a voltage regulator with a conversion module, you will need to do some testing to find the best range. A good start is to find the triggering voltage of the voltage regulator (usually around 1V) and the maximum voltage (usually around 8V) which matches 100%. This is usually written in the specifications of the voltage regulator. Then remap the dimmer ranges to match these values like the example above.

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:

Relays

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 a few seconds. You can at the same time check the statistics on the Output or Overview sections. 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.

TIP

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

IMPORTANT

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

Default Settings

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

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-MK-194T (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-MK-194T (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.

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

TIP

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

You can also use a dedicated ZCD module like the one suggested on this website (build menu).

IMPORTANT

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

Help and support