ModbusMaster HTTP API

ModbusMaster HTTP API

• /help
  
• /
  
• /reload
  
• /mode
  
• /getparam и /setparam
• /status

Базовый URL

/api/v01/<object>/

/help Получение списка доступных команд и параметров.

/ Получение стандартной информации об объекте.

/reload?confile=/path/to/confile Перезагрузить конфигурацию. Параметр confile — абсолютный путь до файла конфигурации (необязательный).

/mode Управление режимом обмена. Поддерживаются команды:

• ?get — получить текущий режим
• ?supported=1 — получить список поддерживаемых режимов
• ?set=<mode> — установить новый режим (если не привязан к датчику)

Примеры

GET /api/v01/MBTCPMaster1/help
GET /api/v01/MBTCPMaster1/
GET /api/v01/MBTCPMaster1/reload
GET /api/v01/MBTCPMaster1/mode?get
GET /api/v01/MBTCPMaster1/mode?supported=1
GET /api/v01/MBTCPMaster1/mode?set=writeOnly

Заметки

При привязке режима к датчику ?set вернёт ошибку: "control via sensor is enabled. Manual change is not allowed."

/help

Возвращает список доступных команд и их краткое описание. Используется для интроспекции API и автоматизации.

GET /<object>/help

Заметки

Возвращает JSON с перечнем доступных команд и параметров.

/

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

GET /<object>/

Заметки

Используется для получения общей информации о процессе ModbusMaster.

/reload

Перезагрузка конфигурации с возможностью указания альтернативного файла конфигурации.

GET /<object>/reload?confile=/path/to/confile
Response:
{
  "result": "OK",
  "confile": "/path/to/confile"
}

Предупреждения

Если указан confile, он должен соответствовать базовому configure.xml. Минимум должен содержать секцию настроек для процесса и используемые датчики. Глобальный конфиг не заменяется — только частично переинициализируется.

/mode

Управление режимом обмена. Доступные команды:

• ?get — получить текущий режим
• ?supported=1 — получить список поддерживаемых режимов
• ?set=<mode> — установить новый режим (если не привязан к датчику)

GET /<object>/mode?get
GET /<object>/mode?supported=1
GET /<object>/mode?set=writeOnly

Заметки

Если режим привязан к датчику, установка через ?set недоступна: "control via sensor is enabled. Manual change is not allowed."

/getparam и /setparam

Чтение и изменение выбранных runtime-параметров процесса обмена. Базовый путь: /api/v01/ <object>/...

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

• force (0|1) — принудительный режим (bool)
• force_out (0|1) — принудительный режим для выходов (bool)
• maxHeartBeat (ms) — максимальный интервал «пульса» (целое, миллисекунды)
• recv_timeout (ms) — таймаут при ожидании ответа от устройства
• sleepPause_msec (ms) — пауза между циклами опроса
• polltime (ms) — период опроса
• default_timeout (ms) — стандартный таймаут обмена

Чтение параметров

GET /api/v01/MBTCPMaster1/getparam?name=force&name=recv_timeout&name=polltime
Response:
{
  "result": "OK",
  "params": {
    "force": 0,
    "recv_timeout": 2000,
    "polltime": 1000
  },
  "unknown": ["..."]        // (опционально) имена, которые не поддерживаются
}

Правила:

• Параметр name может повторяться. Если список пуст, сервер вернёт ошибку.
• Неизвестные name попадают в массив unknown (ответ остаётся "result":"OK").

Изменение параметров

GET /api/v01/MBTCPMaster1/setparam?recv_timeout=3000&polltime=2000
Response:
{
  "result": "OK",
  "updated": {
    "recv_timeout": 3000,
    "polltime": 2000
  },
  "unknown": ["..."]        // (опционально) имена, которые не поддерживаются
}

Правила:

• Передаются пары name=value в query-строке. Допускается изменение нескольких параметров за один запрос.
• Для force и force_out допустимы строки "0" или "1".
• Для таймаутов — целое число миллисекунд (>0 рекомендуется).
• Параметры polltime и recv_timeout применяются динамически.
• Параметры sleepPause_msec и default_timeout являются постоянными.

Коды ошибок

• 400/5xx при отсутствующих или некорректных значениях (например, recv_timeout="abc")
• 400 при отсутствии ключей в запросе /setparam или отсутствии name в /getparam

Заметки

Данные параметры ограничены только перечисленными выше. Добавление новых параметров требует изменений в реализации.

/status

Возвращает текущее состояние объекта в формате JSON (аналогично getInfo()).

GET /api/v01/MBTCPMaster1/status

Response

{
  "result": "OK",
  "status": {
    "name": "MBTCPMaster1",
    "monitor": "vmon: OK",
    "activated": 1,
    "logserver": {
      "host": "127.0.0.1",
      "port": 5510
    },
    "parameters": {
      "reopenTimeout": 5000,
      "config": "TCP(master): 192.168.0.1:502 (10 devices)"
    },
    "statistics": {
      "text": "Packets: 1200 ok, 0 errors",
      "interval": 30000
    },
    "devices": [
      { "id": 1, "info": "Dev1 [10 regs]" },
      { "id": 2, "info": "Dev2 [8 regs]" }
    ],
    "mode": {
      "name": "writeOnly",
      "id": 1,
      "control": "manual"
    },
    "maxHeartBeat": 10,
    "force": 0,
    "force_out": 0,
    "activateTimeout": 2000,
    "reopenTimeout": 5000,
    "notUseExchangeTimer": 0,
    "config_params": {
      "recv_timeout": 1000,
      "sleepPause_msec": 50,
      "polltime": 200,
      "default_timeout": 5000
    }
  }
}

Описание полей

• name — имя объекта обмена
• monitor — краткая строка мониторинга состояния
• activated — флаг активности
• logserver — адрес и порт лог-сервера
• parameters — основные параметры обмена (включая reopenTimeout и краткую конфигурацию)
• statistics — текстовая статистика и интервал обновления
• devices — список подключённых устройств с краткой информацией
• mode — текущий режим работы, включая:
  • name — строковое название режима
  • id — числовой идентификатор режима
  • control — источник управления ("manual" или "sensor")
  • sid — идентификатор датчика, если режим управляется через него
• maxHeartBeat, force, force_out — текущие значения ключевых параметров обмена
• activateTimeout, reopenTimeout — интервалы (мс)
• notUseExchangeTimer — флаг использования таймера обмена
• config_params — набор базовых конфигурационных параметров обмена

Примечания

• Запрос не требует параметров.
• Ответ полностью соответствует содержанию getInfo(), но представлен в виде структурированного JSON.