Update installation instructions

This still draft

docs/install.md

@@ -3,20 +3,118 @@ Welcome to this setup guide, a community-driven approach to integrating NSPanel
 
 Whether you're a first-time smart device user or an enthusiast looking to personalize your setup, this guide provides the necessary tools and instructions. Let's embark on creating a smart home that's uniquely yours.
 
+#### Attention
+Some images or instructions on this guide might be slighly different due to different configurations depending on your ESPHome and Home Assistant implementation or versions.<br>
+If you find something that is not understandable or needs to be updated, please let us know. You can create an issue reporting this, or fix it yourself and submit a Pull Request to this repository.
+
 ## Preparation
-Start by ensuring you have all the necessary tools and files. This includes your NSPanel device, a stable internet connection, and access to your Home Assistant server.
+Start by ensuring you have all the necessary tools and files. This includes your NSPanel device, a stable internet connection, and access to your Home Assistant instance.
+
+If flashing it for the first time, please look for additional preparation and tools on the [Flashing the device for the first time](#flashing-the-device-for-the-first-time) section later in this guide.
 
 ## ESPHome firmware
-### Setup a device on ESPHome dashboard
-![image](pics/ha_esphome_dashboard_new_device_01.png)
-![image](pics/ha_esphome_dashboard_new_device_02.png)
-![image](pics/ha_esphome_dashboard_new_device_03.png)
-![image](pics/ha_esphome_dashboard_new_device_04.png)
-![image](pics/ha_esphome_dashboard_new_device_05.png)
-![image](pics/ha_esphome_dashboard_new_device_06.png)
-![image](pics/ha_esphome_dashboard_new_device_07.png)
+
+### Preparing the ESPHome environment
+In order to flash your NSPanel, you need a firmware generated by ESPHome. You can use ESPHome as an add-on in your Home Assistant, installed locally in your computer or any other type of installation. This guide will be based on the ESPHome dashboard which is available in all implementations.
+
+- For more information on how to install ESPHome as an add-on to your Home Assistant, please refer to this external guide: [Getting Started with ESPHome and Home Assistant](https://esphome.io/guides/getting_started_hassio)
+- For more information on how to install ESPHome manually in your computer, please refer to this external guide: [Installing ESPHome Manually](https://esphome.io/guides/installing_esphome.html)
+
+### Setup a device on ESPHome Dashboard
+Once you have the ESPHome Dashboard available, please follow the steps bellow:
+1. Click the button **+ New device**
+2. Add the unique name of your new device in ESPHome:<br>
+![image](pics/ha_esphome_dashboard_new_device_01.png)<br>&nbsp;
+3. Select **ESP32** as device type:<br>
+![image](pics/ha_esphome_dashboard_new_device_02.png)<br>&nbsp;
+4. Click **Skip** button, as we don't want to start the installation yet:<br>
+![image](pics/ha_esphome_dashboard_new_device_03.png)<br>&nbsp;
+5. Find the entry related to your newly created device in the ESPHome Dashboard and click the button **Edit**.
+![image](pics/ha_esphome_dashboard_new_device_04.png)<br>&nbsp;
+6. In the yaml dialog, you might want to copy the `api:` area to another temporary file, just in case. That is not really necessary, but can be used to improve the security in your system (more details later).
+![image](pics/ha_esphome_dashboard_new_device_05.png)<br>&nbsp;
+7. Take note also of the device name in the beginning of the file. Under `esphome`, it is the value for `name` (in this examble, the device name is `my-new-nspanel`, with dashes between the words):
+![image](pics/ha_esphome_dashboard_new_device_05b.png)<br>&nbsp;
+
+8. Clear all the content and paste the following:
+    ```yaml
+    substitutions:
+      ###### Settings - You can edit these values ######
+      device_name: "YOUR_NSPANEL_NAME" 
+      wifi_ssid: !secret wifi_ssid
+      wifi_password: !secret wifi_password
+
+      nextion_update_url: "http://homeassistant.local:8123/local/nspanel_eu.tft"
+
+      ##### addon-configuration #####
+      # heater_relay: "1" # possible values: 1/2 - Used by add-on climate
+
+      ###### Settings - End #####
+
+    ##### My customization - Start #####
+    ##### My customization - End #####
+
+    ###### Do not change area - Start ######
+    packages:
+      remote_package:
+        url: https://github.com/Blackymas/NSPanel_HA_Blueprint
+        ref: main
+        files:
+          - nspanel_esphome.yaml # Core package
+          # - advanced/esphome/nspanel_esphome_advanced.yaml # activate advanced (legacy) elements - can be useful for troubleshooting
+          # - nspanel_esphome_addon_climate_cool.yaml # activate for local climate (cooling) control
+          # - nspanel_esphome_addon_climate_heat.yaml # activate for local climate (heater) control
+          # - nspanel_esphome_addon_climate_dual.yaml # activate for local climate (dual) control
+        refresh: 300s
+
+    esp32:
+      framework:
+        type: esp-idf
+    ###### Do not change area - End ######
+
+    ```
+![image](pics/ha_esphome_dashboard_new_device_06.png)<br>&nbsp;
+
+9. Edit the **Settings** area. As your device name, ideally use the same device name you recorder on the step 7:
+![image](pics/ha_esphome_dashboard_new_device_06b.png)<br>&nbsp;
+
+10. For `wifi_ssid` and `wifi_password` you can either replace the existing text by your Wi-Fi credentials or, if you want to keep that information a bit safer (and make easier to share your setting later to help someone or to ask for help), you can leave as it is and edit this later by clicking on the button **Secrets** in the top right area of the ESPHome Dashboard.<br>
+This is a quite objective video about secrets if you want to see how it works: [YouTube - 3ATIVE VFX Studio - Home Assistant guide: How I use Secrets in ESPHome]( https://www.youtube.com/watch?v=eW4vKDeHh7Y)
+
+11. You can also edit `nextion_update_url` to point to a local copy of the TFT file.<br>
+We will come back to this on the [Upload TFT](#upload-tft) section, but it is important to know that you have this option which could be useful if your panel don't have access to the Internet or if you have trouble when uploading the TFT file directly from the GitHub repository.
+
+12. (optional) You can optionally enable API encryption by adding the key copied on step 6 and adding it to the **My customization** area. This will encrypt the communication between your panel and Home Assistant, which may be important if you will use your panel to transfer sensitive information, like a pin code when disabling an alarm.<br>
+This can be set later, if you want to skip it for now.<br>
+![image](pics/ha_esphome_dashboard_new_device_07.png)<br>&nbsp;
+
+13. When all settings are correct, click the button **Save** in the top and close this yaml window.
+
+Done! Your NSPanel is all set into your ESPHome Dashbord.
 
 ### Flashing the device for the first time
+
+#### :exclamation: **Warning!!** 
+- **Make sure your panel's controller module is disconnected from main power during all the work.** If your device is open and plugged directly into the wall, you’ll be a single touch away from being electrocuted.
+- **You are solely responsible for your own safety.** If you feel something is wrong or are uncomfortable with continuing, stop immediately. |
+  
+- Don't use any eletronic component above 3.3VDC. Make sure you TTL adapter is set to 3.3VDC. Any value above this treshold can permanently damage your panel.
+- Use a clean area when disassembling your device and make sure you don't scratch your device's screen.
+- Keep all the parts (screws, cables, etc.) safe.
+
+#### Tools:
+If you are going to flash your NSPanel with ESPHome for the first time you also may need:
+1. [USB-to-Serial TTL adapter](https://esphome.io/guides/physical_device_connection#usb-serial-adapter)
+2. [jumper wires](https://esphome.io/guides/physical_device_connection#jumper-wires)
+3. [breakable headers (optional)](https://esphome.io/guides/physical_device_connection#pcb-headers)
+4. An appropriated screw driver for unassembling your panel's controller module (touch plate)
+
+#### Connecting your device via USB-to-Serial TTL interface
+Before start unassembling your panel, please take a look at the following material:
+- [YouTube - Mark Watt Tech - HOW TO - Setup the SIMPLEST Smart Home Scene Controller](https://www.youtube.com/watch?v=jpSTA_ILB8g&t=323s)
+- @blakadder's [Sonoff NSPanel EU Switch in Detail](https://blakadder.com/nspanel-teardown/)
+- [ESPHome - Physically Connecting to your Device](https://esphome.io/guides/physical_device_connection)
+
 ### Making changes Over The Air (OTA)
 ### Updating
 ### Migrating from other custom firmware