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]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]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) and MODBUS_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]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 tests/modbus_ut.c example application provides one possible implementation of such “deferred” support.

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.