<WRAP apidoc></WRAP>

====== @amperka/led-matrix ======

Библиотека для управления [[amp>/product/troyka-led-matrix|монохромной LED матрицей 8×8 (Troyka-модуль)]]. Используйте [[https://igrztv.github.io/led-matrix-editor/|редактор пиктограмм]] для красивых изображений.

<code javascript>
// Подгружаем объект простых печатных символов
var symbols = require('@amperka/basic-font').font;

// Настраиваем интерфейс I2C и подключаем библиотеку
PrimaryI2C.setup({sda: SDA, scl: SCL, bitrate: 100000});
var matrix = require('@amperka/led-matrix').connect(PrimaryI2C);

// Печатаем символы в строке 'Amperka'
var amperka= 'Amperka';
var index = 0;
setInterval(function() {
  // записываем символ под номером index в строке 'Amperka'
  var char = amperka[index];
  index += 1;
  if (index == 7) index = 0;
  matrix.print(symbols[char]);
}, 200);
</code>

===== Функции модуля =====

func:: connect(i2c[, opts])

Создаёт новый объект Matrix. Параметры функции:
  * ''i2c'' — i2c, к которому подключен модуль
  * ''opts'' — объект дополнительных параметров: Поле ''address'' задаёт адрес модуля, если он отличается от стандартного. Можно подключить до четырёх модулей [[продукты:troyka-led-matrix#площадки_выбора_адреса|с разными адресами]]. Стандартный адрес ''0x60''. Допустимые адреса: ''0x60'', ''0x61'', ''0x62'', ''0x63''.
class:: Strip

Класс для подключения матрицы. Для создания нового объекта, используйте функцию ''connect''.

func:: Matrix.print(byteArray)

Выводит изображение на матрицу. Изображение передаётся в массиве из 8 целых чисел. Каждое число — строка матрицы. Разряд числа — столбец. Нумерация строк и столбцов с 0 до 7. 
<code javascript>
// создаём массив «пикселей». Нарисуем английскую букву F.
var picture = [
  0b11111100,
  0b11111100,
  0b11000000,
  0b11111100,
  0b11111100,
  0b11000000,
  0b11000000,
  0b11000000
];
// Нарисует 
matrix.print(picture);
</code>

[[https://igrztv.github.io/led-matrix-editor/|Редактор пиктограмм]] создаёт массив изображений. Каждое доступно по индексу.

<code javascript>
// скопировали массив из редактора
var pictures = [
  [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x10],
  [0x00, 0x00, 0x00, 0x00, 0x00, 0x10, 0x10, 0x10],
  [0x00, 0x00, 0x00, 0x28, 0x10, 0x10, 0x00, 0x00],
  [0x00, 0x00, 0x46, 0x28, 0x04, 0x08, 0x00, 0x00],
  [0x20, 0x92, 0x46, 0x00, 0x03, 0x00, 0x00, 0x00],
  [0x20, 0x80, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00]
];
// Рисуем GIF`ку
var frame = 0;
setInterval(function() {
  matrix.print(pictures[(frame++) % pictures.length]);
}, 100);

</code>
func:: Matrix.write(x, y, state)

Изменяет изображение по одном пикселю. Если ''state == 1'', зажжёт светодиод в строке ''x'' в столбце ''y''. Погасит светодиод, если ''state == 0''. Начало координат в верхнем левом углу.
<code javascript>
// Закрасим нижний правый угол
matrix.write(6, 6, 1)
  .write(6, 7, 1)
  .write(7, 6, 1)
  .write(7, 7, 1);
</code>
<code javascript>
// Нарисуем квадратный бублик: закрасим всё, кроме центральных пикселей
matrix.print([255,255,255,255,255,255,255,255]);
matrix.write(3, 3, 0)
  .write(3, 4, 0)
  .write(4, 3, 0)
  .write(4, 4, 0);
</code>

func:: Matrix.read()

Возвращает массив из 8 целых чисел, соответствующий текущему изображению на матрице.

func:: Matrix.brightness(value)

Устанавливает яркость матрицы. Параметр ''value'' принимает значения в диапазоне 0.0…1.0. Яркость изменяется ступенчато, всего 16 градаций. При запуске модуля яркость устанавливается примерно в половину от максимальной.
<code javascript>
// устанавливаем яркость в 2 раза меньше максимальной
matrix.brightness(0.5);
// полностью выключена
matrix.brightness(0);
// максимум яркости
matrix.brightness(1);
</code>
<code javascript>

// меняем яркость с помощью потенциометра
var brightnessControl = require('@amperka/pot').connect(A1);

setInterval(function() {
  matrix.brightness(brightnessControl.read());
}, 100);
</code>

func:: Matrix.clear()

Устанавливает все светодиоды в выключенное состояние. Эквивалентно вызову ''matrix.print([0,0,0,0,0,0,0,0]);''
<code javascript>
// гасим все светодиоды
matrix.clear();
</code>

func:: Matrix.power(state)

Выключает матрицу, если ''state == false''. Включает, если ''state == true''. По умолчанию матрица включена.
<code javascript>
// выключаем матрицу для экономии энергии
matrix.power(false);
</code>

func:: Matrix.equalizer(state)

Включает режим эквалайзера, если ''state == true'', иначе переводит в обычный режим. Перед запуском необходимо вызвать функцию ''analogInput(true);''.
<code javascript>
// переводим матрицу в режим эквалайзера
matrix.analogInput(true).equalizer(true);
</code>

func:: Matrix.analogInput(state)

Устанавливает пин S на модуле в режим аналогово входа.

func:: Matrix.audioGain(value)

Устанавливает коэффициент усиления на аналоговом входе. Параметр ''value'' принимает значения от 0 до 1. Усиление меняется ступенчато.
<code javascript>

// меняем усиление эквалайзера с помощью потенциометра
var gainControl = require('@amperka/pot').connect(A0);

setInterval(function() {
  matrix.audioGain(gainControl.read());
}, 100);
</code>