JavaScript:Библиотеки/p5.bots
|
Черновик |
p5.bots[1]
Эта библиотека предназначена для упрощения коммуникации между p5.js в браузере и микроконтроллером, работающем на Firmata.
Примечания:
- Библиотека p5.bots была протестирована на Arduino Uno, но должна быть совместима с любыми устройствами, работающими на Firmata
- API для последовательной коммуникации никак от Firmata не зависит
Библиотека p5.bots использует библиотеку socket.io и платформу node.js, чтобы отправлять сообщения между двумя устройствами на языке, который понимают оба этих устройства.
Таким образом, вы можете кликнуть на скетч, чтобы зажечь светодиод, или наоборот, использовать температурные данные для управления происходящем в скетче и т.д.
Для работы с p5.bots необходимы два набора файлов: клиентский файл «p5bots.js», который вместе с «p5.js» нужно подключить в файле «index.html», и серверные файлы «p5bots-server», которые можно загрузить с npm.
Библиотека p5.bots распространяется по лицензии LGPL.
p5.Serial
В библиотеке p5.bots есть метод p5.serial(), который можно использовать вместе со скетчем Arduino, прослушивающим последовательный порт. Все это работает примерно так же, как библиотека Serial для Processing.
Более подробно об этом модуле читайте ниже, в подразделе «Методы для коммуникации через последовательный порт» раздела «Другие специальные методы».
Если вы для коммуникации используете только последовательный порт, то Firmata на плату устанавливать не нужно.
p5.Board
Большая часть функционала p5.bots содержится в классе p5.board. Он многое заимствует у фреймворка Johnny-Five и имеет несколько методов для работы с цифровыми и аналоговыми устройствами, методы для чтения/записи ШИМ, а также методы, предназначенные специально для работы с различными электротехническими компонентами. Более подробно о них читайте ниже. Скетчи-примеры и схемы подключения смотрите по этой ссылке.
С чего начать
Вот материалы, которые помогут побыстрее разобраться, что к чему:
- Вводное руководство «Привет, мир!»
- Проекты-примеры (например, для работы с RGB-светодиодами), демонстрирующие использование p5.bots вместе с функциями p5.js
- Справочник по клиентскому API с описанием функций для использования в p5-коде (там же можно найти подробное руководство по настройке библиотеки)
- Руководство по настройке и тестированию серверной части
- Сайт с руководством и документацией по библиотеке p5.js, предназначенной для рисования графики и текстов в окне браузера
Проблемы
О проблемах сообщайте сюда.
Вклад
Хотите исправить найденную проблему? Хотите добавить новую функцию, которой еще нет? Загляните сюда.
Использование p5.bots вместе с p5.js
Базовые функции
Чтобы начать коммуникацию с устройством, вам нужно для начала инициализируем плату и как минимум один контакт. Для этого сначала вызовите функцию p5.board(). Она вернет объект платы, на котором в дальнейшем можно использовать функцию pin() для инициализации контакта. Созданный таким образом объект поддерживает не только pin(), но и другие функции.
Инициализация платы
// возвращает указатель на объект платы:
p5.board(port, type)
Здесь параметр «port» – значение типа String, обозначающее, соответственно, порт для подключения (о том, как определить порт, читайте в начале этой статьи). Параметр «type» – это тип платы (например, «arduino»).
Инициализация контакта
Теперь, когда у нас есть плата, мы можем создать контакт. Нам понадобится по крайней мере один контакт, чтобы программа знала, куда отправлять информацию. Эту функцию можно задавать со всеми возможными параметрами («num», «mode» и «direction») или только с одним («num»). Она возвращает указатель к объекту контакта, поддерживающему несколько разных методов (подробнее о них – ниже). Вот пример вызова pin() со всеми возможными параметрами:
// возвращает указатель к объекту контакта:
board.pin(num, mode, direction)
Здесь параметр «num» – это номер контакт, «mode» – режим работы контакта («digital» или «цифровой режим», «analog» или «аналоговый режим» и «pwm» или «ШИМ»), а «direction» – это направление передачи информации («input» или ввод данных и «output» или вывод данных).
Вот пример вызова pin() только с параметром «num»:
// сокращенный вариант инициализации контакта:
pin = board.pin(num)
Константы
Выше было показано, как параметры вроде типа платы или направления передачи информации задаются с помощью строк вроде «DIGITAL». Но это также можно сделать при помощи констант вроде «b.HIGH». Библиотека p5.bots поддерживает использование следующих констант:
// значения:
board.HIGH
board.LOW
// направление:
board.INPUT
board.OUTPUT
// базовые режимы работы контакта:
board.ANALOG
board.DIGITAL
board.PWM
// специальные режимы работы контакта:
board.SERVO
board.BUTTON
board.KNOCK
board.LED
board.MOTOR
board.PIEZO
board.RGBLED
board.TEMP
board.TONE
board.VRES
Базовые методы для работы с контактами
Все контакты имеют методы для считывания и записи данных. Эти базовые методы иногда заменяются специальными методами, предназначенными для какого-то специального режима.
Метод write() всегда отправляет значение на контакт. Если контакту задан режим «input» (режим ввода данных), то отправленное значение может выставить этот контакт в положение «HIGH» или «LOW». Принцип работы метода read() в библиотеке p5.bots отличается от того, как он работает в языках Arduino и Processing. Он не возвращает значение напрямую, а принимает функцию обратного вызова, запускаемую при каждом изменении значения. Кроме того, с каждым изменением значения p5.bots меняет значение в свойстве «pin.val», но это асинхронная операция и потому будет выполняться, возможно, с маленькой задержкой.
// с каждым изменением значения будет обновляться свойство «pin.val»,
// а также вызываться опциональная функция обратного вызова:
pin.read([callback fn])
// отправляем значение на контакт:
pin.write(val)
Пример:
// при каждом изменении значения пишем его в консоль:
p.read(function(val){console.log(val);});
Специальные методы для записи данных
При использовании специальных методов направление передачи данных указывать не нужно.
Методы для работы со светодиодами
Вдобавок к чтению/записи светодиоды можно включать/выключать, мигать ими, а также постепенно увеличивать/уменьшать их яркость.
// инициализирует контакт для работы со светодиодом:
led = board.pin(num, 'LED')
// базовые функции чтения/записи,
// работающие на любом другом контакте:
led.write()
led.read()
// запись значений «HIGH» и «LOW»:
led.on()
led.off()
// запускает мигание;
// в параметре «duration» задается, как долго светодиод
// будет оставаться включенным/выключенным (в миллисекундах):
led.blink(duration)
// останавливает мигание:
led.noBlink()
// увеличивает или уменьшает яркость светодиода;
// в параметре «start» задается начальный уровень яркости,
// а в параметре «stop» – конечный уровень яркости;
// яркость – это ШИМ в диапазоне от «0» до «255»;
// время задается в миллисекундах;
// значение по умолчанию в параметре «total time» - 3000,
// а в параметре «interval» – 200:
led.fade([start, stop, [, total time, interval]])
Методы для работы с RGB-светодиодами
Как и обычные светодиоды, RGB-светодиоды можно включать/выключать, мигать ими, а также уменьшать/увеличивать их яркость. При инициализации контакта в первом параметре задается ассоциативный массив или объект с номерами контактов для каждого цвета, а также информация о типе светодиода.
// инициализируем контакт
// при помощи ассоциативного массива
// с настройками для RGB-светодиода:
rgb = board.pin({ r: int, g: int, b: int, common: 'anode' || 'cathode' }, 'RGBLED');
// при помощи этих методов осуществляется
// запись/считывание данных о цветах RGB-светодиода:
rgb.write()
rgb.read()
Метод write() принимает либо объект p5.Color, либо массив из трех чисел в диапазоне между «0» и «255», с помощью которых задаются цвета RGB-светодиода.
К примеру, вот три разных варианта, задающих для RGB-светодиода один и тот же цвет:
var c = color(255, 204, 0);
rgb.write(c);
colorMode(hsla);
var h = color(48, 100, 50);
rgb.write(h);
var a = [255, 204, 0];
rgb.write(a);
Методы on() и off() переключают состояние контакта между значениями «HIGH» и «LOW». При выключении RGB-светодиода его цветовое значение сохраняется.
// включает RGB-светодиод,
// заставляя его загореться прежним или белым цветом:
rgb.on()
// задает для контакта значение «LOW», но сохраняет прежний цвет:
rgb.off()
// запускает мигание,
// в параметре «duration» задается,
// как долго RGB-светодиод будет находиться в положении вкл/выкл:
rgb.blink(duration)
// останавливает мигание (довольно забавным способом):
rgb.noBlink()
// задает яркость трех компонентов RGB-светодиода;
// начальный уровень яркости задается в параметре «start»,
// а конечный уровень яркости – в параметре «stop»;
// яркость – это ШИМ в диапазоне от «0» до «255»;
// время задается в миллисекундах;
// значения по умолчанию в «total time» – 3000, в «interval» - 200;
// каждый контакт RGB-светодиода задается отдельно:
rgb.fade([start, stop, [, total time, interval]], [start, stop, [, total time, interval]], [start, stop, [, total time, interval]])
Методы для работы с мотором
// инициализирует контакт для работы с мотором:
motor = board.pin(num, 'MOTOR')
// эти два метода задают
// самую высокую и самую низкую скорости мотора:
motor.start()
motor.stop()
// задает скорость для мотора;
// она задается в ШИМ в диапазоне между «0» и «255»:
motor.write(int)
Методы для работы с сервоприводом
// инициализирует контакт для работы с сервоприводом:
servo = board.pin(num, 'SERVO')
// задает диапазон перемещения сервопривода в градусах;
// по умолчанию стоит диапазон в промежутке между «0» и «180»:
servo.range([int, int])
// задает позицию, на которую нужно переместиться (в градусах):
servo.write(int)
// перемещают сервопривод вперед и назад по заданному диапазону;
// а также останавливают сервопривод:
servo.sweep()
servo.noSweep()
Методы для работы с пьезодинамиком (в режиме источника звука)
Если сделать контакт пьезодинамика выходным, он будет работать в качестве источника звука.
// инициализирует контакт
// для работы с пьезодинамиком в качестве источника звука:
t = board.pin(num, 'TONE') || board.pin(num, 'PIEZO')
// отправка пьезодинамику одного значения:
t.write()
Информацию о звуках можно отправлять в виде ноты или частоты.
// отправляет пьезодинамику ноту или частоту;
// кроме того, в параметре «duration» задается
// продолжительность проигрывания звука (в миллисекундах):
t.tone(note || freq, duration)
t.noTone()
К примеру, две этих строчки проиграют в течение полсекунды один и тот же звук:
t.tone('c#2', 500)
t.tone(69, 500)
Специальные методы для считывания данных
В этих методах, как и в специальных методах для записи данных, не нужно указывать направление передачи данных.
Методы для работы со кнопкой
Все три «кнопочных» метода являются спецверсиями метода read() – они будут вызываться, когда кнопка будет нажата, отпущена или зажата.
// инициализирует контакт для работы с кнопкой:
button = board.pin(num, 'BUTTON')
// оба этих метода вызывают функцию обратного вызова,
// но pressed() – если кнопка была нажата,
// а released() – если она была отпущена:
button.pressed(cb)
button.released(cb)
// вызывает функцию обратного вызова, если кнопка была зажата;
// в параметре «int» задается, сколько времени (в мс) должно пройти,
// чтобы определить, что кнопка была зажата:
button.held(cb, int)
Методы для работы с регулируемым резистором
Эти методы можно использовать с любым регулируемым резистором (к примеру, с потенциометром, фоторезистором или резистором, чувствительным к прикосновениям).
// инициализирует контакт для работы с регулируемым резистором:
vr = board.pin(num, 'VRES')
// задает диапазон значений для методов ниже;
// по умолчанию стоит диапазон между «0» и «1023»:
vr.range([int, int])
// работает как стандартная функция чтения,
// то есть с каждым изменением значения задает «vr.val»
// и запускает заданную функцию обратного вызова:
vr.read([cb])
// задает пороговое значение:
vr.threshold(int)
// если пороговое значение задано,
// эта функция позволяет узнать, находится ли значение
// выше заданного порога («true» или «false»):
vr.overThreshold
Методы для работы с температурными датчиками
Изначально эти методы были предназначены для датчиков, определяющих температуру при помощи считывания меняющегося напряжения. При инициализации контакта в параметрах нужно указать номер инициализируемого контакта и уровень считываемого напряжения: 3.3 или 5 вольт.
// инициализация контакта с указанием номера контакта и напряжения:
temp = board.pin({pin: num, voltsIn: 5})
// этот метод всегда возвращает необработанные данные -
// на тот случай, если вы работаете не с температурным датчиком;
// кроме того, этот метод можно вызвать в таком виде:
// temp.read( function(val) { console.log(temp.f(val)) } );
temp.read()
// возвращает температуру в заданной единице измерения:
temp.C
temp.F
temp.K
Методы для работы с пьезодинамиком (в режиме датчика шума)
Если задать контакт для пьезодинамика как контакт для ввода данных, то он будет работать в качестве датчика уровня шума.
// инициализирует контакт
// для работы с пьзодинамиком в качестве датчика уровня шума:
k = board.pin(num, 'KNOCK') || board.pin(num, 'PIEZO')
// стандартный метод для чтения:
k.read()
// задает пороговое значение:
k.threshold()
// если было задано пороговое значение,
// этот метод определяет, превышено ли оно;
// возвращает булево значение («true» или «false»):
k.overThreshold()
Другие специальные методы
Методы для коммуникации через последовательный порт
Вдобавок к методам выше, созданным на базе Firmata, в p5.bots также есть универсальная библиотека-обертка node-serialport.
// настраивает доступ к последовательному порту:
serial = p5.serial()
// возвращает список портов, доступных на вашем ПК
// (последовательный порт подключать необязательно):
serial.list()
// вы можете подключиться сразу, без поиска доступных портов;
// опции для объекта «config» перечислены тут: https://github.com/voodootikigod/node-serialport#serialport-path-options-openimmediately-callback
serial.connect(path [, { config obj } ])
// стандартные методы для чтения и записи:
serial.read()
serial.write()
Поскольку метод serial.read() работает в стиле Node.js – то есть принимает функцию обратного вызова, а не возвращает функцию – мы можем добавить еще два метода для чтения:
// как в API Processing:
serial.readEvent([callback function])
// возвращает считанное значение:
serial.readData()
Создание ваших собственных методов
Если вы знакомы с Node.js, то можете написать собственные серверные функции, которые будут прослушивать вызовы со стороны клиента. Для этого:
- Создаем серверный файл, где каждая функция, которую вы хотите использовать, является свойством объекта «exports». У каждой функции есть доступ к сокету и объекту платы Firmata
exports.mine = function mine(board, socket) {
socket.on('event', function(data){ .. });
socket.emit('another', { name: 'data-object' });
}
- Начиная, сообщаем серверу об этом файле при помощи одного из следующих способов:
-p, --ufilepath <p> путь к файлу, содержащему серверные функции-детекторы, заданные пользователем
-n, --ufilename <n> путь к файлу (включая название файла), содержащему серверные функции-детекторы, заданные пользователем
По умолчанию путь ведет к текущей директории, а именем файла является «user.js».
