1. Overview
1.1. Introduction
This document describes the installation, usage, and functionality of the Allen-Bradley Remote I/O (RIO) Scanner software for SoftPLC. (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 RIO TLM implements the master or scanner role within the Allen-Bradley Remote I/O protocol.
This functionality is currently only available on Smart SoftPLC’s equipped with the Smart A-B RIO Master/Scanner Interface hardware (Cat.No. SM-ABRIOMx). The SM-ABRIOM is a factory installed option.
1.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 RIO 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.
1.3. Features
-
Supports racks numbered from 0 to 076 (octal).
-
Can scan up to 5 RIO networks concurrently.
-
Supports a 120 ohm termination resistor, software selectable.
-
Supports baud rates of 57600 (56.7Kbaud), 115200 (115.2Kbaud), and 230400 (230.4Kbaud).
-
Block transfer is fully supported.
1.4. Requirements
1.4.1. Hardware
-
Smart SoftPLC or Smart Gateway.
-
SM-ABRIOM5 and/or SM-ABRIOM6 Smart A-B RIO Master Interface hardware (one per network).
-
SM-COM6CBLTB - Smart COM6 Port Cable to Din-Rail Terminal Block Assembly (required for SM-ABRIOM6) Includes RJ11 interconnect cable and din-rail terminal block.
-
Belden #9463 Blue Hose connection cable(s) [customer supplied] (one per network).
Only version 2.0 (or later) Smart boards can support more than one A-B RIO interface. |
1.4.2. Software
-
Gatecraft Linux 2011A or above
-
SoftPLC version 4.6 runtime or above
-
TOPDOC NexGen 1.6 or above
2. Warranty
2.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.
© Copyright 2011-2016 SoftPLC Corporation ALL RIGHTS RESERVED
First Printing |
August, 2011 |
Latest Printing |
March, 2016 |
SoftPLC Corporation
25603 Red Brangus Drive
Spicewood, Texas 78669
USA Telephone: 1-800-SoftPLC
WW Telephone: 512/264-8390
Fax: 512/264-8399
URL: http://softplc.com
Email: support@softplc.com
3. Installation
3.1. Hardware Installation
The internal A-B RIO interface is factory installed into the Smart SoftPLC/Gateway. SM-ABRIOM5 replaces the COM5 port, SM-ABRIOM6 is available from COM6.
3.2. Component Overview
The figure below shows the port/wiring connection for the blue hose connected to COM5 of a Smart SoftPLC/Gateway with SM-ABRIOM5. Using the center line of text, the Clear wire connects to the terminal marked “C”, the Shield connects to the center marked “S”, and the Blue wire connects to the terminal marked “B”. Version 2.x (and later) Smart boards support RIO via COM5.
The figure below shows a mounted Smart SoftPLC/Gateway attached to the Smart COM6 Cable Assembly (Cat No SM-COM6CBLTB). Version 1.x and Version 2.x Smart Boards support RIO via COM6.
3.3. A-B RIO Wiring Connection to Din-Rail Terminal Block
The Terminals labeled by number in the image below correspond to the following wiring:
|
1. No Connection |
The version 2.x (and later) Smart boards have a 3 point terminal block for each supported RIO network. |
3.4. A-B RIO 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.1K/115.2K, and 82 ohm for 230.4K. |
The RIO (Blue Hose) cable section from the Smart COM5 or the SM-COM6CBLTB Din-Rail terminal block to the 1771-ASB must be at least seven (7) feet in length. |
3.5. 1771-ASB Switch Settings
Set the I/O Rack number on Switch Assembly S1 1-6 and the I/O Group number on S1 7-8. Set the RIO Baud rate on Switch Assembly S2 1-2, S2-3-6 are usually set to OFF.
3.6. 1771 Rack Switch Settings
Recommending settings are SW2 ON and all other switches OFF. When SW2 is ON, the RIO Adapter will be restarted when the Fault is cleared and the PLC is put in RUN Mode.
3.7. Software Installation
The TLM is named rio.tlm.so, and the configuration file is RIO.LST. Both of these files will be pre-installed on the SoftPLC for you. To use it you have to enable and configure it using TOPDOC NexGen’s PLC | MODULES editor. Select Use for RIO.TLM, then click on the Configure button to edit the RIO.LST file.
4. Configuration
4.1. Configuration Editor Usage
Load button will load the configuration file from the development system’s disk.
Save button will write the configuration file to the development system’s disk.
Fetch button will load the configuration file from the runtime system’s disk.
Send button will write the configuration file to the runtime system’s disk.
The next step is to restart or cycle power on the SoftPLC for the changes to take place. As an alternative to cycling power, you may enter "Remote Program" mode using NexGen, then select "Remote Program" a second time. This psuedo transition from Remote Program to Remote Program is a signal to the TLM that it should reload its configuration file. This way you can reconfigure without cycling power, although it does require you enter "Remote Program" mode (twice!).
4.2. RIO.LST Configuration File Details
The configuration file for the RIO TLM is /SoftPLC/tlm/RIO.LST. This file is used to set the debug level, baudrate, termination resistor on/off state, and the I/O Bus Addresses and associated SoftPLC Datatable assignments for each RIO network.
;Configuration file for SoftPLC RIO.TLM. ;Any part of any line in this text file to the right of a semicolon is a ;comment and will be ignored by the TLM. ;There are 4 sections in this file: [DRIVER], [CARDS], [INPUTS], ;and [OUTPUTS]. ;[DRIVER] is a place for global parameters. ;[INTERFACES] lists each RIO interface (i.e. bus or cable) in the system on ; a separate line. ; There are columns for PortNum, and Baudrate. ; Because this driver is optional, acceptable PortNums vary based on device type, ; order options, and in rarer cases firmware revision. ; NeoPacs may utilize PortNums 1 and/or 2. ; Smart4s may utilize PortNums 0, 1, and/or 2. ; Smart2s may utilize PortNums 0 (COM5 port) and/or PortNum 1 (COM6 port). ; Baudrate must be one of 57600, 115200, or 230400. ;[INPUTS] lists blocks of words that are to be copied from each ;interface into the SoftPLC input image table as part of the I/O scan. ;Only I:xxx type addresses may be used here. DtAddr is the ;memory address within SoftPLC and must be in the I: datatable section. ;IOBusAddr is the address that is determined by the physical rack and slot ;used on an RIO bus. ;Each row in this section describes a block whose length is ;given by NumWords. A block may be as long as you like, and ;sometimes you will have only one block, other times you might ;have several. This scheme lets you map any IOBusAddr ;to any real input DtAddr. ;[OUTPUTS] lists blocks of words that are to be copied from ;SoftPLC's output image table onto a bus as part of the I/O scan. ;Only O:xxx type addresses may be used here. DtAddr is the ;memory address within SoftPLC and must be in the O: datatable section. ;IOBusAddr is the address that is determined by the physical rack and slot ;used on an RIO bus. ;Each row in this section describes a block whose length is ;given by NumWords. A block may be as long as you like, and ;sometimes you will have only one block, other times you might ;have several. This scheme lets you map any DtAddr ;to any one or more real output IOBusAddrs. The same DtAddr may ;be mapped to more than one output IOBusAddr. ;A "word" corresponds to an I/O group, and this is the granularity ;given by this configuration strategy. ;Unlike AB PLC's, with this SoftPLC RIO driver, both the I:ABC and O:ABC ;at a given ABC DTAddr element may both be used simaltaneously. [DRIVER] DEBUG=1 ; set to 0 or 1 to enable logging of RIO network traffic DETECT_SECS=10 ; Maximum seconds to spend finding the configured adapters, 1-60 allowed [INTERFACES] ;PortNum Baudrate TermResistor 0 57600 yes [INPUTS] ;DtAddr NumWords PortNum IOBusAddr I:010 200 0 I:020 [OUTPUTS] ;DtAddr NumWords PortNum IOBusAddr O:010 200 0 O:020
5. Usage
5.1. RIO TLM Diagnostic Ladder Instructions
5.1.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 Smart2 devices include: 0 or 1. 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.
5.1.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 Smart2 devices include: 0 or 1. 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.
5.1.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 Smart2 devices include: 0 or 1. 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.
5.2. Block Transfer Instructions
5.2.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.
5.2.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.
5.2.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).
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 |
6. Debugging
When SoftPLC starts, the RIO driver will scan the RIO Network for available racks. If the racks defined in the RIO driver’s configuration file (RIO.LST) can not be found on the network, the PLC will Fault. To help resolve the problem, examining the RIO driver output messages in the system log can help.
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>\RIO.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>\RIO.LST. Then use the editor to Load then Send the file back down to SoftPLC. Remember that you have to restart SoftPLC after each configuration change. |
6.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 can provide greater detail.
In the configuration file (RIO.LST), there is the "DEBUG=" attribute.
-
A debug value of "0" represents the minimal detail to be logged.
-
A debug value of "1" represents the maximal detail to be logged.
6.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:
-
(from Windows) use third-party 'PUTTY' application
-
(from Linux) use SSH from Terminal application
-
(TOPDOC 5.x) use Remote Console feature in the 'PLC' window
Default login credentials are as follows: user: root password: softplc |
Once logged in, the logs can be viewed by executing one of the following:
(the '#' represents the prompt, and is not typed)
-
For SoftPLC firmware 4.x
-
# logread
-
-
For SoftPLC firmware 5.x
-
# 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".
-
-
6.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 text file format is, in the least, efficient for receiving support. Accomplishing this, much like viewing the logs, is firmware dependent (see following sections). 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’s Guide.
6.3.1. Direct Debugging output into a text file (SoftPLC 4.x)
-
Log into SoftPLC using either a) PUTTY from Windows or b) using ssh from Linux or c) at the command prompt of the SoftPLC system.
-
Run this command:
# /etc/init.d/softplc.sh stop -
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 control-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 as a daemon either by a) power cycling the box or b) doing the following:
# /etc/init.d/softplc.sh start
6.3.2. 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 control-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 as a daemon either by a) power cycling the box or b) doing the following:
# systemctl start softplc