Работа с контроллером Q-PLC ESP32 через HTTP API

Работа с контроллером Q-PLC ESP32 через HTTP API

Базовая прошивка Q-PLC предоставляет RESTful HTTP API для удобного взаимодействия с контроллером, используя стандартные HTTP-методы и JSON-формат для интеграции с любыми современными системами.

Основные функции:

🔹 Удалённое управление - контролировать состояние реле и GPIO через сеть
🔹 Мониторинг параметров - получать данные о системе в реальном времени
🔹 Гибкую интеграцию - подключать контроллер к другим системам (Home Assistant, Node-RED и др.)
🔹 Безопасность - встроенная аутентификация и защита данных

Основные возможности API:
✅ Управление реле, с настройкой задержки
✅ Контроль состояния цифровых входов
✅ Настройка WiFi/Ethernet подключения
✅ Работа с MQTT, Webhook и т.п.

HTTP API предназначено для интеграторов систем умного дома, разработчиков IoT-решений и инженеров автоматизации, предоставляя удобный интерфейс для удалённого управления функциями контроллера, мониторинга параметров системы в реальном времени, настройки сетевых подключений (WiFi/Ethernet), работы с MQTT, Webhook и Modbus в формате JSON.

Общая информация
  • Базовый URL: /api/v1/
  • Формат данных: JSON
  • Кодировка: UTF-8
  • Лимит запросов: 10 запросов/сек
Аутентификация

Все запросы требуют Basic-аутентификации:

//логин: admin пароль: admin
Authorization: Basic YWRtaW46YWRtaW4=
Системная информация

Запрос:

GET /api/v1/system/info
Authorization: Basic YWRtaW46YWRtaW4=

Ответ:

{
	"ap": "192.168.4.1",
	"eth": "192.168.12.92",
	"chip_revision": 2,
	"mac_address": "DC:DA:0C:47:B9:64",
	"app_ver": "0.3.0",
	"app_time": "13:56:40",
	"app_date": "Mar  7 2024",
	"flash_size": 8388608,
	"idf_ver": "v5.1.2",
	"cores": 2,
	"minimum_free_heap": 170568,
	"mqtt_is_connected": false,
	"free_heap": 185380,
	"uptime": 4002
}
Перезагрузка устройства:
POST /api/v1/system/reset
Authorization: Basic YWRtaW46YWRtaW4=

Ответ:

{
  "message": "device_will_reboot_after_3_seconds"
}
Получение состояний GPIO:
GET /api/v1/gpio/status
Authorization: Basic YWRtaW46YWRtaW4=

Ответ:

{
 "type": "gpio",
 "mac": "DC:DA:0C:47:B9:64",
 "relays":{
	"out0": 0,
	"out1": 0,
	"out2": 0,
	"out3": 0
 },
 "inputs":{
	"in0": 0,
	"in1": 0,
	"in2": 0,
	"in3": 0,
	"in4": 0,
	"in5": 0,
	"in6": 0,
	"in7": 0
 }
}
Управление реле:
POST /api/v1/relay/switch?out0=1&delay=3&delay_unit=sec
Authorization: Basic YWRtaW46YWRtaW4=

где:

  • outN - номер реле
  • 0 - выключено, 1 - включено
  • delay - задержка в секундах после которой реле вернется в исходное, до команды, состояние.
  • delay_unit - параметр единиц измерения времени задержки для параметра delay. Параметр поддерживает значения: ms - миллисекунды; sec - секунды; min - минуты. Если парамер не задан, то по-умолчанию время считается в секундах. Если параметр delay не задан, то delay_unit будет игнорироваться.

Ответ:

{
 "type": "gpio",
 "mac": "DC:DA:0C:47:B9:64",
 "relays":{
	"out0": 0,
	"out1": 0,
	"out2": 0,
	"out3": 0
 },
 "inputs":{
	"in0": 0,
	"in1": 0,
	"in2": 0,
	"in3": 0,
	"in4": 0,
	"in5": 0,
	"in6": 0,
	"in7": 0
 }
}
Получение текущих настроек
GET /api/v1/networks/status
Authorization: Basic YWRtaW46YWRtaW4=

Ответ:

{
  "networks": {
    "eth": {
      "ip_mode": "static",
      "ip_address": "192.168.1.100",
      "mask": "255.255.255.0",
      "gateway": "192.168.1.1",
      "dns1": "8.8.8.8",
      "dns2": "8.8.4.4"
    },
    "wifi": {
      "wifi_mode": 2,
      "ap_ssid": "",
      "ap_password": "",
      "sta_ssid": "MyWiFi",
      "sta_password": "",
      "ip_mode": "dhcp",
      "ip_address": "192.168.1.101",
      "mask": "255.255.255.0",
      "gateway": "192.168.1.1",
      "dns1": "8.8.8.8",
      "dns2": "8.8.4.4"
    }
  },
  "mqtt": {
    "mqtt_enable": "1",
    "mqtt_host": "mqtt.example.com",
    "mqtt_login": "user",
    "mqtt_passwd": "",
    "mqtt_sub": "device/123/control",
    "mqtt_pub": "device/123/status"
  },
  "webhook": {
    "webhook_enable": 1,
    "webhook_url": "https://example.com/webhook",
    "webhook_username": "user",
    "webhook_password": ""
  },
  "modbus": {
    "modbus_enable": 0,
    "modbus_interface": 0,
    "modbus_slave_id": 1
  },
  "relays": {
    "out0": 1,
    "out1": 0,
    "out2": 1,
    "out3": 0
  },
  "ble": {
    "ble_enable": 1,
    "ble_passkey": 123456
  },
  "heap": 181772
}
Настройка Ethernet:
//dhcp mode
POST /api/v1/networks/ethernet
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/x-www-form-urlencoded
ip-mode=dhcp

//static mode
POST /api/v1/networks/ethernet
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/x-www-form-urlencoded
ip-mode=static&ip-address=192.168.12.92&mask=255.255.255.0&gateway=192.168.12.1&dns1=192.168.12.1&dns2=8.8.8.8

Ответ:

{
  "message": "Ethernet_settings_saved. Reboot for apply"
}
Настройка WiFi:
// ap mode
POST /api/v1/networks/wifi
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/x-www-form-urlencoded

wifi-mode=1&wifi-ap-ssid=QPLC-B964&wifi-ap-password=plc-password&wifi-ip-mode=dhcp

// client mode with dhcp ip
POST /api/v1/networks/wifi
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/x-www-form-urlencoded

wifi-mode=2&sta-ssid=work-wifi&sta-password=wifi-password&wifi-ip-mode=dhcp

// client mode with static ip
POST /api/v1/networks/wifi
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/x-www-form-urlencoded

wifi-mode=2&sta-ssid=work-wifi&sta-password=wifi-password&wifi-ip-mode=static&ip-address=192.168.5.55&subnet-mask=255.255.255.0&gateway=192.168.5.1&dns1=192.168.5.1&dns2=8.8.8.8

// disable wifi
POST /api/v1/networks/wifi
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/x-www-form-urlencoded

wifi-mode=0

Ответ:

{
  "message": "Wi-Fi_settings_saved. Reboot for apply"
}
Настройка MQTT
POST /api/v1/networks/mqtt
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/x-www-form-urlencoded

mqtt_enable=1&mqtt_host=mqtt.example.com&mqtt_login=user&mqtt_passwd=secret&mqtt_sub=device%2F123%2Fcontrol&mqtt_pub=device%2F123%2Fstatus

%2F - экранирование символа /

//disable mqtt
POST /api/v1/networks/mqtt
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/x-www-form-urlencoded

mqtt_enable=0

Ответ:

{
  "message": "MQTT settings saved. Reboot for apply"
}
Настройка Webhook
POST /api/v1/networks/webhook
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/x-www-form-urlencoded

webhook_enable=1&webhook_url=https://example.com/webhook&webhook_username=user&webhook_password=secret

//disable webhook
POST /api/v1/networks/webhook
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/x-www-form-urlencoded

webhook_enable=0

Ответ:

{
  "message": "Webhook settings saved. Reboot for apply"
}

При смене состояний либо входов либо реле на указанный URL будет отправлен POST запрос с данными текущих состояний GPIO

{
 "type": "gpio",
 "mac": "DC:DA:0C:47:B9:64",
 "relays":{
	"out0": 0,
	"out1": 0,
	"out2": 0,
	"out3": 0
 },
 "inputs":{
	"in0": 0,
	"in1": 0,
	"in2": 0,
	"in3": 0,
	"in4": 0,
	"in5": 0,
	"in6": 0,
	"in7": 0
 }
}
Настройка Modbus
POST /api/v1/networks/modbus
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/x-www-form-urlencoded

modbus_enable=1&modbus_interface=0&modbus_slave_id=1

modbus_interface=0 - привязка к ethernet интерфейсу; modbus_interface=1 - привязка к wifi интерфейсу (если он включен)

// disable modbus
POST /api/v1/networks/modbus
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/x-www-form-urlencoded

modbus_enable=0
Настройка Bluetooth
POST /api/v1/networks/ble
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/x-www-form-urlencoded

ble_enable=1&ble_passkey=123654

// disable BLE
POST /api/v1/networks/modbus
Authorization: Basic YWRtaW46YWRtaW4=
Content-Type: application/x-www-form-urlencoded

ble_enable=0
Тэги :

Похожие статьи

Инструкция по обновлению прошивки через WEB-интерфейс

Инструкция по обновлению прошивки через WEB-интерфейс

Данная инструкция описывает процесс обновления прошивки контроллера Q-PLC через веб-интерфейс. Этот метод позволяет быстро и безопасно загрузить новую версию прошивки без использования дополнительного ПО, напрямую через браузер.

Подробнее
Подбор блока питания для контроллера Q-PLC

Подбор блока питания для контроллера Q-PLC

Контроллер Q-PLC — это универсальное и надежное устройство, предназначенное для работы в различных промышленных и автоматизированных системах.

Подробнее
Вышла новая версия прошивки 0.4.0

Вышла новая версия прошивки 0.4.0

Сообщаем о выходе обновления прошивки для контроллера Q-PLC содержащее ряд улучшений и исправлений позволяющих повысить стабильность и упростить использование контроллера.

Подробнее