Часть 03, дополнение: базовые скрипты периферии и исходный код определения кнопок
Это дополнение к основному тексту главы 03 «Быстрый старт и базовая периферия». Основная глава провела читателя от включения платы к работе кнопок, веб-страниц и базовой периферии. Здесь мы отдельно разберём несколько самых ценных низкоуровневых скриптов, чтобы читатель перешёл от «умею запускать» к «понимаю и могу изменить».
Важно: приведённые фрагменты кода взяты из каталога на плате /userdata/magicbox/basic_function_demo/. Они не содержат всей логики готового продукта, а представляют собой минимальные примеры, которые производитель оставил в образе для обучения и проверки оборудования. Поэтому цель их чтения — понять, как именно каждое периферийное устройство обращается, инициализируется и управляется на плате, а не добиться сложности кода.
1. Скрипт сервоприводов: вход в управление PWM
servo.py — самый простой для понимания скрипт, и он лучше всего подходит для первого знакомства. Он напрямую использует Hobot.GPIO и открывает два вывода с поддержкой PWM, а затем выводит скважность с частотой 50 Гц, чтобы приводить в движение два сервопривода. Основной код:
output_pin = 32
output1_pin = 33
GPIO.setmode(GPIO.BOARD)
p = GPIO.PWM(output_pin, 50)
p1 = GPIO.PWM(output1_pin, 50)
p.ChangeDutyCycle(5)
p.start(5)
p1.ChangeDutyCycle(11)
p1.start(11)
Этот фрагмент содержит три ключевых сведения. Во-первых, управление сервоприводами на Magicbox — не «чёрный ящик», а стандартный PWM-выход. Во-вторых, пример использует режим нумерации BOARD, поэтому при изменении скрипта нужно убедиться, что используется номер вывода на плате, а не BCM. В-третьих, положение сервопривода в конечном счёте определяется скважностью, и если дальше жесты, голос или большая языковая модель вызывают физическое движение, то в итоге управление всё равно сводится к этому уровню.
Ценность скрипта не в том, что он «выполняется один раз и завершается». Он даёт базовую модель для всех последующих глав, связанных с движением: верхний уровень — жесты, голос или LLM, а нижний уровень всегда — управление PWM.
2. Скрипт ленты подсветки: почему WS2812B работает через SPI, а не через обычный GPIO
ws2812b.py показывает другой типичный способ управления периферией на плате. Временные требования WS2812B очень строгие, поэтому автор скрипта не пытается «продавить» их обычным переключением высокого и низкого уровня. Вместо этого каждый цветовой байт кодируется в поток битов SPI, и затем этот поток передаётся через spidev. Структура кода:
WS2812B_BIT_PATTERNS = {
0: [1, 0, 0],
1: [1, 1, 0],
}
self.spi = spidev.SpiDev()
self.spi.open(1, 0)
self.spi.max_speed_hz = spi_speed
self.spi.mode = 0
Из этого видно, что управление подсветкой Magicbox — это не просто «установить значение цвета», а отправка целиком закодированного потока времени через SPI на ленту. В скрипте есть ещё одна полезная деталь: WS2812B использует порядок байтов GRB, а не RGB, как предполагает большинство начинающих. Именно такие низкоуровневые детали легко пропустить, поэтому их стоит объяснять отдельно.
Если вы захотите подключить к Magicbox OpenClaw, nanobot или собственную логику «настольного питомца», этот скрипт оказывается самым естественным «мостом к подсветке». Удалённому помощнику не нужно знать протокол SPI: он просто вызывает локальный скрипт, а тот уже переводит цвет и тайминги в команды, которые понимает устройство.
3. Скрипт IMU: почему датчик положения читается через I2C
imu.py демонстрирует ещё один типичный путь работы с датчиком. Скрипт открывает шину I2C номер 5 через smbus2.SMBus(5), обращается к ICM20948 по адресу 0x68, читает регистры акселерометра и гироскопа, затем пересчитывает сырые значения в м/с² и рад/с:
ICM20948_ADDRESS = 0x68
bus = smbus2.SMBus(5)
ax = read_i2c_word(ACCEL_XOUT_H) * accel_scale
gy = read_i2c_word(GYRO_XOUT_H + 2) * gyro_scale
Этот фрагмент помогает увидеть разницу между тремя группами периферии. Сервоприводы управляются через PWM, подсветка — через SPI, IMU — через I2C. Magicbox подходит для мультимодальных задач не потому, что производитель упаковал все возможности в один унифицированный API, а потому, что сама плата уже предоставляет распространённые аппаратные интерфейсы. Когда вы это поймёте, не станете смешивать «восприятие» и «исполнение» в один тип управления — неважно, подключаете ли вы OpenClaw или пишете собственный автомат состояний для питомца.
4. Скрипт кнопок: он показывает подключение, но не заменяет системную точку входа
button.py легко понять неправильно. Многие видят, что скрипт отслеживает три вывода GPIO, и решают, что это и есть готовая реализация «трёх кнопок — трёх функций». На самом деле скрипт выполняет более базовую задачу: ждёт событий спада сигнала на трёх кнопках и печатает в терминал button1 OK, button2 OK, button3 OK. Основной код:
GPIO.setmode(GPIO.BCM)
GPIO.setup(pin1, GPIO.IN)
GPIO.setup(pin2, GPIO.IN)
GPIO.setup(pin3, GPIO.IN)
GPIO.wait_for_edge(self.pin1, GPIO.FALLING)
print("button1 OK")
Это больше похоже на скрипт проверки того, «подключены ли кнопки», а не на промышленный диспетчер. Поэтому в учебнике этот скрипт должен играть роль «помощника для понимания аппаратного пути», а не «точки входа системной демонстрации». Первый вопрос — «прочиталось ли нажатие кнопки», второй — «почему после нажатия запускаются глубина, жесты или голос». Эти два вопроса надо разделять, иначе читатель примет скрипт тестирования за фреймворк управления всей системой.
5. Как использовать это дополнение
Наиболее продуктивный способ — не заучивать четыре скрипта по строкам, а воспринимать их как образцы четырёх низкоуровневых интерфейсов. Если прикладному уровню нужно движение, обычно выполняется управление PWM. Если нужна световая обратная связь, обычно выполняется управление SPI. Если нужны данные о положении, обычно выполняется чтение I2C. Если физическая кнопка должна служить сигналом запуска или переключения, сначала нужно решить задачу прослушивания событий GPIO.
Когда такая картина понятна, Magicbox перестаёт быть просто «платой, на которой работают демо», и становится системой, которую можно дорабатывать, связывать с другими компонентами и переупорядочивать. Бинокулярные, жестовые и голосовые главы, а также главы о подключении OpenClaw строятся на этом понимании.