set ia

Purpose

Configures selected Digi devices to support special parsing and bridging of Industrial Automation (IA) protocols. For example, it enables the Digi device to function as a Modbus/TCP to serial Modbus Bridge. Command options allow for configuring:

Supported IA protocols include Modbus/RTU and Modbus/ASCII on the serial port or encapsulated within TCP/IP or UDP/IP, and Modbus/TCP transported by either TCP/IP or UDP/IP.

To displaying current IA settings, use the show command, as demonstrated in the Syntax section of this description.

For more information on Industrial Automation, see the Industrial Automation and Modbus knowledge base articles and technical notes on the Digi Support site: www.digi.com/support

Required permissions

For Digi products with two or more users, permissions must be set to set permissions s-ia=read to display the current IA settings, and set permissions s-ia=rw to display and configure IA settings. See set permissions for details on setting user permissions for commands.

Syntax

There are several variants of syntax for the set ia command, depending on whether the command is being used to configure serial port-connected devices, network-based masters, or destination tables and route entries within destination tables. These syntax descriptions and their option descriptions are presented separately.

Configure serial-port connected devices—”set ia serial”

set ia serial=range [serial options] [modbus options]
[serial options]:
  type={master|slave}
  table=1..16
  protocol={modbusrtu|modbusascii}
  messagetimeout=100-99999 ms
  slavetimeout=10-99999 ms
  chartimeout=3-99999 ms
  idletimeout={0=disabled|1-99999 seconds}
  priority={high|medium|low}
[modbus options]:
  errorresponse={on|off}
  broadcast={on|off|replace}
  fixedaddress={auto|1-255}
  rbx={off|half}

To set the baud rates for the port, see set serial.

To enable IA protocols, set the serial port profile to ia. See set profile.

Configure network-based masters—”set ia master”

set ia master=range
 state={on|off}
  active={on|off}
  type={tcp|udp}
  ipport=ip port
 table=1..8
  protocol={modbusrtu|modbusascii|modbustcp}
  messagetimeout=100-99999 ms
  chartimeout=3-99999 ms
  idletimeout={0=disabled|1-99999 seconds}
  priority={high|medium|low}

Configure destination tables and route entries—”set ia table”

set ia table=range [table options] 
  [route=range [route options]] 
[table options]:
  state={on|off}
  name=string
 addroute=route index
 removeroute=route index
 moveroute=from_route_index,to_route_index
[route options]:
  active={on|off}
  connect={active|passive}
  protaddr=protocol address range
 type={discard|ip|mapto|nopath|serial|zigbee}
  protocol={modbusrtu|modbusascii|modbustcp}
  port=serial port
 transport={tcp|udp}
  address={ip address|dns name|XBee or ZigBee MAC address}
  ipport=ip port
 replaceip={on|add|sub|off}
  mapto=protocol address
 slavetimeout=10-99999 ms
  chartimeout=3-99999 ms
  idletimeout={0=disabled, 1-99999 seconds}
  reconnecttimeout=0-99999 ms

Display current IA settings

To display current IA settings, use the show command instead of a set ia command with no options:

show ia all

Options

Options for serial-port connected devices—”set ia serial”

serial=range

Specifies that the serial settings apply to the specified serial port or range of serial ports. The default is port 1, and on a single-port device, entering serial is the same as serial=1.

[serial options]

The serial settings, which include:

state={on|off}

Enables the IA serial settings. Setting to off risks the configuration being deleted.

active={on|off}

To temporarily stop processing the serial port, set active to off. The configuration will remain valid and saved.

type={master|slave}

Defines whether the serial device attached is acting as a master or a slave.

table=1..16—applies to master only

Defines which table is used to route messages to their destination. This option applies only to master-attached devices.

protocol={modbusrtu|modbusascii}

The protocol being used by the serial device. The serial protocol also affects the implied incoming network master on TCP and UDP ports 2101.

modbusrtu

Modbus/RTU – 8-bit binary per Modbus specification at www.modbus-ida.org.

modbusasscii

Modbus/ASCII – 7-bit ASCII per Modbus specification at www.modbus-ida.org.

modbustcp

Modbus/TCP: or “Open Modbus” per Modbus specification at www.modbus-ida.org. Can be enabled with UDP/IP as well as TCP/IP.

messagetimeout=100-99999 ms—applies to master only

When messages are received from remote clients, this option defines the time to allow the message to be answered. This includes both the queuing and slave response delays, and this should be set to slightly less than the timeout of the remote client. After this time, the Digi device assumes the remote client no longer wants a response. The range is 100 to 99999 milliseconds. The default is 2500 milliseconds.

slavetimeout=10-99999 ms—applies to slave only

After all bytes of the message have been sent to the slave device, this is the time to wait for the first byte of a response. Note that the serial shift times are not included within this timeout. The range is 10 to 99999 milliseconds. The default is 1000 milliseconds.

chartimeout=3-99999 ms—applies to master or slave

After a first byte is received, this is the time to wait for additional bytes to either consider the message complete or to be aborted. The default is protocol-specific, but usually 50 milliseconds.

idletimeout={0=disabled|1-99000 seconds}

The device aborts a connection on the implied incoming master sockets after the remote client has been idle for this time. The time is saved in seconds, and the best use for this timeout is to speed up fault recovery. For example, many wide-area networks can suffer shutdowns without the Digi device detecting it. Using the idle timeout speeds up detection of lost TCP connections. The range is 1 to 99999 seconds. The default is 5 minutes.

priority={high|medium|low}

Normally messages are processed in a fair round-robin scheme. This becomes unfair when one master acts as many – for example opening 16 TCP sockets to talk to 16 slaves contrasted to a second master using a single TCP socket to talk to 16 slaves. In this situation, the device assumes it has 17 masters and in effect the first master will have 16 requests answered for every one the second master succeeds in getting answered. This option can be used to adjust the handling of serial master requests. For example, set the serial master to high and the network masters to medium. This option’s effectiveness depends on the protocol behavior. Therefore, while some Modbus systems find it useful, it has no effect on most Rockwell protocols.

high

A high-priority master can get up to 50 percent of the bandwidth – of course you cannot have too many high-priority masters. All high-priority masters with queued messages get one message serviced before any low or medium priority masters get any service.

medium

If a high-priority master has queued messages, then one medium-priority master gets one message serviced before all the high-priority masters are offered service again. If only medium-priority masters exist (which is the default setting), all masters are serviced in a round-robin manner.

low

Low-priority masters only get service when no high- or medium-priority master has messages to service.

The default is medium.

[modbus options]

The configuration options specific to the Modbus protocol, which include:

errorresponse={on|off}

Controls behavior for common run-time errors such as no response from the slave device. By default, errorresponse=off for serial Modbus protocols, since most masters assume no response when errors occur. Having this option off also actively filters out returning Modbus exception codes 0x0A and 0x0B from remote Modbus/TCP slaves.

broadcast={on|off|replace}

Specifies how to handle incoming requests with a slave address set to the broadcast value. For Modbus, this is 0. The default is to replace 0 with 1. This default was established to overcome the fact that many Modbus/TCP clients always send requests to unit ID zero (0) and do not want this request treated as a broadcast.

on

Tells the Digi device to send requests as broadcast to the destination device(s) and not expect any response message.

off

Tells the Digi device to throw away the broadcast request.

replace

Changes a broadcast request to a normal request by replacing the unit ID 0 with a value of 1.

fixedaddress={auto|1-255}

Used to override the Modbus protocol address (unit ID) with a fixed address.

auto

When set to auto, the protocol address will not be overwritten.

1-255

Setting it to a fixed number from 1-255 forces this value to be used for all Modbus requests.

The default is auto.

rbx={off|half}

Enables the serial slave driver to handle Report-By-Exception (XMIT) writes between polls.

The Modbus/RTU serial slave driver has a Report-By-Exception (or XMIT) handler. If this handler is enabled, the Digi device pauses between slave polls to receive potential “master requests” initiated by the slave. Just as with a serial master-attached configuration, the Modbus/RTU slave address is used with the IA route table to determine the remote destination.

Behavior is assumed to be half-duplex, and the exact behavior of the slave device after a collision where both units try to send a request at the same time is unpredictable. The Digi device normally ignores the XMIT request and treats its own request as a timeout.

The fixedaddress option must be set to a specific value, not auto or 0. All other values are assumed to be XMIT transactions. This enables any Modbus message seen from the slave and not equaling the fixedaddress to be treated as unsolicited master request. The message will be routed by the table to other destinations. For example, if fixedaddress=1, it is assumed that any network request for slave 1 goes to the serial device, and any message from the serial device marked as from slave 1 is assumed a response to a network request. However, any messages from a slave marked as from slave 2-255 are assumed as master requests instead, and handled through the normal routine table.

Options for network-based masters—”set ia master”

master=range

Specifies the index of the network master to which the master options apply.

state={on|off}

Enables the IA network master settings.

active={on|off}

Enables or disables the network listener that accepts network connections.

type={tcp|udp}

Defines whether the incoming connection is TCP (connected) or UDP (unconnected). The default is tcp.

For cellular connections, using UDP/IP can cut 40% to 60% from your monthly bill.

ipport=ip port

Defines the UDP or TCP port on which to listen for protocol messages. Modbus/TCP defaults to TCP port 502.

table=1..8

Defines which table is used to route messages to their destination. This option applies only to master-attached devices.

protocol={modbusrtu|modbusascii|modbustcp}

The protocol used for the connection.

modbusrtu

Modbus/RTU – 8-bit binary per Modbus specification at
www.modbus-ida.org.

modbusascii

Modbus/ASCII – 7-bit ASCII per Modbus specification at
www.modbus-ida.org.

modbustcp

Modbus/TCP: or “Open Modbus” per Modbus specification at www.modbus-ida.org. Can be enabled with UDP/IP as well as TCP/IP.

messagetimeout=100-99000 ms

When messages are received from remote clients, this is the time to allow the message to wait to be answered. This includes both the queuing and slave response delays, and this should be set to slightly less than the timeout of the remote client. After this time, the Digi device assumes the remote client no longer wants a response. The range is 100 to 99000 milliseconds. The default is 2500 milliseconds.

chartimeout=3-99000 ms

After a first byte is received, this is the time to wait for additional bytes to either consider the message complete or to be aborted. The default is protocol-specific, but usually 50 milliseconds.

idletimeout={0=disabled|1-99000 seconds}

The device aborts a connection after the remote client has been idle for this time. The time is saved in seconds, and the best use for this timeout is to speed up fault recovery. For example, many wide-area networks can suffer shutdowns without the Digi device detecting it. Using the idle timeout will speed up detection of lost TCP connections. The range is 1 to 99999 seconds. The default is 5 minutes.

priority={high|medium|low}

Normally messages are processed in a fair round-robin scheme. This becomes unfair when one master acts as many – for example opening 16 TCP sockets to talk to 16 slaves contrasted to a second master using a single TCP socket to talk to 16 slaves. In this situation, the device assumes it has 17 masters and in effect the first master will have 16 requests answered for every one the second master succeeds in getting answered. This option can be used to adjust the handling of serial master requests. For example, set the serial master to high and the network masters to medium. The effectiveness of this option depends on the protocol behavior. Therefore, while some Modbus systems will find it useful, it has no effect on most Rockwell protocols.

high

A high-priority master can get up to 50 percent of the bandwidth – of course you cannot have too many high-priority masters. All high-priority masters with queued messages get one message serviced before any low or medium priority masters get any service.

medium

If a high-priority master has queued messages, then one medium-priority master gets one message serviced before all the high-priority masters are offered service again. If only medium-priority masters exist (which is the default setting), then all masters are serviced in a round-robin manner.

low

Low-priority masters only get service when no high- or medium-priority master has messages to service.

The default is medium.

Options for destination tables and route entries—”set ia table”

The destination table and routes are used by the incoming master connections to select which one of many potential slaves a request is to be answered by.

table=range

Selects one of eight possible tables in which to look up forwarding information.

[table options]

The configuration options specific to the destination table, which include:

state={on|off}

Enables the IA destination table settings.

name=string

A useful name for the destination table. Default names are table1, table2, and so on. This option gives you the option to rename the table for convenience. Tables are still handled internally by number.

addroute=route index

Inserts a new route at this index of the table. If an existing route occupies this index, it is pushed up to a higher index.

removeroute=route index

Destroys the route at this index in the table.

moveroute=from_route_index,to_route_index

Moves the destination route from one route index to another.

route=range

Specifies the index of the route in this table to which the settings apply.

[route options]

The configuration options specific to the route table entries in the destination table, which include:

active={on|off}

Enables or disables the route in the table.

connect={active|passive}

Defines whether the Digi device attempts immediately to connect to a remote device (active), or waits and only connects on demand (passive). The default is passive.

protaddr=protocol address range

Defines the range of protocol addresses to be forwarded to this destination entry in the table. You can specify a single address or an inclusive range. The permitted values are defined by the protocol. The table is scanned from the first route index to the last, stopping at the first route with the appropriate protocol address. Duplicates or overlapping ranges can exist, but the route with the lowest index will be used.

type={discard|ip|mapto|nopath|serial|zigbee}

Defines the type of destination for this route.

discard

Messages destined for this route entry are discarded without error.

ip

Messages destined for this route entry are forwarded to the entered IP address. If you enter the IP address as 0.0.0.0, the Digi device’s IP address is used to fill in the IP address, and the replaceip function is applied. For example, if the IP address is 0.0.0.0, the Digi device’s IP address is 143.191.23.199, and the protocol address of the message is 45, then the remote IP address used will be 143.191.23.45.

mapto

Messages destined for this route entry are reevaluated as if having the protocol address configured within this entry.

nopath

Messages destined for this route entry are returned to sender with a protocol-defined error message.

serial

Messages destined for this route entry are forwarded to a serial port.

zigbee

Messages destined for this route entry are encapsulated on a Digi XBee wireless network, with the targeted node defined by the IEEE MAC address of the XBee module encoded in the address setting. This option is supported on XBee-enabled products only.

protocol={modbusrtu|modbusascii|modbustcp}

The protocol used for the connection. See www.modbus-ida.org for information on specifications.
modbusrtu

Modbus/RTU – 8-bit binary per Modbus specification.

modbusascii

Modbus/ASCII – 7-bit ASCII per Modbus specification.

modbustcp

Modbus/TCP – or “Open Modbus” per Modbus specification.

Can be enabled with UDP/IP as well as TCP/IP.

port=serial port

Defines the serial port for the route table entry. This option applies only if the route type=serial.

transport={tcp|udp}

Applies only if the route type=ip. Defines whether the outgoing connection is TCP (connected) or UDP (unconnected). The default is tcp.

address={ip address|dns name|XBee or ZigBee MAC address}

Applies only if the route type=ip. The destination IP address of the entry.

ipport=ip port

Applies only if the route type=ip. The UDP or TCP port on which to listen for protocol messages. Modbus/ TCP defaults to TCP port 502.

replaceip={on|add|sub|off}

Applies only if the route type=ip.Specifies whether and how the last octet of the IP address is replaced.

on

The protocol address is used to replace the last octet of the IP address. For example, if the table IP is 192.168.1.75 and the protocol address of this message is 23, the message will be forwarded to the remote IP 192.168.1.23.

add
sub

If the add or sub value is set, the protocol address is added or subtracted from the final octet of the IP address. In the above example, the result would be 192.168.1.98 or 192.168.1.52, respectively.

off

The last octet of the IP address is not replaced.

The default is off.

mapto=protocol address

Used for destination entries of type mapto. This option defines the protocol address for which to reevaluate this message.

slavetimeout=10-99999 ms

After all bytes of the message have been sent to the slave device, this is the time to wait for the first byte of a response. The range is 10 to 99999 milliseconds. The default is 1000 milliseconds.

chartimeout=3-99999 ms

After a first byte is received, this is the time to wait for additional bytes to either consider the message complete or to be aborted. The default is protocol-specific, but usually 50 milliseconds. In TCP/IP network context, this can be thought of as the re-fragment time between packets.

idletimeout={0=disabled, 1-99999 seconds}

The connection is closed after no new messages have been forwarded to the remote slave (server) for this idle time. The time is saved in seconds. The range is 0 to 99999 seconds, where 0 means never close this connection. The default is 5 minutes.

reconnecttimeout=0-99999 ms

If the connection to the remote node fails and connect=active, this time is used to delay attempts to reconnect. The default is 2500 milliseconds.

Examples

Serial port configuration settings

The following set ia commands show the default serial-port configuration settings for the Digi Connect WAN IA:

set ia serial=1 active=on type=slave protocol=modbusrtu table=1 
set ia serial=1 messagetimeout=2500 slavetimeout=1000 chartimeout=20 
set ia serial=1 priority=medium idletimeout=0 
set ia serial=1 errorresponse=off broadcast=replace fixedaddress=0
set ia table=1 route=1 active=on type=serial protaddr=0-32 port=1

Note that future Digi Connect WAN IA firmware releases will expose these configuration settings in the web interface.

Enable a Modbus/RTU serial master

To enable a Modbus/RTU serial master instead, change the configuration settings by entering the following set ia commands via Telnet. These set ia commands change the serial device type from slave to master. In addition, to handle cellular latency, a timeout value of 31 seconds or longer is needed. In addition, the first route, which forwards requests to the serial port, can be turned off.

set ia serial=1 type=master messagetimeout=31000
set ia table=1 route=1 active=off

Additional examples

For more examples of the set ia command, see the application note Remote Cellular TCP/IP Access to Modbus Ethernet and Serial Devices available at www.digi.com/support.

See also