# Тема 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`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://voltbro.gitbook.io/turtlebro_py/tema-9-modul-turtlebro_py.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.