Virtual-IED Documentation

Overview

Comprehensive documentation for the Virtual-IED (Intelligent Electronic Device) protection relay system implementing IEC 61850 standards with real-time performance guarantees.

Documentation Structure

1. ARCHITECTURE.md

System Architecture & Component Design

• High-level system architecture diagrams
• Component breakdown (Network, Measurement, Protection, RT layers)
• Data flow diagrams
• Threading model
• Memory layout and protection
• Latency budget analysis
• Platform support matrix

Audience: System architects, senior developers

2. DEPLOYMENT.md

Production Deployment Guide

• Hardware and software requirements
• PREEMPT_RT kernel installation
• Network interface configuration
• Systemd service setup
• Performance tuning
• Troubleshooting guide
• Security hardening

3. API.md

API Reference Documentation

• Core utilities (logger, protocol helpers, DSP, RT)
• Protection algorithms API
• Configuration structures
• Error codes and exceptions
• Best practices and examples

4. TESTING.md

Testing Guide

• Test infrastructure (sanitizers, presets)
• Integration test suite
• Platform-specific testing
• Performance benchmarks
• CI/CD workflows
• Debugging procedures

Quick Start

For Developers

# Clone repository
git clone https://github.com/Alailton-jr/Virtual-IED.git
cd Virtual-IED

# Build with tests
cmake --preset asan
cmake --build build/asan --parallel
./build/asan/integration_test

# Read architecture
less docs/ARCHITECTURE.md

# Read API reference
less docs/API.md

For Operators

# Read deployment guide
less docs/DEPLOYMENT.md

# Install prerequisites
sudo apt install linux-image-realtime

# Deploy system
sudo ./deploy.sh

# Monitor
sudo journalctl -u virtual-ied -f

Document Overview

Document	Purpose	Pages
ARCHITECTURE.md	System design	~35
DEPLOYMENT.md	Installation & ops	~40
API.md	Code reference	~50
TESTING.md	Test procedures	~25
README-RT.md	Linux RT configuration	~10
README-macOS.md	macOS workflow	~5

Total: ~150 pages of comprehensive documentation

Additional Resources

Source Code Documentation

• In-code comments and doxygen annotations
• Header file documentation (src/tools/include/*.hpp)
• Example configurations (src/files/ied_config*.json)
  • Include the optional Network block for per-interface overrides
  • Runtime also respects VIED_IF_PROCESS, VIED_IF_STATION, VIED_IF_GOOSE, VIED_IF_API and optional CPU affinity variables VIED_CPU_SNIFFER, VIED_CPU_GOOSE, VIED_CPU_PROTECTION

Standards References

• IEC 61850-9-2: Sampled Values protocol
• IEC 61850-8-1: GOOSE protocol
• IEC 60255: Protection relay characteristics
• IEEE 1588: Precision Time Protocol (PTP)

Documentation Philosophy

1. Accuracy

• All examples are tested and verified
• Platform-specific notes clearly marked
• Version information included

2. Completeness

• All public APIs documented
• Edge cases and error conditions covered
• Cross-references between documents

3. Accessibility

• Clear navigation structure
• Progressive disclosure (quick start → deep dive)
• Multiple audience perspectives

4. Maintainability

• Markdown format (version control friendly)
• Modular structure (easy to update sections)
• Consistent formatting and terminology

Contributing to Documentation

Style Guide

• Use Markdown for all documentation
• Include code examples for APIs
• Provide platform-specific notes where applicable
• Keep line length < 100 characters
• Use British English spelling

Review Process

1. Create feature branch
2. Update relevant documentation
3. Test code examples
4. Submit pull request
5. Technical review + editorial review

Version History

Version	Date	Changes
1.0.0	2025-10-18	Initial release (Phases 0-5)
		- Architecture documentation
		- Deployment guide
		- API reference
		- Testing procedures

Support

Documentation Issues: https://github.com/Alailton-jr/Virtual-IED/issues

Questions: docs@virtual-ied.com

Updates: Subscribe to documentation repo for notifications

---

Last Updated: October 18, 2025
Documentation Version: 1.0.0
Software Version: 1.0.0 (feat/hardening-rt-macos)