ModbusMaster HTTP API

ModbusMaster HTTP API

• help
• root
• reload
• mode
• params
• status
• registers
• devices
• get
• takeControl / releaseControl

Базовый URL: /api/v2/<object>/

/help

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

GET /api/v2/<object>/help

/

Стандартная информация об объекте (включая extensionType), плюс секция LogServer (если сервер включён).

{
  "object": {
    "id": 1001,
    "name": "MBTCPMaster1",
    "extensionType": "ModbusMaster"
  }
}

/reload

Перезагрузка конфигурации. Параметр confile — абсолютный путь к альтернативному конфигу (необязателен).

GET /api/v2/<object>/reload?confile=/path/to/confile

Ответ:

{ "result": "OK", "confile": "/path/to/confile" }

Указанный confile должен соответствовать configure.xml (минимум секции процесса и датчиков).

/mode

Управление режимом обмена:

• ?get — текущий режим
• ?supported=1 — поддерживаемые режимы
• ?set=<mode> — установка режима

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

• none (0) — нормальная работа (по умолчанию)
• writeOnly (1) — только посылка данных (работают только write-функции)
• readOnly (2) — только чтение (работают только read-функции)
• skipSaveToSM (3) — не записывать данные в SM (обмен ведётся полностью, но данные не сохраняются в SharedMemory)
• skipExchange (4) — отключить обмен (при этом данные "из SM" обновляются)

Важно: Для установки режима через ?set=<mode> необходимо сначала включить HTTP-контроль. См. раздел /takeControl и /releaseControl.

Примеры:

GET /api/v2/MBTCPMaster1/mode?get
GET /api/v2/MBTCPMaster1/mode?supported=1
GET /api/v2/MBTCPMaster1/mode?set=writeOnly

/getparam и /setparam

Чтение/изменение runtime‑параметров. Базовый путь: /api/v2/<object>/....

Параметры:

• force (0|1)
• force_out (0|1)
• maxHeartBeat (ms)
• recv_timeout (ms)
• sleepPause_msec (ms)
• polltime (ms)
• default_timeout (ms)

Чтение:

GET /api/v2/MBTCPMaster1/getparam?name=force&name=recv_timeout&name=polltime

Ответ:

{
  "result": "OK",
  "params": { "force": 0, "recv_timeout": 2000, "polltime": 1000 },
  "unknown": ["..."]
}

Изменение:

GET /api/v2/MBTCPMaster1/setparam?recv_timeout=3000&polltime=2000

Ответ:

{
  "result": "OK",
  "updated": { "recv_timeout": 3000, "polltime": 2000 },
  "unknown": ["..."]
}

Правила и ошибки:

• Ключи передаются как name=value; пустые запросы дают 400.
• Для bool параметров допустимы строки 0|1|true.
• Неизвестные имена попадают в unknown.
• Некорректные значения → 400/5xx.
• Изменение доступно только если в конфиге/CLI указано --<prefix>-http-enabled-setparams=1, иначе вернётся ошибка.

/status

Текущее состояние (аналог getInfo()):

GET /api/v2/MBTCPMaster1/status

Ключевые поля: result, status.name, monitor, activated, logserver, parameters.config, статистика (если включена), список устройств, режим (mode.name/id/control), force, force_out, maxHeartBeat, httpControlAllow, httpControlActive, httpEnabledSetParams, config_params (recv_timeout, sleepPause_msec, polltime, default_timeout).

/registers

Список регистров с фильтрацией/пагинацией.

GET /api/v2/MBTCPMaster1/registers
GET /api/v2/MBTCPMaster1/registers?offset=0&limit=50
GET /api/v2/MBTCPMaster1/registers?search=Sensor&iotype=AI
GET /api/v2/MBTCPMaster1/registers?filter=1003,Sensor1_AI,1005

Параметры: offset, limit, search, filter, iotype (AI/AO/DI/DO). Фильтры по addr/regs не поддерживаются.

Пример ответа:

{
  "result": "OK",
  "devices": {
    "1": { "respond": 1, "dtype": "rtu", "mode": 0, "safeMode": 0 }
  },
  "registers": [
    {
      "id": 1003,
      "name": "Sensor1_AI",
      "iotype": "AI",
      "value": 42,
      "vtype": "signed",
      "device": 1,
      "register": { "mbreg": 10, "mbfunc": 3, "mbval": 1 },
      "nbit": 0,
      "mask": 0,
      "precision": 0
    }
  ],
  "total": 150,
  "count": 50,
  "offset": 0,
  "limit": 50
}

/devices

Список устройств (по Modbus-адресам) с их состоянием. Реализация повторяет ModbusMaster API.

{
  "result": "OK",
  "devices": [
    { "addr": 1, "respond": 1, "dtype": "rtu", "regCount": 10, "mode": 0, "safeMode": 0 }
  ],
  "count": 1
}

/get

Возвращает указанные датчики по ID/имени, совместимо с IONC /get.

GET /api/v2/MBTCPMaster1/get?filter=1003,Sensor1_AI,1005

Ответ: массив sensors[] с полями id, name, iotype, value; для несуществующих — { "name": "<requested>", "error": "not found" }.

/takeControl и /releaseControl

Управление режимом через HTTP требует двух шагов:

1. Разрешить HTTP-контроль в конфигурации

Через командную строку:

--prefix-http-control-allow 1

Или в XML-конфиге:

<MBTCPMaster1 name="MBTCPMaster1" httpControlAllow="1" ... />

2. Взять/освободить контроль через API

Взять контроль:

GET /api/v2/MBTCPMaster1/takeControl

Ответ при успехе:

{ "result": "OK", "message": "HTTP control enabled", "previousMode": 0 }

Ответ если контроль уже активен:

{ "result": "OK", "message": "HTTP control already active", "currentMode": 0 }

Ответ при запрете (httpControlAllow=0, HTTP 403):

{ "result": "ERROR", "error": "HTTP control is not allowed. Set httpControlAllow=1 in config." }

Освободить контроль:

GET /api/v2/MBTCPMaster1/releaseControl

Ответ:

{ "result": "OK", "message": "control returned to sensor", "currentMode": 0 }

Как это работает

• httpControlAllow — разрешение из конфига (по умолчанию 0)
• httpControlActive — флаг активного HTTP-контроля

Пока httpControlActive=1, режим от датчика (exchangeModeID) игнорируется — используется режим, установленный через /mode?set=....

При вызове /releaseControl восстанавливается режим от датчика.

Пример использования

# 1. Взять контроль
curl "http://localhost:8080/api/v2/MBTCPMaster1/takeControl"
 
# 2. Установить режим "только чтение"
curl "http://localhost:8080/api/v2/MBTCPMaster1/mode?set=readOnly"
 
# 3. Вернуть управление датчику
curl "http://localhost:8080/api/v2/MBTCPMaster1/releaseControl"