**nr_micro_shell**
[Китайская версия](./readme.md)
> v1.0.2
## 1 Введение
При отладке и обслуживании часто необходимо взаимодействовать с микроконтроллером (MCU), чтобы получать, устанавливать параметры или выполнять некоторые операции. **nr_micro_shell** — это базовый инструмент командной строки, написанный для MCU с ограниченными ресурсами, чтобы удовлетворить этот спрос. Хотя в компоненте RT_Thread предоставляется мощный инструмент взаимодействия с командной строкой **finsh**, для MCU с меньшим объёмом ROM и RAM ресурсов **finsh** всё ещё слишком велик. Если вы хотите использовать инструмент командной строки на этих платформах, **nr_micro_shell** может быть хорошим выбором.
**nr_micro_shell** имеет следующие преимущества:
1. Меньшие ресурсы, простота использования, гибкость и удобство. В процессе использования задействованы только две функции: ***shell_init()*** и ***shell()***. Этот инструмент удобно использовать без дополнительной работы по кодированию на MCU с RTOS или голом MCU.
2. Хороший опыт взаимодействия. Он точно похож на командную строку Linux. Когда терминал последовательного порта поддерживает ANSI (например, терминал hypertrm), он не только поддерживает базовое взаимодействие с командной строкой, но также предоставляет функцию завершения команды табуляции, запроса истории команд и изменения курсора с помощью клавиш направления.
3. Хорошая расширяемость. **nr_micro_shell** предоставляет пользователям стандартные прототипы функций пользовательских команд. Когда вы хотите определить свою собственную команду, просто напишите функции команд и зарегистрируйте их.
Сравнение ресурсов, занимаемых **nr_micro_shell** и **finsh** (finsh не использует MSH) при одинаковой конфигурации:
| | Исходный проект | Увеличение после добавления nr_micro_shell | Увеличение после добавления finsh
|--- | ----- | ------------------- | ----------
|ROM | 63660 | +3832 | +26908
|RAM | 4696 | +1104 | +1304
Конфигурация:
- До 3 исторических команд.
- Поддержка завершения табуляции.
- Максимальная длина командной строки — 100.
- До 10 параметров команды.
- Стек потока командной строки составляет 512 байт.
Демонстрация **nr_micro_shell**:
### 1.1 Структура файла
Название | Описание
-------- | --------------------------------------------------------------------------------------------
docs | Каталог документов, включая GIF-изображения для демонстрации и т. д.
examples | Каталог примеров, включая примеры функций команд: ***nr_micro_shell_commands.c*** и примеры использования под rt_thread ***nr_micro_shell_thread.c***.
inc | Каталог заголовков.
src | Каталог исходного кода.
### 1.2 Лицензия
Пакет **nr_micro_shell** следует лицензии MIT. Пожалуйста, обратитесь к файлу «license» для получения подробной информации.
### 1.3 Зависимости
Нет
## 2 Использование пакета **nr_micro_shell** под RT_Thread с ENV
Вам нужно выбрать пакет **nr_micro_shell** из менеджера пакетов RT_Thread. Конкретный путь выглядит следующим образом:
```
Онлайн-пакеты RT-Thread
Пакеты инструментов --->
[*] nr_micro_shell: Лёгкий инструмент взаимодействия с командной строкой. --->
```
После нажатия клавиши «пробел», чтобы выбрать соответствующие настройки, нажмите «Enter», чтобы настроить соответствующие параметры. Затем позвольте менеджеру пакетов rt_thread автоматически обновиться или используйте команду «Pkgs --update», чтобы обновить пакет до BSP.
Если вам нужно запустить образцы, убедитесь, что в конфигурации rt_thread включена опция «использование консоли для kt_printf», kt_printf может работать нормально, а опция «использовать компоненты автоматически инициализации» включена. **nr_micro_shell** можно использовать для прямой загрузки или моделирования. Когда командная строка пуста, нажмите клавишу табуляции, чтобы отобразить все поддерживаемые команды. Для примера тестовой команды см. использование GIF-файлов в doc/pic. Процесс создания пользовательской команды см. в методе, описанном ниже в разделе **3 Использование пакета nr_micro_shell без RTOS**.
## 3 Использование пакета **nr_micro_shell** без RTOS
### 3.1 Конфигурация:
Всю работу по настройке можно выполнить в ***nr_micro_shell_config.h***. Подробности см. в комментариях к файлу.
### 3.2 Использование:
- Убедитесь, что все файлы добавлены в ваш проект.
- Сделайте Конечно, вот перевод текста на русский язык:
Конечно, функция макроса «shell_printf()», «ansi_show_char()» может быть использована в вашем проекте.
Пример приведён ниже:
```c
#include "nr_micro_shell.h"
int main(void)
{
/* Инициализация */
shell_init();
while (1)
{
if (USART GET A CHAR 'c')
{
/* nr_micro_shell получает символы. */
shell(c);
}
}
}
```
Перед использованием аппаратного ввода напрямую рекомендуется использовать следующий код (убедитесь, что информация может быть напечатана нормально), чтобы проверить, работает ли nr_micro_shell:
```c
#include "nr_micro_shell.h"
int main(void)
{
unsigned int i = 0;
/* NR_SHELL_END_OF_LINE 0 */
char test_line[] = "test 1 2 3\n"
/* Инициализация */
shell_init();
/* тест */
for (i = 0; i < sizeof(test_line)-1; i++)
{
shell(test_line[i]);
}
while (1)
{
if (USART GET A CHAR 'c')
{
/* nr_micro_shell принимает символы */
shell(c);
}
}
}
```
### 3.3 Добавьте свою собственную команду
**ШАГ 1**:
Вы должны реализовать функцию команды в ***nr_micro_shell_commands.c***. Прототип функции команды выглядит следующим образом:
```c
void your_command_funtion(char argc, char *argv)
{
.....
}
```
**argc** — это количество параметров. **argv** хранит начальный адрес и содержимое каждого параметра. Если ваша входная строка:
```c
test -a 1
```
то **argc** будет равно 3, а содержимое **argv** будет:
```c
-------------------------------------------------------------
0x03|0x08|0x0b|'t'|'e'|'s'|'t'|'\0'|'-'|'a'|'\0'|'1'|'\0'|
-------------------------------------------------------------
```
Если вы хотите узнать содержимое первого или второго параметра, вы должны использовать:
```c
/* "-a" */
printf(argv[argv[1]])
/* "1" */
printf(argv[argv[2]])
```
**ШАГУ 2**:
Вам необходимо зарегистрировать команды перед их использованием. Есть два способа регистрации команд.
1. Когда NR_SHELL_USING_EXPORT_CMD не определён в файле конфигурации, зарегистрируйте вашу команду в таблице **static_cmd[]**, как показано ниже:
```c
const static_cmd_st static_cmd[] =
{
.....
{"your_command_name",your_command_funtion},
.....
{"\0",NULL}
};
```
***Внимание: НЕ УДАЛЯЙТЕ {"\0", NULL}!***
2. Когда NR_SHELL_USING_EXPORT_CMD определён в файле конфигурации и NR_SHELL_CMD_EXPORT() поддерживает используемый компилятор, вы можете зарегистрировать команду следующим образом:
```c
NR_SHELL_CMD_EXPORT(your_command_name,your_command_funtion);
```
## 4、Использование симулятора nr_micro_shell под Linux
В каталоге проекта `./examples/simulator/` хранится код имитации nr_micro_shell, продолжайте добавлять пользовательские команды в файл `./examples/nr_micro_shell_commands.c`, как описано выше. После добавления вы можете использовать команду make для компиляции исходного кода, созданный исполняемый файл — `./examples/simulator/out/nr_micro_shell` или `./examples/simulator/out/nr_micro_shell_db`. Доступные команды make следующие:
Код симулятора nr_micro_shell хранится в каталоге `./examples/simulator/`, вы можете добавить свою команду в `./examples/nr_micro_shell_commands.c` как описано выше. После добавления можно использовать команду `make` для компиляции исходного кода. Созданный исполняемый файл: `./examples/simulator/out/nr_micro_shell` или `./examples/simulator/out/nr_micro_shell_db`。 Доступные команды `make`:
```sh
# компиляция исполняемого файла
make
# компиляция файла gdb
make debug
# очистка файлов
make clean
```
## 5 Внимание
Используйте NR_SHELL_USING_EXPORT_CMD для выбора метода регистрации команд в соответствии с вашими привычками использования.
При использовании static_cmd[], убедитесь, что в вашем проекте существует реестр:
```c
const static_cmd_st static_cmd[] =
{
.....
{"\0",NULL}
};
```
При использовании NR_SHELL_CMD_EXPORT(), убедитесь, что NR_SHELL_CMD_EXPORT() поддерживает используемый компилятор, иначе будет сообщено об ошибке.
Клавиша ESC не поддерживается.
## 6 Контакты
- Сопровождающий: Nrusher
- Домашняя страница: <https://github.com/Nrusher/nr_micro_shell> или <https://gitee.com/nrush/nr_micro_shell>