# 1. Быстрый старт

## Установка ПО
  
1. **Установить arm-none-eabi toolchain версии 10.x 2021.10**  
   
   Установить в папку по умолчанию: `C:\Program Files (x86)\GNU Arm Embedded Toolchain\10 2021.10`

   - [Ссылка](https://developer.arm.com/downloads/-/gnu-rm)  

2. **Установить CMake**

   Установить в папку по умолчанию: `C:\Program Files\CMake`.  
   Галочку `Add CMake to the PATH enviroment variable` ставить **не обязательно**.
   
   - [Ссылка 1](https://cmake.org/download/)  
   - [Ссылка 2](https://github.com/Kitware/CMake/releases/download/v3.31.6/cmake-3.31.6-windows-x86_64.msi)  
   
3. **Скачать систему сборки ninja**  
   
   Распаковать в папку `С:\ninja`

   - [Ссылка](https://github.com/ninja-build/ninja/releases) 

4. **Установить VSCode**  
   
   - [Ссылка](https://code.visualstudio.com/)


## Запуск

1. **Распаковать базовый проект**
   
   Базовый проект пользовательской прошивки и программу для загрузки прошивки распаковать в папку `С:\ntc`.

2. **Запустить VSCode**

3. **Открыть папку с проектом**

   Для этого выбрать пункт меню `File -> Open Folder...` и выбрать папку `C:\ntc\ntc-user-app`.

   > ***Примечание.***  
   > *Если появится диалоговое окно, с предложением указать являетесь вы автором проекта или нет, выбрать - **Да**.*

4. **Установить расширения**
   
   В правом нижнем углу должно появиться сообщение с предложением установить рекомендуемые расширения.  
   Согласиться и дождаться установки.

5. **Скомпилировать проект**

   Нажать сочетание клавиш `CTRL`+`SHIFT`+`B`, для компиляции проекта. 
   
   При первом запуске компиляции VSCode спросит, какую сборку компилировать *(Debug или Release)*.  
   В верхнем поле ввода выбрать **Debug**. После чего проект должен успешно быть скомпилирован.

6. **Загрузить прошивку в устройство**

   Для загрузки прошивки в устройство и запуска монитора:
   - нажать сочетание клавиш `CTRL`+`SHIFT`+`P`
   - в верхнем поле ввода набрать `>Tasks: Run Task`
   - затем нажать `Enter`  
   - далее выбрать `run` 
   - снова нажать `Enter` 

   Произойдёт загрузка прошивки, а затем запуститься монитор.  
   Для выхода из монитора нажмите `CTRL`+`C`.

&nbsp;

# 2. Подробное описание

## Структура проекта

**Проект VSCode:**

```
- ntc-user-app                      - Папка с шаблоном проекта
   ├ .vscode
   │   ├ tasks.json                 - Задачи компиляции и запуска прошивки
   │   ├ settings.json              - Локальные настройки VSCode
   │   ├ extensions.json            - Список нужных расширений VSCode
   │   └ launch.json                - Конфигурация отладки
   ├ cmake
   │   └ gcc-arm-none-eabi.cmake    - Файл с настройками toolchain
   ├ ntc_api                        - Папка со статической библиотекой, которая позполяет получить доступ к перефирии устройства
   │  ├ inc
   │  │  └ ...                      - Заголовочные файлы статической библиотеки
   │  └ lib
   │     └ libntc_api.a
   ├ ntc_linker_script.ld           - Скрипт линковщика
   ├ main.c                         - Основной исполняемый файл с пользовательской прошивкой
   ├ CMakePresets.json              - CMake пресеты для VSCode
   ├ app.cmake                      - Файл с основными перменными проекта
   └ CMakeLists.txt                 - Основной файл проекта CMake
```

**Утилита для загрузки прошивки:**

```
- ntc-file-loader                  - Папка с программой загрузки прошивки
   ├ ntc_file_loader.exe           - Программа для загрузки прошивки
   └ ...
```

## Утилиты для сборки

> ***Примечание.***  
> *Пути с перечисленными утилитами можно добавить в системную переменную `PATH` (но не обязательно).*  
> *Для `arm-none-eabi` и `CMake` это можно сделать установив соответствующие галочки при из установке. Для `Ninja` и `ntc_file_loader` это нужно делать в ручную.*

- **CMake** - программное средство автоматизации сборки.  
  Путь к утилите `cmake.exe` прописывается в файле `ntc-user-app\.vscode\settings.json`, переменная `cmake.cmakePath`.  

  В данном случаем, путь к `cmake.exe` прописывается для данного проекта. Так же можно выполнить данную настройку для всех проектов **VSCode** в глобальном файле настроек. 
  
  Если путь к `cmake.exe` присутствует в системной переменной `PATH`, то данную настройку выполнять не нужно *(нужно удалить строку с переменной `cmake.cmakePath` из файла `settings.json`)*.
      
- **Ninja** - сборщик.  
  Путь к утилите `ninja.exe` прописывается в файле `ntc-user-app\CMakePresets.json`, переменная `CMAKE_MAKE_PROGRAM`. 

  Если путь к `cmake.exe` присутствует в системной переменной `PATH`, то данную настройку выполнять не нужно (нужно удалить строку с переменной 'CMAKE_MAKE_PROGRAM' из файла CMakePresets.json).
      
- **arm-none-eabi** - компилятор и компоновщик.  
  Путь к папке с `toolchain` прописывается в файле `ntc-user-app\cmake\gcc-arm-none-eabi.cmake`, переменная `TOOLCHAIN_DIR`.
  
  Так же для работы отладчика, в файле `ntc-user-app\.vscode\launch.json`, в переменную `armToolchainPath` нужно прописать корректный путь к исполняемым файлам компилятора
  
  Если путь к исполнительным файлам `toolchain` присутствует в системной переменной `PATH`, то файл `gcc-arm-none-eabi.cmake` нужно соответствующим образом настроить.

- **ntc_file_loader** - программа для загрузки прошивки и вывода отладочной информации.  
  Путь к утилите `ntc_file_loader.exe` прописан в соответствующих тасках *(`run` и `monitor`)* файла `ntc-user-app\.vscode\tasks.json`, переменная `command`.  
  
  Если путь к `ntc_file_loader.exe` присутствует в системной переменной `PATH`, то в переменной `command` нужно прописать значение `ntc_file_loader.exe`.

## Работа с проектом

Для автоматизации сборки проекта используется `CMake`.  

> *Для более подробной информации обратитесь к соответствующей документации (https://cmake.org/documentation/).*  

Переменные проекта находятся в файле `ntc-user-app\app.cmake`.  

- Переменная `SOURCES` - список исполняемых файлов проекта

  ```cmake
  set(SOURCES 
      main.c
      abc.c
      foo/bar.c
  )
  ```
      
- Переменная `INCLUDES` - список папок для поиска заголовочных файлов

  ```cmake
  set(INCLUDES 
      foo
      foo/bar
  )
  ```

- Переменная `DEFINITIONS` - список переменных предпроцессора

  ```cmake
  set(DEFINITIONS 
      FOO
      BAR=1
  )
  ```


## Сборка, загрузка прошивки, трассировка

> *Для сборки прошивки, загрузки и отладки в VSCode используются таски (`Task` - задача)*

Для запуска тасков нужно нажать `CTRL`+`SHIFT`+`P`, далее набрать и выбрать `>Tasks: Run Task`, нажать `ENTER`, выбрать нужный таск:

- `cmake-configure` - запуск обработчика CMake.  
  При сохранении файлов `*.cmake` или `CMakeLists.txt`, запускается автоматически.

- `cmake-build` - сборка проекта *(горячие клавиши `CTRL`+`SHIFT`+`B`)*

- `cmake-clean` - очистка проекта

- `cmake-clean-rebuild` - чистая сборка проекта *(очистка затем сборка)*

- `run` - загрузка прошивки затем запуск монитора для трассировки

- `monitor` - запуск монитора для трассировки
      
## Выбор типа сборки  

1. Перейдите на вкладку `CMake` *(нажать на кнопку на вертикальной панели слева)*

2. В группе `Configure` должна быть выбрана текущая сборка *(`Debug` или `Release`)*. 

3. Навести курсором мыши на текущую сборку, напротив надписи появится кнопка - `Select configure preset` *(пиктограмма - карандаш)*. Нажать кнопку.

4. В поле ввода сверху выбрать нужную сборку `Debug` или `Release`. 

## Отладка через jLink

1. **Установить J-Link Software**

   - [Ссылка](https://www.segger.com/downloads/jlink/)

2. **Настроить путь к GDB серверу**  
   
   Перед запуском отладчика убедитесь, что в файле `ntc-user-app\.vscode\launch.json` в переменной `serverpath` прописан существующий путь к GDB серверу

3. **Отладка**  

   > *Перед началом отладки не забудьте выполнить сборку проекта `cmake-build` или `cmake-clean-rebuild`*

   Перейдите на закладку `Run and Debug`, и нажмите кнопку `NTC Debug (JLink)`.