IR8xx Platforms

IR829 is a fleet-targeted mobile gateway that addresses the majority of use cases for fleets. The goal is to provide an “off the shelf” solution for the widest possible number of fleet applications with the fewest number of SKUs and least amount of custom developments possible. The Fleet Gateway is a ruggedized router integrating WiFi and Cellular radios.

IR809 targets markets like Distribution Automation, ATM, POS, Telemetry, Enterprise Fleet, mobile machine-to-machine (M2M), bill boards, and so forth. IR809 brings in 4G LTE capabilities to small form factor M2M routers.

These routers ship with one Cisco provided IOXVM which enables IOx on the platform. All IOx applications run within this IOXVM.

In certain cases, a customer may decide to install a custom operating system on the platform. In this situation, IOx support ceases to exist on the platform (and for the customer).

Platform Architecture – High Level

Both IR829 and IR809 use the same Intel Rangeley Dual-Core CPU, 2GB DDR3 memory, 8MB SPI Bootflash, 8GB (4GB usable) eMMC bulk flash.

Hypervisor, provided by LynxWorks, runs on the bare metal hardware upon which IOS and a Guest OS (e.g. Linux) run as two separate Virtual Machines (VMs).

The Hypervisor presents underlying hardware to virtual machines (IOS and Guest OS) as a subset of actual physical hardware. Which devices must be allocated to which VM is provided by a configuration to the Hypervisor. The VMs access a virtual CPU, pre-configured memory regions, pre-divided flash disk storage, and other hardware devices. LynxSecure Separation Kernel v. 5.1 has been selected as a Hypervisor.

Each PCI device can be owned exclusively by one VM in the Hypervisor architecture. However, IOS and the Guest OS need to access some shared devices, for example eMMC flash. The solution is a Virtual Device Server (VDS), which is a separate VM that owns shared devices. IOS and Guest OS access the virtual devices emulated in Hypervisor. The Hypervisor and VDS then coordinate access to the shared devices. The VDS also provides communication channels between VMs, using emulated Ethernet interfaces.

IOS acts as a gateway to network resources for the Linux partition, using IP and a virtual switch connection provided to the Hypervisor. IOS and Linux each operate as a Guest OS of the Hypervisor.

The network path from IOXVM to IOS is available via an emulated Ethernet link between them. Either IPv4 or IPv6 protocol can be run on the Ethernet link.

The IOXVM runs CAF and other IOx infrastructure elements on the host Linux and hosts all the LXC applications.

Hardware Platform Caveats

IR800 series devices do not have a dedicated storage for apps. These platforms have a single, soldered-on flash storage that is shared between IOS and apps. The flash part is not field replaceable.

Flash has a finite number of P/E cycles. Flash lasts as long as the box life cycle if used only for IOS configurations. If applications write frequently to the flash, wear-out becomes a serious concern.

Developers and customers are encouraged to watch and throttle the frequency of writes to flash. If the application or use case demands frequent writes or large amount of data storage, customers are advised to export the data for off-the-device storage.

IOS Image

The minimum IOS version required for IOx support is 15.6(1)T1.

IOx Images

IOx functionality is available in IR829 as part of a bundle IOS image or a standalone IOx image.

• Bundle image: A bundle image contains Hypervisor, IOS, VDS, and IOx image. The image name is of the format ir800-universalk9-bundle.xxxx or ir800-universalk9_npe-bundle.xxxx
• Standalone IOx image: Once a compatible IOS image is present on the platform, you can install or upgrade IOx using the standalone image. The image name is of the format ir800-ioxvm.xxx.bin

Basic IOS and IOx Configuration

Provide network connectivity to your device

• Login to the console of your device. This WAN GIGE0 port needs an Ethernet SFP to connect an RJ45 Ethernet cable.
• Connect the WAN (GigabitEthernet0) port to your network. Configure the IP address and the required routes.

CopyIR800-163#configure terminal
Enter configuration commands, one per line.  End with CNTL/Z.
IR800-163(config)#interface GigabitEthernet 0
IR800-163(config-if)#ip address <your_ip> <subnet_mask>

• Configure the required route and gateway.

CopyIR800-163#configure terminal
Enter configuration commands, one per line.  End with CNTL/Z.
IR800-163(config)#ip route 0.0.0.0 0.0.0.0 <GW ip address>
IR800-163(config)#ip default-gateway <GW ip address>

• If you use LAN ports GIGE1,2,3,4, configure a VLAN and assign an IP address since they are L2 switch ports.

Configure WAN Interface

Enable nat outside on GigE0 or the interface that connects internal traffic to outside world.

Copyinterface GigabitEthernet0
 ip nat outside
 ip virtual-reassembly in
!

Configure Networking

Configure the IOXVM and IOS connectivity interface

• ip nat inside - Enter this command to specify that the interface is connected to the inside network.
• ipv6 enable - IPv6 must be enabled.

Configure local DHCP pool for IOXVM IPv4 address assignment

To assign an IPv4 address to IOx and apps, configure a Local DHCP pool on IOS with GIG5 as the default router.

Copyip dhcp excluded-address 192.168.1.1 192.168.1.5
!
ip dhcp pool gospool
 network 192.168.1.0 255.255.255.0
 default-router 192.168.1.1         <<<<<<<<<<<<<<<,GE5 is the gateway to IOXVM
 domain-name <domainname>
 dns-server <dnsip>
 remember
!

Note: The Guest OS VM periodically compares its time with the Cisco IOS time. If the difference in times is more than 60 seconds, the Guest OS VM resynchronizes its time to the Cisco IOS time. No user configuration is required to initiate Guest OS VM clock synchronization or to modify clock settings. You can configure Cisco IOS to synchronize to an external NTP server.

Obtain IOx Details

• If IOXVM is not started, start it using:

CopyIR800# guest-os 1 start

• The boot time for IOXVM is approximately 5-6 minutes. Once completely booted, you can get the IP address of IOx:

CopyIR800#show iox host list detail

IOX Server is running. Process ID: 325
Count of hosts registered: 1

Host registered:
===============
    IOX Server Address: FE80::200:CFF:FEAE:A349; Port: 22222

    Link Local Address of Host: FE80::1FF:FE90:8B05
    IPV4 Address of Host:       192.168.1.2   <<<<<<<<<<<<<<<<<<<<<<ip address got from the DHCP Pool
    IPV6 Address of Host:       fe80::1ff:fe90:8b05
    Client Version:             0.4
    Session ID:                 2
    OS Nodename:                iox-ir809-10-GOS-1
    Host Hardware Vendor:       Cisco Systems, Inc.
    Host Hardware Version:      1.0
    Host Card Type:             not implemented
    Host OS Version:            1.5.3.3
    OS status:                  RUNNING

    Interface Hardware Vendor:  None
    Interface Hardware Version: None
    Interface Card Type:        None

NAT Configurations

Since the DHCP pool of configured IP addresses is internal and cannot be routed externally, configure NAT rule on IOS to allow ports 8443 (on which CAF is running) and 22 for allowing console access to applications.

The below snippet assumes that the IOx IP address is 192.168.1.6

Copyip nat inside source list NAT_ACL interface GigabitEthernet0 overload
ip nat inside source static tcp 192.168.1.6 22 interface GigabitEthernet0 2222
ip nat inside source static tcp 192.168.1.6 8443 interface GigabitEthernet0 8443

!
ip access-list standard NAT_ACL
 permit 192.168.0.0 0.0.255.255

Configure User Privileges on IOS

Before IOx Hosting Infrastructure is used for application management, either through Local WebUI or issuing REST API commands, users must authenticate in IOS to obtain administrative privileges.

The IOx Hosting Infrastructure relies on IOS local user authentication for this purpose. This local user authentication is same as the one which allows users to identify with IOS to get administrative access. Only the users who have configured a password with privilege 15 level on IOS are eligible to log on Local WebUI. This section shows how to configure user privileges for IOx.

Copy// Enter the configure terminal mode
IR800#config t
Enter configuration commands, one per line.  End with CNTL/Z.

// Add privilege level 15 for user: johndoe. "secret" means password - which is entered right after: !john^*!doe!123!
IR800(config)#username johndoe privilege 15 secret !john^*!doe!123!

// Enter end to get out of configure terminal mode
IR800(config)#end
*Oct 17 18:58:06.173: %SYS-5-CONFIG_I: Configured from console by console

// Check if the user was added by doing a section search for username in running-config
IR800#sh run | sec username
username johndoe privilege 15 secret 5 $1$vQHM$Q6FFDsfgsk4YMTKEt75KF0

Configure IPv6 for IOxVM

If an application needs to be IPv6 addressable, first enable IPv6 on the router using the global configuration command ipv6 unicast-routing.

Copyipv6 unicast-routing

Configure the IPv6 prefix to assign stateless DHCPv6 addresses to the IOxVM and the applications.

Copyinterface GigabitEthernet5
 ip address 192.168.1.1 255.255.255.0  <<< Internal private IP
 ip nat inside
 ip virtual-reassembly in
 duplex auto
 speed auto
 ipv6 address 2001:192:168:1::1/64
 ipv6 enable
 ipv6 dhcp server v6gospool
!

Configure the DHCPv6 pool if a stateful DHCPv6 address needs to be assigned to applications.

Copyipv6 dhcp pool v6gospool
  address prefix 2001:192:168:1::/64 lifetime infinite infinite

Configure NTP server for the router

Note: The Guest OS VM periodically compares its time with the Cisco IOS time. If the difference in times is more than 60 seconds, the Guest OS VM resynchronizes its time to the Cisco IOS time. No user configuration is required to initiate Guest OS VM clock synchronization or to modify clock settings. You can configure Cisco IOS to synchronize to an external NTP server.

In config terminal, use the following commands:

Copyntp update-calendar
ntp server 10.64.58.50

Download, Install, and Enable IOx

Upgrade of IOx

1. Copy the IOXVM image.

Copyiox-ir829gw-1#copy http://<URL>/ir800-ioxvm.1.0.0.0.bin flash:

• Install the IOXVM image.

Copyguest-os 1 stop
guest-­os 1 image uninstall
guest-os 1 image install flash:ir800-ioxvm.1.0.0.0.bin verify
guest-os 1 start

• Start the Guest OS.

Copyguest-os 1 start

Upgrade Using Bundle

1. Copy the bundle image.

Copycopy http://<URL>/ir800-universalk9-bundle.SSA.156-0.00.17.GB flash:

• Install the bundle image.

Copybundle install flash:ir800-universalk9-bundle.SSA.156-0.00.17.GB
 Installing bundle image: /ir800-universalk9-bundle.SSA.156-0.00.17.GB.....

updating Hypervisor image...
 Sending file modes: C0444 23739221 ir800-hv.srp.SPA.0.33
    SRP md5 verification passed!

updating IOS image...
 Sending file modes: C0644 61868196 ir800-universalk9-mz.SSA.156-0.00.17.GB
    IOS md5 verification passed!
Done!

3. Reload.

Copyreload
Do you want to reload the internal AP ? [yes/no]: yes
Proceed with reload? [confirm]

4. Restart the IOXVM instance to take effect.

IOXVM Disk Repartitioning

CAUTION: Disk repartitioning causes ALL data (IOx apps, IOXVM Kernel, and root file system) on the two disks to be erased. Ensure that you backup your data prior to repartitioning. After completing the disk-repartition, you MUST reinstall the IOXVM using the steps above.

IOXVM has two disks. disk1 contains the operating system kernel and root files system. disk2 is used for storing IOx application data. The default storage sizes for the disks are ..* disk1: 500MB vs disk2: 1800MB

We recommend that you use the default profile since it allows the maximum storage for IOx applications.

The size of these disks can be modified using the disk-repartitioning CLI from IOS.

Copyiox-ir809-03# guest-os 1 disk-repartition ?
  1  disk1: 500MB vs disk2: 1800MB (NOTE : Actual storage available for apps will be less than the value chosen for disk2 for all profiles. See the  documentation for more information.)
  2  disk1: 700MB vs disk2: 1600MB
  3  disk1: 900MB vs disk2: 1400MB
  4  disk1: 1100MB vs disk2: 1200MB
  5  disk1: 1300MB vs disk2: 1000MB
  6  disk1: 1500MB vs disk2: 800MB
  7  disk1: 1700MB vs disk2: 600MB

IOXVM Version Detail

Copyshow platform guest-os
Guest OS status:
Installation: Cisco-GOS,version-1.29
State: RUNNING

Stopping IOXVM

Copyguest-os 1 stop

Enabling Serial Ports

IR8x9 has two RJ45 serial ports on the faceplate. External serial devices connected to the host platform can be exposed to IOx applications.

Serial port 0 can be configured for either RS232 DTE or RS485. Serial port 1 can be configured for RS232 DTE only. Please refer to the following page for RJ45 pinouts.

Cisco IR829 Industrial Integrated Services Router Hardware Installation Guide

Data Flow on IR8x9

Serial data flow for containerized applications on an IR8x9 consists of multiple segments:

• Connection between a physical line and a virtual line in IOS
• Connection between a virtual line in IOS and a TTY port in IOXVM
• Connection between a TTY port in IOXVM and an application

Configuring Serial Interfaces for IOx Applications

• To use serial port 0:

Copyinterface Async0
 no ip address
 encapsulation relay-line
end

line 1
 exec-timeout 0 0
 no exec
 transport preferred none
 transport input all
 transport output none
 stopbits 1


relay line 1 1/5

• To use serial port 1:

Copyinterface Async1
 no ip address
 encapsulation relay-line
end

line 2
 exec-timeout 0 0
 no exec
 transport preferred none
 transport input all
 transport output none
 stopbits 1


relay line 2 1/6

The relay line 1 1/5 command links the first physical line to virtual line 5, which is connected to ttyS1 in IOXVM. The relay line 2 1/6 command links the second physical line to virtual line 6, which is connected to ttyS2 in IOXVM.

By default, only RS232 is enabled on Async0.

• To enable RS485:

Copyinterface Async0
no ip address
encapsulation relay-line
half-duplex
media-type rs485

• Change the baud rate of a line (using the right line depending on Async0/1):

Copy829-163(config)#line 1/5
829-163(config-line)#speed 115200
829-163(config-line)#end
829-163#show line 1/5
   Tty Line Typ     Tx/Rx    A Modem  Roty AccO AccI  Uses  Noise Overruns  Int
    1/5   71 TTY 115200/115200-    -      -    -    -     0      0    0/0      -

Troubleshooting Guides

Serial Interface Status

Copysh interfaces Async 0
Async0 is up, line protocol is up
  Hardware is Serial in async mode
  MTU 1500 bytes, BW 9 Kbit/sec, DLY 100000 usec,
     reliability 255/255, txload 1/255, rxload 1/255
  Encapsulation RELAY-LINE, loopback not set
  Keepalive not set
  DTR is pulsed for 5 seconds on reset
  Last input never, output never, output hang never
  Last clearing of "show interface" counters 1d23h
  Input queue: 0/75/0/0 (size/max/drops/flushes); Total output drops: 0
  Queueing strategy: fifo
  Output queue: 0/10 (size/max)
  5 minute input rate 0 bits/sec, 0 packets/sec
  5 minute output rate 0 bits/sec, 0 packets/sec
     0 packets input, 0 bytes, 0 no buffer
     Received 0 broadcasts (0 IP multicasts)
     0 runts, 0 giants, 0 throttles
     0 input errors, 0 CRC, 0 frame, 0 overrun, 0 ignored, 0 abort
     0 packets output, 0 bytes, 0 underruns
     0 output errors, 0 collisions, 0 interface resets
     0 unknown protocol drops
     0 output buffer failures, 0 output buffers swapped out
     0 carrier transitions     DCD=up  DSR=up  DTR=up  RTS=up  CTS=up

Verifying Serial Line Status

Copysh line 1/5
   Tty Line Typ     Tx/Rx    A Modem  Roty AccO AccI  Uses  Noise Overruns  Int
    1/5   71 TTY   9600/9600  -    -      -    -    -     0      0    0/0      -

Line 1/5, Location: "", Type: ""
Length: 24 lines, Width: 80 columns
Baud rate (TX/RX) is 9600/9600, no parity, 1 stopbits, 8 databits
Status: Ready
Capabilities: EXEC Suppressed
Modem state: Ready
Group codes:    0
Special Chars: Escape  Hold  Stop  Start  Disconnect  Activation
                ^^x    none   -     -       none
Timeouts:      Idle EXEC    Idle Session   Modem Answer  Session   Dispatch
               00:10:00        never                        none     not set
                            Idle Session Disconnect Warning
                              never
                            Login-sequence User Response
                             00:00:30
                            Autoselect Initial Wait
                              not set
Modem type is unknown.
Session limit is not set.
Time since activation: never
Editing is enabled.
History is enabled, history size is 20.
DNS resolution in show commands is enabled
Full user help is disabled
Allowed input transports are none.
Allowed output transports are none.
Preferred transport is none.
Shell: enabled
Shell trace: off
No output characters are padded
No special data dispatching characters

Restrictions

• Serial signaling is always terminated by IOS. Terminal line settings, including baud rate, data bits, parity bits, and flow control need to be configured in IOS.
• RS485 support is only available on async0 on IR8x9. Otherwise, an external RS485 to RS232 converter must be used.