====== @amperka/gprs-shield ======

Драйвер для работы с модулем [[amp>product/gprs-shield|GPRS Shield]].

Позволяет отправлять команды и обрабатывать события модуля через последовательный порт UART.

Инициализируется функцией ''connect''.

func:: connect([opts])

Возвращает новый объект ''Sim900r'' для работы с модулем через порт последовательный порт. Для модуля [[Iskra_JS|Iskra JS]] — это порт ''Serial3''

Необязательный параметр ''opts'' задаёт характеристики соединения с модулем. Ожидается объект со свойствами:
  * ''serialPort'' — объект последовательного порта. По умолчанию — ''Serial3''.
  * ''serialSpeed'' — скорость взаимодействия по последовательному порту. По умолчанию — ''9600''.
  * ''powerPin'' — контакт для включения и выключения модуля. По умолчанию — ''P2''.
  * ''statusPin'' — контакт для определения готовности модуля. По умолчанию — ''P3''.

<code javascript>
var sim = require('@amperka/Sim900r').connect();
</code>

class:: Sim900r

Класс для управления GPRS-модулем, работы со звонками и SMS, USSD, а так же для прямого доступа к AT-командам. 

Обратите внимание, на выполнение команды модулю требуется время. Поэтому для обработки результата команды используются функции обратного вызова ''callback'', в которые и передаются параметры ответа. Так же модуль сообщает о различных событиях: готовности к работе, входящих звонках, СМС и прочих. При возникновении события ''event'' вызывается соответствующая ему функция обратного вызова.


=== Управление питанием и проверка статуса готовности ===

func:: Sim900r.powerOn()

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


func:: Sim900r.powerOff()

Выключает модуль. Не будет выполнена, если модуль уже отключен.
func:: Sim900r.isReady()

Проверяет модуль на готовность к работе — взаимодействию с контроллером по последовательному порту. Функцию не следует использовать для проверки регистрации модуля в сети сотового оператора. При готовности модуля функция возвращает ''true'', если модуль не готов или выключен — ''false''. 

==== События, инициируемые модулем ====

event:: Sim900r.on('powerOn', function() { ... })
Возникает после инициализации при включении модуля.

event:: Sim900r.on('powerOff', function() { ... })
Возникает при выключении модуля.
  
event:: Sim900r.on('simReady', function() { ... })
Возникает в момент обнаружения SIM-карты.

event:: Sim900r.on('simError', function(code) { ... })
Возникает при отсутствии SIM-карты.
  * ''code'' — код ошибки, отданный модулем.

event:: Sim900r.on('ready', function() { ... })
Возникает в момент регистрации модуля с SIM-картой в сети оператора.


event:: Sim900r.on('ring', function(phone, cnt) { ... })
Возникает в момент входящего звонка. При входящем звонке событие возникает приблизительно раз в три секунды, пока вы не ответите или не разорвете соединение, или это не сделает вызывающая сторона. Параметры функции обратного вызова:
  * ''phone'' — телефон вызывающего абонента (если он определен) или ''undefined'';
  * ''cnt'' — количество вызовов события ''ring'' с начала попытки дозвона.

event:: Sim900r.on('noCarrier', function() { ... })
Возникает в момент разъединения соединения другим лицом. Если соединение разрываете вы — событие не возникает.

event:: Sim900r.on('sms', function(phone, time, text) { ... })
Возникает в момент приема SMS-сообщения. Параметры функции обратного вызова:
  * ''phone'' — телефон отправителя;
  * ''time'' — дата и время отправления;
  * ''text'' — текст сообщения.



event:: Sim900r.on('unknown', function(event, data) { ... })
Возникает событие инициированное модулем, но оно отличается от вышеперечисленных. Параметры функции обратного вызова:
  * ''event'' — событие генерируемое модулем;
  * ''data'' — строка с данными по этому событию.



==== Работа с прямыми командами модуля ====
func:: Sim900r.cmd(command, callback);
Отправляет команду ''command'' модему и возвращает в функции обратного вызова полученный результат. При получении ответа, вызывает функцию ''callback''  вида ''function(error, data) { … }'' с параметрами:

  * ''error'' — ''undefined'' при успешном запросе; [[Error]] — если произошла ошибка;
  * ''data'' — массив, где каждый элемент — строка отданная модулем в рамках обработки команды.



==== Голосовая связь ====

func:: Sim900r.call(phone, callback)
Вызывает попытку дозвона до абонента с номером ''phone'', переданным в виде строки. Вызывает ''callback''.

В качестве ''callback'' ожидается функция вида ''function(error) { ... }'' с параметрами:

  * ''error'' — ''undefined'', если запрос успешен, или одну из следующих ошибок:
    * ''NO DIALTONE'' — нет сигнала;
    * ''NO CARRIER'' — звонок отклонен;
    * ''NO ANSWER'' — нет ответа;
    * ''BUSY'' — занято.

    

func:: Sim900r.cancel(function(error) { ... })
Разрывает текущее соединение. Вызывает ''callback'' при исполнении.

В качестве ''callback'' ожидается функция вида ''function(error) { ... }'' с параметрами:

  * ''error'' — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка.

func:: Sim900r.answer(callback)
Ответ на входящий звонок. Вызывает ''callback'' при исполнении.

В качестве ''callback'' ожидается функция вида ''function(error) { ... }'' с параметрами:

  * ''error'' — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка.

==== Работа с SMS-сообщениями ====

func:: Sim900r.smsSend(phone, text, function(error) { ... })
Отправляет SMS-сообщение. По результату, вызывает функцию ''callback''  вида ''function(error) { … }'' с параметрами:

  * ''error'' — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка.

<code javascript>
var sim = require('@amperka/Sim900r').connect();
sim.powerOn();
sim.smsSend("+79160001122", "hello", function(error){   
  console.log(error);  
});
</code>

func:: Sim900r.smsList(function(error, data) { ... })
Читает список SMS-сообщений, сохраненных на SIM-карте. По результату, вызывает функцию ''callback''  вида ''function(error, data) { … }'' с параметрами:
  * ''error'' — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка.
  * ''data'' — массив объектов, описывающих СМС, со свойствами:
    * ''index'' — индекс сообщения в памяти SIM-карты;
    * ''phone'' — номер телефона отправителя;
    * ''date'' — объект типа [[Date]], с информацией о дате и времени отправки;
    * ''text'' — текст сообщения;

func:: Sim900r.smsRead(index, function(error, data) { ... })
Читает SMS-сообщение с индексом ''index'', сохраненное на SIM-карте. По результату, вызывает функцию ''callback''  вида ''function(error, data) { … }'' с параметрами:
  * ''error'' — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка.
  * ''data'' — объект, описывающих СМС, со свойствами:
    * ''index'' — индекс сообщения в памяти SIM-карты;
    * ''phone'' — номер телефона отправителя;
    * ''date'' — объект типа [[Date]], с информацией о дате и времени отправки;
    * ''text'' — текст сообщения;

func:: Sim900r.smsDelete(index, function(error) { ... })
Удаляет SMS-сообщение с индексом ''index'', сохраненное на SIM-карте. В качестве значения параметра ''index'' можно указать ''all'', что приведет к удалению всех сообщений. По результату, вызывает функцию ''callback''  вида ''function(error) { … }'' с параметрами:
  * ''error'' — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка.


==== Информация о SIM-карте и сети оператора связи ====

func:: Sim900r.netProvider(callback)

Запрашивает название оператора SIM-карты. Вызывает ''callback'' для передачи результата.

В качестве ''callback'' ожидается функция вида ''function(error, provider) { ... }'' с параметрами:

  * ''error'' — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка;
  * ''provider'' — название оператора сим-карты в виде строки ''string''.



func:: Sim900r.netStatus(callback)
Запрашивает информацию о регистрации в сети. Вызывает ''callback'' для передачи результата.

В качестве ''callback'' ожидается функция вида ''function(error, status) { ... }'' с параметрами:

  * ''error'' — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка;
  * ''status'' — статус регистрации в виде строки и имеющее одно из следующих значений:
    * ''"search"'' — идёт поиск сети;
    * ''"home"'' — модуль зарегистрирован в домашней сети;
    * ''"roaming"'' — модуль зарегистрирован в роуминговой сети;
    * ''"error"'' — регистрация не удалась;
    * ''"unknown"'' — другая ошибка.


func:: Sim900r.netQuality(callback)
Запрашивает информацию о качестве приема. Вызывает ''callback'' для передачи результата.

В качестве ''callback'' ожидается функция вида ''function(error, quality) { ... }'' с параметрами:

  * ''error'' — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка;
  * ''quality'' — качество приема в виде целого числа от 0 до 10.


func:: Sim900r.netCurrent(callback)
Запрашивает информацию об операторе связи, в сети которого зарегистрирован модуль. Вызывает ''callback'' для передачи результата.

В качестве ''callback'' ожидается функция вида ''function(error, provider) { ... }'' с параметрами:

  * ''error'' — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка;
  * ''provider'' — название оператора сотовой сети.


==== Получение информации о модуле ====

func:: Sim900r.getImei(callback)
Получает IMEI модуля. Вызывает ''callback'' для передачи результата.

В качестве ''callback'' ожидается функция вида ''function(error, imei) { ... }'' с параметрами:
  * error — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка;
  * imei — IMEI модуля в виде строки ''string''.

func:: Sim900r.getFirmware(function(error, firmware) { ... })
Получает информацию о ревизии модуля. Вызывает ''callback'' для передачи результата.

В качестве ''callback'' ожидается функция вида ''function(error, firmware) { ... }'' с параметрами:
  * error — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка;
  * firmware — значение ревизии типа ''string''.


func:: Sim900r.getTime(callback)
Получает дату и время на устройстве. Вызывает ''callback'' для передачи результата.

В качестве ''callback'' ожидается функция вида ''function(error, datetime) { ... }'' с параметрами:
  * error — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка;
  * datetime — объект [[Date]].



func:: Sim900r.getCallerID(callback)
Получение информации о включении автоматического определителя номера. Вызывает ''callback'' для передачи результата.

В качестве ''callback'' ожидается функция вида ''function(error, enable) { ... }'' с параметрами:
  * error — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка;
  * enable — включен ли АОН (тип ''boolean'').

==== Настройка модуля ====

func:: Sim900r.setTime(datetime [, callback])
Устанавливает дату и время из параметра ''datetime'', переданного в виде объекта [[Date]].

В качестве ''callback'' ожидается функция вида ''function(error) { ... }'' с параметрами:

  * error — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка.


func:: Sim900r.setCallerID(enable [, callback])
Включение и отключение определителя номера. Параметр ''enable'' имеет булевый тип. Вызывает ''callback'' по окончанию.

В качестве ''callback'' ожидается функция вида ''function(error) { ... }'' с параметрами:

  * error — ''undefined'', если запрос успешен; [[Error]] — если произошла ошибка.


===== Ссылки =====
  * {{:продукты:gprs_shield:gprs-shield_sim900_at_commands.pdf|мануал для изучения AT команд}}