TSYSDevStack-SupportStack-Cloudron/Package-Workspace/Documentation-Tools/wireviz-web/README.md

# WireViz Web Cloudron Package

## Description

WireViz Web is a web wrapper around WireViz tool for documenting cables, wiring harnesses, and connector pinouts. It takes plain text, YAML-formatted files as input and produces beautiful graphical output (SVG, PNG, etc.).

## Features

### Core Capabilities
- **Wire Diagram Generation**: Create professional cable and wiring diagrams
- **YAML Input**: Human-readable YAML format for defining connectors, cables, and connections
- **Multiple Output Formats**: SVG, PNG, and other graphics formats
- **Automatic BOM**: Bill of Materials generation for components
- **Color Coding Support**: IEC 60757, DIN 47100, and 25-pair color codes
- **Wire Gauge Handling**: Support for mm² and AWG gauges
- **Connector Libraries**: Extensive connector type database
- **Web Interface**: REST API for programmatic access

### WireViz Features
- **Text-Based Input**: No special editor required, use any text editor
- **Version Control Friendly**: Plain YAML files work perfectly with Git
- **UTF-8 Support**: Handle special characters in labels and descriptions
- **Custom Color Schemes**: Standard and custom color schemes supported
- **Auto-Routing**: Automatic wire routing for 1-to-1 connections
- **Complex Harness Support**: Suitable for simple and complex wiring
- **Pinout Diagrams**: Document connector pinouts clearly
- **PlantUML Compatibility**: PlantUML Text Encoding format included

## Configuration

### Environment Variables

#### Application Configuration
- `FLASK_APP`: Flask application (default: wireviz_web)
- `PYTHONUNBUFFERED`: Disable Python output buffering (default: 1)

### Ports
- **3005**: Main HTTP port (web interface and API)

### Addons
- **Localstorage**: Used for storing uploaded diagrams and generated outputs

## Usage

### 1. Create Wiring Diagram via Web Interface

1. Open WireViz Web
2. Click "New Diagram"
3. Enter YAML configuration:
   ```yaml
   connectors:
     X1:
       type: D-Sub
       subtype: female
       pinlabels: [DCD, RX, TX, DTR, GND, DSR, RTS, CTS]
     X2:
       type: Molex KK 254
       subtype: female
       pinlabels: [GND, RX, TX]

   cables:
     W1:
       gauge: 0.25 mm2
       length: 0.2
       color_code: DIN
       wirecount: 3
       shield: true

   connections:
     - - X1: [5,2,3]
       - W1: [1,2,3]
       - X2: [1,3,2]
     - - X1: 5
       - W1: s
   ```
4. Click "Generate Diagram"
5. View SVG/PNG output
6. Download BOM (Bill of Materials)

### 2. Use REST API

Generate diagram programmatically:

```bash
# Create diagram via POST request
curl -X POST http://localhost:3005/render \
  -H "Content-Type: application/yaml" \
  --data-binary @diagram.yaml

# Get diagram in SVG format
curl -X POST http://localhost:3005/render \
  -H "Content-Type: application/yaml" \
  -H "Accept: image/svg+xml" \
  --data-binary @diagram.yaml \
  -o output.svg

# Get diagram in PNG format
curl -X POST http://localhost:3005/render \
  -H "Content-Type: application/yaml" \
  -H "Accept: image/png" \
  --data-binary @diagram.yaml \
  -o output.png

# Get BOM (Bill of Materials)
curl -X POST http://localhost:3005/render \
  -H "Content-Type: application/yaml" \
  -H "Accept: text/tab-separated-values" \
  --data-binary @diagram.yaml \
  -o bom.tsv
```

### 3. Color Coding Examples

**IEC 60757 Color Code:**
```yaml
cables:
  W1:
    color_code: IEC
    # Generates: BK, RD, OR, YE, GN, BU, VT, GY, WH, PK
```

**DIN 47100 Color Code:**
```yaml
cables:
  W1:
    color_code: DIN
    # Generates: WT/BN, GN/YE, OG/BK, etc.
```

**Custom Colors:**
```yaml
cables:
  W1:
    colors: ["#FF0000", "#00FF00", "#0000FF"]
    # Or use full names: ["red", "green", "blue"]
    # Or abbreviations: ["RD", "GN", "BU"]
```

### 4. Connector Examples

**D-Sub Connector:**
```yaml
connectors:
  X1:
    type: D-Sub
    subtype: female
    pinlabels: [DCD, RX-, RX+, TX-, TX+, GND, CEC]
```

**USB-C Connector:**
```yaml
connectors:
  X1:
    type: USB
    subtype: C
    pinlabels: [VBUS, CC1, CC2, D+, D-, SBU1, SBU2, GND]
```

**HDMI Connector:**
```yaml
connectors:
  X1:
    type: HDMI
    subtype: A
    pinlabels: [TMDS_D2+, TMDS_D2-, TMDS_D1+, TMDS_D1-, ...]
```

### 5. Cable Examples

**Multi-Conductor Cable:**
```yaml
cables:
  W1:
    gauge: 0.25 mm2
    length: 2.5
    color_code: IEC
    wirecount: 8
    shield: true
```

**Coaxial Cable:**
```yaml
cables:
  W1:
    gauge: 1.5 mm2
    length: 10.0
    colors: [BK]
    wirecount: 1
    shield: true
```

### 6. Complex Harness Example

```yaml
connectors:
  MAIN:
    type: Terminal_Block
    pinlabels: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
  DEVICE1:
    type: D-Sub
    subtype: female
    pinlabels: [DCD, RX, TX, GND]
  DEVICE2:
    type: USB
    subtype: A
    pinlabels: [VBUS, D+, D-, GND]

cables:
  MAIN_POWER:
    gauge: 1.5 mm2
    length: 5.0
    colors: [RD, BK]
    wirecount: 2
  MAIN_SIGNAL:
    gauge: 0.25 mm2
    length: 5.0
    color_code: IEC
    wirecount: 4
  DEVICE1_CABLE:
    gauge: 0.25 mm2
    length: 2.0
    color_code: DIN
    wirecount: 4
  DEVICE2_CABLE:
    gauge: 0.25 mm2
    length: 1.0
    color_code: IEC
    wirecount: 4

connections:
  - - MAIN: [1,2]
    - MAIN_POWER: [1,2]
  - - MAIN: [3,4,5,6]
    - MAIN_SIGNAL: [1,2,3,4]
  - - MAIN: [7,8,9,10]
    - DEVICE1_CABLE: [1,2,3,4]
    - DEVICE1: [5,2,3,4]
  - - MAIN: [7,8,9,10]
    - DEVICE2_CABLE: [1,2,3,4]
    - DEVICE2: [1,4,3,2]
```

## Architecture

```
                    ┌─────────────┐
                    │   Client    │
                    │  (YAML)     │
                    └──────┬──────┘
                           │
                    HTTP POST (YAML)
                           ▼
                   ┌──────────────┐
                   │ WireViz Web │
                   │  (Flask)     │
                   │  REST API    │
                   └──────┬──────┘
                           │
                           ▼
                   ┌──────────────┐
                   │   WireViz    │
                   │  (Python)    │
                   │   Parser     │
                   └──────┬──────┘
                           │
              ┌────────────┼────────────┐
              │            │            │
              ▼            ▼            ▼
       ┌──────────┐  ┌──────────┐  ┌──────────┐
       │   SVG    │  │   PNG    │  │   BOM    │
       │  Output  │  │  Output  │  │  Output  │
       └──────────┘  └──────────┘  └──────────┘
```

## WireViz YAML Format

### Basic Structure
```yaml
connectors:
  # Define connector pins
  CONNECTOR_NAME:
    type: CONNECTOR_TYPE
    subtype: SUBTYPE
    pinlabels: [PIN1, PIN2, ...]

cables:
  # Define cables
  CABLE_NAME:
    gauge: GAUGE
    length: LENGTH
    color_code: COLOR_SCHEME
    wirecount: NUMBER_OF_WIRES

connections:
  # Define connections between connectors and cables
  - - CONNECTOR: [PIN_NUMBERS]
    - CABLE: [WIRE_NUMBERS]
```

## Documentation

For more information on WireViz:
- [WireViz Documentation](https://github.com/wireviz/wireviz)
- [WireViz Web Repository](https://github.com/wireviz/wireviz-web)
- [WireViz Examples](https://github.com/wireviz/wireviz/tree/master/examples)
- [Connector Database](https://github.com/wireviz/wireviz/blob/master/lib/wireviz/data/connectors.yaml)

## Support

For issues and questions:
- [WireViz Web Issues](https://github.com/wireviz/wireviz-web/issues)
- [WireViz Issues](https://github.com/wireviz/wireviz/issues)

## Upstream

[GitHub Repository](https://github.com/wireviz/wireviz-web)
[WireViz Project](https://github.com/wireviz/wireviz)