Бампер с 9 датчиками линий, FLASH-I2C, подключаем к Raspberry

Общие сведения:

Модуль - Бампер с 9 датчиками линий с шагом 14мм или шагом 7мм, I2C-flash - предназначен для установки на подвижные механизмы (машины, тракторы, танки, роботы) для их движения по линии без участия оператора. Модуль снабжен световой индикацией наличия линии и поворотниками.

Управление модулем осуществляется по шине I2C. Модуль относится к серии «Flash», а значит к одной шине I2C можно подключить более 100 модулей, так как их адрес на шине I2C (по умолчанию 0x09), хранящийся в энергонезависимой памяти, можно менять программно.

Модуль можно использовать в любых проектах где требуется организовать движение мобильных устройств без участия оператора.

Видео:

Редактируется ...

Спецификация:

• Напряжение питания: 3,3 В или 5 В (постоянного тока).
• Потребляемый ток: до 20 мА (все светодиоды включены).
• Расстояние от трассы до датчиков: от 2 до 50 мм.
• Максимальная скорость движения бампера (м/с): ширина линии (мм) / 3.
• Интерфейс: I2C.
• Скорость шины I2C: 100 кбит/с.
• Адрес на шине I2C: устанавливается программно (по умолчанию 0x09).
• Уровень логической 1 на линиях шины I2C: Vcc.
• Рабочая температура: от -20 до +70 °С.
• Габариты модуля с шагом 14мм: 119 x 25 мм (без креплений), 119 x 35 мм (с креплениями).
• Габариты модуля с шагом 7мм: 59 x 25 мм (без креплений), 59 x 35 мм (с креплениями).
• Вес: 10 г.

Модуль крепится на различные механизмы при помощи винтов M3 устанавливаемых в отверстия креплений бампера. При желании, некоторые (или все) крепления бампера можно удалить, для этого аккуратно согните ненужные крепления вверх или вниз.

Подключение:

Модуль подключается по шине I2C, все выводы которой (GND, Vcc, SDA, SCL) размещены на двух одинаковых колодках.

• SCL - вход/выход линии тактирования шины I2C.
• SDA - вход/выход линии данных шины I2C.
• Vcc - вход питания 3,3 или 5 В.
• GND - общий вывод питания.

Для подключения модуля можно использовать любую из двух колодок (верхнюю или нижнюю), а оставшуюся колодку можно применить для подключения второго бампера или иного модуля к шине I2C.

Модуль удобно подключать 2 способами, в зависимости от ситуации:

Способ - 1: Используя провода и Raspberry Pi

Используя провода «Мама — Мама», подключаем  напрямую к Raspberry Pi, согласно следующей таблице:

Вывод модуля	Вывод Raspberry
Vcc	3.3V
GND	GND
SDA	GPIO 23
SCL	GPIO 24

Способ - 2: Используя Trema+Expander Hat

Используя 4-х проводной шлейф, подключаем к Trema+Expander Hat.

Питание:

Входное напряжение питания модуля 3,3В или 5В постоянного тока (поддерживаются оба напряжения питания), подаётся на выводы Vcc и GND.

Подробнее о модуле:

Модуль построен на базе микроконтроллера STM32F030F4, снабжен собственным стабилизатором напряжения, имеет на борту 9 датчиков отражения (линий) и кнопку калибровки. Светодиодная индикация модуля позволяет определять наличие линий под датчиками - светодиод расположенный перед датчиком светится если под датчиком есть линия. Так же на модуле установлены светодиоды сигналов поворота.

Модуль позволяет:

• Изменить свой адрес на шине I2C, временно (пока есть питание) или постоянно.
• Получать аналоговые значения (АЦП) с датчиков линий.
• Получать цифровые значения с датчиков линий (есть линия под датчиком или нет).
• Выполнить калибровку для цветов линий и фона используемых на трассе.
• Узнать тип трассы для которой откалиброван модуль (трасса со светлой или тёмной линией).
• Изменить тип трассы (считать фон как линию, а линию как фон).
• Задать скорость мигания поворотников.
• Управлять поворотниками самостоятельно, или указать им работать в автоматическом режиме.

Специально для работы с модулем - Бампер с 9 датчиками линий с шагом 14мм или шагом 7мм, I2C-flash, нами разработана библиотека pyiArduinoI2Cbumper которая позволяет реализовать все функции модуля.

Для подключения библиотеки необходимо сначала её установить. Сделать это можно в менеджере модулей в Thonny или в терминале Raspberry, в виртуальной среде, командой:

pip install pyiArduinoI2Cbumper

Подробнее об установке библиотек можно узнать в этой статье.

Калибровка:

Калибровка модуля может быть запущена методами библиотеки pyiArduinoI2Cbumper, или нажатием на кнопку «калибровка».

Калибровка позволяет модулю отличать линии трассы от фона. Автоматическая калибровка состоит из двух этапов: чтение количества отражённого света от поверхности линии и чтение количества отражённого света от поверхности фона трассы. Результаты калибровки сохраняются в энергонезависимую память модуля, а значит модуль будет отличать линии от фона и после отключения питания.

Установите модуль так, что бы все его датчики находились над линией трассы и нажмите на кнопку «калибровка», или обратитесь к методу setCalibrationRun(). О начале калибровки сигнализирует включение левого поворотника и поочерёдное включение светодиодов расположенных перед датчиками линий, далее светодиоды отключатся, после чего все светодиоды начнут мигать в шахматном порядке, информируя о необходимости перехода к чтению фона трассы для завершения калибровки.

Установите модуль так, что бы все его датчики находились над фоном трассы и нажмите на кнопку «калибровка», или обратитесь к методу setCalibrationEnd(). О начале калибровки сигнализирует включение правого поворотника и поочерёдное включение светодиодов расположенных перед датчиками линий, далее светодиоды отключатся, после чего все светодиоды расположенные перед датчиками одновременно включатся на пол секунды или быстро мигнут три раза, информируя о результате калибровки.

Успех калибровки определяется модулем по контрасту между фоном и линией, при малой контрастности калибровка будет считаться неудачной, а её результаты не сохранятся в памяти модуля. Если калибровка закончилась провалом, то все светодиоды расположенные перед датчиками линий быстро мигнут три раза. Если калибровка закончилась успехом, то все светодиоды расположенные перед датчиками линий включатся на пол секунды. Так же о результате калибровки можно судить по флагам возвращаемым методами setCalibrationRun() и setCalibrationEnd(), или по значению статуса калибровки, возвращаемому методом getCalibrationStage().

В результате калибровки модуль не только сможет отличать линии от фона, но и определит тип трассы (трасса с тёмной линией на светлом фоне, или со светлой линией на тёмном фоне). Тип линии трассы можно узнать методом getLineType(). Если на трассе есть участки, где цвет линии меняется с цветом фона, то достаточно сменить тип линии трассы методом setLineType().

Смена адреса модуля на шине I2C:

В первой строке скрипта необходимо записать в переменную newAddress адрес, который будет присвоен модулю.  После этого подключите модуль к контроллеру и загрузите скрипт. Адрес может быть от 0х07 до 0х7F.

# Подключаем библиотеку для работы с бампером I2C-flash
from pyiArduinoI2Cbumper import *
import sys

# Объявляем объект module для работы с функциями и методами библиотеки pyiArduinoI2Cbumper.
# Если при объявлении объекта указать адрес, например, module(0x0B),
# то пример будет работать с тем модулем, адрес которого был указан.
module = pyiArduinoI2Cbumper(auto = NO_BEGIN, bus = "/dev/i2c-3")

# Если сценарию не были переданы аргументы
if len(sys.argv) < 2:
    # Назначаем модулю адрес (0x07 < адрес < 0x7F).
    newAddress = 0x09

# Иначе
else:
    # Новый адрес - первый аргумент
    newAddress = int(sys.argv[1])

# Если модуль найден
if module.begin():
    print("Найден модуль %#.2x" % module.getAddress())

    # Если адрес удалось изменить
    if module.changeAddress(newAddress):
            print("Адрес изменён на %#.2x" % module.getAddress())

    else:
            print("Адрес не изменён!")

else:
    print("Датчик не найден!")

Примеры:

В данном разделе раскрыты примеры работы модуля по шине I2C с использованием библиотеки pyiArduinoI2Cbumper.

Чтение линий под датчиками модуля:

# Пример чтения линий под датчиками бампера:                #
                                                            #
from time import sleep                                      #
from pyiArduinoI2Cbumper import *                           #   Подключаем библиотеку для работы с бампером I2C-flash.
bum = pyiArduinoI2Cbumper(address = 0x09, bus = "/dev/i2c-3")   #   Объявляем объект bum для работы с функциями и методами библиотеки pyiArduinoI2Cbumper, указывая адрес модуля на шине I2C.
                                                            #   Если объявить объект без указания адреса bum = pyiArduinoI2Cbumper(bus = "/dev/i2c-3"), то адрес будет найден автоматически.
while True:                                                 #
    print("Линия находится под датчиком:", end="")          #   Выводим текст.
    if bum.getLineDigital(1): print(" 1", end="")           #   Выводим номер 1 датчика, если под ним находится линия.
    if bum.getLineDigital(2): print(" 2", end="")           #   Выводим номер 2 датчика, если под ним находится линия.
    if bum.getLineDigital(3): print(" 3", end="")           #   Выводим номер 3 датчика, если под ним находится линия.
    if bum.getLineDigital(4): print(" 4", end="")           #   Выводим номер 4 датчика, если под ним находится линия.
    if bum.getLineDigital(5): print(" 5", end="")           #   Выводим номер 5 датчика, если под ним находится линия.
    if bum.getLineDigital(6): print(" 6", end="")           #   Выводим номер 6 датчика, если под ним находится линия.
    if bum.getLineDigital(7): print(" 7", end="")           #   Выводим номер 7 датчика, если под ним находится линия.
    if bum.getLineDigital(8): print(" 8", end="")           #   Выводим номер 8 датчика, если под ним находится линия.
    if bum.getLineDigital(9): print(" 9", end="")           #   Выводим номер 9 датчика, если под ним находится линия.
    print(".")                                              #   Завершаем строку.
    sleep(.2)                                               #

После загрузки данного примера, в мониторе последовательного порта будут появляться номера тех датчиков бампера, под которыми находится линия трассы.

Чтение аналоговых значений с датчиков модуля:

# Пример чтения аналоговых значений с датчиков линий:       #
                                                            #
from time import sleep
from pyiArduinoI2Cbumper import *                           #   Подключаем библиотеку для работы с бампером I2C-flash.
bum = pyiArduinoI2Cbumper(address = 0x09, bus = "/dev/i2c-3")   #   Объявляем объект bum для работы с функциями и методами библиотеки pyiArduinoI2Cbumper, указывая адрес модуля на шине I2C.
                                                            #   Если объявить объект без указания адреса bum = pyiArduinoI2Cbumper(), то адрес будет найден автоматически.
while True:                                                 #
    t = "Аналоговые значения датчиков 1-9: "\
        "{}, {}, {}, {}, {}, {}, {}, {}, {}".format(
            bum.getLineAnalog(1),                           #   Значение АЦП снятое с 2 датчика линии.
            bum.getLineAnalog(2),                           #   Значение АЦП снятое с 2 датчика линии.
            bum.getLineAnalog(3),                           #   Значение АЦП снятое с 3 датчика линии.
            bum.getLineAnalog(4),                           #   Значение АЦП снятое с 4 датчика линии.
            bum.getLineAnalog(5),                           #   Значение АЦП снятое с 5 датчика линии.
            bum.getLineAnalog(6),                           #   Значение АЦП снятое с 6 датчика линии.
            bum.getLineAnalog(7),                           #   Значение АЦП снятое с 7 датчика линии.
            bum.getLineAnalog(8),                           #   Значение АЦП снятое с 8 датчика линии.
            bum.getLineAnalog(9)                            #   Значение АЦП снятое с 9 датчика линии.
            )
    print(t)
    sleep(.2)

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

Аналоговыми значениями датчиков линий являются показания АЦП (аналого-цифрового преобразователя). Чем светлее объект находящийся под датчиком линий, тем выше показания АЦП. Оперируя аналоговыми значениями бампера, можно использовать трассы с разметками разных цветов.

Чтение ошибки центрирования линии для ПИД регулятора:

#   Подключаем библиотеку для работы с бампером I2C-flash.
from pyiArduinoI2Cbumper import *

#   Объявляем объект bum для работы с функциями и методами библиотеки pyiArduinoI2Cbumper,
#   указывая адрес модуля на шине I2C.
bum = pyiArduinoI2Cbumper(address = 0x09, bus = "/dev/i2c-3")

val_Speed   = ЗНАЧЕНИЕ                               #   Скорость движения машины.
pid_KP      = ЗНАЧЕНИЕ                               #   Коэффициент пропорциональной обратной связи ПИД регулятора.
pid_KI      = ЗНАЧЕНИЕ                               #   Коэффициент интегральной     обратной связи ПИД регулятора.
pid_KD      = ЗНАЧЕНИЕ                               #   Коэффициент дифференциальной обратной связи ПИД регулятора.
#   Список последних ошибок для формирования интегральной составляющей ПИД регулятора.
arr_ERR = [0,0,0,0,0,0,0,0,0,0]

#   Переменные для работы со списком последних ошибок «arr_ERR».
i = 0
j = 0

while True:

    #   Определяем значения переменных.
    i += 1
    i %= 10
    j=10

    #   Получаем текущую ошибку центрирования линии:
    #   Функция getErrPID() возвращает ошибку от 0 до ±4.5, где 0 - линия по центру,
    #   ±4.0 - линия на крайнем датчике, ±4.5 - линия потеряна.
    arr_ERR[i] = bum.getErrPID()

    #   Вычисляем все составляющие ПИД регулятора:
    #   Пропорциональная составляющая «pid_P» представлена величиной текущей ошибки «ARR_ERR[i]».
    pid_P = arr_ERR[i]
    pid_I = 0

    while j:

        j -= 1
        #   Интегральная составляющая «pid_I» представлена суммой последних
        #   ошибок взятых из массива «arr_ERR».
        pid_I += arr_ERR[j-1]

    #   Дифференциальная составляющая «pid_D» представлена разницей между
    #   текущей «ARR_ERR[i]» и предыдущей «arr_ERR[(i+9)%10]» ошибкой.
    pid_D = arr_ERR[i] - arr_ERR[(i + 9) % 10]

    #   Вычисляем результат ПИД регулирования.
    PID   = pid_P * pid_KP + pid_I * pid_KI + pid_D * pid_KD

    #   Устанавливаем скорость вращения колёс:
    setSpeedL( val_Speed + PID )
    setSpeedR( val_Speed - PID )

Данный скрипт демонстрирует возможность получения ошибки центрирования линии getErrPID(), для движения машины по линии с использованием ПИД регулятора.

Для работы скрипта необходимо указать скорость val_Speed, коэффициенты обратной связи ПИД регулятора (pid_KP, pid_KI, pid_KD) и определить функции управления моторами setSpeedL() и setSpeedR().

Управление поворотниками:

from time import sleep

#   Подключаем библиотеку для работы с бампером I2C-flash.
from pyiArduinoI2Cbumper import *

#   Объявляем объект bum для работы с функциями и методами библиотеки
#   pyiArduinoI2Cbumper, указывая адрес модуля на шине I2C.
#   Если объявить объект без указания адреса bum = pyiArduinoI2Cbumper(),
#   то адрес будет найден автоматически.
bum = pyiArduinoI2Cbumper(address = 0x09, bus = "/dev/i2c-3")

# Задаём скорость мигания поворотников в 400мс.
# Возможные значения: BUM_TURN_100, BUM_TURN_200, BUM_TURN_400 и BUM_TURN_800.
bum.setTurnPeriod(BUM_TURN_400)

while True:

    #   Включаем левый поворотник.
    bum.setTurnSignal(BUM_TURN_LEFT)
    sleep(5)

    #   Включаем правый поворотник.
    bum.setTurnSignal(BUM_TURN_RIGHT)
    sleep(5)

    #   Включаем поворотниками аварийный сигнал.
    bum.setTurnSignal(BUM_TURN_EMERGENCY)
    sleep(5)

    #   Включаем поворотники в полицейский режим.
    bum.setTurnSignal(BUM_TURN_POLICE)
    sleep(5)

    #   Отключаем поворотники.
    bum.setTurnSignal(BUM_TURN_OFF)
    sleep(5)

После загрузки данного примера, постоянно, будут выполняться следующие действия:

• 5 секунд мигает левый поворотник
• 5 секунд мигает правый поворотник
• 5 секунд мигают оба поворотника - аварийный сигнал
• 5 секунд поворотники работают в режиме полицейской машины
• 5 секунд поворотники не мигают.

Калибровка модуля:

from time import sleep

#   Подключаем библиотеку для работы с бампером I2C-flash.
from pyiArduinoI2Cbumper import *
#   Объявляем объект bum для работы с функциями и методами библиотеки pyiArduinoI2Cbumper, указывая адрес модуля на шине I2C.
bum = pyiArduinoI2Cbumper(address = 0x09, bus = "/dev/i2c-3")

print("Установите бампер над линией трассы")
print("У Вас есть 5 секунд...\r\n")

sleep(5)
print("Запускаем калибровку.")
print("Ждите...\r\n")

#   Запускаем калибровку.
f = bum.setCalibrationRun()

if f == True:
    print("Линия считана!")
else:
    print("Ошибка!.")
    exit()

print("------------")
sleep(1)
print("Установите бампер над фоном трассы")
print("У Вас есть 5 секунд...\r\n")

sleep(5)
print("Завершаем калибровку.")
print("Ждите...\r\n")

#   Завершаем калибровку.
f = bum.setCalibrationEnd()

if f == True:
    print("Фон считан!")
else:
    print("Ошибка!.")
    exit()

print("------------")
sleep(1)
print("Калибровка успешно завершена!")

# Получаем тип линии.
if bum.getLineType() == BUM_LINE_BLACK:
    line = " тёмной линией на светлом фоне."
else:
    line = "о светлой линией на тёмном фоне."

print(
    "Бампер откалиброван для трассы с {}"
    "".format(line)
    )
print("============")

После загрузки данного примера, в мониторе последовательного порта, появится текст предлагающий установить модуль так, что бы все его датчики находились над линией трассы.

Через 5 секунд произойдёт обращение к функции setCalibrationRun() которая запустит калибровку и модуль считает данные с датчиков. Функция может выполняться до 5 секунд, после чего в мониторе появится результат чтения линий.

Далее, в мониторе последовательного порта, появится текст предлагающий установить модуль так, что бы все его датчики находились над фоном трассы.

Через 5 секунд произойдёт обращение к функции setCalibrationEnd() которая инициирует завершение калибровки и модуль считает данные с датчиков. Функция может выполняться до 5 секунд, после чего в мониторе появится результат чтения фона.

Если при выполнении всего скрипта в мониторе не появилась надпись «Ошибка!», значит модуль откалиброван и способен отличать линии данной трассы от фона.

Вместо обращения к функциям setCalibrationRun() и setCalibrationEnd(), на любом этапе калибровки, можно просто нажать на кнопку «калибровка».

Автоматическая смена типа линии на трассе:

#   Подключаем библиотеку для работы с бампером I2C-flash.
from pyiArduinoI2Cbumper import *
#   Объявляем объект для работы с функциями и методами
#   библиотеки pyiArduinoI2Cbumper, указывая адрес модуля на шине I2C.
bum = pyiArduinoI2Cbumper(address = 0x09, bus = "/dev/i2c-3")

while True:
    b = bum.getLineSum()
    if b > 4:
        bum.setLineType(BUM_LINE_CHANGE)

Данный пример сменит тип линии трассы если более 4 датчиков бампера одновременно фиксируют линию. Это значит, что если ширина линии используемой вами трассы уже чем расстояние между 4 датчиками, то скрипт будет корректно определять линию, даже если на трассе есть места где цвет линии меняется с цветом фона.

Описание функций библиотеки:

В данном разделе описаны функции библиотеки pyiArduinoI2Cbumper

Подключение библиотеки:

• Если адрес модуля известен (в примере используется адрес 0x09):

#   Подключаем библиотеку для работы с бампером I2C-flash.
from pyiArduinoI2Cbumper import *

# Создаём объект bum для работы с функциями и методами библиотеки iarduino_I2C_Bumper, указывая адрес модуля на шине I2C.
bum = pyiArduinoI2Cbumper(address = 0x09, bus = "/dev/i2c-3")

• Если адрес модуля неизвестен (адрес будет найден автоматически):

#   Подключаем библиотеку для работы с бампером I2C-flash.
from pyiArduinoI2Cbumper import *   

# Создаём объект bum для работы с функциями и методами библиотеки iarduino_I2C_Bumper.
bum = pyiArduinoI2Cbumper(bus = "/dev/i2c-3")         

При создании объекта без указания адреса, на шине должен находиться только один модуль.

Функция begin()

• Назначение: Инициализация работы с модулем.
• Синтаксис: begin()
• Параметры: Нет.
• Возвращаемое значение: - результат инициализации (True или False).
• Примечание: По результату инициализации можно определить наличие модуля на шине.
• Пример:

if bum.begin():
    print( "Модуль найден и инициирован!" )
else:
    print( "Модуль не найден на шине I2C" )

Функция reset()

• Назначение: Перезагрузка модуля.
• Синтаксис: reset()
• Параметры: Нет.
• Возвращаемое значение: - результат перезагрузки (True или False).
• Пример:

if bum.reset():
    print( "Модуль    перезагружен" )
else:
    print( "Модуль не перезагружен" )

Функция changeAddress()

• Назначение: Смена адреса модуля на шине I2C.
• Синтаксис: changeAddress( АДРЕС )
• Параметр: АДРЕС - новый адрес модуля на шине I2C (целое число от 0x08 до 0x7E)
• Возвращаемое значение: - результат смены адреса (True или False).
• Примечание: Текущий адрес модуля можно узнать функцией getAddress().
• Пример:

if bum.changeAddress(0x12):
    print( "Адрес модуля изменён на 0x12" )
else:
    print( "Не удалось изменить адрес"    )

Функция getAddress()

• Назначение: Запрос текущего адреса модуля на шине I2C.
• Синтаксис: getAddress()
• Параметры: Нет.
• Возвращаемое значение: АДРЕС - текущий адрес модуля на шине I2C (от 0x08 до 0x7E)
• Примечание: Функция может понадобиться если адрес модуля не указан при создании объекта, а обнаружен библиотекой.
• Пример:

print( "Адрес модуля на шине I2C = %#.2x" % module.getAddress())

Функция getVersion()

• Назначение: Запрос версии прошивки модуля.
• Синтаксис: getVersion()
• Параметры: Нет
• Возвращаемое значение: ВЕРСИЯ - номер версии прошивки от 0 до 255.
• Пример:

print( "Версия прошивки модуля {}".format( bum.getVersion() )

Функция setTurnSignal()

• Назначение: Указание режима работы поворотников.
• Синтаксис: setTurnSignal( РЕЖИМ )
• Параметр: РЕЖИМ работы поворотников, может принимать следующие значения:
  • BUM_TURN_OFF - поворотники отключены.
  • BUM_TURN_LEFT - включён (мигает) левый поворотник.
  • BUM_TURN_RIGHT - включён (мигает) правый поворотник.
  • BUM_TURN_EMERGENCY - поворотники работают в режиме аварийного сигнала.
  • BUM_TURN_POLICE - поворотники работают в режиме полицейской машины.
  • BUM_TURN_AUTO - поворотники работают в автоматическом режиме.
• Возвращаемое значение: - результат применения нового режима (True или False).
• Примечание: Параметры автоматического режима задаются функцией settingsTurnAuto().
• Пример:

bum.setTurnSignal(BUM_TURN_LEFT ) # Включить только левый  поворотник.
bum.setTurnSignal(BUM_TURN_RIGHT) # Включить только правый поворотник.

Функция setTurnPeriod()

• Назначение: Указание периода мигания поворотников.
• Синтаксис: setTurnPeriod( ПЕРИОД )
• Параметр: ПЕРИОД мигания поворотников, может принимать следующие значения:
  • BUM_TURN_100 - период мигания равен 100мс (10Гц) 50мс вкл / 50мс выкл.
  • BUM_TURN_200 - период мигания равен 200мс (5Гц) 100мс вкл / 100мс выкл.
  • BUM_TURN_400 - период мигания равен 400мс (2,5Гц) 200мс вкл / 200мс выкл.
  • BUM_TURN_800 - период мигания равен 800мс (1,25Гц) 400мс вкл / 400мс выкл.
• Возвращаемое значение: - результат применения нового периода (True или False).
• Примечание: Функцию можно вызывать как до включения поворотников, так и во время их работы.
• Пример:

bum.setTurnPeriod(BUM_TURN_800) # Задать период мигания поворотников равен 800 мс.

Функция settingsTurnAuto()

• Назначение: Указание условий работы поворотников в автоматическом режиме.
• Синтаксис: settingsTurnAuto( ВКЛ , ВЫКЛ [, ФЛАГ] )
• Параметры:
• ВКЛ - условие включения поворотников, может принимать следующие значения:
• BUM_AUTO_ON_1 - Линия под любым из двух самых крайних датчиков.
• BUM_AUTO_ON_2 - Линия под любым из трёх самых крайних датчиков.
• BUM_AUTO_ON_3 - Линия под любым из четырёх датчиков со стороны поворотника.
• ВЫКЛ - условие отключения поворотников, может принимать следующие значения:
• BUM_AUTO_OFF_CEN - Под центральным датчиком есть линия.
• BUM_AUTO_OFF_ANY - Линия есть под любым датчиком кроме указанных в условии включения.
• ФЛАГ - значение True или False указывающее добавить 2 мигания перед отключением. Данный параметр является необязательным, если он не указан, значит ФЛАГ = False.
• Возвращаемое значение: - результат применения новых настроек (True или False).
• Примечание: Функцию можно вызывать как до включения поворотников, так и во время их работы в автоматическом режиме.
• Пример:

bum.settingsTurnAuto(BUM_AUTO_ON_2, BUM_AUTO_OFF_ANY, True) # Условие работы поворотников в автоматическом режиме.

Разбор примера:

В условии включения указан параметр BUM_AUTO_ON_2, значит поворотник будет включаться когда линия находится под любым из трёх самых крайних датчиков со стороны поворотника.

• Для левого поворотника это датчики № 1, 2 и 3.
• Для правого поворотника это датчики № 7, 8 и 9.

В условии отключения указан параметр BUM_AUTO_OFF_ANY, значит поворотник будет отключаться если линия находится под любым датчиком (или датчиками) бампера, при условии что не соблюдается условие для включения этого поворотника.

В качестве третьего (необязательного) параметра указано значение True, значит при наступлении условия отключения поворотника он выключится не сразу, а спустя 2 мигания.

Функция setCalibrationRun()

• Назначение: Запуск автоматической калибровки модуля.
• Синтаксис: setCalibrationRun()
• Параметры: Нет.
• Возвращаемое значение: - результат запуска калибровки (True или False).
• Примечание:
  • Обращение к данной функции равносильно первому нажатию на кнопку «калибровка».
  • Во время выполнения функции все датчики должны находиться над линией трассы.
  • Запуск автоматической калибровки приводит к началу чтения показаний АЦП со всех датчиков линий, этот процесс занимает до 5 секунд.
  • По завершению чтения показаний датчиков, модуль перейдёт в стадию ожидания завершения калибровки. Инициировать завершение калибровки можно нажатием на кнопку «калибровка» или обращением к функции setCalibrationEnd().
• Пример:

bum.setCalibrationRun() # Начать калибровку.

Функция setCalibrationEnd()

• Назначение: Завершение автоматической калибровки модуля.
• Синтаксис: setCalibrationEnd( [ ФЛАГ ] )
• Параметр: ФЛАГ - значение True указывает на то что датчики требуется откалибровать не по отдельности, а определить одно общее значение для всех датчиков.
• Возвращаемое значение: - результат инициализации завершения калибровки (True или False).
• Примечание:
  • Обращение к данной функции равносильно второму нажатию на кнопку «калибровка».
  • Во время выполнения функции все датчики должны находиться над фоном трассы.
  • Инициализация завершения автоматической калибровки приводит к началу чтения показаний АЦП со всех датчиков линий, этот процесс занимает до 5 секунд.
  • По завершению чтения показаний датчиков, модуль рассчитает граничные значения АЦП датчиков между фоном и линией трассы, определит тип линии трассы и сохранит результаты в энергонезависимую память.
  • Если функция вызвана без параметра (или с параметром False), то модуль рассчитает граничные значения АЦП для каждого датчика в отдельности (как при нажатии на кнопку «калибровка»).
  • Если функция вызвана с параметром True, то модуль рассчитает общее граничное значение АЦП, одинаковое для всех датчиков (может помочь при сильной боковой засветке трассы).
  • По сохранённым граничным значениям АЦП (между линией и фоном) модуль будет определять наличие линии под датчиками.
  • Более подробно про граничные значения АЦП рассказано в пояснении к ручной калибровке.
• Пример:

bum.setCalibrationEnd() # Завершить калибровку.

Функция setCalibrationManual()

• Назначение: Выполнение ручной калибровки модуля.
• Синтаксис: setCalibrationManual( АЦП [, АЦП, АЦП, АЦП, АЦП, АЦП, АЦП, АЦП, АЦП ] )
• Параметры:
  • АЦП - число (0...4095) соответствующее граничному значению АЦП датчика.
• Возвращаемое значение: - результат записи калибровочных значений (True или False).
• Примечание:
  • Функция принимает 9 граничных значений АЦП для каждого датчика модуля, или одно граничное значение АЦП для всех датчиков модуля.
  • Граничное значение АЦП является средним значением между АЦП датчика для линии и АЦП датчика для фона.
  • АЦП любого датчика, для линии и фона, можно получить функцией getLineAnalog().
  • Указанные значения сохраняются в энергонезависимую память модуля и используются им в последствии для определения наличия линий под датчиками.
  • При ручной калибровке, помимо указания значений АЦП, может понадобится указание типа используемой линии при помощи функции setLineType().
• Пример:

bum.setCalibrationManual( 700 )                                          # Применить граничное значение 700 для всех датчиков модуля.
bum.setCalibrationManual( 710, 770, 750, 899, 900, 700, 800, 650, 1000 ) # Применить граничное значение 710 для 1 датчика, 770 для второго и т.д.

Пояснение ручной калибровки:

• Предположим что нами используется трасса с тёмной линией на светлом фоне, это можно указать модулю обратившись к функции setLineType( BUM_LINE_BLACK )
• Предположим что при помощи функции getLineAnalog( 1 ) мы выяснили, что АЦП первого датчика для линии равно 500, а для фона 2500. Значит граничное значение АЦП для первого датчика равно 1500 (среднее значение). Аналогичным образом рассчитываются граничные значения АЦП для остальных датчиков.
• После выполнения ручной калибровки, модуль будет знать что граничное значение АЦП первого датчика равно 1500. Так как мы указали модулю, что линия трассы темнее её фона, то все значения датчика ниже граничного, модуль будет воспринимать как линия, а выше граничного - как фон. Чем светлее поверхность под датчиком, тем выше значение АЦП.
• Стоит учесть что зона в ±30 значений АЦП возле границы является гистерезисом.

Функция getCalibrationStage()

• Назначение: Получение текущего статуса автоматической калибровки.
• Синтаксис: getCalibrationStage()
• Параметры: Нет.
• Возвращаемое значение: СТАТУС - одно из возможных значений:
  • BUM_STAGE_READ_LN - выполняется чтение АЦП с датчиков над линией трассы.
  • BUM_STAGE_WAITING - модуль ожидает поступления команды на чтение фона.
  • BUM_STAGE_READ_BG - выполняется чтение АЦП с датчиков над фоном трассы.
  • BUM_STAGE_OFF_ERR - калибровка завершена провалом.
  • BUM_STAGE_OFF_OK - калибровка завершена успехом.
• Примечание:
  • Функцию можно использовать для контроля выполнения и результата автоматической калибровки, запускаемой как функциями, так и нажатием кнопки «калибровка».
  • В примере Arduino IDE: Файл / Примеры / iarduino I2C Bumper (бампер) / controlCalibrationButton показан пример контроля за ходом выполнения калибровки с кнопки.
• Пример:

if bum.getCalibrationStage() == BUM_STAGE_OFF_OK:
    print("Калибровка выполнена успешно")

Функция getLineDigital()

• Назначение: Чтение линий под датчиками модуля.
• Синтаксис: getLineDigital( НОМЕР )
• Параметр: НОМЕР датчика, может принимать значение от 1 до 9.
• Возвращаемое значение: - флаг наличия линии под датчиком (True или False).
• Примечание:
  • Если в качестве параметра НОМЕР указать не число, а значение BUM_LINE_ALL, то функция вернёт не флаг, а число состоящее из 9 бит, где каждый бит (кроме нулевого) является флагом наличия линии под датчиком, номер которого совпадает с номером бита.
• Пример:

i = bum.getLineDigital( 5 )           # Если под 5 датчиком есть линия, то i = True.

Функция getLineAnalog()

• Назначение: Чтение значений АЦП снятых с датчиков модуля.
• Синтаксис: getLineAnalog( НОМЕР )
• Параметр: НОМЕР датчика, может принимать значение от 1 до 9.
• Возвращаемое значение: - число от 0 до 4096 соответствующее значению АЦП датчика.
• Примечание:
  • Обращение к функции позволяет получить значение АЦП того датчика номер которого был указан в качестве параметра.
  • Чем светлее поверхность под датчиком, тем выше значение АЦП.
• Пример:

i = bum.getLineAnalog( 5 ) # Получить значение АЦП с 5 датчика в переменную i.

Функция getErrPID()

• Назначение: Чтение ошибки центрирования линии для ПИД регулятора.
• Синтаксис: getErrPID()
• Параметры: Нет.
• Возвращаемое значение: - число от 0 до ±4,5.
• Примечание:
• Обращение к функции позволяет получить ошибку центрирования линии.
• Функция возвращает отрицательные значения если линия находится левее центра.
• Функция возвращает положительные значения если линия находится правее центра.
  • 0 - нет ошибки, линия находится под центральным датчиком бампера.
  • ±0,5 - линия находится между центральным и соседним с ним датчиком.
  • ±1.0 - линия находится под датчиком соседним с центральным.
  • ±3.5 - линия находится между самым крайним и соседним с ним датчиком.
  • ±4.0 - линия находится под самым крайним датчиком.
  • ±4.5 - линия потеряна, знак указывает на сторону потери линии.
• Функция позволяет работать с линиями ширина которых находится в диапазоне от 1 до 7 дистанций между датчиками линий.
• Пример:

i = bum.getErrPID() # Получить ошибку центрирования линии в переменную i.

Функция getLineSum()

• Назначение: Запрос количества датчиков находящихся над линией.
• Синтаксис: getLineSum( [ПЕРЕМЕННАЯ] )
• Параметр: ПЕРЕМЕННАЯ для получения флагов наличия линий.
• Возвращаемое значение: - число от 0 до 9 соответствующее количеству датчиков находящихся над линией.
• Примечание:
  • Данная функция позволяет получить не только количество датчиков находящихся над линией (в качестве возвращаемого значения), но и флаги наличия линий (если в качестве необязательного параметра указана переменная для получения этих флагов).
  • Флаги возвращаемые параметру соответствуют значению возвращаемому функцией getLineDigital( BUM_LINE_ALL ).
• Пример:

i = bum.getLineSum( )       # Получить количество датчиков которые находятся над линией.
a = 0
i, j = bum.getLineSum(a)    # «i» получает количество датчиков над линией, а «j» получает флаги наличия линий под датчиками, как если написать j=getLineDigital(BUM_LINE_ALL).

Функция getLineType()

• Назначение: Запрос типа линии трассы для которой откалиброван модуль.
• Синтаксис: getLineType()
• Параметры: Нет.
• Возвращаемое значение: - ТИП лини, может принимать следующие значения:
  • BUM_LINE_BLACK - модуль откалиброван для трассы с тёмной линией на светлом фоне.
  • BUM_LINE_WHITE - модуль откалиброван для трассы со светлой линией на тёмном фоне.
• Пример:

if bum.getLineType() == BUM_LINE_BLACK:
    print("Трасса с  тёмной  линией")
else:
    print("Трасса со светлой линией")

Функция setLineType()

• Назначение: Установка типа линии трассы.
• Синтаксис: setLineType( ТИП )
• Параметры: ТИП лини, может принимать следующие значения:
  • BUM_LINE_BLACK - указать модулю что трасса использует тёмную линию.
  • BUM_LINE_WHITE - указать модулю что трасса использует светлую линию.
  • BUM_LINE_CHANGE - изменить тип линии трассы на противоположный.
• Возвращаемое значение: - результат записи нового типа линии в модуль (True или False).
• Примечание:
  • Тип используемой линии сохраняется в энергонезависимую память модуля, а значит модуль будет работать с данным типом трассы и после отключения питания.
  • Функцию удобно использовать с параметром BUM_LINE_CHANGE, если на трассе есть участки, где цвет линии и фона резко меняют друг друга.
• Пример:

bum.setLineType(BUM_LINE_BLACK) # Указываем модулю что на трассе используется тёмная линия на светлом фоне.

Функция changeBus()

• Назначение: смена шины I2C
• Синтаксис: changeBus( ПУТЬ К ФАЙЛУ ШИНЫ )
• Параметр:
  • ПУТЬ К ФАЙЛУ ШИНЫ - строка
• Возвращаемые значения: Нет.
• Пример:

# Меняем шину 
bum.changeBus("/dev/i2c-3")

Ссылки:

• Бампер с 9 датчиками линий с шагом 14мм, FLASH-I2C.
• Бампер с 9 датчиками линий с шагом 7мм, FLASH-I2C.
• Wiki - Бампер с 9 датчиками линий, I2C-Flash - Datasheet.