|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Cpppo (Communication Protocol Python Parser and Originator) is a Python library for implementing binary communications protocol parsers using deterministic finite automata. The project primarily focuses on EtherNet/IP CIP (Common Industrial Protocol) communication with industrial controllers like Rockwell ControlLogix systems, along with Modbus/TCP support for PLC communication. |
| 8 | + |
| 9 | +## Build System and Common Commands |
| 10 | + |
| 11 | +This project uses a GNUmakefile build system with Python setuptools. The main Python interpreter targets are Python 2.7 and Python 3.x. |
| 12 | + |
| 13 | +### Core Development Commands |
| 14 | + |
| 15 | +- `make test` - Run all unit tests (pytest-based) |
| 16 | +- `make test-<pattern>` - Run specific tests matching pattern (e.g., `make test-enip`) |
| 17 | +- `make unit-<pattern>` - Run specific unit tests by keyword (e.g., `make unit-client`) |
| 18 | +- `make analyze` - Run flake8 linting on the codebase |
| 19 | +- `make pylint` - Run pylint static analysis |
| 20 | +- `make build` - Build wheel package |
| 21 | +- `make install` - Install the package with all dependencies |
| 22 | +- `make clean` - Remove build artifacts |
| 23 | + |
| 24 | +### Testing Configuration |
| 25 | + |
| 26 | +- Uses pytest with configuration in `pytest.ini` |
| 27 | +- Tests assume `TZ=Canada/Mountain` timezone |
| 28 | +- To run tests with serial support: `make SERIAL_TEST=1 test` |
| 29 | +- Single test files can be run with: `python -m pytest <test_file.py>` |
| 30 | + |
| 31 | +### Package Management |
| 32 | + |
| 33 | +- `make install-dev` - Install development dependencies |
| 34 | +- `make install-tests` - Install test dependencies |
| 35 | +- `make venv` - Create and activate virtual environment |
| 36 | +- `pip install cpppo[all]` - Install with all optional dependencies |
| 37 | + |
| 38 | +### Optional Dependencies |
| 39 | + |
| 40 | +The project has several optional dependency groups: |
| 41 | +- `[modbus]` - Modbus TCP/RTU support via pymodbus |
| 42 | +- `[logix]` - Alternative Logix I/O via pylogix |
| 43 | +- `[serial]` - Serial communication support |
| 44 | +- `[dev]` - Development tools |
| 45 | +- `[timestamp]` - Timestamp handling |
| 46 | +- `[all]` - All optional dependencies |
| 47 | + |
| 48 | +## Architecture |
| 49 | + |
| 50 | +### Core Components |
| 51 | + |
| 52 | +1. **automata.py** - Deterministic finite automata implementation using greenery library |
| 53 | +2. **server/enip/** - EtherNet/IP CIP protocol implementation |
| 54 | + - `main.py` - EtherNet/IP server entry point |
| 55 | + - `client.py` - EtherNet/IP client implementation |
| 56 | + - `parser.py` - Protocol message parsing |
| 57 | + - `device.py` - Device simulation capabilities |
| 58 | + - `logix.py` - Rockwell Logix-specific functionality |
| 59 | +3. **remote/** - Remote PLC communication utilities |
| 60 | + - `plc.py` - Generic PLC communication |
| 61 | + - `plc_modbus.py` - Modbus-specific PLC communication |
| 62 | +4. **history/** - Historical data management |
| 63 | +5. **tools/** - Utility modules |
| 64 | + |
| 65 | +### Key Entry Points |
| 66 | + |
| 67 | +- `python -m cpppo.server.enip` - Start EtherNet/IP server |
| 68 | +- `enip_server` - Console script for EtherNet/IP server |
| 69 | +- `enip_client` - Console script for EtherNet/IP client |
| 70 | +- `enip_get_attribute` - Console script for attribute reading |
| 71 | +- `modbus_sim` - Modbus simulator (Python 2 only) |
| 72 | +- `modbus_poll` - Modbus polling utility (Python 2 only) |
| 73 | + |
| 74 | +### Protocol Support |
| 75 | + |
| 76 | +- **EtherNet/IP CIP**: Industrial Ethernet protocol for communication with PLCs |
| 77 | +- **Modbus/TCP**: Serial communication protocol for industrial devices |
| 78 | +- **Support for Rockwell ControlLogix, MicroLogix controllers** |
| 79 | + |
| 80 | +## Development Workflow |
| 81 | + |
| 82 | +1. Clone repository: `git clone [email protected]:pjkundert/cpppo.git` |
| 83 | +2. Install dependencies: `make install install-dev install-tests` |
| 84 | +3. Run tests: `make test` |
| 85 | +4. Make changes and test: `make test-<relevant_pattern>` |
| 86 | +5. Run linting: `make analyze` |
| 87 | +6. Build package: `make build` |
| 88 | + |
| 89 | +## Testing |
| 90 | + |
| 91 | +- Tests use pytest framework |
| 92 | +- All test files follow `*_test.py` naming convention |
| 93 | +- Test configuration in `pytest.ini` includes custom logging format |
| 94 | +- Tests can be run individually or by pattern matching |
| 95 | +- Some tests require specific timezone settings (Canada/Mountain) |
| 96 | + |
| 97 | +## Configuration |
| 98 | + |
| 99 | +- EtherNet/IP server configurations in `*.cfg` files |
| 100 | +- Default configurations in `server/enip/defaults.py` |
| 101 | +- Pytest configuration in `pytest.ini` |
| 102 | +- Package metadata in `setup.py` |
| 103 | + |
| 104 | +## Virtual Environment Support |
| 105 | + |
| 106 | +The project includes Nix shell support (`shell.nix`, `default.nix`) and traditional Python virtual environments. Use `make venv` to create a complete development environment. |
| 107 | + |
| 108 | +## Docker and Virtualization |
| 109 | + |
| 110 | +Docker configurations are available in the `docker/` directory with various container setups for different deployment scenarios. |
0 commit comments