Merge pull request #705 from Dasharo/wessel-documentation-update

novacustom: documentation improvements for 1.5.2/1.7.2

Author: macpijan

docs/dasharo-tools-suite/overview.md

@@ -21,5 +21,5 @@ on [Dasharo
 issues](https://github.com/Dasharo/dasharo-issues/issues?q=is%3Aopen+is%3Aissue+label%3ADasharoToolsSuite).
 
 And if you have already used this system and would be interested in supporting
-the project, please check [How to support us?](../osf-trivia-list/dts.md#how-to-support-us)
-section.
+the project, please check the
+[How to support us?](../osf-trivia-list/dts.md#how-to-support-us) section.

docs/images/NV40-front-1.png

@@ -2,7 +2,7 @@
 
 There are two fan profiles implemented. The profiles can be selected via the
 [Power Management Options](/dasharo-menu-docs/dasharo-system-features/#power-management-options)
-menu in Setup Menu.
+menu in the Setup Menu.
 
 Fan profiles are defined as follows:
 

docs/unified/novacustom/fan-profiles.md

@@ -2,44 +2,92 @@
 
 The following documentation describes the process of Dasharo open-source
 firmware update. The update process may be different, depending on which
-firmware version is currently installed on your device. The currently installed
-firmware version can be checked with the following command in a Linux
-environment:
+firmware version is currently installed on your device.
+
+You can check your current firmware version with the following Linux command.
 
 ```bash
 sudo dmidecode -t bios | grep Version
 ```
 
-Alternatively, it can be checked in the `BIOS Setup Menu`.
+Alternatively, it can be checked in the
+[Dasharo Setup Menu](/dasharo-menu-docs/overview/#dasharo-menu-guides)
+when booting the device.
 
 ## Prerequisites
 
-Depending on firmware version (1) there may be manual steps required to ensure
-that the firmware can be updated.
-{ .annotate }
+First, determine your device version with the following Linux command.
+
+```bash
+sudo dmidecode -t system | grep "Product Name"
+```
+
+Alternatively, it can be checked in the
+[Dasharo Setup Menu](/dasharo-menu-docs/overview/#dasharo-menu-guides)
+as well.
+
+Note the `Device name` based on the previous output and the following table.
+
+| Product Name output |  Device name      |
+|---------------------|-------------------|
+| NV4XMB,ME,MZ        | NV4x 11th Gen     |
+| NS50_70MU           | NS5x/7x 11th Gen  |
+| NV41PZ              | NV4x 12th Gen     |
+| NS50_70PU           | NS5x/7x 12th Gen  |
+
+Depending on the firmware version, there may be manual steps required to ensure
+that the firmware can be updated. `11th Gen` devices starting from version v1.5.0
+and `12th Gen` devices starting from version v1.7.0 have support for [Firmware
+Update Mode](#firmware-update-mode). For older versions, please continue with
+the [Updating older versions](#updating-older-versions) section.
 
-1. v1.5.0 for TGL-U models and v1.7.0 for ADL-P introduced support for Firmware
-   Update Mode
+> Advanced users can also [build](./building-manual.md) and/or flash the
+> binaries themselves by following the steps under the [Manual
+> update](#manual-update) section.
 
 ### Firmware Update Mode
 
 If the currently installed Dasharo version supports Firmware Update Mode, follow
-the steps outlined in
-[generic Firmware Update documentation](../../guides/firmware-update.md#firmware-update-mode).
+the steps outlined in the [generic Firmware Update documentation](../../guides/firmware-update.md#firmware-update-mode).
 
-### Manual
+Check out our [YouTube video](https://www.youtube.com/watch?v=muWjhrQ7bQk)
+for a demonstration of Firmware Update Mode.
 
-Ensure that the firmware protections are disabled in
+### Updating older versions
+
+1. First, ensure that [UEFI Secure Boot](../../dasharo-tools-suite/documentation.md#disabling-secure-boot)
+   has been disabled.
+
+1. Boot to the [Dasharo Tools Suite](../../dasharo-tools-suite/documentation.md#bootable-over-a-network).
+   We recommend the network boot option.
+
+1. In the main menu of Dasharo Tools Suite, select option `5` to proceed with
+   the installation of the firmware update.
+
+1. In case you want to know more about the firmware update option in Dasharo
+   Tools Suite, please check out the
+   [features section](../../dasharo-tools-suite/documentation.md#firmware-update)
+   of the dedicated Dasharo Tools Suite documentation page.
+
+### Manual update
+
+This update method is for advanced users only and is not recommended for
+regular end users.
+
+Ensure that the firmware protections are disabled (1) in
 [Dasharo Security Options](../../dasharo-menu-docs/dasharo-system-features.md).
 Both `BIOS boot medium lock` and `Enable SMM BIOS write protection` should
 be unchecked. [UEFI Secure Boot](../../dasharo-menu-docs/device-manager.md#secure-boot-configuration)
 must be disabled as well (uncheck `Attempt Secure Boot` if
-`Current Secure Boot State` does not say `Disabled`). To apply changes you
+`Current Secure Boot State` does not say `Disabled`). To apply changes, you
 will need to reboot.
+{ .annotate }
 
-### Update using Dasharo Tools Suite
+1. These options were introduced in v1.5.0 for TGL models and v1.7.0 for ADL
+   models. You can skip these steps if you are using an older firmware version.
 
-* Boot into
-  [Dasharo Tools Suite](/dasharo-tools-suite/documentation/#running)
+* Follow the manual update procedure described in the [DTS firmware update
+  documentation](https://docs.dasharo.com/dasharo-tools-suite/documentation/#local-firmware-update).
 
-* Follow the procedure described in [DTS firmware update documentation](https://docs.dasharo.com/dasharo-tools-suite/documentation/#firmware-update)
+> Please make sure you that you update the BIOS firmware and the EC firmware
+> respectively.

docs/unified/novacustom/firmware-update.md

@@ -3,6 +3,12 @@
 This document describes the process of installing firmware updates from LVFS
 using fwupd.
 
+> Warning: this documentation is
+> [temporarily depreciated](https://github.com/Dasharo/dasharo-issues/issues/96#issuecomment-1807920611).
+> Since the use of open EC firmware, we can no longer offer fwupd/LVFS support.
+> Currently, updating is only possible by following the
+[firmware update guide](./firmware-update.md).
+
 ## Installing fwupd
 
 ### Using binary packages

docs/unified/novacustom/fwupd-usage.md

@@ -4,7 +4,7 @@
 
 This document is a guide for the initial installation of Dasharo on a supported
 device. It assumes some knowledge about external flashing and is primarily aimed
-at technicians performing initial installation and not for end users of the
+at technicians performing the initial installation and not for end users of the
 devices.
 
 ## Installing Dasharo
@@ -18,8 +18,8 @@ devices.
     from within the operating system and external flashing of the whole flash
     chip using a programmer like the CH341a is required.
 
-    > Publicly released binaries do not contain ME binary. If you need an Intel ME
-    > update for your device, contact us via already established commercial support
+    > Publicly released binaries do not contain the ME binary. If you need an Intel ME
+    > update for your device, contact us via an already established commercial support
     > channel.
 
     ### Preparation
@@ -44,29 +44,29 @@ devices.
         === "NV4x"
             ![nv4x chips](../../images/nv4x_board_chips.jpg)
 
-    1. Disconnect the primary battery. (1)
-    1. Disconnect the CMOS battery. (2)
-    1. Attach a WSON-8 probe to the SPI flash chip. (3)
+    2. Disconnect the primary battery. (1)
+    3. Disconnect the CMOS battery. (2)
+    4. Attach a WSON-8 probe to the SPI flash chip. (3)
 
         > For TGL devices use SOIC clip instead of WSON
 
-    1. Backup the current firmware, in case you want to be able to restore it
+    5. Backup the current firmware, in case you want to be able to restore it
         at some point:
 
         ```bash
         flashrom -p ch341a_spi -r bios_backup.rom
         ```
 
-    1. Install Dasharo BIOS, replacing `[path]` with the path to the firmware
+    6. Install Dasharo BIOS, replacing `[path]` with the path to the firmware
         image you want to flash, e.g. `novacustom_ns5x_adl_full_v1.4.0.rom`
 
         ```bash
         flashrom -p ch341a_spi -w [path]
         ```
 
-    1. Detach the WSON-8 probe.
-    1. Connect the primary battery and reconnect the CMOS battery
-    1. Power on the laptop. The laptop may shut down once after training the memory.
+    7. Detach the WSON-8 probe.
+    8. Connect the primary battery and reconnect the CMOS battery.
+    9. Power on the laptop. The laptop may shut down once after training the memory.
 
     ### EC firmware installation
 
@@ -83,21 +83,21 @@ devices.
         apt install git build-essential debhelper pkg-config libpci-dev libusb-1.0-0-dev libftdi1-dev meson
         ```
 
-    1. Obtain source code:
+    2. Obtain source code:
 
         ```bash
         git clone https://github.com/dasharo/flashrom.git
         cd flashrom
         ```
 
-    1. Build flashrom:
+    3. Build flashrom:
 
         ```bash
         make
         sudo make install
         ```
 
-    1. Make a backup of the EC firmware:
+    4. Make a backup of the EC firmware:
 
         > Remember to store the backup on the separate device in case flashing
         > fails.
@@ -106,7 +106,7 @@ devices.
         flashrom -p ite_ec -r ec_backup.rom
         ```
 
-    1. Install the EC firmware:
+    5. Install the EC firmware:
 
         > Warning: After running this command, the internal keyboard and power
         > button will stop responding until the device is power cycled (all
@@ -129,24 +129,24 @@ devices.
 
 === "11th Gen (Tiger Lake)"
 
-### Initial deployment
+    ### Initial deployment
 
-To ensure a smooth deployment process, it is recommended to use the latest
-version of DTS available from the [releases
-page](../../dasharo-tools-suite/releases.md). Once you have obtained it, you can
-then proceed with following the [Dasharo zero-touch initial deployment
-section](../../dasharo-tools-suite/documentation.md#dasharo-zero-touch-initial-deployment)
-procedure. This will help you set up Dasharo effectively and without manual
-intervention.
+    To ensure a smooth deployment process, it is recommended to use the latest
+    version of DTS available from the [releases
+    page](../../dasharo-tools-suite/releases.md). Once you have obtained it, you can
+    then proceed with following the [Dasharo zero-touch initial deployment
+    section](../../dasharo-tools-suite/documentation.md#dasharo-zero-touch-initial-deployment)
+    procedure. This will help you set up Dasharo effectively and without manual
+    intervention.
 
-If something went wrong or EC installation was not done, the firmware will
-print an error string during boot:
+    If something went wrong or EC installation was not done, the firmware will
+    print an error string during boot:
 
-![](/images/menus/sol_error1.jpg){ class="center" }
+    ![](/images/menus/sol_error1.jpg){ class="center" }
 
-OR
+    OR
 
-![](/images/menus/sol_error2.jpg){ class="center" }
+    ![](/images/menus/sol_error2.jpg){ class="center" }
 
-In such case please follow the EC firmware update instructions for a specific
-board variant.
+    In such case please follow the EC firmware update instructions for a specific
+    board variant.

docs/unified/novacustom/initial-deployment.md

@@ -6,35 +6,35 @@
     The `NovaCustom NS5x/7x 12th Gen` section is related to the two physical
     NovaCustom laptops based on the 12th generation Intel Core processor:
 
-    - [NS51 series](https://configurelaptop.eu/ns51-series/)
-    - [NS70 series](https://configurelaptop.eu/ns70-series/)
+    - [NS51 Series](https://configurelaptop.eu/ns51-series/)
+    - [NS70 Series](https://configurelaptop.eu/ns70-series/)
 
     ![](/images/NS51-front-1.png)
 
 === "NV4x 12th Gen"
     The `NovaCustom NV4x 12th Gen` section is related to the one physical
     NovaCustom laptops based on the 12th generation Intel Core processor:
 
-    - [NV41 series](https://configurelaptop.eu/nv41-series/)
+    - [NV41 Series](https://configurelaptop.eu/nv41-series/)
 
     ![](/images/NV4x-front-1.png)
 
 === "NS5x/7x 11th Gen"
     The `NovaCustom NS5x/7x 11th Gen` section is related to the two physical
     NovaCustom laptops based on the 11th generation Intel Core processor:
 
-    - [NS51 series](https://configurelaptop.eu/ns51-series/)
-    - [NS70 series](https://configurelaptop.eu/ns70-series/)
+    - [NS51 Series](https://configurelaptop.eu/ns51-series/)
+    - [NS70 Series](https://configurelaptop.eu/ns70-series/)
 
     ![](/images/NS51-front-1.png)
 
 === "NV4x 11th Gen"
     The `NovaCustom NV4x 11th Gen` section is related to the one physical
     NovaCustom laptops based on the 11th generation Intel Core processor:
 
-    - [NV41 series](https://configurelaptop.eu/nv41-series/)
+    - [NV40 Series](https://configurelaptop.eu/nv40-series/)
 
-    ![](/images/NV4x-front-1.png)
+    ![](/images/NV40-front-1.png)
 
 For more information on the hardware, please refer to the references in above
 links.
@@ -48,8 +48,8 @@ Each firmware release contains of two parts:
   firmware.
 
 They both interact with each other tightly, so keeping their compatible versions
-in in sync is important. Information on compatibility should be always explained
-in the release pages:
+in sync is important. Information on compatibility should always be explained
+on the release pages:
 
 - [NV4x 12th Gen](/variants/novacustom_nv4x_adl/releases/)
 - [NV4x 11th Gen](/variants/novacustom_nv4x_tgl/releases/)

docs/unified/novacustom/overview.md

@@ -2,11 +2,11 @@
 
 ## Prerequisites
 
-To proceed with the recovery procedure the backup with the vendor firmware or
+To proceed with the recovery procedure, the backup with the vendor firmware or
 vendor EC firmware will be necessary eg. `bios_backup.rom`, `ec_backup.rom`.
 
 The backup file should be generated before making any changes in the device
-flash chip according to documentation:
+flash chip according to the following documentation sections:
 
 - [Firmware backup](initial-deployment.md#bios-installation)
 - [EC firmware backup](initial-deployment.md#ec-firmware-installation)
@@ -19,7 +19,7 @@ flash chip according to documentation:
 ### BIOS recovery
 
 Follow the [Initial deployment](initial-deployment.md#initial-installation)
-section to perform the external flash. When running the flashrom commands use a
+section to perform the external flash. When running the flashrom commands, use a
 backup file you've prepared previously, like `bios_backup.rom`.
 
 ### EC firmware recovery
@@ -98,10 +98,13 @@ make BOARD=arduino/mega2560 flash
   ![](/images/nvc_ec_flash/ns5x_battery_unplugged.jpg)
 
 - Reattach the bottom cover (without screwing it in) and flip the laptop over
-- Using a prying tool like a credit card, pull up the keyboard from the laptop
+- Put the laptop on its side, while the screen is in an opened state. By using
+  a little screw driver, carefully push in the screw holes of the keyboard and
+  take the keyboard out. Please check out
+  [this video](https://www.youtube.com/watch?v=A66cLJcMLbI) for a demonstration.
 
-> Start prying at the top of the keyboard. Be extra careful when removing the
-> keyboard to avoid damaging the keyboard cable, which is extremely fragile
+> Be extra careful when removing the keyboard to avoid damaging the keyboard
+> cable, which is extremely fragile
 
 === "NS5x / NS7x"
     ![](/images/nvc_ec_flash/ns5x_keyboard_connectors.jpg)