Макросы: Элементарная система (Classic)
Макросы (или скрипты) — это мощнейший внутренний механизм автоматизации агрегаторов SIM Roulette. С помощью макросов могут быть реализованы абсолютно любые сценарии работы. При этом очень важно, что написание макросов доступно даже пользователям не знакомым с программированием, макросы не требуют компиляции (предварительного перевода в машинные коды), всегда готовы к исполнению и доступны для редактирования.
Устройство макроса
Синтаксис
Первые шаги
Полезные приемы
Примеры
Первые шаги
Что же из себя представляет макрос или скрипт? Это набор команд агрегатору (все команды к вашему устройству подробно описаны в соответвующем разделе Документации), некоторые из них, вам возможно уже знакомы. Например, modem>connect — команда для подключения контактной группы к СИМ-карте.
Давайте попробуем написать наш первый макрос. Для этого перейдем в раздел Макросы WEB-интерфейса вашего устройства и нажмем кнопку «Создать макрос». В поле «Название» введем my_connect. А в поле «Содержание»
modem>connect
modem>on
Макрос готов. 1 команда подключает контактную группу, вторая включает модем. Вот так просто мы уже произвели небольшую автоматизацию. Теперь надо сохранить макрос нажав соответствующую кнопку.
Как запустить (выполнить) макрос. Через WEB-интерфейс макрос можно запустить двумя способами:
- В разделе Макросы, в списке найти строку с названием нужного макроса и нажать на иконку исполнения. Строка запущенного на исполнение макроса подсветится, к иконкам добавится новая — иконка остановки.
- В разделе Терминал ввести команду macro: и название вашего макроса — macro:my_connect. Существует также сокращенная команда m — m:my_connect. Запуск через терминал позволяет передать макросу входные данные. Делается это так m:my_connect>Текст_для_передачи_макросу. После запуска макроса в статус-строке терминала появится иконка исполнения при наведении на которую можно увидеть название исполняемого макроса.
Как остановить макрос. Для прерывания работы макроса также существуют 2 способа:
- В разделе Макросы, в списке найти строку с названием запущенного макроса и нажать на иконку остановки.
- В разделе Терминал ввести команду macro:stop. Существует также сокращенная команда m:stop.
Итак, запустите любым способом ваш первый макрос. Получилось?
Давайте вернемся к редактированию (иконка редактирования в строке с названием макроса) и добавим новый функционал. Перед подключением сделаем проверку, может быть контакты уже подключены. Тогда повторное подключение не требуется — мы сэкономим время.
modem>status:connect
if next
modem>connect
modem>on
[next]
Добавились 3 новые строки:
Команда modem>status:connect возвращает нам текущий статус контактов: 0 (NULL) — контакты не подключены, 1 — контакты подключены. Следующая строка if next содержит оператор ветвления. Если предыдущая команда вернет 1 — оператор перенаправит дальнейшее выполнение программы на метку next. Если нет — будет выполнена команда в следующей после оператора строке. Последняя новая строка [next] содержит метку на которую и будет совершен переход из строки с оператором if.
Сохраните и запустите обновленный макрос. Как видите ничего не произошло, потому что модем уже был присоединен к СИМ-карте и включен. Если сейчас отсоединить модем командой modem>disconnect и заново запустить макрос — модем снова будет присоединен и включен.
Ну как понравилось? Продолжим?
Усложним макрос еще больше — добавим проверку регистрации СИМ-карты в мобильной сети:
modem>status:connect
if next
modem>connect
modem>on
[next]
pause 30000
buffer>clear
buffer>modem:grab=1
modem>send:AT+CREG?
pause 200
buffer>test:0,1
if ok
echo>СИМ-карта не зарегистрирована в сети
goto end
[ok]
echo>СИМ-карта готова к работе
[end]
buffer>modem:grab=0
Разберем новые строки:
pause 30000 — пауза в программе 30000 миллисекунд (30 секунд). Она нужна для того, чтобы СИМ-карта гарантировано успела зарегистрироваться в мобильной сети.
buffer>clear — мы начинаем работу с буфером, так как в нем могут быть данные оставшиеся от предыдущей работы — очищаем его. Буфер в SIM Roulette — это примерно то же, что clipboard на компьютере, но с ним можно производить намного больше операций: поиск, замену текста, выполнение команды из буфера и т.д., подробнее почитать об этом можно в разделе о программировании вашей модели SR.
buffer>modem:grab=1 — команда включает захват ответов модема в буфер, до ввода этой команды все что отвечал модем просто выводилось в выходной поток терминала.
modem>send:AT+CREG? — отправляем модему AT-команду для выяснения статуса регистрации СИМ-карты в сети. Подробнее об AT-командах можно прочитать в соответствующем разделе документации.
pause 200 — небольшая пауза в 0,2 секунды нужная для того чтобы модем успел сформировать и прислать ответ.
buffer>test:0,1 — проверяем есть ли в довольно длинном ответе модема интересующий нас код 0,1 сигнализирующий о том, что СИМ-карта принята мобильной сетью.
if ok — если код 0,1 — предыдущая команда вернет ответ 1, а значит оператор ветвления перенаправит выполнение программы на метку ok.
echo>СИМ-карта не зарегистрирована в сети — если регистрации в сети нет — выводим в Терминал сообщение.
goto end — без каких-либо условий переходим к метке end.
[ok] — метка ok.
echo>СИМ-карта готова к работе — выводим в Терминал сообщение.
[end] — метка end.
buffer>modem:grab=0 — перед завершением макроса возвращаем настройки на место, отключаем захват ответов модема в буфер.
Запустите макрос через Терминал. По окончании мы теперь видим результат выполнения, но в процессе в выходной поток выводятся ответы промежуточных операций они нам не нужны, давайте их спрячем. Для запрещения вывода в начало добавим answer=0, а в конце вернем все на место командой answer=1.
answer=0
modem>status:connect
if next
modem>connect
modem>on
[next]
pause 30000
buffer>clear
buffer>modem:grab=1
modem>send:AT+CREG?
pause 200
buffer>test:0,1
if ok
echo>СИМ-карта не зарегистрирована в сети
goto end
[ok]
echo>СИМ-карта готова к работе
[end]
buffer>modem:grab=0
answer=1
Теперь макрос стал совсем хорош. Но можно сделать еще одну полезную модификацию — прокомментировать команды:
answer=0 // Выключаем вывод ответов
modem>status:connect // Запрашиваем статус подключения
if next // Если контакты подключены переходим на метку next
modem>connect // Подключаем контакты
modem>on // Включаем модем
[next]
pause 30000 // Ждем 30 секунд
buffer>clear // Очищаем буфер
buffer>modem:grab=1 // Включаем захват ответов модема в буфер
modem>send:AT+CREG? // Запрашиваем у модема статус регистрации в сети
pause 200 // Ждем 0,2 секунды, чтобы модем успел ответить
buffer>test:0,1 // Проверяем есть ли в ответе код успешной регистрации
if ok // Если есть идем на метку ok
echo>СИМ-карта не зарегистрирована в сети // Иначе пишем, что СИМ-карта не зарегистрирована
goto end // Переходим на метку end
[ok]
echo>СИМ-карта готова к работе // Сообщаем, что СИМ-карта готова
[end]
buffer>modem:grab=0 // Выключаем захват ответов модема в буфер
answer=1 // Включаем вывод ответов
Комментарии позволяют ориентироваться к коде, но есть у них еще одно предназначение — комментарии выводятся на экран устройства при включении функции отладки командой Терминала debug=1 (выключение debug=0). Таким образом если вы запутались в ветвлении вашего макроса — включите отладку и смотрите как выполняется программа.
В дальнейшем новые команды и операторы мы будем описывать в комментариях.
А что же с нашим макросом? Он готов. Но не все в нем оптимально. Попробуйте найти место, где мы теряем время и которое следовало бы переписать.
Нашли?
Да, там где мы ждем 30 секунд регистрации модема, в том время как, минимальное время регистрации составляет 9 секунд. Как же быть, ведь мы не знаем сколько уйдет времени на регистрацию? Значит нужно повторять проверку до тех пор, пока мы не получим либо положительного либо отрицательного ответа:
answer=0 // Выключаем вывод ответов
modem>status:connect // Запрашиваем статус подключения
if next // Если контакты подключены переходим на метку next
modem>connect // Подключаем контакты
modem>on // Включаем модем
[next]
pause 5000 // Ждем 5 секунд
buffer>clear // Очищаем буфер
buffer>modem:grab=1 // Включаем захват ответов модема в буфер
modem>send:AT+CREG? // Запрашиваем у модема статус регистрации в сети
pause 200 // Ждем 0,2 секунды, чтобы модем успел ответить
buffer>test:0,1 // Проверяем есть ли в ответе код успешной регистрации
if ok // Если есть идем на метку ok
buffer>test:0,5 // Проверяем есть ли в ответе код успешной регистрации, статус "Роуминг"
if ok // Если есть идем на метку ok
buffer>test:0,2 // Ищем статус "не зарегистрирован, идёт поиск новой сети"
if next
[error]
echo>СИМ-карта не зарегистрирована в сети // Иначе пишем, что СИМ-карта не зарегистрирована
goto end // Переходим на метку end
[ok]
echo>СИМ-карта готова к работе // Сообщаем, что СИМ-карта готова
[end]
buffer>modem:grab=0 // Выключаем захват ответов модема в буфер
answer=1 // Включаем вывод ответов
Ну вот и все, теперь вы умеете писать макросы для SIM Roulette. Ознакомьтесь с синтаксисом макросов, почитайте документацию для SR-Nano, SR-Train, SR-Box, посмотрите примеры макросов. А когда напишите полезный макрос можете поделиться им с другими бесплатно либо выставить на продажу.
Устройство макроса
Строки в макросе выполняются последовательно сверху вниз. Для изменения порядка выполнения применяются метки, операторы ветвления и безусловного перехода.
Метка - любое слово латиницей обрамленное квадратными скобками, ставится над строкой на которую должен быть осуществлен переход.
Пример метки: [next]
Текст макроса не должен содержать пустых строк. Каждая команда макроса может сопровождаться комментарием, отделенным от команды символами //, при этом команда debug=1 позволяет отслеживать ход выполнения макроса, на экране устройства будут отображаться комментарии к выполняемым макросом строкам, debug=0 отключает этот режим.
При запуске макроса через Терминал можно передать ему входные параметры m:my_macros>Текст_для_передачи_макросу Строка после > поступит в буфер, а дальше может быть разобрана стандартными методами работы с буфером.
Макросы размещаются в папке /m файловой системы.
Сложные макросы представляют собой комплексы файлов, в этом случае целесообразно хранить их в одной папке. При запуске макроса через терминал достаточно указать имя папки, SR найдет и запустит одноименный файл внутри указанной папки. При наличии макроса m/scanner/scanner его можно запустить как командой m:scanner/scanner так и m:scanner.
Также целесообразно снабжать сложные комплексы макросов файлом-руководством в формате макроса (среди примеров есть образец) с именем help и файлом-меню если предполагается запуск различных макросов из набора (пример также есть).
Синтаксис
Операторы ветвления
if — Проверяет результат выполнения предыдущей команды. Если результат равен 1 — осуществляется переход к указанной метке.
value>a<10
if next
...
[next]
...
unless — Проверяет результат выполнения предыдущей команды. Если результат равен 0 (NULL/Пустой) — осуществляется переход к указанной метке.
unless next
Оператор безусловного перехода
goto — Осуществляет переход к указанной метке.
goto next
...
[next]
...
Операторы завершения программы
stop — Завершение работы макроса.
stop
return — Производит досрочный возврат из вложенного макроса (по умолчанию возврат происходит после выполнения команды в последней строке вложенного макроса).
return
Оператор ввода
input — Производит запрос действия сотрудника-оператора в разделе WEB-интерфейса Оператор. Параметры: максимальная длина вводимых данных;текст который будет выведен оператору над полем ввода).
input 1;Выберите действие:<br>1-первый вариант<br>2-второй вариант
Операторы выполнения команды из буфера
exec Выполняет команду из буфера (текст помещенный в буфер будет передан на выполнение как команда).
buffer>write=sound:beep
exec
exec2 Выполняет команду из копии буфера в стеке.
buffer>write=sound:beep
buffer>push
exec2
Оператор подключения вложенного макроса
include Подключает указанный макрос и передает ему управление (степень вложенности макросов неограничена), по окончании управление возвращается в текущий макрос.
include macrosname
Пауза
pause Пауза (приостановка программы) в миллисекундах (1/1000 секунды)
pause 1000
Полезные приемы
Оформление текста
В тексте выводящимся в выходной поток терминала можно использовать следующую мнемонику для трансформаций:
[br] — перевод строки
[b]жирный текст[/b]
[i]курсив[/i]
Таблицы
Данные в выходной поток Терминала можно выводить в виде таблицы для этого используется следующий синтаксис (для удобства воcприятия он разложен по строкам, но в макросе текст команды всегда вводится одной строкой):
[table]
[tr]
[th]Заголовок 1-го столбца[/th]
[th]Заголовок 2-го столбца[/th]
[/tr]
[tr]
[td]Содержимое 1-го столбца[/td]
[td]Содержимое 2-го столбца[/td]
[/tr]
[/table]
Переход на другую страницу WEB-интерфейса/Перезагрузка страницы
Для перехода на любой _URL_ в текст, выводящийся в выходной поток Терминала (командами echo> или buffer>view), необходимо вставить команду sr>reload_URL_;
buffer>write=sr>reload/terminal;
buffer>view
echo>sr>reloadhttps://google.com;
Очистка выходного потока Терминала
Для очистки выходного потока Терминала в текст необходимо вставить команду sr>clear;
buffer>write=sr>clear;
buffer>view
echo>sr>clear;
Эмуляция ручного ввода команды и ее исполнение
Для исполнения любой команды (_COM_) в любое место текста, выводящегося в выходной поток Терминала (командами echo> или buffer>view), необходимо вставить команду sr>com:_COM_; Команда будет выполнена с текущим шагом (step) Терминала и останется в логе команд.
buffer>write=sr>com:sound:beep;
buffer>view
echo>sr>com:sound:beep;
Вывод текста в поле ввода команды Терминала
Для вывода произвольного текста (_TEXT_) в поле для ввода команды Терминала в любое место текста, выводящегося в выходной поток Терминала (командами echo> или buffer>view), необходимо вставить команду sr>enter:_TEXT_; После вставки текста в поле для ввода команды туда же переместится фокус браузера.
buffer>write=sr>text:sound:;
buffer>view
echo>sr>text:sound:;
Гиперсылки
Для удобства навигации вместо или наряду со списком команд можно выводить готовые гиперссылки содержащие команды. Для этого в любое место текста, выводящегося в выходной поток Терминала (командами echo> или buffer>view), вставляются конструкции [link]_КОМАНДА_[name]_НАЗВАНИЕ_[/name][/link]
buffer>write=sr>Команда [link]sound:beep[name]ЗВУК[/name][/link]
buffer>view
echo>sr>Команда [link]sound:beep[name]ЗВУК[/name][/link]
Примеры
autoexec (SR-Nano)
Макрос для управления устройством с пульта ДУ, предлагает выбрать из меню сканирование карт на диске, переход к карте A0, переход к следующей карте.
answer=0 // Выключаем вывод ответов
key>discover // Проверяем включен ли режим работы с пультом
unless finish // Если нет - выходим
[loop]
display=10::C::64::0::[ {MENU~МЕНЮ} ]|10::L::0::10::1 {Cards scanning~Сканирование карт}|10::L::0::25::2 {Card A0~Карта A0}|10::L::0::40::3 {Next card~Следующая карта} // Выводим на экран устройства меню
[next]
buffer>clear // Очищаем буфер
key // Запрашиваем команду с пульта
unless wait // Если команды нет - отправляемся ждать ее
buffer>test:1 // Ищем в буфере 1
if a1 // Если нашли
buffer>test:2 // Ищем в буфере 2
if a2 // Если нашли
buffer>test:3 // Ищем в буфере 2
if a3 // Если нашли
[wait]
pause 100 // Ждем 0.1 секунды
goto next // Повторяем
[a1]
sound:beep // Подаем звук
display=10::C::64::15::1 #123Cards scanning~Сканирование карт} // Выводим на экран устройства текст
include scanner // Передаем управление макросу сканирования СИМ-карт
goto loop
[a2]
sound:beep // Подаем звук
display=10::C::64::15::1 #123Card A0~Карта A0} // Выводим на экран устройства текст
card:A0 // Выбираем карту A0
goto loop
[a3]
sound:beep // Подаем звук
display=10::C::64::15::1 #123Next card~Следующая карта} // Выводим на экран устройства текст
card>next // Выбираем следующую карту
goto loop
[finish]
answer=1 // Включаем вывод ответов
com_add
Макрос для добавления в Терминал кнопок быстрых ссылок.
answer=0 // Выключаем вывод ответов
buffer>swap // Меняем буфер и копию местами
buffer>fs>load>file:/terminal.dat // Загружаем в буфер текущее содержание кнопок
buffer>merge= // Склеиваем буфер и копию буфера
buffer>postfix=; // Добавляем в конец буфера ;
buffer>fs>save>file:/terminal.dat // Сохраняем отредактированный файл
buffer>write=Command added // Готовим уведомление о том, что кнопка добавлена
answer=1 // Включаем вывод ответов
buffer>view // Выводим уведомление
answer=0 // Выключаем вывод ответов
pause 1000 // Ждем секунду
buffer>write=sr>reload/terminal; // Готовим текст для обновления окна Терминала
answer=1 // Включаем вывод ответов
buffer>view // Обновляем окно Терминала