<WRAP apidoc/>

====== Встроенные функции и константы ======

===== Стандартные для JavaScript =====


prop:: Infinity

Значение положительной бесконечности. Результат ''1 / 0''.

prop:: NaN

Значение Not a Number для вещественной арифметики.

prop:: arguments

Переменная-массив содержит аргументы, переданные в текущую функцию. См. [[https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Functions/arguments|справочник MDN]].

func:: atob(base64string)

Декодирует строку ''base64string'' из кодировки Base 64 в строку с двоичными данными. Параметр и результат имеют тип ''String''.

<code javascript>
>atob("AAECAw==");
="\x00\x01\x02\x03"
</code>

func:: btoa(binaryData)

Кодирует строку с двоичными данными ''binaryData'' в кодировку Base 64. Параметр и результат имеют тип ''String''.

<code javascript>
>btoa("\x00\x01\x02\x03");
="AAECAw=="
</code>

func:: changeInterval(id, time)

Изменяет период интервальной функции.
  * ''id'' — идентификатор, который вернул ''setInterval'';
  * ''time'' — новый период в миллисекундах.

<code javascript>
var id = setInterval(function() { print('Hello'); }, 1000); // каждую секунду
// ...
changeInterval(id, 1500); // теперь каждые 1.5 секунды
</code>

Изменения вступают в силу с очередным вызовом функции-обработчика — таким образом изменения не моментальны.

func:: clearInterval([id])

Останавливает работу интервальной функции. Параметр ''id'' — идентификатор, который вернул ''setInterval''.

<code javascript>
var id = setInterval(function() { print('Hello'); }, 1000); // каждую секунду
// ...
clearInterval(id);
</code>

Если ''id'' опущен, будут остановлены все интервальные и отложенные функции.

func:: clearTimeout([id])

Отменяет запуск отложенной функции. Параметр ''id'' — идентификатор, который вернула ''setTimeout''.

<code javascript>
var id = setTimeout(function() { print('Hello'); }, 1000); // через секунду
// ...
clearTimeout(id);
</code>

Если ''id'' опущен, будут остановлены все отложенные и интервальные функции.


func:: eval(code)

Исполняет код JavaScript, переданный в виде строки ''code''.

Возвращает результат последнего выполненного выражения из ''code''.


prop:: global

Ссылка на объект глобальной области видимости.

func:: isNaN(x)

Возвращает ''true'', если ''x'' имеет значение ''[[#NaN|NaN]]''.


func:: parseFloat(string)

Преобразует строку ''string'' в вещественное число. Возвращает ''NaN'', если строка по содержимому не соответствует числу.

func:: parseInt(string[, radix])

Преобразует строку ''string'' в целое число.

Если задан ''radix'' определяет основание числа. По умолчанию используется десятичная система счисления.

Возвращает ''NaN'', если строка по содержимому не соответствует числу.

func:: require(moduleName)

Загружает модуль (библиотеку) ''moduleName'' и возвращает объект, экспортируемый этим модулем.

Подробности [[для_тех_кто_переходит_с_arduino#библиотеки|о библиотеках]] приведены в статье об особенностях Iskra JS, а примеры использования функции рассмотрены в описаниях конкретных библиотек. 

func:: setInterval(callback, timeout[, args, …])

Заставляет систему вызывать функцию ''callback'' или код переданный в виде строки каждые ''timeout'' миллисекунд.

Вы можете передать один или несколько параметров, которые будут переданы как есть при вызове ''callback''.

<code javascript>
// Печатаем Hello каждую секунду
setInterval(function() {
  console.log('Hello');
}, 1000);

// То же самое
setInterval("console.log('Hello');", 1000);

// Печатаем значение пина каждые 100 мс
setInterval(function(pin) {
  console.log(analogRead(pin));
}, 100, A0);
</code>

''setInterval'' возвращает число-идентификатор интервальной функции. Используйте его в качестве параметра ''[[#clearInterval|clearInterval]]'', чтобы остановить процесс.

Если был разрешён режим глубокого сна ([[#setDeepSleep|setDeepSleep]]), а ''timeout'' более 5000 мс, платформа может проспать время вызова на величину до 1 секунды. Это связано с тем, что необходимость пробуждения от глубокого сна платформа определяет раз в секунду.


func:: setTimeout(callback, timeout[, args, …])

Заставляет систему вызывать функцию ''callback'' или код переданный в виде строки через ''timeout'' миллисекунд.

Вы можете передать один или несколько параметров, которые будут переданы как есть при вызове ''callback''.

<code javascript>
// Печатаем Hello через секунду
setTimeout(function() {
  console.log('Hello');
}, 1000);

// То же самое
setTimeout("console.log('Hello');", 1000);

// Печатаем значение пина через 100 мс
setTimeout(function(pin) {
  console.log(analogRead(pin));
}, 100, A0);
</code>

''setTimeout'' возвращает число-идентификатор отложенной функции. Используйте его в качестве параметра ''[[#clearTimeout|clearTimeout]]'', чтобы отменить запланированный вызов.

Если был разрешён режим глубокого сна (''[[#setDeepSleep|setDeepSleep]]''), а ''timeout'' более 5000 мс, платформа может проспать время вызова на величину до 1 секунды. Это связано с тем, что необходимость пробуждения от глубокого сна платформа определяет раз в секунду.

===== Объекты-пины =====

Функциям и методам, которые принимают пины в качестве параметров, передают встроенные объекты-пины. Среди них есть синонимы. Используйте то обозначение, которое более уместно в конкретном контексте.

    * ''P0'', ''P1'', ''P2'', … ''P//n//'' — соответствуют пинам, промаркированным на плате; это удобные синонимы к непосредственным портам микроконтроллера вида ''B//x//'', ''C//x//'';
    * ''A0'', ''A1'', ''A2'', … ''A//n//'' — также соответствуют маркировке на плате, но в то же время 1-в-1 совпадают с наименованием портов микроконтроллера;
    * ''B0'', ''B1'', ''B2'', … ''B//n//'', ''C0'', ''C1'', ''C2'', … ''C//n//'' — непосредственные порты микроконтроллера, их соответствие с ''P//x//'' смотрите в документации на свою плату;
    * ''LED1'', ''LED2'', ''BTN1'' — пины подключенные к встроенным на плату светодиодам и кнопкам;

Все перечисленные объекты являются экземплярами класса [[.:pin|Pin]], поэтому помимо передачи их в функции, можно вызывать их собственные методы.

===== Функции работы с пинами =====

func:: analogRead(pin)

Считывает значение аналогового сигнала на пине ''pin'' и возвращает результат в виде числа в диапазоне [0.0; 1.0].

Пин должен поддерживать чтение [[сенсоры:аналоговые|аналоговых сигналов]]. См. функции пинов в документации на свою плату.

Если перед вызовом не вызывалась функция ''[[#pinMode|pinMode]]'', пин будет автоматически переведён в режим ''%%'%%analog%%'%%''.

func:: analogWrite(pin, value[, opts])

Выдаёт аналоговый сигнал на пине ''pin''. Используется аппаратный [[конспект-arduino:шим|ШИМ]] или ЦАП, если они доступны на пине.
См. функции пинов в документации на свою плату.

В случае ШИМ ''value'' задаёт скважность, в случае ЦАП — величину напряжения. В любом случае ожидается значение в диапазоне [0.0; 1.0].

В качестве необязательного параметра ''opts'' принимается объект с полями:
  * ''freq'' — частота ШИМ в герцах;
  * ''soft'' — если ''true'' и аппаратный ШИМ не доступен на пине, будет использован программный ШИМ;
  * ''forceSoft'' — если ''true'', будет использован программный ШИМ даже при наличии аппаратного.

<code javascript>
analogWrite(P9, 0.5);
analogWrite(P8, 0.4, {freq: 20});
analogWrite(P7, 0.1, {freq: 20, soft: true});
</code>

Если перед вызовом функции не вызывалась ''[[#pinMode|pinMode]]'', пин будет автоматически переведён в режим ''%%'%%output%%'%%''.


func:: clearWatch([id])
Останавливает наблюдение за пином. Параметр ''id'' — идентификатор, который вернула ''setWatch''.

<code javascript>
var id = setWatch(function() { print('Hello'); }, P3);
// ...
clearWatch(id);
</code>

Если ''id'' опущен, будут остановлены все наблюдения за пинами.

func:: digitalPulse(pin, value, time)

Генерирует импульс на пине ''pin'' длительностью ''time'' миллисекунд. ''value'' задаёт значение пульса: ''1'' — высокий сигнал, ''0'' — низкий.

Для точности функция использует аппаратный таймер и не блокирует исполнение программы, т.е. возвращается до того, как закончится импульс. Передайте 0 в качестве ''time'', чтобы дождаться окончания предыдущего импульса.

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

<code javascript>
digitalPulse(A3, 1, 1.5); // высокий импульс на 1.5 мс
digitalPulse(A3, 1, 0); // остановка до завершения импульса

// 100 мкс — низкий сигнал
// 200 мкс — высокий
// 300 мкс — снова низкий
digitalPulse(A3, 0, [0.1, 0.2, 0.3]); 
</code>

Используйте функцию для коротких и очень точных импульсов. Для работы с периодами свыше нескольких миллисекунд используйте ''[[#setTimeout|setTimeout]]''.

Если перед вызовом не вызывалась функция ''[[#pinMode|pinMode]]'', пин будет автоматически переведён в режим ''%%'%%output%%'%%''.

func:: digitalRead(pin)

Считывает цифровой сигнал с пина ''pin''. Возвращает ''1'', если на пине — логическая единица и ''0'', если на пине — логический ноль.

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

<code javascript>
var x = digitalRead(A0); // считываем с одного пина

// считываем с группы
x = digitalRead([A2, A1, A0]);
// если на A2 и A1 — единица, а на A0 — ноль,
// результатом будет 0b110
</code>

Если перед вызовом не вызывалась функция ''[[#pinMode|pinMode]]'', пин будет автоматически переведён в режим ''%%'%%input%%'%%''.

func:: digitalWrite(pin, value)

Устанавливает цифровой сигнал на пине ''pin'': логическую единицу, если ''value'' — ''1'' или ''true'', логический ноль, если ''value'' — ''0'' или ''false''.

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

<code javascript>
digitalWrite(P3, 1); // выставляем логическую единицу на P3

// делаем короткий импульс на P5 и сразу после него
// короткий импульс на P4
digitalWrite([P4, P5], 0b0101);
</code>

Если перед вызовом не вызывалась функция ''[[#pinMode|pinMode]]'', пин будет автоматически переведён в режим ''%%'%%output%%'%%''.

func:: getPinMode(pin)

Возвращает текущий режим работы пина ''pin'' в виде строковой константы. Смотрите [[#pinMode|pinMode]] для возможных значений.

func:: pinMode(pin[, mode])

Устанавливает режим работы пина ''pin'' в соответствие с ''mode'':
  * ''%%'%%analog%%'%%'' — аналоговый вход;
  * ''%%'%%input%%'%%'' — цифровой вход;
  * ''%%'%%input_pullup%%'%%'' — цифровой вход с внутренним подтягивающим резистором (~40 кОм);
  * ''%%'%%input_pulldown%%'%%'' — цифровой вход с внутренним стягивающим резистором (~40 кОм);
  * ''%%'%%output%%'%%'' — цифровой выход;
  * ''%%'%%opendrain%%'%%'' — цифровой выход с открытым стоком, для которого логическая единица замыкает пин на землю, а логический ноль формирует разрыв цепи;
  * ''%%'%%af_output%%'%%'' — цифровой выход встроенной периферии;
  * ''%%'%%af_opendrain%%'%%'' — цифровой выход с открытым стоком внутренней периферии;
  * не задан — автоматический режим.

Функции для работы с пинами — например ''digitalRead'' или ''digitalWrite'' — самостоятельно устанавливают нужный режим работы пина, если вы предварительно не вызвали ''pinMode'' явно. Чтобы вернуть автоматический режим, вызовите ''pinMode'' без параметра ''mode''.

func:: setWatch(callback, pin [, opts])

Заставляет платформу вызвать функцию ''callback'' при изменении цифрового сигнала на входе ''pin''. В качестве ''opts'' принимается объект с полями:
  * ''repeat'' — если ''true'', функция будет вызвана каждый раз при изменении; если ''false'' — однократно; по умолчанию ''false''.
  * ''edge'' — ''%%'%%rising%%'%%'' для фиксации только восходящего фронта, ''%%'%%falling%%'%%'' — только нисходящего, ''%%'%%both%%'%%'' — при изменении в любую сторону; по умолчанию ''%%'%%both%%'%%''.
  * ''debounce'' — время в миллисекундах для программного подавления [[:дребезг|дребезга сигнала]].

В ''callback'' при вызове система передаёт параметр-объект с полями:
  * ''state'' — текущее значение пина: ''0'' или ''1'';
  * ''time'' — системное время в секундах, когда произошло наблюдаемое изменение сигнала;
  * ''lastTime'' — системное время в секундах, когда последний раз происходило //любое// изменение сигнала; для значений ''edge'' ''%%'%%rising%%'%%'' и ''%%'%%falling%%'%%'' это значение не совпадает с временем предыдущего вызова.

<code javascript>
// Наблюдаем за кнопкой
setWatch(function(e) {
  console.log('BTN1 was just pressed');
}, BTN1, {
  repeat: true,
  edge: 'falling',
  debounce: 10
});

// Измеряем длину импульса с логическим нулём
setWatch(function(e) {
  print('Pulse length:', e.time - e.lastTime, 'seconds');
}, P4, {edge: 'rising'});
</code>

Функция возвращает число-идентификатор, который можно передать в ''[[#clearWatch|clearWatch]]'', чтобы отменить наблюдение за пином.

===== Системные функции =====

func:: getSerial()

Возвращает заводской номер платы.

func:: getTime()

Возвращает текущее системное время в секундах, как вещественное число. При включении платы системное время выставляется в ноль.

func:: load()

Загружает программу из flash-памяти. Восстанавливает состояние интерпретатора на момент последнего вызова ''[[#save|save]]''.


func:: peek8(addr[, count])

Считывает 8 бит памяти по адресу ''addr'' и возвращает значение в виде целого числа.

Если ''count'' передан, определяет количество последовательных значений для считывания. Результат в этом случае представляется в виде ''[[js:typedarray#типизированные_массивы|Uint8Array]]''.

Используйте функцию для низкоуровневой работы с микроконтроллером.
func:: peek16(addr[, count])

Считывает 16 бит памяти по адресу ''addr'' и возвращает значение в виде целого числа.

Если ''count'' передан, определяет количество последовательных значений для считывания. Результат в этом случае представляется в виде ''[[js:typedarray#типизированные_массивы|Uint16Array]]''.

Используйте функцию для низкоуровневой работы с микроконтроллером.

func:: peek32(addr[, count])

Считывает 32 бита памяти по адресу ''addr'' и возвращает значение в виде целого числа.

Если ''count'' передан, определяет количество последовательных значений для считывания. Результат в этом случае представляется в виде ''[[js:typedarray#типизированные_массивы|Uint32Array]]''.

Используйте функцию для низкоуровневой работы с микроконтроллером.

func:: poke8(addr, value)

Записывает 8 бит из числа ''value'' в память по адресу ''addr''.

В качестве ''value'' можно передать массив. В этом случае элементы будут записаны в память последовательно, начиная с ''addr''.

Используйте функцию для низкоуровневой работы с микроконтроллером.

func:: poke16(addr, value)

Записывает 16 бит из числа ''value'' в память по адресу ''addr''.

В качестве ''value'' можно передать массив. В этом случае элементы будут записаны в память последовательно, начиная с ''addr''.

Используйте функцию для низкоуровневой работы с микроконтроллером.

func:: poke32(addr, value)

Записывает 32 бита из числа ''value'' в память по адресу ''addr''.

В качестве ''value'' можно передать массив. В этом случае элементы будут записаны в память последовательно, начиная с ''addr''.

Используйте функцию для низкоуровневой работы с микроконтроллером.

func:: reset()

Производит сброс интерпретатора: очищает память, но не загружает сохранённую в flash-памяти программу.

Метод не сбрасывает микроконтроллер, только интерпретатор. Это позволяет не терять соединение с платой во время сброса.

Для полной перезагрузки, используйте кнопку Reset на плате.

func:: save()

Сохраняет текущее состояние интерпретатора в flash-памяти. Оно будет восстановлено всякий раз, когда на плату подаётся питание или происходит аппаратная перезагрузка.

Если вы написали программу, которая вешает микроконтроллер, зажмите кнопку BTN1 на плате перед тем, как нажать Reset или подать питание. В этом случае ''load'' не будет вызван при старте.

func:: setBusyIndicator([pin])

Когда плата исполняет код (не спит), на пин ''pin'' будет подаваться логическая единица.

Не передавайте параметр ''pin'', чтобы отключить это поведение.

func:: setDeepSleep(enable)

Если ''enable'' — ''true'', разрешает режим глубокого сна, когда микроконтроллеру нечем заняться.

func:: setSleepIndicator([pin])

Заставляет платформу подавать логический ноль на пин ''pin'', когда она находится в режиме сна и логическую единицу в обычном режиме.

Не передавайте параметр ''pin'', чтобы отключить это поведение.

func:: setTime(time)

Устанавливает значение текущего системного времени в секундах в ''time''.

===== Функции для отладки =====

func:: dump()

Выводит в консоль текущее состояние интерпретатора в текстовом виде так, что оно может быть скопировано на новое устройство.

func:: echo(echoOn)

Определяет должна ли платформа возвращать обратно в консоль то, что через неё принимает. По умолчанию используется значение ''true''. Вы видите инструкции, которые вводите в панели интерпретатора именно благодаря тому, что платформа при получении символа тут же отправляет его обратно.

При выключенном эхе, будет отображаться только явный вывод через функции типа ''[[#print|print]]''.
func:: edit(funcName)

Выводит в консоль объявление функции с именем ''funcName'', чтобы её можно было изменить.

Это отладочная функция. Используйте её для экспериментов на лету.

''edit'' не работает для встроенных функций.

func:: print(text, …)

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

<code javascript>
print("Value", val, "units");
</code>

Если плата соединена с компьютером по USB, но на нём не запущена консоль или другой терминал, который может потребить пересылаемые данные, исполнение программы будет заморожено до тех пор, пока данные не считают.

func:: trace([root])

Выводит отладочную информацию интерпретатора в виде иерархии, начиная с объекта ''root''.

Если ''root'' не задан, выводит всю информацию.