| Chapter 110. API Overview | ||
|---|---|---|
 | Part XXX. MODBUS |  |
Chapter 110. API Overview
Table of Contents
- 110.1. Application API
- cyg_modbus_server_start — Start MODBUS server
- cyg_modbus_server_stop — Stop MODBUS server
- 110.2. Backend API
- cyg_modbus_response — Provide MODBUS response
- cyg_modbus_raw_pdu — Access raw PDU buffer
- cyg_modbus_response_nocopy — Provide MODBUS response (no copy)
- cyg_modbus_response_exception — Provide MODBUS exception response
- cyg_modbus_get_uid — Read “Unit ID” of request
- 110.3. ModbusTCP specific API
- cyg_modbus_acm_add — Add client address to Access Control Mechanism pool
- cyg_modbus_acm_remove — Remove ACM registered client address
- 110.4. MODBUS Exceptions
- 110.5. Backend Interface
- cyg_mbop_read_discrete_inputs — Read discrete inputs
- cyg_mbop_read_coils — Read coils
- cyg_mbop_write_single_coil — Write single coil
- cyg_mbop_write_multiple_coils — Write multiple coils
- cyg_mbop_read_input_regs — Read input registers
- cyg_mbop_read_holding_regs — Read holding registers
- cyg_mbop_write_single_reg — Write single holding register
- cyg_mbop_write_multiple_regs — Write multiple holding registers
- cyg_mbop_rw_multiple_regs — Read and/or write multiple holding registers
- cyg_mbop_mask_reg — Mask holding register
- cyg_mbop_read_fifo_queue — Read FIFO contents
- cyg_mbop_read_file_record — Read file records
- cyg_mbop_write_file_record — Write file records
- cyg_mbop_read_id — Return specific extended device ID
- cyg_mbop_canopen — Perform CANOPEN operation
- 110.6. Example backend
The main MODBUS API provides a serialisation layer between the low-level MODBUS operations and user-application threads.
For MODBUS server configurations the main server control loop thread interacts with a transport layer, for example ModbusTCP, and an application specific backend layer.
The transport layer provides the physical communication support for the selected medium. For ModbusTCP this will normally be Ethernet, and for MODBUS ASCII/RTU a RS232 or RS485 connection. The transport medium layer wraps the common MODBUS PDU request and response messages for transmission.
The server control thread processes the MODBUS PDU encapsulated requests, calling the provided backend routines as appropriate.
The application supplied backend descriptor
provides the support for the specific hardware I/O present on the
device being implemented.
110.1. Application API
- cyg_modbus_server_start — Start MODBUS server
- cyg_modbus_server_stop — Stop MODBUS server
These functions are used by the user application to configure the server operation.
110.2. Backend API
- cyg_modbus_response — Provide MODBUS response
- cyg_modbus_raw_pdu — Access raw PDU buffer
- cyg_modbus_response_nocopy — Provide MODBUS response (no copy)
- cyg_modbus_response_exception — Provide MODBUS exception response
- cyg_modbus_get_uid — Read “Unit ID” of request
These functions are provided for the user application attached backend
handler routines. They are used to provide responses back to the remote
client, with the necessary control thread and transport layer
information referenced by the
opaque cyg_handle_t ctx parameter passed to
the backend handler function.
For handlers that can provide immediate responses the functions can be called directly from the handler function (in the main MODBUS control thread context). If the handler cannot provide an immediate response, then the processing should be deferred to another thread which can then subsequently use the same API to deliver a response.
![[Note]](pix/note.png) | Note |
|---|---|
For valid responses it is the responsibility of the handler function to return a correctly formatted PDU object to the client. |
110.3. ModbusTCP specific API
- cyg_modbus_acm_add — Add client address to Access Control Mechanism pool
- cyg_modbus_acm_remove — Remove ACM registered client address
These functions are used by the user application to configure features of the ModbusTCP specific transport layer.
110.4. MODBUS Exceptions
The MODBUS standard defines a fixed set of exception codes, with
implicit interpretations. These should be used in conjunction with
the cyg_modbus_exception() function by backend
handlers to notify the requesting client of an error.
- MODBUS_EXCEPTION_ILLEGAL_FUNCTION
- The function code received in the request is not an allowable action for the server. This may be because the function code is only applicable to newer devices, and was not implemented in the unit selected. It could also indicate that the server is in the wrong state to process a request of this type, for example because it is unconfigured and is being asked to return register values.
- MODBUS_EXCEPTION_ILLEGAL_ADDRESS
- The data address supplied in the request is not an allowable starting address for the server when taken into account with the number of items to be accessed. For example, for a device with 100 registers (accessed as addresses 0 thru 99) then the PDU supplied address 96 is valid when a request for 4 or fewer items is made, but invalid if 5 or more items are requested.
- MODBUS_EXCEPTION_ILLEGAL_VALUE
- A value suppled in the request is not valid for the server. This normally indicates a fault in the structure of a request PDU (e.g. unexpected length). It should be noted that it does NOT indicate that a supplied data item is outside of the set acceptable for a specific register. The MODBUS protocol does not interpret or apply any significance of any particular data values for any particular registers.
- MODBUS_EXCEPTION_DEVICE_FAIL
- Indicates an unrecoverable error occurred whilst the server was performing the requestion MODBUS function.
- MODBUS_EXCEPTION_ACKNOWLEDGE
This is a specialized response used with specific programming commands. This is where the server has accepted a request, and is processing it, but where the action will take a long time to complete. This response is returned to the client to prevent a client timeout error waiting for a standard response. It is expected that the client will periodically issue the specific “Poll Program Complete” request to check if the processing has completed.
Note The eCosPro-MODBUS server does not explcitly support this functionality, since it would be a feature of the user-application supplied backend driver.
- MODBUS_EXCEPTION_DEVICE_BUSY
- This is a specialized response used with specific programming commands. This is used to indicate to the client that the server is busy processing a long-duration command. The client should re-attempt the request in the future.
- MODBUS_EXCEPTION_MEMORY_PARITY_ERROR
-
This exception is specific to
the
MODBUS_FUNC_READ_FILE_RECORD(20) andMODBUS_FUNC_WRITE_FILE_RECORD(21) functions, when using with reference type 6. It is used to indicate that the extended file area failed to pass a consistency check. i.e. the server attempted to read the record file, but detected a parity error in the memory. The client may retry the request, but maintenance of the server device may be required. - MODBUS_EXCEPTION_GW_PATH_UNAVAILABLE
- This is a specialized exception returned in conjunction with gateway support. It indicates that the gateway was unable to allocate an internal communication path to the requested UID. This exception usually indicates the gateway device is misconfigured or overloaded.
- MODBUS_EXCEPTION_GW_TARGET_FAILED
- This is a specialized exception returned in conjuction with gateway support. It indicates that no response was obtained from the target device. This usually indicates that the target device is not present on the MODBUS network.
110.5. Backend Interface
- cyg_mbop_read_discrete_inputs — Read discrete inputs
- cyg_mbop_read_coils — Read coils
- cyg_mbop_write_single_coil — Write single coil
- cyg_mbop_write_multiple_coils — Write multiple coils
- cyg_mbop_read_input_regs — Read input registers
- cyg_mbop_read_holding_regs — Read holding registers
- cyg_mbop_write_single_reg — Write single holding register
- cyg_mbop_write_multiple_regs — Write multiple holding registers
- cyg_mbop_rw_multiple_regs — Read and/or write multiple holding registers
- cyg_mbop_mask_reg — Mask holding register
- cyg_mbop_read_fifo_queue — Read FIFO contents
- cyg_mbop_read_file_record — Read file records
- cyg_mbop_write_file_record — Write file records
- cyg_mbop_read_id — Return specific extended device ID
- cyg_mbop_canopen — Perform CANOPEN operation
The cyg_modbus_backend_t structure defines the set
of handler functions used to implement the support for the relevant
MODBUS operation. A simple NUL terminated
ASCII name can be provided as a human-readable
description of the backend. The application attaches the backend
descriptor structure via
the cyg_modbus_server_start() function.
| Note |
|---|---|
To avoid blocking the main MODBUS server processing loop the attached
handler functions should NEVER block. The
handlers should be written to return control as quickly as
possible. If a hardware operation required by the specific MODBUS
function then the handler should schedule suitable code, which will
asynchronously respond to the request when the required data is
available or action has been performed. The
provided |
If a particular MODBUS function is not supported (or required) by the
backend implementation then a NULL pointer can be
used, with the server support returning
a CYG_MB_EXCEPTION_ILLEGAL_FUNCTION equivalent
error to the calling client.
The backend structure is defined in
the <cyg/modbus.h> header, which also
provides the function prototypes for the individual handlers as
detailed over the following pages. The cyg_mbop_
prefix is used for the prototypes to indicate a MODBUS Backend
OPeration.
Each handler is passed the
parameters ctx
and private. The ctx value is an
opaque context descriptor for the main server loop, and is used to
identify individual transactions via the
API. The private parameter is
the private context value specified when the
backend is registered, and can be the hook for the user application
hardware support.
The backend descriptor also provides the BASIC (mandatory) and REGULAR (optional) NUL terminated ASCII identification strings accessed via the MEI Type 14 function code.
The timeout descriptor field is used to force a
timely “exception” response back to a client when the
backend does not provide a response within the configured number of
seconds. This MODBUS control generated timeout exception replaces any
subsequent response made by the user-application for the
relevant ctx handle.
Other than the device idread function the handlers
do not return any error state. The handlers are passed validated
requests, and are expected to return a valid response or exception via
the provided MODBUS API.
110.6. Example backend
The packages/services/modbus/current/tests/backend_dummy.c
source file provides an example of the backend support required for a
MODBUS server implementation. It can form the starting point for a
customer hardware solution.
The source as provided implements a very basic system to allow verification of the MODBUS server support. The backend does not provide real hardware I/O interaction, but “simulates” responses.
| |  | |
| Chapter 109. Configuration |  | cyg_modbus_server_start |
| 2024-03-18 | eCosPro Non-Commercial Public License |