mirror of
https://github.com/GyverLibs/GyverMotor2.git
synced 2026-06-05 14:47:00 +03:00
AlexGyver
227 lines
15 KiB
Markdown
227 lines
15 KiB
Markdown
[](https://github.com/GyverLibs/GyverMotor2/releases/latest/download/GyverMotor2.zip)
|
|
[](https://registry.platformio.org/libraries/gyverlibs/GyverMotor2)
|
|
[](https://alexgyver.ru/)
|
|
[](https://alexgyver.ru/support_alex/)
|
|
[](https://github-com.translate.goog/GyverLibs/GyverMotor2?_x_tr_sl=ru&_x_tr_tl=en)
|
|
|
|
[](https://t.me/GyverLibs)
|
|
|
|
# GyverMotor2
|
|
Библиотека для управления коллекторными моторами через драйвер, улучшенная версия библиотеки [GyverMotor](https://github.com/GyverLibs/GyverMotor)
|
|
- Контроль скорости и направления вращения
|
|
- Работа с ШИМ любого разрешения
|
|
- Плавный пуск и изменение скорости
|
|
- Порог минимального ШИМ
|
|
- Программный deadtime
|
|
- Поддержка 7 типов драйверов
|
|
|
|
### Совместимость
|
|
Совместима со всеми Arduino платформами (используются Arduino-функции)
|
|
|
|
## Содержание
|
|
- [Использование](#usage)
|
|
- [Версии](#versions)
|
|
- [Установка](#install)
|
|
- [Баги и обратная связь](#feedback)
|
|
|
|
<a id="usage"></a>
|
|
|
|
## Использование
|
|
### Тип драйвера
|
|
| Драйвер | Описание | Пины | speed > 0 | speed < 0 | stop/disable | brake |
|
|
|----------------------|-------------------------|-------------------|-------------|-------------|--------------|-------------|
|
|
| `GM2::ONLY_PWM` | Только ШИМ | (PWM) | (PWM) | (PWM) | (0) | (0) |
|
|
| `GM2::DIR_DIR` | Только направление | (GPIO, GPIO) | (0, 1) | (1, 0) | (0, 0) | (1, 1) |
|
|
| `GM2::DIR_PWM` | Один ШИМ без инверсии | (GPIO, PWM) | (0, PWM) | (1, PWM) | (0, 0) | (1, MAX) |
|
|
| `GM2::DIR_PWM_INV` | Один ШИМ с инверсией | (GPIO, PWM) | (0, PWM) | (1, ~PWM) | (0, 0) | (1, MAX) |
|
|
| `GM2::PWM_PWM_SPEED` | Два ШИМ, режим скорости | (PWM, PWM) | (0, PWM) | (PWM, 0) | (0, 0) | (MAX, MAX) |
|
|
| `GM2::PWM_PWM_POWER` | Два ШИМ, режим момента | (PWM, PWM) | (~PWM, MAX) | (MAX, ~PWM) | (0, 0) | (MAX, MAX) |
|
|
| `GM2::DIR_DIR_PWM` | Два направления и ШИМ | (GPIO, GPIO, PWM) | (0, 1, PWM) | (1, 0, PWM) | (0, 0, 0) | (1, 1, MAX) |
|
|
|
|
Примечания:
|
|
|
|
- В скобках указаны пины в порядке конструктора, т.е. например для `DIR_PWM` инициализация будет `GyverMotor2<GM2::DIR_PWM> motor(gpio, pwm)`, где gpio - обычный цифровой пин (digitalWrite), pwm - пин с поддержкой ШИМ (analogWrite)
|
|
- `MAX` - максимальное значение ШИМ при указанном разрешении
|
|
- `PWM` - прямой ШИМ `(0.. MAX)`
|
|
- `~PWM` - обратный ШИМ `(MAX.. 0)`
|
|
|
|
Выбор режима для H-мост драйвера (2 пина, обычно IN1 и IN2) - большинство модулей-драйверов для Arduino:
|
|
|
|
- Для симметричной по скорости работы в обоих направлениях рекомендуется режим с двумя ШИМ, где `PWM_PWM_SPEED` имеет более высокую скорость, а `PWM_PWM_POWER` более стабилен на низких оборотах и имеет более высокий момент на некоторых моторах и драйверах. Идеален для колёсных роботов
|
|
- Для работы в обоих направлениях, когда симметричность работы мотора не важна, можно использовать режим `DIR_PWM_INV` - он экономит один ШИМ пин. Драйверы, которые работают с `DIR_PWM` (без инверсии), встречаются редко
|
|
- Для работы в одну сторону с контролем скорости (MOSFET или мост с замкнутым пином) подходит режим `ONLY_PWM` и использует только один пин
|
|
- Для релейного управления (без контроля скорости) можно использовать режим `DIR_DIR`
|
|
|
|
Для драйверов с раздельным управлением направлением и скоростью IN1+IN2+EN нужен режим `DIR_DIR_PWM`.
|
|
|
|
### Настройки компиляции
|
|
Перед подключением библиотеки
|
|
|
|
```cpp
|
|
#define GMOTOR2_NO_ACCEL // вырезать модуль ускорения
|
|
```
|
|
|
|
### Описание класса
|
|
```cpp
|
|
// инициализация с указанием типа драйвера, разрешения ШИМ (бит) и пинов
|
|
GyverMotor2<driver, res = 8>(uint8_t pinA, uint8_t pinB = 0xff, uint8_t pinC = 0xff);
|
|
|
|
// установить deadtime (задержка при смене направления) в микросекундах (умолч. 0)
|
|
void setDeadtime(uint8_t us);
|
|
|
|
// получить deadtime в микросекундах
|
|
uint8_t getDeadTime();
|
|
|
|
// установить реверс направления (умолч. false)
|
|
void setReverse(bool rev);
|
|
|
|
// получить реверс направления
|
|
bool getReverse();
|
|
|
|
// установить минимальный ШИМ (умолч. 0)
|
|
void setMinDuty(uint16_t duty);
|
|
|
|
// установить минимальный ШИМ в % от максимального (умолч. 0)
|
|
void setMinDutyPerc(uint8_t perc);
|
|
|
|
// получить минимальный ШИМ
|
|
uint16_t getMinDuty();
|
|
|
|
// получить максимальный ШИМ
|
|
uint16_t getMaxDuty();
|
|
|
|
// установить скорость ШИМ (-макс.. макс)
|
|
void runSpeed(int16_t speed);
|
|
|
|
// установить скорость в % от максимального ШИМ (-100.. 100%)
|
|
void runSpeedPerc(int8_t perc);
|
|
|
|
// получить текущую скорость мотора в ШИМ
|
|
int16_t getSpeed();
|
|
|
|
// получить направление: мотор крутится (1 и -1), мотор остановлен (0)
|
|
int8_t getDir();
|
|
|
|
// остановка. Если включено ускорение, то плавная
|
|
void stop();
|
|
|
|
// активное торможение (оставляет пины драйвера активными)
|
|
void brake();
|
|
|
|
// остановить и отключить мотор
|
|
void disable();
|
|
|
|
// установить ускорение в ШИМ в секунду. Реальный минимум - 5. 0 чтобы отключить
|
|
void setAccel(uint16_t accel);
|
|
|
|
// установить ускорение в процентах в секунду. 0 чтобы отключить
|
|
void setAccelPerc(uint8_t perc);
|
|
|
|
// получить период, не реже которого нужно вызывать tick, мс
|
|
uint8_t getDt();
|
|
|
|
// получить целевую скорость (режим ускорения)
|
|
int16_t getTarget();
|
|
|
|
// плавное изменение к указанной скорости с ускорением setAccel, вызывать в loop. Вернёт true при достижении скорости
|
|
bool tick();
|
|
```
|
|
|
|
### Описание фич
|
|
#### Запуск и остановка
|
|
- `runSpeed` запускает мотор с указанной скоростью, поддерживает отрицательные значения для вращения в обратную сторону. При значении `0` отключает мотор
|
|
- `stop` - остановка и отключение, равносильно вызову `runSpeed(0)`
|
|
- `setReverse` - реверс мотора, при установке `true` будет вращаться в противоположную сторону
|
|
- `brake` - активное торможение через драйвер (поддерживается не везде)
|
|
- `disable` - остановка и отключение драйвера
|
|
|
|
#### DeadTime
|
|
Внутри `runSpeed` при смене направления вращения отключает драйвер и создаёт задержку на указанное кол-во микросекунд, после чего подаёт нужный сигнал на мотор. Это нужно для самодельных простых драйверов по схеме H-мост, чтобы избежать замыкания моста. У драйверов в виде микросхем и модулей обычно есть встроенный аппаратный deadtime и в библиотеке его включать не нужно.
|
|
|
|
#### MinDuty
|
|
Позволяет настроить минимальный сигнал на мотор. Значение, поданное в `runSpeed` будет линейно масштабироваться от указанного MinDuty до максимума (если не равно нулю). Это позволяет "пропустить" значения, при которых мотор не может тронуться, не меняя логику задания скорости. Пример значений для 8 бит и `MinDuty=50`:
|
|
|
|
| `runSpeed` | Фактический PWM |
|
|
|------------|-----------------|
|
|
| 0 | 0 |
|
|
| 1 | 50 |
|
|
| 50 | 90 |
|
|
| 150 | 170 |
|
|
| 200 | 210 |
|
|
| 255 | 255 |
|
|
|
|
#### Accel
|
|
При задании ненулевого ускорения (в единицах ШИМ в секунду) вызов `runSpeed` не применяет указанную скорость сразу, вместо этого скорость будет плавно меняться к заданной. Для работы нужно вызывать тикер в основном цикле программы не реже, чем `getDt` миллисекунд (варьируется от 30 до 200 в зависимости от ускорения). Вызов `stop` сделает плавную остановку, а `brake` и `disable` остановят мотор резко:
|
|
|
|
```cpp
|
|
void setup() {
|
|
motor.setAccel(80);
|
|
motor.runSpeed(170);
|
|
}
|
|
|
|
void loop() {
|
|
motor.tick(); // плавно разгонит мотор до скорости 170
|
|
}
|
|
```
|
|
|
|
Может пригодиться при управлении тяжёлым колёсным роботом, чтобы избежать рывков при разгоне и торможении.
|
|
|
|
## Примеры
|
|
```cpp
|
|
#include <GyverMotor2.h>
|
|
|
|
// GyverMotor2<GM2::DIR_DIR> motor(5, 6);
|
|
// GyverMotor2<GM2::DIR_PWM> motor(5, 6);
|
|
GyverMotor2<GM2::DIR_PWM_INV> motor(5, 6);
|
|
// GyverMotor2<GM2::PWM_PWM_SPEED> motor(5, 6);
|
|
// GyverMotor2<GM2::PWM_PWM_POWER> motor(5, 6);
|
|
// GyverMotor2<GM2::DIR_DIR_PWM> motor(5, 6, 7);
|
|
|
|
void setup() {
|
|
// motor.setDeadtime(5);
|
|
// motor.setMinDuty(50);
|
|
// motor.setReverse(true);
|
|
}
|
|
|
|
void loop() {
|
|
int speed = map(analogRead(0), 0, 1023, -255, 255);
|
|
motor.runSpeed(speed);
|
|
}
|
|
```
|
|
|
|
<a id="versions"></a>
|
|
|
|
## Версии
|
|
- v1.0
|
|
|
|
<a id="install"></a>
|
|
## Установка
|
|
- Библиотеку можно найти по названию **GyverMotor2** и установить через менеджер библиотек в:
|
|
- Arduino IDE
|
|
- Arduino IDE v2
|
|
- PlatformIO
|
|
- [Скачать библиотеку](https://github.com/GyverLibs/GyverMotor2/archive/refs/heads/main.zip) .zip архивом для ручной установки:
|
|
- Распаковать и положить в *C:\Program Files (x86)\Arduino\libraries* (Windows x64)
|
|
- Распаковать и положить в *C:\Program Files\Arduino\libraries* (Windows x32)
|
|
- Распаковать и положить в *Документы/Arduino/libraries/*
|
|
- (Arduino IDE) автоматическая установка из .zip: *Скетч/Подключить библиотеку/Добавить .ZIP библиотеку…* и указать скачанный архив
|
|
- Читай более подробную инструкцию по установке библиотек [здесь](https://alexgyver.ru/arduino-first/#%D0%A3%D1%81%D1%82%D0%B0%D0%BD%D0%BE%D0%B2%D0%BA%D0%B0_%D0%B1%D0%B8%D0%B1%D0%BB%D0%B8%D0%BE%D1%82%D0%B5%D0%BA)
|
|
### Обновление
|
|
- Рекомендую всегда обновлять библиотеку: в новых версиях исправляются ошибки и баги, а также проводится оптимизация и добавляются новые фичи
|
|
- Через менеджер библиотек IDE: найти библиотеку как при установке и нажать "Обновить"
|
|
- Вручную: **удалить папку со старой версией**, а затем положить на её место новую. "Замену" делать нельзя: иногда в новых версиях удаляются файлы, которые останутся при замене и могут привести к ошибкам!
|
|
|
|
<a id="feedback"></a>
|
|
|
|
## Баги и обратная связь
|
|
При нахождении багов создавайте **Issue**, а лучше сразу пишите на почту [alex@alexgyver.ru](mailto:alex@alexgyver.ru)
|
|
Библиотека открыта для доработки и ваших **Pull Request**'ов!
|
|
|
|
При сообщении о багах или некорректной работе библиотеки нужно обязательно указывать:
|
|
- Версия библиотеки
|
|
- Какой используется МК
|
|
- Версия SDK (для ESP)
|
|
- Версия Arduino IDE
|
|
- Корректно ли работают ли встроенные примеры, в которых используются функции и конструкции, приводящие к багу в вашем коде
|
|
- Какой код загружался, какая работа от него ожидалась и как он работает в реальности
|
|
- В идеале приложить минимальный код, в котором наблюдается баг. Не полотно из тысячи строк, а минимальный код |