updates

.gitignore

@@ -3,10 +3,10 @@
 
 ### VisualStudioCode
 .vscode/*
-!.vscode/settings.json
-!.vscode/tasks.json
-!.vscode/launch.json
-!.vscode/extensions.json
+# !.vscode/settings.json
+# !.vscode/tasks.json
+# !.vscode/launch.json
+# !.vscode/extensions.json
 
 .history
 site/

docs/Configuring.md

@@ -42,7 +42,7 @@ This next section describes some of key application settings that can be configu
 - **Enable Analog Sensors**. This enables any GPIO to collect signals, whether it's a digital I/O, a pulse counter or ADC measuring mv.
 - **Convert temperature values to Fahrenheit**. For our US friends.
 - **Bypass Access Token authorization on API calls**. For RESTful write commands via HTTP POST the access token is required. This is for security reasons to prevent anyone changing device settings. Setting this flag makes the API open. Not recommended!
-- **Enable Read only mode**. This disables any outgoing Tx write commands to the EMS bus, essentially putting EMS-ESP into listening mode.
+- **Enable Read only mode**. This disables any outgoing Tx write commands to the EMS bus, essentially putting EMS-ESP into listening mode. However Tx is needed to detect EMS devices (as it sends out a Version command). If you want to explicitly put EMS-ESP into a read-only/sniffer mode use `set tx_mode 0` from the console.
 - **Underclock CPU speed**. Under-clocks the ESP to 160Mhz, saving on power, heat and prolonging the lifespan of the chip at the cost of performance and response time. A reboot of EMS-ESP is required.
 - **Enable Shower Timer**. Enable to time how long the hot water runs for and it will send out an MQTT message with the duration. The timer starts after a minimal of 2 minutes running time.
 - **Enable Shower Alert**. This is somewhat experimental and may not work on all boilers. After 7 minutes (configurable) running the hot water it will send out a warning by sending cold water for 10 seconds (also configurable). The boiler goes into test mode to perform this operation so use with caution!
@@ -128,6 +128,14 @@ Limits:
 - PWM: `max frequency 5000Hz, resolution 13bits``
 - Counter/timer/rate trigger: `high->low edge with 15 ms debounce. Only for low pulse rates.`
 
+### Controlling Relay's
+
+A common use case is to control a relay to switch on/off a device. This can be done by adding a digital output sensor and then creating a command to control it. The command can be added to the dashboard and scheduled to turn on/off at specific times.
+
+Create an Analog Sensor with type 'Digital Out'.
+
+The professional way is to use a separate relay board with opto-isolation and a flyback diode. The relay board is then powered by a separate power supply and the relay is connected to the digital output of the EMS-ESP as described above. The relay board is then connected to the device you want to control. This way the device is completely isolated from the EMS-ESP and the relay board can handle the higher voltage and current.
+
 ## Customizing Entities
 
 The Customization page shows all registered entities and allows to exclude commands and values from publishing via mqtt/api or remove them from dashboard. The dashboard only shows entities with values, the customization page shows all. If an entity has no value then it is supported by EMS-ESP, but not by your boiler/thermostat/etc.
@@ -142,6 +150,6 @@ Use the scheduler to call commands at specific intervals. This is useful for exa
 
 ## Creating Custom Entities
 
-If you know where specific data is hiding in a telegram you can sniff them out and create a custom entity. This is useful way to test for new values before we can extend officially in the firmware.
+Custom Entities is an advanced and powerful way to extend EMS-ESP by adding your own EMS entities that extracts data from a specific EMS telegram. This is useful when EMS-ESP doesn't yet support a specific entity, or when you want to extract data from a telegram that is not yet supported. Another common use case is for debugging or watching specific behaviour when changing parameters on an EMS device. For example, a modern Heat Pump may have new features that are not included in EMS-ESP. Here you would use the `watch` command to view the incoming EMS traffic in combination with manual adjusting specific parameters and when you have located the specific telegram and the offset, create a Custom Entity to fine-tune the type and verify the the value. Then request it to be included in the next EMS-ESP release update.
 
 ![Web](_media/screenshot/web_customentities.png)

docs/Troubleshooting.md

@@ -6,6 +6,8 @@ Below are answers to some common problems.
 
 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.
@@ -50,7 +52,7 @@ If EMS-ESP becomes unresponsive, as in it appears to be active and hasn't restar
 - description of your network (which vendor, WiFi or Ethernet, etc)
 - any anomalies in the network (servers down, Access point roaming, channel switching etc)
 
-## EMS data and bus connectivity
+## EMS Data and Connectivity
 
 ### Not all EMS devices are recognized
 
@@ -88,8 +90,7 @@ If you're using the EMS wires, on some systems the order is important. Try switc
 
 A BBQKees Gateway is DCE, and the ESP32s are DTE so you have to connect TX(esp)-TX(gateway) and RX-RX. TX on the ESP32 is sending data, TX on gateway is the input for sending data to the ems-bus. Note a crossed (nullmodem) connection is only used for DTE-DTE connections.
 
-The most common wiring mistake though is that when people connect the interface board to an ESP32 module, they connect it to the pins marked TX and RX on the ESP32 module.
-But these are for the USB chip, not for the interface board.
+The most common wiring mistake though is that when people connect the interface board to an ESP32 module, they connect it to the pins marked TX and RX on the ESP32 module. If you're unsure of which pins to use, go to EMS-ESP Settings, select the Interface Board Profile for your board and select 'Custom' to view the default assigned GPIOs.
 
 ### Changing a value on an EMS Device doesn't work
 
@@ -194,3 +195,19 @@ See @swa72's fix [here](https://github.com/swa72/home-assistant/blob/main/README
 ### HA has messed up the names of my entities
 
 This happens, when HA make changes to MQTT Discovery. There's a nice tool called [homeassistant-entity-renamer](https://github.com/saladpanda/homeassistant-entity-renamer) that can help you fix this.
+
+## Specific EMS settings
+
+### Thermostat Date/Time
+
+The correct format for setting the Thermostat time is:
+
+```
+< NTP | dd.mm.yyyy-hh:mm:ss-day(0-6)-dst(0/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.