API Options

Опция обеспечивает доступ к параметрам контроллера из внешних программ или систем через GET-запросы или MQTT.

Настройки опции

В целях безопасности по-умолчанию установлено ограничение функций API.

Если галочка "только API конструктора строк (linesdesigner)" установлена, то через API запросы будут доступны только операции чтения и записи строк в модуле конструктора строк (функционал соответствует вкладке Designer_lines в веб интерфейсе).

На практике группа linesdesigner часто применяется для управления выводом информации на дисплеи.
Подробнее примеры установки данных на светодиодное табло рассмотрены в разделе LED PLC API.

Внимание!

Если используется полный функционал API и галочка "только API конструктора строк (linesdesigner)" снята, то без дополнительной защиты возможен доступ ко всем настройкам в открытом виде, включая пароли!

Будьте внимательны включая опцию "API Options" в прошивке!
Эта опция даёт широкие возможности по чтению и изменению параметров.
Список доступных групп параметров зависит от конфигурации прошивки.

Для защиты от несанкционированных операций чтения или записи параметров крайне рекомендуется ограничить доступ к веб-интерфейсу контроллера или к локальной сети, к которой подключен контроллер. Также возможно установить пароль на вкладке Main и обязательно установить галочку Full Security!

Управление через GET запросы

Чтение настроек

http://[ip_adr]/jsonoptions?select=XXXXX, где XXXXX - имя группы настроек (main, hardware, servers и прочие... all - выведет все настройки). Как правило имя группы настроек соответствует названиям вкладок в веб-интерфейсе. В ответ контроллер пришлёт настройки группы в формате JSON.

Пример 1:

http://192.168.100.1/jsonoptions?select=thermostat - выдаст содержимое настроек термостата.

Пример 2:

http://192.168.100.1/jsonoptions?select=all - выдаст содержимое всех настроек модуля.

Запись настроек

http://[ip_adr]/jsonoptions?write=XXXXX, где XXXXX параметры в формате JSON (можно отправлять только параметры, которые требуется изменить). После отправки покажет OK и число измененных параметров. Параметры должны быть сгруппированы по группам.

Чтобы верно сформировать JSON-строку, удобно сначала прочитать содержимое нужной группы, исправить нужные поля и записать исправленную строку обратно.

Пример 3:

http://192.168.100.1/jsonoptions?write={"hardware":{"interval":2,"i2c":{"scl":5,"sda":4},"ds18b20":{"en":1,"gpio":13}}} - установит настройки группы hardware.

Ограничения по использованию

Опция экспериментальная. При попытке чтения или отправки чрезмерно большого пакета данных возможен отказ или сбой в работе прошивки.
При чтении желательно использовать вместо all чтение каждой группы отдельно, а при записи указывать только изменяемые параметры.

Управление через MQTT

При включенной опции контроллер подписывается на MQTT-топик вида: login/hostname[/set]/optionsget и login/hostname[/set]/optionsset и публикует ответы в топик login/hostname/optionsdata.

Если в топик login/hostname[/set]/optionsget отправить 0, в ответ в топик login/hostname/optionsdata в формате JSON придет список групп, доступных для конфигурации.

Если в топик login/hostname[/set]/optionsget отправить название группы, в ответ в топик login/hostname/optionsdata в формате JSON придет список параметров данной группы и их текущие значения.

Если в топик login/hostname[/set]/optionsset отправить настройки в формате JSON (аналогичном полученным на предыдущем шаге), настройки будут изменены. Допускается публикация только тех параметров, значения которых должны быть изменены.

Примечание. Рекомендуется в прошивке в настройках MQTT включать "отдельный топик на запись". В этом случае в топиках на запись добавляется секция /set

Поддерживаемые группы параметров

Набор доступных параметров зависит от конфигурации прошивки.
Чтобы узнать какие группы поддерживаются для конкретного контроллера, можно выполнить GET-запрос вида http://[ip_adr]/jsonoptions (без параметров), либо отправить 0 в топик вида login/hostname[/set]/optionsget и получить в топике login/hostname/optionsdata список.

Возможна поддержка следующих групп:

main (не реализована установка времени)
servers (настройка серверов)
hardware
gpiomode (режимы работы GPIO: out, outinv, input, inputev, outf, outinvf)
interrupt (прерывания, режимы: counter, activesend, key, timekey)
linesdesigner (конструктор строк)
thermostat
ping (ping тест)
phoneaccess (список доступа телефонов для GSM control)
ipsecurity
display (Работа с дисплеями)
vgpio
vsens
template (sms/email шаблоны)
wol
mp3 (mp3 uart конструктор фраз)
scheduler (планировщик задач)
promode (активация ключа)
ddns (myddns.ru)
logic2 (Логический модуль 2, не отображается в секции all, ограничено до 5 шагов)
notifications (настройки уведомлений от gsm и sms сервисов)
emailnotice (email уведомления)
gsmcontrol
pwm
irrec (ИК приемник)
rcrec (RCswitch приемник)
mcpgpio (MCP23017 только одна микросхема)
mcp8gpio (MCP23008 только одна микросхема)
narodmonget (Narodmon GET)
telegram
webkey
Interpreter
gpiokeys
pid (не все параметры записываются)
d2d
cron
domoticz
camera

Пример JSON пакета настроек

Прошивка выдает и принимает JSON только одной строкой. Ниже приведён текст с форматированием для удобства.

Чтобы упаковать JSON в одну строку, можно применить один из онлайн-сервисов, которые можно найти в интернете по ключевым словам "JSON Minifier".

{
   "main": {
      "hostname": "esptest",
      "admin": {
         "login": "",
         "passw": "",
         "security": 0
      },
      "wifi": {
         "apname": "megarouter",
         "appassw": "20100100",
         "apmode": 0,
         "ip": "192.168.1.200",
         "gw": "192.168.1.1",
         "staticip": 1
      },
      "ntp": {
         "utc": 3,
         "ip": "85.114.26.194"
      }
   },
   "hardware": {
      "interval": 2,
      "i2c": {
         "scl": 5,
         "sda": 4
      },
      "ds18b20": {
         "en": 1,
         "gpio": 13
      }
   },
   "servers": {
      "mjd": {
         "en": 1,
         "ip": "192.168.1.154",
         "interval": 300
      },
      "narodmon": {
         "en": 1,
         "interval": 5
      },
      "flymon": {
         "en": 1
      },
      "mqtt": {
         "en": 0,
         "interval": 60,
         "server": "mqtt.wifi-iot.com",
         "port": 1883,
         "login": "maksms",
         "passw": "pass"
      }
   },
   "promode": {
      "en": 1,
      "key": "78J7941000"
   },
   "gpiomode": {
      "0": "",
      "1": "",
      "2": "",
      "3": "",
      "4": "",
      "5": "",
      "12": "",
      "13": "",
      "14": "",
      "15": "",
      "16": "out"
   },
   "display": {
      "mode": "oled",
      "backlight": 1,
      "dislogo": 0
   },
   "phoneaccess": {
      "1": "79091441234",
      "2": ""
   },
   "interrupt": {
      "divider": 10,
      "mode": "neg",
      "1": {
         "intgpio": 0,
         "keygpio": 5,
         "mode": "",
         "timeforkey": 10
      },
      "2": {
         "intgpio": 0,
         "keygpio": 193,
         "mode": "key"
      },
      "3": {
         "intgpio": 255,
         "keygpio": 2,
         "mode": ""
      },
      "4": {
         "intgpio": 255,
         "keygpio": 2,
         "mode": ""
      }
   },
   "scheduler": {
      "1": {
         "hour": 6,
         "min": 0,
         "week": "1,2",
         "mode": "display",
         "num": 1,
         "state": 1
      },
      "2": {
         "hour": 22,
         "min": 0,
         "week": "1,2,3,4,5,6,7",
         "mode": "display",
         "num": 0,
         "state": 0
      }
   },
   "linesdesigner": {
      "1": "_DSW1_ !! _VDD_ ! _GPIO16_ !",
      "2": "_CNT1I_",
      "3": "Сегодня _DATE_ _WEEK_ . дома _DSW1_ градусов",
      "4": "_DATE_ _WEEK_"
   },
   "ping": {
      "en": 0,
      "ip": "8.8.8.8",
      "gpio": 255
   },
   "ipsecurity": {
      "en": 1,
      "homeen": 1,
      "ipaccess": {
         "1": "192.168.1.255",
         "2": "109.194.190.101",
         "3": "255.255.255.255",
         "4": "192.168.100.255",
         "5": "255.255.255.255"
      }
   },
   "vgpio": {
      "20": 154,
      "40": 170,
      "60": 177
   },
   "vsens": {
      "1": {
         "ip": "192.168.1.177",
         "sens": {
            "1": 2,
            "2": 3,
            "3": 7,
            "4": 5,
            "5": 6
         }
      },
      "2": {
         "ip": "192.168.1.153",
         "sens": {
            "1": 2,
            "2": 3,
            "3": 0,
            "4": 0,
            "5": 0
         }
      },
      "3": {
         "ip": "255.255.255.255",
         "sens": {
            "1": 31,
            "2": 31,
            "3": 31,
            "4": 31,
            "5": 31
         }
      }
   },
   "notifications": {
      "interrupt": 0,
      "pingalarm": 1,
      "gsmen": 1,
      "fone": "79005123456"
   },
   "emailnotice": {
      "emailen": 1,
      "mailfrom": "mail@wifi-iot.ru",
      "server": "smtp-devices.yandex.com",
      "port": 25,
      "login": "mail@wifi-iot.ru",
      "passw": "12345",
      "mailto": "mail@ya.ru"
   },
   "template": {
      "1": {
         "txt": "DS: _DSW1_ VS: _VS11_ IP: _IP_",
         "cmd": "cmd1"
      },
      "2": {
         "txt": "no sms text",
         "cmd": "cmd2"
      },
      "3": {
         "txt": "no sms text",
         "cmd": "cmd3"
      }
   },
   "mp3": {
      "1": "0,0,41,T111",
      "2": "0",
      "3": "0"
   }
}