CIP Emulator

#depends: pip install grpcio grpcio-tools pip install aiofiles

Overview

The CIP Emulator is a tool designed to simulate network load similar to that generated by the Common Industrial Protocol (CIP), commonly used in industrial automation systems. Rather than fully emulating the CIP protocol, this emulator replicates the traffic patterns and packet flows, enabling users to assess their network's capability to support CIP-like communication. This tool is ideal for stress-testing networks, troubleshooting performance, and verifying infrastructure capacity in CIP environments.

How It Works

The emulator employs a server-client architecture to replicate CIP network communications, including TCP and UDP packet flows. Here’s a breakdown of its main components:

1. Server (Consumer):
   • The server listens for TCP and UDP packets from multiple clients, resembling how a CIP consumer would operate.
   • It tracks packets from each client, monitors sequence numbers, and logs any missed packets, simulating typical CIP network load and error conditions.

Note on Consumer Initiation in CIPCM

In typical CIP Connection Management (CIPCM) setups, the consumer (originator) is responsible for initiating the communication flows. However, in this emulator, the consumer is designed to passively receive simulated traffic from the producers.

This approach is intentional and focuses on generating realistic CIP-like network load to stress test network infrastructure. The objective is to ensure the network can support CIP traffic under load, rather than to emulate exact protocol behaviors like flow initiation. This distinction allows us to focus on assessing the infrastructure's robustness for handling CIP-style traffic without adhering strictly to protocol initiation roles.

2. Clients (Producers):

   • Multiple clients generate traffic simultaneously, each tagged for identification.
   • Clients send packets with sequence numbers and timestamps, allowing the server to detect missed or delayed packets, similar to CIP producer traffic.
   • QoS (DSCP): Each client can be configured with a qos field to set the Differentiated Services Code Point (DSCP) for UDP packets. This feature allows users to simulate CIP Safety (DSCP 47) and CIP IO (DSCP 43) traffic levels to ensure network infrastructure can handle CIP traffic prioritization.
   • Packet Skip Simulation: Clients can optionally skip packets (using enable_packet_skip), which can be useful for testing the server's missed packet counter by intentionally dropping packets for simulation and code testing.

3. Graphical Interface (GUI):

   • The GUI allows users to configure the emulator, view logs, and monitor real-time packet flow and errors.
   • Users can control server and client startup, edit configuration, and observe real-time logs.

4. Command-Line Interface (CLI):

   • For headless use cases, the emulator can be run in CLI mode, with options to start the server, clients, or both. Logs are output directly to the terminal.

Usage Instructions

Directory Structure and Files

The CIP Emulator is organized into several folders, each serving a specific purpose within the project. Please ensure the config.json file is located in the root of the project directory to allow correct configuration loading. Below is the directory structure:

C:.
├───.vscode             # VSCode configuration files (optional)
├───core                # Core components including CIP client and server modules
│   └───__pycache__     # Compiled Python files for `core`
├───gui                 # GUI components and display logic
│   └───__pycache__     # Compiled Python files for `gui`
├───logs                # Directory for log files (generated at runtime)
└───utils               # Utility functions and helpers, such as configuration loading and logging
    └───__pycache__     # Compiled Python files for `utils`

### Configuration
The emulator relies on a `config.json` file that defines settings for the application, server, and clients:
- **Application Configuration**: General settings for the emulator.
- **Consumer Configuration**: Specifies TCP and UDP ports and buffer size for the server.
- **Producers Configuration**: Defines each client’s settings, such as tag, packet intervals, client-specific configurations, and QoS.

### Running the Emulator

#### Graphical Interface (GUI Mode)
1. Ensure that `config.json` is in the same directory as the emulator.
2. Run the emulator in GUI mode (default) without any arguments:
    ```bash
    python cip_emulator.py
    ```
3. In the GUI, you can:
   - Start and stop the server (Consumer).
   - Start and stop multiple clients (Producers).
   - View real-time logs in individual windows for the server and each client.
   - Edit configurations and save changes to `config.json`.

#### Command-Line Interface (CLI Mode)
Run the emulator in headless mode using the following arguments:

- **Run Without GUI**: Starts in headless mode.
    ```bash
    python cip_emulator.py --no-gui
    ```

- **Run Server Only**:
    ```bash
    python cip_emulator.py --no-gui --server-only
    ```

- **Run Clients Only**:
    ```bash
    python cip_emulator.py --no-gui --client-only
    ```

- **Run Both Server and Clients**:
    ```bash
    python cip_emulator.py --no-gui --both
    ```

- **Show Configuration**: Displays the current configuration without starting the emulator.
    ```bash
    python cip_emulator.py --show-config
    ```

### Logging and Output
Logs are generated for:
- **Server (Consumer)**: Tracks connections, packet receptions, and any packet loss or errors.
- **Clients (Producers)**: Logs each sent packet, including sequence numbers and timestamps. Errors and missed packets are logged as well.

#### GUI Mode
Logs are displayed in individual windows for each client and the server, with color-coding for error messages.

#### CLI Mode
Logs output directly to the terminal with ANSI color coding (if supported) for readability.

### Future Enhancements
Future improvements may include:
- Support for additional CIP features or more complex traffic simulations.
- Enhanced configuration for granular packet control and error simulation.
- Reporting tools for detailed network performance analysis under simulated CIP load.

--- 

This README provides an overview, functionality details, and usage instructions, making it easy to get started with the CIP Emulator.