====== @amperka/hysteresis ======

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

В качестве параметров объекту-гистерезису определяют 2 порога: верхний и нижний, и 2 времени задержки: верхнее и нижнее. Время задержки называют //лагом//.

Гистерезис может генерировать 2 события:

  * ''"high"'' — спустя верхний лаг после того, как входной сигнал стал стабильно выше верхнего порога;
  * ''"low"'' — спустя нижний лаг после того, как входной сигнал стал стабильно ниже нижнего порога.

Значения входного сигнала передают через метод ''[[#push|push]]''.

===== Область применения =====

Гистерезис используют там, где приводить в действие исполнительное устройство можно только после стабилизации входного сигнала. Например:
  * Система управления освещением автомобиля. Фары не должны мигать, если машина едет в тоннеле или галерее с колоннами, где быстро сменяется тень и свет.
  * Система распознания кодовых хлопков или стука. Устройство должно отфильтровывать пиковые значения шума и определять шаблон по лагам между пиками.
  * Пожарная сигнализация. Тревогу стоит включать только когда газовые датчики фиксируют стабильное превышение посторонних веществ в воздухе, чтобы избежать ложных срабатываний от наводок и случайных небольших порций вредных газов.

===== Принцип действия =====

Представим гистерезис, у которого нулевой нижний лаг и ненулевой верхний.

{{ :js:hysteresis:hysteresis.png?nolink |}}

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

Ключевые моменты таковы:

  - Входной сигнал пересекает нижний порог. Т.к. у гистерезиса нет нижнего лага, выход переходит в нижнее состояние, он генерирует событие ''"low"''.
  - Сигнал возвращается в зону неопределённости. Гистерезис остаётся в нижнем состоянии, событий не происходит.
  - Сигнал снова пересекает нижний порог. Т.к. гистерезис уже находится в нижнем состоянии, ничего не меняется.
  - Сигнал пересекает верхний порог, начинается отсчёт верхнего лага, состояние не меняется.
  - Сигнал возвращается в зону неопределённости, не дождавшись прошествия лага, состояние не меняется.
  - Сигнал вновь пересекает верхний порог. Отсчёт лага начинается заново, состояние не меняется.
  - Время верхнего лага истекло. Гистерезис переходит в верхнее состояние, генерируется событие ''"high"''.
  - Гистерезис переходит в нижнее состояние, генерирует событие ''"low"''.

===== Функции модуля =====
func:: create(opts)

Создаёт новый объект ''Hysteresis'' с параметрами, заданными в объекте ''opts''.

В ''opts'' ожидаются поля:

  * ''low'' — нижняя граница;
  * ''high'' — верхняя граница;
  * ''lowLag'' — нижний лаг в секундах;
  * ''highLag'' — верхний лаг в секундах.

Если ''lowLag'' или ''highLag'' не заданы, они принимаются равными нулю.

Значения ''low'' и ''high'' могут совпадать. В этом случае одно из значений можно опустить.

class:: Hysteresis

Класс, представляющий гистерезис. Используйте функцию ''create'', чтобы создать новый объект.
  
meth:: Hysteresis.push(val)

Добавляет новое значение ''val'' входного сигнала.

Насколько часто программа должна вызывать метод — ваше решение. Если входной сигнал динамично меняется, важно вызывать ''push'' достаточно часто, чтобы гистерезис попросту не пропустил ключевые моменты, когда сигнал пересекает пороговые значения.

Вызывать ''push'' через //равные// промежутки времени не обязательно.

event:: Hysteresis.on('high', …)

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

event:: Hysteresis.on('low', …)

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