<WRAP apidoc/>

====== @amperka/ultrasonic ======

Модуль для работы с [[amp>product/hc-sr04-ultrasonic-sensor-distance-module|ультразвуковыми дальномерами HC-SR04]].

Звуковой пучок нужно сгенерировать и дождаться возвращения отражённого сигнала. При этом сигнал может не вернуться, если препятствие находится дальше 5 метров. Эхо текущего измерения важно не перепутать с эхом предыдущего. А полученное значение времени нужно пересчитать в расстояние. Все эти детали библиотека скрывает в себе.

<code javascript>
var sonic = require('@amperka/ultrasonic')
  .connect({trigPin: P12, echoPin: P11});

sonic.ping(function(err, value) {
  if (err) {
    console.log('An error occurred:', err);
  } else {
    console.log('The distance is:', value, 'millimeters');
  }
}, 'mm');
</code>

func:: connect(pins)

Создаёт новый объект ''Ultrasonic'' для дальномера, подключённому к пинам, которые задаются объектом-параметром ''pins''.

В ''pins'' должны быть 2 поля:

  * ''trigPin'' обозначает пин платформы, к которому подключен пин //trig// дальномера;
  * ''echoPin'' — пин //echo// дальномера.

class:: Ultrasonic

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

meth:: Ultrasonic.ping(callback[, units])

Запускает процесс измерения расстояния. При возвращении ультразвукового эха или при возникновении ошибки вызывает
функцию ''callback(err, value)'':
  * ''err'' — объект ''[[Error]]'', если произошла ошибка измерения; ''undefined'', если измерение успешно;
  * ''value'' — значение расстояния в единицах, определяемыми параметром ''units''.

В качестве единиц измерения можно использовать:
  * ''"m"'', ''"cm"'', ''"mm"'' — метры, сантиметры, миллиметры соответственно;
  * ''"s"'', ''"ms"'', ''"us"'' — секунды, миллисекунды, микросекунды соответственно.

Если параметр ''units'' опущен, используются секунды (''"s"'').

Для пересчёта времени в расстояние используется скорость звука при стандартных атмосферных параметрах: температуре 25 °C и нормальном давление на уровне моря.

В качестве сообщения ошибки ''err.msg'' может быть одно из значений:
  * ''"timeout"'' — эхо не вернулось: расстояние больше 4 метров или препятствие поглощает звук;
  * ''"busy"'' — совершена попытка нового измерения, пока старое ещё не завершено;
  * ''"wrong connection"'' — сенсор не подтверждает начало измерения, он подключен неправильно или неисправен.