Chapter 109. Configuration

This chapter shows how to incorporate the MODBUS support into an eCos configuration, and how to configure it once included.

109.1. Configuration Overview

The MODBUS support is contained in a single eCos package CYGPKG_MODBUS. However, it depends on the services of a collection of other packages for complete functionality. For example, the ModbusTCP server implementation is tightly bound with the eCos networking stack support.

109.1.1. Quick Start

Incorporating the MODBUS support into your application is straightforward. The essential starting point is to incorporate the MODBUS eCos package (CYGPKG_MODBUS) into your configuration.

This may be achieved directly using ecosconfig add on the command line, or the Build->Packages… menu item within the eCos Configuration Tool.

Depending on the MODBUS package configuration other packages may be required (e.g. network stack support). The package requires that the CYGPKG_KERNEL, CYGPKG_ERROR and CYGPKG_MEMALLOC packages are included in the eCos application configuration.

109.1.2. Configuring the MODBUS server

The common MODBUS server support is enabled by the CYGFUN_MODBUS_SERVER option. When enabled it provides access to the following relevant options.

CYGNUM_MODBUS_SERVER_MAXSERVER
This option defines the maximum number of client connections supported by the server. This is the number of individual, active, concurrent, socket connections allowed.
CYGNUM_MODBUS_SERVER_TRANSACTIONS
This option specifies the maximum number of active, simultaneous, MODBUS transactions per client connection.
CYGNUM_MODBUS_SERVER_TRANSPORTS
This option defines the maximum number of active transports the MODBUS server will support. If the end application configuration provides more than this number then not all transports may be instantiated. For most applications only a single transport will ever be provided and needed. For example, ModbusTCP for Ethernet based systems.
CYGNUM_MODBUS_SERVER_MESSAGES_API
Depending on the other configuration options the package will define a base number of message descriptors needed in CYGNUM_MODBUS_SERVER_MESSAGES. This option extends the size of the message pool over and above the explicit active MODBUS transaction message requirement. This can be tuned to reflect the requirements of the user application implementing the backend.
CYGNUM_MODBUS_SERVER_THREAD_STACK_SIZE
This option is used to increase the size of the main MODBUS control thread. This value is added to the platform defined CYGNUM_HAL_STACK_SIZE_TYPICAL.
CYGNUM_MODBUS_SERVER_THREAD_PRIORITY
This option defines the scheduler priority of the main MODBUS control thread.

109.1.3. Configuring the ModbusTCP Server

The CYGPKG_MODBUS_TRANSPORT_TCP provides the transport implementation for ModbusTCP. When enabled the configuration must include a suitable network stack (BSD or lwIP).

CYGNUM_MODBUS_SERVER_PORT
This option defines the port that the ModbusTCP server will listen to for client requests. The default of 502 is the standard ModbusTCP port, and normally would not need to be re-configured.
CYGIMP_MODBUS_TRANSPORT_TCP_ACM

Enabling this option allows a set of client network addresses to be configured at run-time via the ACM API. When addresses have been configured only connections from those registered hosts will be accepted.

  • The Disabled mode configures the ModbusTCP transport to ignore ACM API operations, and to accept connections from any host.
  • The Insecure mode will accept any connection UNTIL at least one explicit address has been registered via the ACM API, and then host addresses will be checked for acceptance.
  • The Secure mode will NOT accept any connections unless the address has been explicitly registered via the ACM API.

The setting of this option will depend on how the server device will be deployed and accessed in the field. For testing it may be acceptable to have any client host interact with the device, in which case Disabled or Insecure should be selected. Selecting Insecure allows for start-of-day acceptance of any client host address, but for some application control, configuration, to subsequently limit the acceptable addresses. The Secure mode ensures that only application configured client host addresses are ever supported, which requires suitable run-time application configuration to setup the required ACM pools to allow access.

[Warning]Warning

Using Secure mode means that if the application does NOT call the cyg_modbus_acm_add() to register an address then NO connections can be established to the MODBUS server.

CYGNUM_MODBUS_TRANSPORT_TCP_IDLE_TIMEOUT

This option specifies the number of seconds before idle connections to the ModbusTCP server are closed. The default setting of 0 disables the feature. Normally connections from clients are held open until the client explicitly closes them. This option allows for an “idle” timeout to be specified that will close the connection at the server end if no MODBUS requests are received from a client connection within this configured timeout.

[Note]Note

If ACM support is configured then only non-priority connections will be closed by the ModbusTCP server.

CYGNUM_MODBUS_TRANSPORT_TCP_THREAD_STACK_SIZE

This option is used to increase the size of the ModbusTCP internal thread. This value is added to the platform defined CYGNUM_HAL_STACK_SIZE_TYPICAL.

CYGNUM_MODBUS_TRANSPORT_TCP_THREAD_PRIORITY
This option defines the scheduler priority of the ModbusTCP internal thread.