Update install.md

2024-01-05 02:16:03 +01:00
parent 4416605d85
commit d3388f2f01
1 changed files with 72 additions and 73 deletions
--- a/docs/install.md
+++ b/docs/install.md
@@ -11,7 +11,7 @@ Whether you're a first-time smart device user or an enthusiast looking to person

 - [Preparation](#preparation)
 - [ESPHome firmware](#esphome-firmware)
-  - [Preparing the ESPHome environment](#preparing-the-esphome-environment)
+  - [Preparing the ESPHome Environment](#preparing-the-esphome-environment)
  - [Setup a device on ESPHome Dashboard](#setup-a-device-on-esphome-dashboard)
  - [Flashing the device for the first time](#flashing-the-device-for-the-first-time)
  - [Integrating your panel to Home Assistant](#integrating-your-panel-to-home-assistant)
@@ -37,127 +37,123 @@ Start by ensuring you have all the necessary tools and files. This includes your

 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
+## ESPHome Firmware

-### 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.
+### Preparing the ESPHome Environment

- 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)
+To flash your NSPanel, ESPHome firmware is required. ESPHome can be integrated into your setup in various ways, including as a Home Assistant add-on or through a local installation on your computer. This guide is based on using the ESPHome dashboard, which is available in all standard implementations.

-### 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):<br>
-![image](pics/ha_esphome_dashboard_new_device_05b.png)<br>&nbsp;
+- **Installing ESPHome as a Home Assistant Add-On**: For seamless integration with Home Assistant, ESPHome can be installed as an add-on. This method provides an easy-to-navigate interface and direct integration with your Home Assistant setup. For detailed instructions on this installation method, refer to [Getting Started with ESPHome and Home Assistant](https://esphome.io/guides/getting_started_hassio).

-8. Clear all the content and paste the following:
+- **Manual Installation of ESPHome**: A manual installation on your computer might be preferred if your Home Assistant's host is resource-limited and struggles with compiling ESPHome projects. Standalone installations on a normal computer typically offer faster and more efficient compiling. This method is ideal if you're working with a system that doesn't support Home Assistant add-ons or if you prefer a separate management environment for your ESPHome devices. Detailed steps for a manual installation can be found in the guide [Installing ESPHome Manually](https://esphome.io/guides/installing_esphome.html).
+
+### Setting Up a Device on ESPHome Dashboard
+
+Follow these steps to add a new device in the ESPHome Dashboard:
+1. Click the **+ New Device** button.
+2. Enter a unique name for your new ESPHome device.  
+   ![New Device Name](pics/ha_esphome_dashboard_new_device_01.png)
+3. Select **ESP32** as the device type.  
+   ![Select ESP32](pics/ha_esphome_dashboard_new_device_02.png)
+4. Click **Skip** as we're not starting the installation yet.  
+   ![Skip Installation](pics/ha_esphome_dashboard_new_device_03.png)
+5. Locate your newly created device in the ESPHome Dashboard and click **Edit**.  
+   ![Edit Device](pics/ha_esphome_dashboard_new_device_04.png)
+6. (Optional) For enhanced security, consider copying the `api:` section to a temporary file.  
+   ![API Section](pics/ha_esphome_dashboard_new_device_05.png)
+7. Note the device name at the beginning of the file under `esphome`.  
+   ![Device Name](pics/ha_esphome_dashboard_new_device_05b.png)
+
+8. Clear all existing content and paste the following YAML configuration:
    ```yaml
    substitutions:
-      ###### Settings - You can edit these values ######
+      # Settings - Editable 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"
+      # Add-on configuration (if needed)
+      # heater_relay: "1" # possible values: 1/2

-      ##### addon-configuration #####
-      # heater_relay: "1" # possible values: 1/2 - Used by add-on climate
-
-      ###### Settings - End #####
-
+    # Customization area
    ##### My customization - Start #####
    ##### My customization - End #####

-    ###### Do not change area - Start ######
+    # Core and optional configurations
    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
+          # Optional advanced and add-on configurations
+          # - advanced/esphome/nspanel_esphome_advanced.yaml
+          # - nspanel_esphome_addon_climate_cool.yaml
+          # - nspanel_esphome_addon_climate_heat.yaml
+          # - nspanel_esphome_addon_climate_dual.yaml
        refresh: 300s

    esp32:
      framework:
        type: esp-idf
-    ###### Do not change area - End ######
-
    ```
-![image](pics/ha_esphome_dashboard_new_device_06.png)<br>&nbsp;
+   ![YAML Code](pics/ha_esphome_dashboard_new_device_06.png)

-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;
+9. Modify the **Settings** section with your device name (as noted in step 7) and Wi-Fi details.  
+   ![Edit Settings](pics/ha_esphome_dashboard_new_device_06b.png)

-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)
+10. For Wi-Fi credentials, use `!secret` for added security or input them directly. Learn about secrets in ESPHome: [Home Assistant 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.
+11. Optionally, adjust `nextion_update_url` to the URL of a TFT file hosted on an HTTP or HTTPS server, ensuring that the file is accessible to the NSPanel. This URL will be used by ESPHome to download the TFT file to your panel. For more information on hosting the TFT file and setting up the URL, see the [Upload TFT](#upload-tft) section.

-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;
+12. (Optional) Enhance security with API encryption by adding the copied key from step 6 to the **My Customization** area.

-13. When all settings are correct, click the button **Save** in the top and close this yaml window.
+13. After finalizing settings, click **Save** and close the YAML window.

-Done! Your NSPanel is all set into your ESPHome Dashbord.
+Your NSPanel is now configured in your ESPHome Dashboard.

-### Flashing the device for the first time
+### Flashing the Device for the First Time

-#### Drive safe
+#### Drive Safe

-> [!CAUTION]
-> **Make sure your panel's controller module is disconnected from main power during all the work.**<br>
->If your device is open and plugged directly into the wall, you’ll be a single touch away from being electrocuted.
+> :warning: **WARNING**  
+> **Disconnect your panel's controller module from main power during all work.**  
+> Operating on an open device that's plugged into the wall puts you at risk of electrocution.

-> [!WARNING]  
-> **You are solely responsible for your own safety.**<br>
-> If you feel something is wrong or are uncomfortable with continuing, stop immediately.
+> :warning: **CAUTION**  
+> **You are solely responsible for your own safety.**  
+> If you're uncomfortable or if something feels wrong, 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.
+- Use only electronic components rated for 3.3VDC. Ensure your TTL adapter is set to 3.3VDC. Exceeding this voltage can cause permanent damage to your panel.
+- Maintain a clean work area to prevent damage to your device, especially the screen.
+- Keep all small parts, like screws and cables, safely stored.

-#### Required Tools:
-If you are going to flash your NSPanel with ESPHome for the first time you also may need:
+#### Required Tools
+For first-time flashing of your NSPanel with ESPHome, you 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)
+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. Appropriate screwdriver to disassemble 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:
+#### Connecting Your Device via USB-to-Serial TTL Interface
+Before disassembling your panel, review the following resources:
 - [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)
+- [ESPHome - Physically Connecting to Your Device](https://esphome.io/guides/physical_device_connection)

-<<add pictures of the board & wiring>>
-<<add step by step how to generate firmware on ESPHome Dashboard>>
-<<add step by step how to flash the firmware using serial TTL>>
+
+##### Pending: (Pictures of the board & wiring will be added here)
+##### Pending: (Steps to generate firmware on ESPHome Dashboard will be added here)
+##### Pending: (Steps to flash the firmware using serial TTL will be added here)

 ### Integrating your panel to Home Assistant

 ### Making changes Over The Air (OTA)
-<< add instructions how to flash wirelessly>>
+##### Pending: (add instructions how to flash wirelessly)

 ### Updating
-<< add instructions how to flash wirelessly>>
-<< considerations - update all to the same version >>
+##### Pending: (add instructions how to flash wirelessly)
+##### Pending: (considerations - update all to the same version)

 ### Migrating from other custom firmware
 The installation in a NSPanel with Sonoff's original firmware should be straighforward, however, if you have installed some other custom firmware before, you may have additional steps to execute.
@@ -169,8 +165,11 @@ If you have already installed on your NSPanel the "nspanel-lovelace-ui" firmware
 Please try the standard process and if you find any issue, please [create a new issue](/Blackymas/NSPanel_HA_Blueprint/issues) and inform which custom firmware you have installed before migrating to NSPanel HA Blueprint.

 ## Upload TFT
+##### Pending: 
 ### Select the right file
+##### Pending: 
 ### Uploading to Nextion
+##### Pending: 
 ### Troubleshooting TFT transfer issues
 We have an useful guide for [troubleshooting TFT transfer issues](tft_upload.md). Please take a look there.