> For the complete documentation index, see [llms.txt](https://voltbro.gitbook.io/turtlebro_py/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://voltbro.gitbook.io/turtlebro_py/tema-9-modul-turtlebro_py.md).

# Тема 9: Модуль Turtlebro\_py

Это заключительная тема перед финальным проектом. В ней мы подробно рассмотрим все те  функции модуля turtlebro\_py, которых мы не касались ранее. 

Модуль turtlebro\_py это "обертка" над Robot Operating System (ROS), которая написана специально для нашего робота TurtleBro, чтобы скрыть сложности ROS, и при этом дать возможность попользоваться роботом всем, вне зависимости от уровня знаний Python.

Robot Operating System это мета-операционная система, управляющая роботами по всему миру. Это стандарт де-факто в коллаборативной и сервисной робототехнике. Она представляет широкие возможности для разработчиков робототехники, но слегка сложновата в освоении. Подробнее про ROS мы поговорим на наших специальных курсах по ней, а сейчас вернемся к модулю turtlebro\_py.

Данный пакет представляет из себя аналог стандартного модуля `turtle`, который используется при обучении Python для школьников. Аналогично с модулем `turtle`, в котором черепашка выполняет простые команды и рисует геометрические фигуры на экране, с помощью данного пакета, учашиеся смогут управлять роботом TurtleBro ([www.trurtlebro.ru](http://www.trurtlebro.ru/)), при помощи простых команд, описанных ниже. Данный пакет предполагается использовать для предварительного обучения Python и основам робототехники перед погружением в изучение Robot Operation System ([www.ros.org](http://www.ros.org/)).

Пакет входит в сборку метапакета `turtlebro_extra` и устанавливается автоматически при установке этого пакета. По умолчанию, данный пакет входит в нашу стандартную образ-сборку. Однако, если по какой-то причине вы хотите переустановить или обновить пакет, выполните команды (на роботе):

### Установка пакета

Пакет входит в сборку метапакета `turtlebro_extra` и устанавливается автоматически при установке этого пакета. Для установки метапакета на роботе выполните команды:

```bash
cd ~/catkin_ws/src
git clone https://github.com/voltbro/turtlebro_extra
cd ../
catkin_make --pkg=turtlebro_extra
```

#### Использование библиотеки команд

Для работы с роботом импортируйте класс `TurtleBro` из библиотекyи `turtlebro_py` в Python, и инстанцируйте этот класс с присвоением ему какого-то имени, например вот так:

```python
from turtlebro_py import TurtleBro
tb = TurtleBro()
```

Для движения робота вперед используйте команду `forward`, указав в качестве аргумента количество метров на которое вы хотите переместить робота:

```python
tb.forward(0.7)  #робот проедет вперед 0.7 метра
```

Для движения робота назад используйте команду `backward`, указав в качестве аргумента количество метров на которое вы хотите переместить робота:

```python
tb.backward(0.3)  #робот проедет назад 0.3 метра
```

Для поворота робота направо, (т.е. против часовой стрелки) используйте команду `right`, указав в качестве аргумента количество градусов на которое вы хотите повернуть робота

```python
tb.right(90)  #робот повернется против часовой стрелки на 90 градусов
```

Для поворота робота налево, (т.е. по часовой стрелке) используйте команду `left`, указав в качестве аргумента количество градусов на которое вы хотите повернуть робота

```python
tb.right(90)  #робот повернется по часовой стрелке на 90 градусов
```

Для того чтобы робот поехал на точку с координатами `x, y` (в метрах), используйте команду goto, указав в качестве аргументов `x` и `y`:

```python
tb.goto(0.5, 1)  #робот поедет на точку с координатами x = 0.5 м, y = 1 м.
```

При расчете координат используется правило правой руки.

Для получения текущих координат `x, y` (в метрах) в системе отсчета связанной с точкой на земле откуда стартовал робот, используйте переменную coords

```python
x,y = tb.coords  #робот присвоит в x, y значения своих текущих координат x, y 
```

При расчете координат используется правило правой руки.

Для включения светодиодов на роботе используйте команду `color`, указав в качестве аргумента цвет светодиодов (red, green, yellow, blue, white, off):

```python
tb.color("green")  #робот зажжет зеленые светодиоды
tb.color("red")  #робот зажжет красные светодиоды
tb.color("off")  #робот выключит светодиоды
```

Для определения расстояния до препятствия перед роботом используйте команду `distance`,

```python
dist = tb.distance() #Расстояние до препятствия "перед" роботом.
```

Для определения расстояния до препятствия находящегося на определенном углу, используйте команду `distance` с аргументом равным градусу по которому вы хотите получить расстояние до препятствия:

```python
dist = tb.distance(90) #Расстояние до препятствия "слева" от робота.
```

Опционально, вы можете указать аргумент = 360 для команды, тогда она вернет массив из 360 точек (по одной на градус) расстояний до препятствий вокруг робота.

```python
ranges = []
ranges = tb.distance(360)
```

Для получения изображения с камеры робота используйте команду `save_photo`:

```python
tb.save_photo() #Робот сохранит изображение в файл /home/pi/robophoto.jpg.
```

Опционально, вы можете указать имя файла в который надо сохранить изображение.

```python
tb.photo("myphoto")
```

Для получения изображения с камеры робота в виде массива `numpy` используйте переменную `photo`:

```python
photo = tb.photo #Робот сохранит изображение в виде массива numpy в переменную photo
```

Для записи звука с камеры робота используйте команду `record`:

```python
tb.record() #Робот сохранит 3-секунды записанного звука в файл /home/pi/turtlebro_sound.ogg
```

Опционально, вы можете указать время в течение которого записывать звук, а также имя файла в который надо сохранить запись

```python
tb.record(10, "mysound") #Робот будет записывать звук 10 секунд, и затем сохранит это в файл /home/pi/mysound.ogg
```

Для воспроизведения голосом какого-то текста из динамиков робота используйте команду `say`:

```python
tb.say("Однажды в студёную зимнюю пору...") #Робот воспроизведет фрагмент стихотворения Н.А.Некрасова
```

Для вызова написанной вами функции при нажатии на кнопку 24 используйте команду `call`:

```python
def myfunc():
    print("Hello from my function")

tb.call(myfunc) #при нажатии на кнопку 24, вызовется функция myfunc и выведет принт "Hello from my function"
```

Опционально, вы можете привязать по одной функции на каждую кнопку 22,23,24,25, для этого вызовите команду `call` с параметрами (имя\_функции, номер\_кнопки)

```python
def myfunc1():
    print("Hello from my function1")

def myfunc2():
    print("Hello from my function2")

tb.call(myfunc1, 24) #при нажатии на кнопку 24, вызовется функция myfunc1
tb.call(myfunc1, 25) #при нажатии на кнопку 25, вызовется функция myfunc2
```

Пример кода для езды по квадрату длиной 20 см, со скоростью 0.1 м/с и смены цвета диодов на каждой стороне квадрата:

```python
import turtlebro_py as tb

tb.color("green")
tb.move(0.2, 0.1)
tb.turn(90)

tb.color("red")
tb.move(0.2, 0.1)
tb.turn(90)

tb.color("yellow")
tb.move(0.2, 0.1)
tb.turn(90)

tb.color("blue")
tb.move(0.2, 0.1)
tb.turn(90)
```

#### Использование TurtleNav

Для ознакомления с базовой функциональностью автономной навигации в ROS можно использовать класс TurtleNav из данной библиотеки. Однако для того, чтобы использовать автономную навигацию, ее надо предварительно включить !на роботе! командой `roslaunch turtlebro_navigation turtlebro_slam_navigation.launch`

```python
from turtlebro_py import TurtleNav
tn = TurtleNav()
```

Основная команда, которая может использоваться для перемещения робота при помощи автономной навигации это `goto`, lля того чтобы робот поехал на точку с координатами `x, y` (в метрах), укажите в качестве аргументов `x` и `y`:

```python
tn.goto(0.5, 1)  #робот поедет на точку с координатами x = 0.5 м, y = 1 м.
```

При расчете координат используется правило правой руки. Обратите внимание, что теперь робот будет ехать по навигационным целям, при этом он, например, будет объезжать препятствия возникающие у него на пути. Кроме команды `goto`, вы можете использовать остальные команды передвижения (`forward, backward, left, right`) и все остальные команды типа `photo` или `say`