Skip to content
Start free evaluation

pdcomm_modbus_call

Function

Runs one JSON command on an endpoint and returns the JSON reply.

int32_t pdcomm_modbus_call(pdcomm_modbus_handle endpoint, const uint8_t *input, size_t size, pdcomm_modbus_handle *out)

Declared in: #include <pdcomm/modbus/pdcomm_modbus.h>

The input is one UTF-8 JSON object whose action member selects the command. The reply is {"ok":true,"result":...} with #PDCOMM_MODBUS_OK, or {"error":"...","ok":false} with #PDCOMM_MODBUS_SERVICE_ERROR.

Commands:

  • capabilities, state: build features; configuration and connection.
  • configure with config: replaces the configuration while disconnected. Members: transport ("tcp", "rtu", "ascii"), role ("client", "server", "gateway"), address (TCP socket address IP:port, such as 127.0.0.1:502 or [::1]:502; host names are not resolved), port (serial device), unit (1 to 247), baud, parity ("even", "odd", "none"), stop_bits (1 or 2; "none" parity needs 2), timeout_ms (1 to 60000), optional ascii_timeout_ms, turnaround_ms, routes (gateway unit map) and security. security enables Modbus/TCP Security: chain, private_key and trust are PEM file paths, mode is "encrypted" (default) or "authentication_only", roles maps a role name from the peer certificate to its allowed function codes, null_role lists the codes allowed without a role, and crls, require_revocation and hostname control certificate validation.
  • connect, disconnect: open or close the socket, listener or serial port. A server bound to port 0 reports its actual address in config.address. A TCP client closes its connection after a request timeout, a peer close or an I/O error; it then reports "connected":false and its requests fail with Closed until it connects again.
  • poll: serves pending requests of a server or gateway once and returns {"handled":N}. Call it regularly; nothing runs in the background.
  • request with pdu and optional unit: a client sends one request and waits for the response on the wire.
  • execute with pdu and optional unit: processes the request against the endpoint's own data model without any I/O.
  • data_get, data_set (table, address, values), model_set: read or change the data model. Tables are coils, discrete_inputs, holding_registers and input_registers.
  • diagnostics, diagnostics_set (register, busy): the Diagnostics (function code 08) register, listen-only state and counters. trace, trace_clear: the last 1000 traced requests and wire frames.
  • project_export, project_import (project): configuration and data model as one pdcomm.modbus.project version 1 document.
  • fault (bytes, optional transport, gap_us): decodes synthetic wire bytes with the TCP, RTU or ASCII frame decoder, without I/O. serial_ports lists the serial devices of the host.
  • logging_configure (config), logging_status, logging_flush: the same control as the pdcomm_modbus_logging_* functions.
  • license_install with text: installs PDComm license text for this library (all endpoints), replacing text installed earlier; an empty string removes it. The result is {"installed":N}, the number of license blocks whose signature verified. Text without such a block fails with "code":"license_invalid" and keeps the earlier text.
  • license_status: the license status object (schema_version 1) with build_date, host_id, program, the found sources, every license block in licenses with its verification, and modules, which maps each module id to its state (licensed, evaluation, missing, expired, not-yet-valid, updates-expired, program-mismatch or host-mismatch), granted and days_left.
  • host_id: {"host_id":"PDH1-XXXX-XXXX-XXXX-XXXX"}, the id that host-bound licenses name; fails with "code":"host_id_unavailable" when the machine id cannot be read.

Error replies of the license checks carry a code member in addition to error: a refused connect returns {"code":"license_required","error":"PDComm license required for module 'modbus' (missing): ...","license":{"license_id":null,"module":"modbus", "state":"missing"},"ok":false}.

A pdu is the Modbus Application Protocol PDU (function code followed by data, no unit identifier, MBAP header, CRC or LRC) as a byte array or a hex string. The request and execute result is {"response":[...]|null,"status":"success"|"exception"|"no_response","source":"wire"|"local"}; an exception response has the function code with bit 0x80 set followed by the exception code.

pdcomm_modbus_handle endpoint = 0, buffer = 0;
size_t size = 0;
assert(pdcomm_modbus_endpoint_create(&endpoint) == 0);
const char *request = "{\"action\":\"execute\",\"pdu\":[6,0,0,0,9]}";
assert(pdcomm_modbus_call(endpoint, (const uint8_t *)request, strlen(request),
                          &buffer) == 0);
assert(pdcomm_modbus_buffer_copy(buffer, NULL, 0, &size) ==
       PDCOMM_MODBUS_BUFFER_TOO_SMALL);
char *text = (char *)malloc(size + 1);
assert(text);
assert(pdcomm_modbus_buffer_copy(buffer, (uint8_t *)text, size, &size) == 0);
text[size] = 0;
assert(strstr(text, "\"response\":[6,0,0,0,9]"));
free(text);
assert(pdcomm_modbus_release(buffer) == 0);
assert(pdcomm_modbus_release(endpoint) == 0);

Parameters

NameDescription
endpointEndpoint handle.
inputUTF-8 JSON command, copied during the call.
sizeSize of input in bytes, 1 to 16 MiB.
outReceives the owned reply buffer. Zero is written once the pointer and size checks pass.

Returns

#PDCOMM_MODBUS_OK with a result buffer, #PDCOMM_MODBUS_SERVICE_ERROR with an error buffer, #PDCOMM_MODBUS_INVALID_INPUT for a null pointer, a zero or oversized size or invalid JSON (no buffer), #PDCOMM_MODBUS_INVALID_HANDLE, or #PDCOMM_MODBUS_INTERNAL_ERROR (no buffer).

Notes

  • Blocks while another thread runs a command on the same endpoint, and a client request blocks until the response or timeout_ms. Release the returned buffer with pdcomm_modbus_release().

Privacy Policy