add project wizard doc fix openocd configs (#651)

brianignacio5 · web-flow · commit 5bb08c4c5e64 · 2022-02-18T15:33:49.000+08:00
* add project wizard doc fix openocd configs

* add openOcd config links

* update extension template project

* update confirm image

* fix template app project name
diff --git a/README.md b/README.md
@@ -111,6 +111,7 @@ Click <kbd>F1</kbd> to show Visual studio code actions, then type **ESP-IDF** to
 | Doctor command                                          |                                        |                                           |
 | Erase flash memory from device                          | <kbd>⌘</kbd> <kbd>I</kbd> <kbd>R</kbd> | <kbd>Ctrl</kbd> <kbd>E</kbd> <kbd>R</kbd> |
 | Execute custom task                                     | <kbd>⌘</kbd> <kbd>I</kbd> <kbd>J</kbd> | <kbd>Ctrl</kbd> <kbd>E</kbd> <kbd>J</kbd> |
+| Flash (DFU) your project                                |                                        |                                           |
 | Flash (UART) your project                               |                                        |                                           |
 | Flash (with JTag)                                       |                                        |                                           |
 | Full clean project                                      | <kbd>⌘</kbd> <kbd>I</kbd> <kbd>X</kbd> | <kbd>Ctrl</kbd> <kbd>E</kbd> <kbd>X</kbd> |
diff --git a/docs/ONBOARDING.md b/docs/ONBOARDING.md
@@ -16,6 +16,7 @@
 10. [ESP-ADF, ESP-MDF and other frameworks](./tutorial/additional_frameworks.md)
 11. [eFuse Explorer](./tutorial/efuse.md)
 12. [Rainmaker](./tutorial/rainmaker.md)
+13. [New project wizard](./new_project_wizard.md)
 
 ## Documentation
 
diff --git a/docs/tutorial/new_project_wizard.md b/docs/tutorial/new_project_wizard.md
@@ -0,0 +1,27 @@
+# New project wizard
+
+This feature allows you to create a new project using the ESP-IDF, ESP-ADF and ESP-MDF frameworks and configure the extension settings and the project name.
+
+1. Click menu View -> Command Palette... and search for the **ESP-IDF: New Project**.
+
+<p>
+  <img src="../../media/tutorials/new_project/new_project_init.png" alt="New project wizard" height="500">
+</p>
+
+2. Choose the project name, the directory to create this new project, the Espressif board you are using (or any general Espressif device) and the serial port of the device. You could also choose to import any component directory `component-dir` to the new project which will be copied to the new project's directory `components` sub directory (`<project-dir>/components/component-dir`).
+
+> **NOTE:** If using the custom board option, please take a look at [Configuring of OpenOCD for specific target](https://docs.espressif.com/projects/esp-idf/en/stable/esp32/api-guides/jtag-debugging/tips-and-quirks.html#configuration-of-openocd-for-specific-target) for more information about these openOCD configuration files and the [debugging tutorial](./debugging.md) for values examples.
+
+3. After that click the `Choose Template` button and choose a template from Extension templates and, if configured; ESP-IDF, ESP-ADF and ESP-MDF frameworks. If you want to create a blank project, choose ESP-IDF `sample_project` or the extension `template-app`.
+
+<p>
+  <img src="../../media/tutorials/new_project/new_project_templates.png" alt="New project templates" height="500">
+</p>
+
+4. Choose your desired template and click the `Create project using template <template-name>` button where `<template-name>` is the name of the selected template.
+
+5. After the project is created, a notification window will show up to open the newly created project or not.
+
+<p>
+  <img src="../../media/tutorials/new_project/new_project_confirm.png" alt="New project templates" height="100">
+</p>
diff --git a/docs/tutorial/toc.md b/docs/tutorial/toc.md
@@ -14,3 +14,4 @@
 10. [ESP-ADF, ESP-MDF and other frameworks](./additional_frameworks.md)
 11. [eFuse Explorer](./efuse.md)
 12. [Rainmaker](./rainmaker.md)
+13. [New project wizard](./new_project_wizard.md)
diff --git a/media/tutorials/new_project/new_project_confirm.png b/media/tutorials/new_project/new_project_confirm.png
diff --git a/media/tutorials/new_project/new_project_init.png b/media/tutorials/new_project/new_project_init.png
diff --git a/media/tutorials/new_project/new_project_templates.png b/media/tutorials/new_project/new_project_templates.png
diff --git a/src/newProject/newProjectPanel.ts b/src/newProject/newProjectPanel.ts
@@ -167,8 +167,8 @@ export class NewProjectPanel {
           ) {
             const defConfigFiles =
               newProjectArgs.boards && newProjectArgs.boards.length > 0
-                ? newProjectArgs.boards[0].configFiles
-                : newProjectArgs.targetList[0].configFiles;
+                ? newProjectArgs.boards[0].configFiles.join(",")
+                : newProjectArgs.targetList[0].configFiles.join(",");
             this.panel.webview.postMessage({
               boards: newProjectArgs.boards,
               command: "initialLoad",
diff --git a/src/newProject/utils.ts b/src/newProject/utils.ts
@@ -2,13 +2,13 @@
  * Project: ESP-IDF VSCode Extension
  * File Created: Tuesday, 27th July 2021 4:35:42 pm
  * Copyright 2021 Espressif Systems (Shanghai) CO LTD
- * 
+ *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
- * 
+ *
  *    http://www.apache.org/licenses/LICENSE-2.0
- * 
+ *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
@@ -52,7 +52,10 @@ export async function setCurrentSettingsInTemplate(
   if (mdfPathDir) {
     settingsJson["idf.espMdfPath" + isWin] = mdfPathDir;
   }
-  settingsJson["idf.openOcdConfigs"] = openOcdConfigs.split(",");
+  settingsJson["idf.openOcdConfigs"] =
+    openOcdConfigs.indexOf(",") !== -1
+      ? openOcdConfigs.split(",")
+      : [openOcdConfigs];
   if (port.indexOf("no port") === -1) {
     settingsJson["idf.port" + isWin] = port;
   }
diff --git a/templates/template-app/CMakeLists.txt b/templates/template-app/CMakeLists.txt
@@ -1,4 +1,6 @@
-# The following lines of boilerplate have to be in your project's
+# For more information about build system see
+# https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html
+# The following five lines of boilerplate have to be in your project's
 # CMakeLists in this exact order for cmake to work correctly
 cmake_minimum_required(VERSION 3.5)
 
diff --git a/templates/template-app/README.md b/templates/template-app/README.md
@@ -0,0 +1,32 @@
+# _Sample project_
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+This is the simplest buildable example. The example is used by command `idf.py create-project`
+that copies the project to user specified path and set it's name. For more information follow the [docs page](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html#start-a-new-project)
+
+
+
+## How to use example
+We encourage the users to use the example as a template for the new projects.
+A recommended way is to follow the instructions on a [docs page](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/build-system.html#start-a-new-project).
+
+## Example folder contents
+
+The project **sample_project** contains one source file in C language [main.c](main/main.c). The file is located in folder [main](main).
+
+ESP-IDF projects are built using CMake. The project build configuration is contained in `CMakeLists.txt`
+files that provide set of directives and instructions describing the project's source files and targets
+(executable, library, or both). 
+
+Below is short explanation of remaining files in the project folder.
+
+```
+├── CMakeLists.txt
+├── main
+│   ├── CMakeLists.txt
+│   └── main.c
+└── README.md                  This is the file you are currently reading
+```
+Additionally, the sample project contains Makefile and component.mk files, used for the legacy Make based build system. 
+They are not used or needed when building with CMake and idf.py.
diff --git a/templates/template-app/main/CMakeLists.txt b/templates/template-app/main/CMakeLists.txt
@@ -1,4 +1,2 @@
-idf_component_register(
-    SRCS "main.c"
-    INCLUDE_DIRS ""
-)
+idf_component_register(SRCS "main.c"
+                    INCLUDE_DIRS ".")
diff --git a/templates/template-app/main/main.c b/templates/template-app/main/main.c
@@ -1,40 +1,6 @@
-/* Hello World Example
-
-   This example code is in the Public Domain (or CC0 licensed, at your option.)
-
-   Unless required by applicable law or agreed to in writing, this
-   software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
-   CONDITIONS OF ANY KIND, either express or implied.
-*/
 #include <stdio.h>
-#include "freertos/FreeRTOS.h"
-#include "freertos/task.h"
-#include "esp_system.h"
-#include "esp_spi_flash.h"
-
 
 void app_main(void)
 {
-    printf("Hello world!\n");
-
-    /* Print chip information */
-    esp_chip_info_t chip_info;
-    esp_chip_info(&chip_info);
-    printf("This is ESP32 chip with %d CPU cores, WiFi%s%s, ",
-            chip_info.cores,
-            (chip_info.features & CHIP_FEATURE_BT) ? "/BT" : "",
-            (chip_info.features & CHIP_FEATURE_BLE) ? "/BLE" : "");
-
-    printf("silicon revision %d, ", chip_info.revision);
-
-    printf("%dMB %s flash\n", spi_flash_get_chip_size() / (1024 * 1024),
-            (chip_info.features & CHIP_FEATURE_EMB_FLASH) ? "embedded" : "external");
 
-    for (int i = 10; i >= 0; i--) {
-        printf("Restarting in %d seconds...\n", i);
-        vTaskDelay(1000 / portTICK_PERIOD_MS);
-    }
-    printf("Restarting now.\n");
-    fflush(stdout);
-    esp_restart();
-}
+}
