Using Python for Cisco Serial I/O

• Download pySerial
• Download pyCiscoConsole

Contents

• Overview
• Requirements
• Installation
• CiscoDevice Class
• Public Methods
• __init__
• set_receive_wait
• get_mode
• set_mode
• send_command
• DeviceMode Class
• Usage Example

Overview

pyCiscoConsole provides a class based interface for communicating with a Cisco device over a console cable. pyCiscoConsole is single threaded and uses a heuristic approach for timing. Details below. The class is designed for compatibility with the new Python with statement for a more “Pythonic” approach for error handling. Use cases are under the “Usage” section.

Requirements

• pySerial for serial communications. The home page is here and it can be downloaded here.
• Python 3
• It has only been tested on Windows, but the code should port smoothly. Minimal if any editing will probably be required.

Installation

Simply drop pyCiscoConsole into the local directory and include it in your project. If you haven’t already, you will also need to install pySerial as mentioned in the requirements section above.

Class CiscoDevice

Public Attributes

connected

The connected attribute indicates whether a serial connection was successfully established to the requested port. It will be False if the connection failed and True if the connection succeeded.

Public Methods

The following section describes the methods available in the pyCiscoConsole module.

__init__(enable_password, port_number, baud_rate=9600)

Parameters

• enable_password (str): The enable password for the device
• port_number (int): The port number for the attached serial port. (COM1=0, COM2=1, etc)
• baud_rate (int): Optional. If you changed the baud_rate on the Cisco device, you need to change it here

Description

The CiscoDevice class takes as arguments the enable password for the device, the serial port number, and an optional baudrate if you changed the baudrate on the device. For the port number COM1 would be 0, COM2 would be 1, etc. This probably goes without saying, but the baudrate must match on the device and the program. If the port is already in use or the __init__ method cannot connect to it, the __init__ method will leave the connected attribute at its default value of false. If the connection succeeds, the __init__ method will set the value of the connected attribute to True.

set_receive_wait(wait)

Parameters

• wait (int): The additional time in seconds you want to wait to receive more data.

Description

Serial IO has varying delays. To optimize the speed of pyCiscoConsole, I tuned the wait timers to receive data aggressively. While this works for the vast majority of cases, some commands take longer than others to return IO. For example, the ping command displays some initial IO very quickly, but then takes a while to receive responses. This command allows the caller to temporarily increase the time that an instance of CiscoDevice will wait to receive data allowing time for delayed output to arrive. You must manually set the receive wait back to zero when you no longer wish to have an extended wait timer.

get_mode()

Returns

• Returns the current device mode as a DeviceMode object. The four modes are enable, global_config, sub_config, and non_privileged. See DeviceMode for details.

Description

This command returns the current privilege mode of the device as a DeviceMode object.

set_mode(desired_mode)

Parameters

• desired_mode (DeviceMode): The privilege mode you would like to set the device to. The four modes are enable, global_config, sub_config, and non_privileged. See DeviceMode for details.

Returns

• Returns the current device mode as a DeviceMode object. The four modes are enable, global_config, sub_config, and non_privileged. See DeviceMode for details.

Description

This commands sets the device privilege mode to the specified privilege mode. It automates the process of typing enable, exit, end, etc.

send_command(user_input)

Parameters

• user_input (str): This is the command you would like to send to the Cisco device. You do not need to add the return. The return is added in the function.

Returns

• This method returns the output of the command sent to the Cisco device.

Description

This method sends a command to the Cisco device. It is worth noting that the “show run” command is handled specially. It takes a moment for the device to build the configuration and display it. I handled this internally by lengthening the time given for receiving IO if the input buffer contains the phrase “building configuration”. This is the only special case handled. If you need to provide a longer than normal time for waiting for return output, you should use the set_receive_wait(wait) to lengthen the wait period manually.

Class DeviceMode

This class defines the possible privilege modes the device may be in.

Attributes

• enable: Defines enable mode for the device
• global_config: Defines the global configuration mode for the device
• sub_config: Defines sub configuration mode for the device
• non_privileged: Defines non-privileged mode for the device

Usage Example

# This is a usage example for the class
# This uses an enable password of "cisco" and COM3 as the selected port
with CiscoDevice("cisco",2) as device:

    # Make sure the device is actually connected
    if device.connected:

        # Change the device to enable mode and print the mode to standard out
        print(device.set_mode(DeviceMode.enable))

        # Just for giggles, double check the mode by printing it again
        print(device.get_mode())

        # Display a user driven loop to give the user a simple command prompt
        while True:

            # Get the command from the user
            command = input()

            # Check to see if the command is the ping command. If it is, allow for extra time for the command
            # to process
            if "ping" in command:
                # Wait an extra 15 seconds for additional IO
                device.set_receive_wait(15)
                # Send the command to the device and print the output back to the user.
                print(device.send_command(command))
                device.set_receive_wait(0)
            else:
                print(device.send_command(command))

    # If we failed to connect to the device print a failure message to standard out
    else:
        print("Unable to connect to the device.")