A-B RIO Master for SoftPLC® Runtime

1. Warranty

1.1. Terms of Use

Because of the variety of uses of the information described in this manual, the users of, and those responsible for applying this information must satisfy themselves as to the acceptability of each application and use of the information. In no event will SoftPLC Corporation be responsible or liable for its use, nor for any infringements of patents or other rights of third parties which may result from its use.

SOFTPLC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE CONTENTS HEREOF AND SPECIFICALLY DISCLAIMS ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE.

SoftPLC Corporation reserves the right to change product specifications at any time without notice. No part of this document may be reproduced by any means, nor translated, nor transmitted to any magnetic medium without the written consent of SoftPLC Corporation.

SoftPLC and TOPDOC are registered trademarks of SoftPLC Corporation.

First Printing	September 2024
Latest Printing	September 2024

SoftPLC Corporation
25603 Red Brangus Drive
Spicewood, Texas 78669

USA Telephone: 1-800-SoftPLC
WW Telephone: 512/264-8390
Fax: 512/264-8399
URL: https://softplc.com
Email: support@softplc.com

2. Overview

2.1. Introduction

This document describes the installation, usage, and functionality of the SoftPLC A-B Remote I/O Master (RIOMASTER) software. (Historically the A-B RIO network has sometimes been called the blue hose.) This software is a TOPDOC Loadable Module (TLM) that extends a SoftPLC runtime engine, enabling it to be a master/scanner on one or more RIO networks. This RIOMASTER TLM implements the master or scanner role within the Allen-Bradley Remote I/O protocol.

This TLM’s functionality is only available on SoftPLC’s equipped with the optional SoftPLC A-B RIO Interface hardware (Cat.No. SPO-BH). The SPO-BH is a factory installed option. One SPO-BH is required for each separate RIO network.

2.2. Concepts

The SoftPLC runtime engine software supports TLM’s, which are shared library extensions to SoftPLC. A TLM may be loaded either as a DRIVER or as a MODULE. The difference between a DRIVER and a MODULE is that a DRIVER is called once per SoftPLC scan, and optionally an additional number of times per scan. A MODULE is only called when the control program decides to call it and not as an inherent part of the scan. TLM’s are made known to SoftPLC in the MODULES.LST file which may be edited by TOPDOC NexGen by traversing to: PLC → Modules.

This RIOMASTER TLM is a DRIVER and has a number of TOPDOC Loadable Instructions contained within it. These are Ladder Logic instructions that can be used to control or query the operation of the TLM.

2.3. Features

Supports racks numbered from 0 to 76 (octal).
Can scan up to 3 RIO networks concurrently.
Supports a software selectable (internal) 120 ohm termination resistor.
Supports baud rates of 57600 (56.7Kbaud), 115200 (115.2Kbaud), and 230400 (230.4Kbaud).
Block transfer (read/write) is fully supported.

2.4. Requirements

2.4.1. Hardware

Smart (SMx4-) or NeoPAC (SNx2-) SoftPLC/Gateway
SoftPLC A-B RIO Interface hardware: SPO-BH (one per network).
Belden #9463 Blue Hose connection cable(s) [customer supplied].

2.4.2. Hardware Installation

The internal SoftPLC A-B RIO Interface hardware is factory installed into the Smart or NeoPAC SoftPLC/Gateway. The interface must be included when ordering the SoftPLC/Gateway.

Smart (version 4)
- SPO-BH: available for ports 0, 1, and/or 2
NeoPAC
- SPO-BH: available for ports 1 and/or 2

2.4.3. Software

SoftPLC version 5.1.1 runtime, or later
TOPDOC NexGen 5.1, or later

2.4.4. Software Installation

The TLM is named riomaster.tlm.so, and the configuration file is RIOMASTER.LST. The configuration file is located on the SoftPLC at /SoftPLC/tlm/RIOMASTER.LST. If your SoftPLC hardware was produced after the release of this driver, the aforementioned files are pre-installed on the SoftPLC for you. If your SoftPLC hardware does not include these files, and you are interested in using this driver; please contact SoftPLC Support.

With TOPDOC NexGen’s PLC | MODULE editor, we can instruct SoftPLC to engage the RIOMASTER TLM by checking its 'Use' box; as shown above. Then, execute a 'Local Save' followed by a 'Remote Send'. At this point, the SoftPLC is ready to run the RIOMASTER TLM upon the next restart.

Load button will load the configuration file from the PC’s disk.
Save button will save the configuration file to the PC’s disk.
Fetch button will fetch the configuration file from the SoftPLC’s disk.
Send button will send the configuration file to the SoftPLC’s disk.

3. Configuration

3.1. Configuration Editor Usage

To configure the driver, connect to your SoftPLC. Load the PLC | MODULE editor. Highlight the RIOMASTER.TLM by clicking on this entry; then, click on the Configure button. From the new RIOMASTER.LST configuration window, click 'Fetch' to edit the RIOMASTER.LST file.

After editing the configuration file, execute a 'Save' to record the changes to your development/local PC. Then, execute a 'Send' to record the changes to your SoftPLC/remote device.

The next step is to restart (or cycle power on) the SoftPLC for the changes to take effect. To restart, navigate to the 'Startup' tab and click 'Restart SoftPLC Runtime Now'.

If your TOPDOC NexGen does not include the 'Restart SoftPLC…' button; your TOPDOC installation must be updated. Contact SoftPLC Support for update information.

As an alternative to both restarting and power cycling, you may enter 'Remote Program' mode using 'Edit Remotely', and then select 'Remote Program' a second time. This pseudo transition from Remote Program to Remote Program is a signal to the TLM that it should reload its configuration file.

3.2. RIOMASTER.LST Configuration File Sample

Sample RIOMASTER.LST

# RIO Driver Configuration for SoftPLC Runtime Software.
# This file uses an "s-expression" format, which is like XML but uses
# parentheses instead of angle bracketed keywords.  The syntax of s-expression
# files is well documented and can be googled.  The grammar, on the other hand,
# unlike the syntax, is application specific.  SoftPLC uses '#' to indicate
# a single line comment. If the first non-blank character is #, then this
# line is a single line comment.  Single line comments cannot follow
# any other token on the same line.  Multiline 'C' style comments are also
# supported: /* followed by an eventual */
#
# S-expressions are thought to be more human readable than XML
# and are easy to parse with a programming language.  Parentheses are balanced.
#
# The supported "grammar" is documented in the next several lines of comments.
#
# Grammar rules are declared like this, for example:
# (timeout_mult <4 | 8 | 16 | 32 | 64 | 128 | 256 | 512 > )
# This means "timeout_mul" is a keyword and it can be followed with
#   4, 8, 16, 32, 64, 128, 256, or 512.  The '|' means "or". e.g. (timeout_mult 4)
#
# If something is wrapped in angle brackets <> in a grammar rule, this means
# it is a grouping.  Only one of the choices in a grouping may actually be used.
# Angle brackets, being only part of the grammar definition, are never actually
# used in real configuration statements.
#
# If something is wrapped in square brackets [] in a grammar rule, this means
# whatever appears in the brackets is optional.  If omitted, then a default value
# will be used and the default is defined in the grammar rule by a comment following
# a ':'.  The square brackets, being only part of the grammar definition,
# are never actually used in real configuration statements.
#
# White spaces includeing tabs and newlines (CR, LF, etc.) are all ignored.

#------ Grammar Rules: ----------
# (rio                                  ` master element for the driver level.
#                                       ` every nested element is contained within
#                                       ` this master element.
#   (driver_version VERSION_NUM)        ` VERSION_NUM must be 2
#   [(detect_secs SECONDS)]             ` how long to wait at startup for adapters
#                                       ` to come online
#                                       ` default: 10, max: 60, min: 2
#   [(fault_when_missing <yes|no>)]     ` see below for (fault_when_missing)
#                                       ` driver level default: "yes"
#   (port PORT_NUMBER ...)              ` see below for (port).
#   [(port PORT_NUMBER ...) ...]        ` (port) may occur multiple times.
#   )                                   ` end of (rioslave)
#
# Details on nested elements:

# Element (port ...)
# contains data for a particular bluehose port.  It will consist of one or more
# (rack_part) elements.
#
# (port PORT_NUMBER                     ` PORT_NUMBER says which bluehose port to use
#                                       ` Smart4: 0, 1, or 2.
#                                       ` NeoPAC: 1 or 2
#   (baudrate BAUDRATE)                 ` BAUDRATE must be 57600, 115200 or 230400
#   [(termination_resistor <yes|no>)]   ` default: "no"
#   [(debug BIT_MAP)]                   ` BIT_MAP may be 0 or non-zero and
#                                       ` controls debug logging statements
#                                       ` default: 0
#   [(fault_when_missing <yes|no>)]     ` see below for (fault_when_missing)
#                                       ` port level default: inherit from driver level
#   (rack_part ...)                     ` See below for (rack_part)
#   [(rack_part ...) ...]               ` (rack_part) may occur multiple times
#   )                                   ` end of (port)

# Element (rack_part)
# contains data for a particular adapter. A (rack_part) normally corresponds to
# an adapter and will take an Allen-Bradley remote IO address range length of
# either 2, 4, 6 or 8 words in an octal numeric format.  The data transfered to
# an adapter is mapped into the SoftPLC datatable for both directions: inputs
# and outputs.  This is done with two different types of s-expression elements,
# (inputs) and (outputs).
#
# (rack_part <OCTAL_RACK_NUM><STARTING_WORD_IN_RACK>-<OCTAL_RACK_NUM><LAST_WORD_IN_RACK>
#   (inputs ...)                        ` see below, only one allowed
#   (outputs ...)                       ` see below, only one allowed
#   [(fault_when_missing <yes|no>)]     ` see below for (fault_when_missing)
#                                       ` rack_part level default: inherit from port level
#   )                                   ` end of (rack_part)

# Element (inputs)
# contains the SoftPLC datatable address where the scanner should put digital inputs
# for the (rack_part).  The range (count) of words at the supplied starting DT_ADDRESS is
# implicit in the (rack_part) word range.  For example, (rack_part 010-017 ...)
# says that 8 words are mapped, numbered 0 thru 7.  Or (rack_part 126-127 ...)
# says 2 words are mapped, again starting at DT_ADDRESS given in the (inputs) element.
# (inputs DT_ADDRESS
#   )                                   ` end of (inputs)

# Element (outputs)
# contains the SoftPLC datatable address where the scanner should find digital outputs
# for the (rack_part).  The range (count) of words at the supplied starting DT_ADDRESS is
# implicit in the (rack_part) word range.  For example, (rack_part 010-017 ...)
# says that 8 words are mapped, numbered 0 thru 7.  Or (rack_part 126-127 ...)
# says 2 words are mapped, again starting at DT_ADDRESS given in the (outputs) element.
# (outputs DT_ADDRESS
#   )                                   ` end of (outputs)

# Element (fault_when_missing ...)
# is context specific and the meaning depends on the context.  The context
# of this setting may be (rio) aka "driver level", (port) aka "port level",
# or (rack_part).
#
# The higher the context, the greater the number of rack_parts that are
# affected by the setting.  If this setting resolves to "yes" for a rack_part,
# taking into consideration the inheritance mechanism, then when the adapter
# corresponding to that rack_part is not online a processor fault will ensue.
# If this setting resolves to "no" for a rack_part, then the adapter can go
# offline and this will not cause a processor fault.  This driver will resume
# communications with an offline adapter as soon as it comes back online.  However
# once the processor is faulted, it will not change mode by itself.  A processor fault
# shuts all reachable outputs off, and changes the mode of the CPU to "Fault" mode.

# end of intro comments and grammar rules.
# Next comes actual configuration statements:

(rio (driver_version 2)
  #(fault_when_missing no)       /* defaults to yes */
  (detect_secs 11)
  (port 1
    (baudrate 57600)
    #(debug 0x1)
    (termination_resistor yes)
    (rack_part 020-027 (inputs I:020)(outputs O:020))
    (rack_part 044-045 (inputs I:044)(outputs O:044))
    )

  (port 2
    (baudrate 57600)
    (termination_resistor yes)
    (fault_when_missing no)
    (rack_part 020-021 (inputs I:030)(outputs O:030)(fault_when_missing yes))
    )
  )             /* end of rio */

3.3. RIOMASTER.LST Configuration File Elements

Let’s examine each configurable element of the RIOMASTER.LST configuration file:

detect_secs

How long (in seconds) for SoftPLC to wait at startup for adapters to come online before reporting an error.

Possible values are 2 thru 60.

port number

The port on the SoftPLC device which is physically connected to the RIO network. Sensible numbers are device specific; i.e., the same port number may not work for every SoftPLC.

Possible values include:

Smart4: 0 thru 2

NeoPAC: 1 or 2

If in doubt about which port number to assign, note your
device's serial number; then, contact SoftPLC Support with your
serial number. Support can verify the port settings of your
specific device, and recommend which value to use in this field.

baudrate

The baudrate of the RIO network. All devices on the RIO network should use the same baudrate to communicate.

Possible values are: 57600, 115200, or 230400

termination resistor

Setting to 'Yes' engages a 120-ohm resistor which is internal to the SoftPLC device. If external, physical resistors are used on the network, or the SoftPLC is not an 'end-of-line device', the termination resistor element should be set to 'No'.

debug

See 'Debugging' section of this manual for greater detail.

rack_part

The range of logical words for a particular RIO rack. It is possible to have more than one 'rack_part' element.

If your rack is a 3/4-rack, addressed at seven, starting at word 2, then; "072-077" would be your 'rack-part'

inputs

Contains the SoftPLC data-table address where the scanner should put digital inputs for the 'rack_part'.

outputs

Contains the SoftPLC data-table address where the scanner should find digital outputs # for the 'rack_part'.

fault_when_missing

This element allows user(s) to modify the processor’s response to missing/failed adapters. If 'fault_when_missing' is set to 'yes'; then, the processor will fault upon missing/failed adapter(s). If 'fault_when_missing' is set to 'no'; then, the processor will continue running regardless of missing/failed adapter(s).

This element may be included at the top level (rio), port level (port), and/or adapter level (rack_part). The level at which "fault_when_missing" is included defines the setting’s scope of influence. For example, when included at the top level (rio); the element’s setting will respond to any missing/failed adapters. However, when included only at the adapter level (rack_part); the element’s setting will influence only the response pertinent to that specific adapter’s status. Should the user(s) omit this element, the driver defaults to 'yes' at the top level (rio).

It is important to consider this element’s influence on an adapter’s 'return' to the network. If 'fault_when_missing' is set to 'no'; the driver will resume control of the adapter immediately. However, if set to 'yes', the processor faults. A processor fault shuts all reachable outputs off, and changes the mode of the CPU to "Fault".

4. Diagnostic Ladder Instructions

The implementation of network query/response type ladder instructions should be carefully considered. These instructions directly impact network loads. Although not shown in examples below, recommended logic would include conditional statements based on network traffic. These conditional statements become increasingly important as the network size increases.

4.1. RIORETRYCOUNTS – Get Rack Retry Counts

This permissive instruction is used to get the rack retry counter values (Counts) for a given RIO Interface (Port). Four words are allocated for each full rack where each word corresponds to the starting quarter rack offset (1st, 2nd, 3rd, and 4th). Thirty-two (32) racks are supported. Total length of the assigned file is 128 (4x32) words. Valid count range will be 0-255 (8 bits).

Sensible port numbers for Smart4 devices include: 0, 1, or 2. Sensible port numbers for NeoPAC devices include: 1 or 2.

If the left side of the instruction is TRUE and the Port index is valid, then the rung state to the right of the instruction will be TRUE.

4.2. RIOGETFAULTMAP – Get Rack Adapter Fault Map

This permissive instruction is used to monitor rack faults for a given RIO interface (Port) network. Each word corresponds to a rack number where bits 0, 1, 2, 3 are set to indicate that adapters for the 1st, 2nd, 3rd, or 4th logical quarter racks, respectively are in a faulted state.

Sensible port numbers for Smart4 devices include: 0, 1, or 2. Sensible port numbers for NeoPAC devices include: 1 or 2.

If the left side of the rung is TRUE and the Port index is valid, the rung state to the right of the instruction will become TRUE if a rack fault is detected.

4.3. RIORACKEXISTS – Get Existing Racks Map

This output instruction creates a 32 word file (Map) of the existing racks on the specified RIO Interface (Port) network. Each word corresponds to a rack number where bits 8, 9, 10, 12 are set to indicate that adapters for 1st, 2nd, 3rd, or 4th logical quarter racks, respectively are present.

Sensible port numbers for Smart4 devices include: 0, 1, or 2. Sensible port numbers for NeoPAC devices include: 1 or 2.

If the left side of the rung is TRUE and the Port index is valid, then the rung state to the right of the instruction will be TRUE.

4.4. Block Transfer Instructions

4.4.1. BTW - Block Transfer Write

In this example, the BTW is executed one time during the first ladder scan to write configuration data to an analog Input Module.

The BTW instruction is also used to send logical data to an analog output module.

When assigning values the Rack, Group, and Slot parameters of the BTW instruction; use the values assigned to the 'outputs' element of the RIOMASTER.LST file. Not the values assinged to the 'rack_part' element. For example, if 'outputs' is assinged 'O:020'; the rack is '2' and the group is '0'. The slot value is determined by the slave RIO device’s location.

4.4.2. BTR - Block Transfer Read

In this example, the BTR will be enable if the BTW was successful, assuring that the analog Input module was successfully configured. Then the BTR will be executed repeatedly during the ladder scan to read the analog input values.

When assigning values the Rack, Group, and Slot parameters of the BTR instruction; use the values assigned to the 'inputs' element of the RIOMASTER.LST file. Not the values assinged to the 'rack_part' element. For example, if 'inputs' is assinged 'I:020'; the rack is '2' and the group is '0'. The slot value is determined by the slave RIO device’s location.

4.4.3. BTR/BTW Error Codes

If a block transfer error occurs, the error bit (/ER) will be set and a negative error code will be stored in the transmitted word count (.DLEN). Block transfer error codes are viewed at the address of the BT element in question (e.g., BT9:0/ER or BT9:0.DLEN).

Error Code	Description
-3	Data table block too small
-4	BTW reply error
-5	Checksum error
-6	Data file Length invalid for destination module
-7	Physical slot mismatch
-8	Invalid response
-9	Rack not defined
-10	Timeout
-11	Rack out of range

5. Debugging

To aid troubleshooting efforts, the SoftPLC drivers display output messages in the SoftPLC’s system log. Enabling and displaying these system log messages are discussed in the following subsections.

Before you start debugging, you should use the configuration editor to Fetch and then Save your existing full blown configuration. Then, on your development system (Windows computer), temporarily copy the file \SoftPLC\plc\<PLCNAME>\RIOMASTER.LST to a safe place. Then, you can edit the configuration file temporarily and experiment freely. Later, restore by copying from the safe place back to \SoftPLC\plc\<PLCNAME>\RIOMASTER.LST. Then, use the editor to Load then Send the file back down to SoftPLC.

Remember, after each configuration change the SoftPLC requires either a restart, power cycle, or 'double-clutch' prior to the change taking effect.

5.1. Enable Debugging

The SoftPLC runtime engine constantly monitors its processes, and 'logs' these observations as process output. By default, these logs are minimal. However, for troubleshooting purposes, the logs may be expanded to provide greater detail.

In the configuration file (RIOMASTER.LST), there is the "debug" element.

A debug value of "0x0" represents the minimal detail to be logged.
- Minimal detail is logged when the debug element is commented out of the configuration.
A debug value of "0x1" represents the maximal detail to be logged.

5.2. View Debugging

Viewing these logs shall be completed at the command prompt of the SoftPLC system. To access the command prompt, log into the SoftPLC by either:

(TOPDOC 5.x) use Remote Console feature in the 'PLC' window
(from Windows) use third-party 'PUTTY' application
(from Linux) use SSH from Terminal application

Default login credentials are as follows:
user: root
password: softplc

Once logged in, the logs can be viewed by executing:
(the '#' represents the prompt, and is not typed)
# journalctl -u softplc

You may need to use the arrow keys to scroll down to the end of the logs. The last logs are the most recent.
To exit the "journalctl" viewer, press "q".

5.3. Direct Debugging to Text File

The previous sections have shown how to view the logs from the command prompt. However, recording the logs to a text file is, in the least, efficient for receiving support. Once the text file is created, it can be transferred via (S)FTP to the TOPDOC machine. A detailed explanation of (S)FTP transfers can be found in the TOPDOC User Guide.

5.3.1. Direct Debugging output into a text file (SoftPLC 5.x)

Log into SoftPLC using either a) the remote console feature in TOPDOC’s PLC window, b) PUTTY from Windows, or c) using ssh from Linux.
Run this command:
# systemctl stop softplc
Change into the /SoftPLC/run directory:
# cd /SoftPLC/run
You can run SoftPLC from the command prompt now and redirect its output to an arbitrary file (named out.txt here). We put that file into the RAM disk which is anchored in the /tmp directory.
# ./runsplc > /tmp/out.txt
Let this run for 5-60 seconds, then press [Ctrl][C]. Now you have the output captured in file /tmp/out.txt, each request-response transaction will be captured in that file.
You can look at the file using the program named "less".
# less /tmp/out.txt
Press ESC when done.
You can make configuration file changes and Send them down to SoftPLC. Then merely repeat the part of this process starting at step 4 above.
When done, remember to set debug back to "0", then you can start SoftPLC normally either by a) power cycling the box or b) doing the following:
# systemctl start softplc

5.4. Fault Error Codes

The following error code values are viewable via the data-table Status Word 'S:15'. Typically, when a fault error code exists, the driver will set the Status Word 11, bit 6 (S:0011/06). Setting this bit immediately faults the SoftPLC. However, the configuration variable "fault_when_missing" may override faults during some '108' errors (see Section 3.3 - "fault_when_missing" for more details).

Error Code	Description	Resolution
100	Software version conflict between RIOMASTER driver and supporting software packages.	Contact SoftPLC Support for assistance.
101	Driver cannot initialize the configured port for 'Blue-hose' communications.	Contact SoftPLC Support for assistance.
102	The SoftPLC device lacks requisite firmware for 'Blue-hose' communications. Likely because the option was not ordered from the factory.	Contact SoftPLC Support to discuss options for adding 'Blue-hose' communications to your device.
103	Driver cannot open the configured port for 'Blue-hose' communications. Likely because the configured port lacks the requisite hardware for 'Blue-hose' communications.	Configuration file (RIOMASTER.LST) should be edited to include a port which is built for 'Blue-hose' communications. See Section 3.3 - "port number".
104	Upon startup of the driver, it will 'ask' each adapter to 'report' its size (1/4, 1/2, 3/4, or Full rack). Should this reported size be different than the configured size (per RIOMASTER.LST), error code '104' will occur.	Edit RIOMASTER.LST to coincide with the size of the adapter; or, change adapter/chassis DIP switches to coincide with the configuration file.
105	The RIOMASTER.LST file is improperly formatted (parsing error).	Review RIOMASTER.LST for errant/omitted characters. Correct as necessary. Restart SoftPLC runtime.
106	The RIOMASTER.LST file does not exist on the remote PLC, is improperly named, or resides at an incorrect location (/SoftPLC/tlm/).	'Send' a new copy of the RIOMASTER.LST configuration file to the remote PLC. This can be done via the Configuration Editor (see Chapter 3).
107	The configuration, per RIOMASTER.LST, includes an 'overlap' between two (or more) 'rack_part' ranges.	Edit RIOMASTER.LST such that the rack and group number assignments of one 'rack_part' do not conflict with the rack and group number assignments of another 'rack_part'.
108	Driver unable to find, on the RIO network, a 'rack_part' which was configured with RIOMASTER.LST.	Verify RIO network and settings of the problematic adapter. When complete, restart SoftPLC runtime. Alternatively, the 'rack_part' may be removed from RIOMASTER.LST configuration file.
109	Driver unable to change runtime modes (RUN, PROGRAM, FAULT, etc.)	Save all recent editing. Close 'Edit Remotely' window. Restart SoftPLC runtime, or power cycle the device.
110	Data-table file is too short.	Via 'Edit Remotely' expand the data-table to, at least, the size necessary; per the RIOMASTER.LST configuration. Alternatively, the configuration could be changed to fit within the existing data-table.

Error Code

Description

Resolution

100

Software version conflict between RIOMASTER driver and supporting software packages.

Contact SoftPLC Support for assistance.

101

Driver cannot initialize the configured port for 'Blue-hose' communications.

Contact SoftPLC Support for assistance.

102

The SoftPLC device lacks requisite firmware for 'Blue-hose' communications. Likely because the option was not ordered from the factory.

Contact SoftPLC Support to discuss options for adding 'Blue-hose' communications to your device.

103

Driver cannot open the configured port for 'Blue-hose' communications. Likely because the configured port lacks the requisite hardware for 'Blue-hose' communications.

Configuration file (RIOMASTER.LST) should be edited to include a port which is built for 'Blue-hose' communications.
See Section 3.3 - "port number".

104

Upon startup of the driver, it will 'ask' each adapter to 'report' its size (1/4, 1/2, 3/4, or Full rack). Should this reported size be different than the configured size (per RIOMASTER.LST), error code '104' will occur.

Edit RIOMASTER.LST to coincide with the size of the adapter; or, change adapter/chassis DIP switches to coincide with the configuration file.

105

The RIOMASTER.LST file is improperly formatted (parsing error).

Review RIOMASTER.LST for errant/omitted characters. Correct as necessary. Restart SoftPLC runtime.

106

The RIOMASTER.LST file does not exist on the remote PLC, is improperly named, or resides at an incorrect location (/SoftPLC/tlm/).

'Send' a new copy of the RIOMASTER.LST configuration file to the remote PLC. This can be done via the Configuration Editor (see Chapter 3).

107

The configuration, per RIOMASTER.LST, includes an 'overlap' between two (or more) 'rack_part' ranges.

Edit RIOMASTER.LST such that the rack and group number assignments of one 'rack_part' do not conflict with the rack and group number assignments of another 'rack_part'.

108

Driver unable to find, on the RIO network, a 'rack_part' which was configured with RIOMASTER.LST.

Verify RIO network and settings of the problematic adapter. When complete, restart SoftPLC runtime. Alternatively, the 'rack_part' may be removed from RIOMASTER.LST configuration file.

109

Driver unable to change runtime modes (RUN, PROGRAM, FAULT, etc.)

Save all recent editing. Close 'Edit Remotely' window. Restart SoftPLC runtime, or power cycle the device.

110

Data-table file is too short.

Via 'Edit Remotely' expand the data-table to, at least, the size necessary; per the RIOMASTER.LST configuration. Alternatively, the configuration could be changed to fit within the existing data-table.

Appendix A: Wiring Recommendations

A.1. Wiring connection to A-B 1771-ASB

A termination resistor should be connected across 1 (Blue) & 3 (Clear) on the last adapter on the RIO link.

The termination resistor value is determined by the RIO baud rate:

150-ohm for 57.6K or 115.2K
82-ohm for 230.4K

The RIO (Blue Hose) cable section from the SoftPLC device to the 1771-ASB must be at least seven (7) feet in length.

A.2. 1771-ASB Adapter Switch Settings

A.3. 1771 Chassis Switch Settings

A.4. Wiring connection to A-B 1747-ASB

A.5. 1747-ASB Adapter Switch Settings

A.6. Wiring connection to A-B 1794-ASB(x)

Appendix B: Migrating from legacy SoftPLC RIO driver

B.1. Automatically Converting to new (RIOMASTER) config file

The latest version (1.5.0) of the legacy RIO driver included a feature to automatically configure the RIOMASTER.LST file. The 'auto-config' process, will occur anytime the legacy RIO driver is in use by the SoftPLC hardware AND the RIOMASTER.LST file does not exist within the SoftPLC hardware’s /SoftPLC/tlm/ directory.

The legacy driver’s configuration file (RIO.LST) must be a working copy, compatible with the RIO network connected, prior to successful completion of the auto-config process. Should the RIO.LST file not represent the connected RIO network, the auto-config process will develop an unreliable RIOMASTER.LST file.

To initate the auto-config process, first remove RIOMASTER.LST file from the /SoftPLC/tlm/ directory by using the 'Remote Console' feature from the PLC window.

Once at the command line, execute the following command:
(the '#' represents the prompt, and is not typed)
# rm /SoftPLC/tlm/RIOMASTER.LST

Then, confirm legacy RIO driver is in use via PLC | Modules tab. And finally, restart SoftPLC Runtime from the PLC | Startup tab.

Upon restart, the legacy driver will check for the presence of RIOMASTER.LST. If not present, the driver will develop RIOMASTER.LST based on the contents of the existing RIO.LST file, and the responses of the present RIO network adapters: the auto-config process is complete.

The user may verify the contents of the newly created RIOMASTER.LST file via the PLC | Modules tab. Upon satisfactory review, the user may disengage the legacy driver. Then engage the RIOMASTER driver, followed by a SoftPLC Runtime restart in order to switch over to the new driver.

B.2. Manually Converting from legacy (RIO) config file

The software requirements (section 2.4.3) for the RIOMASTER driver differ from the requirements of the legacy RIO driver. Contact SoftPLC Support to assist with updating your SoftPLC hardware to support the new driver.

The image below displays two separate RIO networks driven by a single SoftPLC hardware. An example of the legacy driver’s configuration file (RIO.LST), considering these networks, is shown. Next, the RIOMASTER drivers configuration file (RIOMASTER.LST) is shown. The configuration files are functionally identical.

RIO.LST Configuration

[DRIVER]
DEBUG=0
DETECT_SECS=10

[INTERFACES]
;PortNum        Baudrate    TermResistor
1               57600       yes
2				115200	    no

[INPUTS]
;DtAddr         NumWords    PortNum     IOBusAddr
I:010           2           1           I:010
I:020			4	    	1			I:020
I:024			4	    	1			I:024
I:030           6           2           I:030
I:040           8           2           I:040

[OUTPUTS]
;DtAddr,        NumWords,   PortNum,    IOBusAddr
O:010           2           1           O:010
O:020			4	    	1			O:020
O:024			4	    	1			O:024
O:030           6           2           O:030
O:040           8           2           O:040

From the configuration above, note the following parameters

DEBUG is off
DETECT_SECS is 10 seconds
Two ports (i.e., two separate RIO networks) are used

Port 1 (57.6 Kbaud, Termination Resistor set)

Rack# 01 (IOBusAddr) is a quarter-rack beginning at Group 0
- Inputs landing at data-table I:010-011
- Ouputs sourced at data-table O:010-011
Rack# 02 (IOBusAddr) is a half-rack beginning at Group 0
- Inputs landing at data-table I:020-023
- Ouputs sourced at data-table O:020-023
Rack# 02 (IOBusAddr) is a half-rack beginning at Group 4
- Inputs landing at data-table I:024-027
- Ouputs sourced at data-table O:024-027

Port 2 (115.2 Kbaud, Termination Resistor not set)

Rack# 03 (IOBusAddr) is a three-quarter-rack beginning at Group 0
- Inputs landing at data-table I:030-035
- Ouputs sourced at data-table O:030-035
Rack# 04 (IOBusAddr) is a full-rack beginning at Group 0
- Inputs landing at data-table I:040-047
- Ouputs sourced at data-table O:040-047

RIOMASTER.LST Configuration

(rio (driver_version 2)
  (detect_secs 10)
  (port 1
	(baudrate 57600)
	(termination_resistor yes)
	(rack_part 010-011 (inputs I:010)(outputs O:010))
	(rack_part 020-023 (inputs I:020)(outputs O:020))
	(rack_part 024-027 (inputs I:024)(outputs O:027))
	)

  (port 2
	(baudrate 115200)
	(termination_resistor no)
	(rack_part 030-035 (inputs I:030)(outputs O:030))
	(rack_part 040-047 (inputs I:040)(outputs O:040))
	)
  )