Edge Gateway for Cisco Routers

This document contains information about the EdgeGateway application for Cisco Routers, designed to read data from a Rockwell ontrolLogix PLC and publish it to a MQTT Broker using SparkPlugB specification.

MQTT: It is a lightweight, publish-subscribe network protocol that transports messages between devices. The SparkPlugB has additional control and standards allowing to know about birth, death and a better data exchange control. For more information on the SparkplugB specification, please refer to the SparkPlugB specification at eclipse.org.


System Requirements

To use this feature, the following system requirements need to be met.

  • Cisco Router, model IR1101.
  • *.tar file, containing the docker image with the application to be installed.
    • iox-edge-gateway-Arm64.tar, if your Router's processor is ARM.
    • iox-edge-gateway-X86.tar, if your Router's processor is x86.
  • Allen-Bradley/Rockwell - ControlLogix PLC / Micro800.
  • MQTT Broker with support to SparkPlugB specification.

How Does it Work?

The EdgeGateway application consists of a docker image with a program that handles all communication exchange. The programs were written in Python they manage two independent connections, one with the Rockwell ControlLogix PLC and the one with the MQTT Broker.

  • ControlLogix PLC Client: Client implementation over TCP/IP running on an independent thread. Reads real-time data from the ControlLogix PLC and forwards it to the main program, so it can be published to an MQTT Broker.
  • MQTTspB Client: Client implementation for MQTTspB protocol, running on an independent thread. Receives data from the ControlLogix Client (through the main program) and publishes to the MQTT Broker.


This program behavior is illustrated as per image below.

EdgeGateway on Cisco Routers, getting data from ControlLogix, publishing to MQTT


How to Install and Deploy Apps

The first step is to make sure you have downloaded the *.tar with support to your Router's processor. Then, choose one of the following ways to install the application.

Using Cisco Local Manager

Cisco Local Manager is a platform-specific application that is installed on a host system as part of the installation of the Cisco IOx framework on that device. It provides a web-based user interface that you can use to manage, administer, monitor, and troubleshoot apps on the host system, and to perform various related activities.
For more information about it, please refer to the Cisco official documentation. To Install and Deploy your application, follow the procedure below.

  • Go to Applications Tab in the Menu Bar.

  • Click Add New.

  • Select the *.tar file and enter a friendly name to the Application. It will be used as an Identifier.

  • Click Activate to activate the app.


  • From inside your App's configuration display, go to the App-Config tab. Customize the parameters if necessary. More information available in section 5.

     

Below you will find some definitions for terms frequently used when dealing with applications in Cisco Environment:

  • Deployed: Means the Application has been imported.
  • Activate: Reserves host system resources that the app requires to run, designates the network from which the app obtains its IP address, and assigns host system serial ports for use by the app, if requested.
  • Start: Starts the app container for the app on the host system. CPU and memory (RAM) resources that were reserved for the app become in use.

Using Cisco IOx Client

For this procedure, you must have IOx Client installed on your environment.
The official installation guide and documentation for IOx Client is available here.

  • Launch the IOxClient.exe in your OS command line terminal. It is easier if you add it to PATH and run the terminal from the same folder as your *.tar file.
  • If your IOxClient does not have a profile connected to the Router already, do as follows:


ioxclient profiles create
// here you will connect to the Router
// values inside brackets will be used by default if empty

Your / your organization's name : <OrganizationName>
Your / your organization's URL : <OrganizationUrl>
Your IOx platform's IP address[127.0.0.1] : <RouterIPAddress>
Your IOx platform's port number[8443] : <RouterPortNumber> 
Authorized user name[root] : <UserName>
Password for <UserName> : <PasswordForUser>
Local repository path on IOx platform[/software/downloads]: <Repository> 
URL Scheme (http/https) [https]: <TransferProtocol>
API Prefix[/iox/api/v2/hosting/]: <ApiPreffix>
Your IOx platform's SSH Port[2222]: <SshPortForRouter>


  • Run the following commands to install, activate and start the package:
ioxclient application install <AppName> <PackageName>.tar 
ioxclient application activate --payload activation.json <AppName> 
ioxclient application start <AppName>

Where AppName is a friendly name used to identify the application inside the Router.

  • Use the following commands to stop/disable and uninstall the application:
ioxclient application stop <AppName> ioxclient application deactivate <AppName>
ioxclient application uninstall <AppName> <PackageName>.tar

Use the following command to see the application status

ioxclient application status <AppName>


Mapping MQTT and PLC addresses

To customize your client parameters, at Cisco Local Manager make sure your application is in Activated state. Then, inside your App Tab, go to App-Config.

You should see a text content, with some parameters. Configure them according to your architecture.

[logging]
# DEBUG:10, INFO: 20, WARNING: 30, ERROR: 40, CRITICAL: 50, NOTSET: 0
log_level: 10
# Enable/disable logging to stdout
console: yes
filename: status.log

# Create as many Broker connections as you want, using the syntax 'mqtt_broker_X' for the section name
# where x is an index for your broker
[mqtt_broker_1]
# broker IpAddress
host:127.0.0.1
# broker port number
port:1883
# username credential for connection (optional)
user_name:
# password credential for connection (optional)
password:

# Uncomment this section to connect to a second broker
#[mqtt_broker_2]
#host:127.0.0.1
#port:1883
#user_name:
#password:

[mqtt_client_info]
# flag indicating if MQTT Client is Enabled
enabled: yes
# groupID for Payload
group_id: Group
# nodeID for Payload
node_id: Node
# deviceID for Payload
device_id: Device
# Indicates the time for publishing in milliseconds.
#The messages that will be published to MQTT Broker are grouped and sent using this period
publish_rate:1000
# Flag that indicates if it should replace brackets by parentheses in the metric name (yes/no)
use_parentheses_for_array: yes

[control_logix_client_info]
# flag indicating if ControlLogix Client is Enables (yes/no)
enabled: no
# plc ip address
ip_address: 127.0.0.1
# plc slot number
slot: 0
# flag indicating if PLC is Micro800 (yes/no)
is_micro800: no
# read pooling rate in milliseconds
refresh_rate:1000
# list variable names (only main element) separated by comma. E.g.: MyInt, MyUDT
# If you use wildcard "*" (without quotes) ALL PLC variables will be added to the communication
variable_addresses:
# variables, from 'variable_addresses' field, that will be read/write access, separated by comma. Can use Variable FullName
read_write_addresses:


Troubleshoot

In this section, you will find a troubleshoot procedure for some common errors.

App was missing at Least one interface

If you encounter this error, it means that your router is missing a network configuration for applications. To solve it, follow the procedure described at Configure a VirtualPortGroup to a Layer 3 Data Port section. <<<<. link is broken >>>>
Connect to your Router via SSH (either via terminal or in Cisco Local Manager) and do as follows.

In this section...