### LibrePCB Library File Structure Examples

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-format-specification.md

Concrete examples of the file organization for device and package category libraries.

```text
dev/77982dbc-3e3f-45c2-a7e9-bff5b95a56fd/.librepcb-dev
dev/77982dbc-3e3f-45c2-a7e9-bff5b95a56fd/device.lp
pkgcat/ea8e29c6-3436-403c-b640-598d1bf836de/.librepcb-pkgcat
pkgcat/ea8e29c6-3436-403c-b640-598d1bf836de/package_category.lp
```

--------------------------------

### Example Package Category Directory: Vishay

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-structure.md

An example of a package category directory for Vishay components, including the UUID and file names.

```text
pkgcat/
└── ea8e29c6-3436-403c-b640-598d1bf836de/
    ├── .librepcb-pkgcat           # Contains: 2
    └── package_category.lp        # Vishay category definition
```

--------------------------------

### Example Device Directory: BYG21

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-structure.md

A concrete example of a device directory structure for the BYG21 rectifier, showing the UUID and file names.

```text
dev/
└── 77982dbc-3e3f-45c2-a7e9-bff5b95a56fd/
    ├── .librepcb-dev              # Contains: 2
    └── device.lp                  # BYG21 device definition
```

--------------------------------

### Type Inference Examples

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/types-and-attributes.md

Demonstrates how specifying type and unit allows design tools to infer capabilities for voltage and current.

```text
Type: voltage, Unit: volt
  → Can calculate voltage derating
  → Can validate circuit voltage limits
  → Can suggest safety margins

Type: current, Unit: ampere
  → Can calculate PCB trace width requirement
  → Can validate circuit current capacity
  → Can suggest thermal dissipation
```

--------------------------------

### Schematic Netlist Example

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/integration-guide.md

Shows a schematic netlist for a boost rectifier design, detailing component designators, connections, and basic properties.

```text
D1: BYG21K-E3/TR
  Anode: BOOST_OUT (from boost converter)
  Cathode: HV_OUT (+800V rail)

R_LOAD: 1kΩ
  P1: HV_OUT
  P2: GND

C_OUT: 10μF/1000V
  P+: HV_OUT
  P-: GND

```

--------------------------------

### LibrePCB Project Structure Example

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/integration-guide.md

Illustrates the typical directory structure for a LibrePCB project, including schematic, board, library cache, and external dependencies like the Vishay library.

```text
MyProject.lppx
├── schematic/
│   └── my_circuit.lp
├── board/
│   └── my_board.lp
└── library-cache/
    └── (cached copies of referenced component definitions)

External Dependencies:
├── Vishay.lplib/
│   ├── library.lp
│   ├── dev/77982dbc-3e3f-45c2-a7e9-bff5b95a56fd/
│   └── pkgcat/ea8e29c6-3436-403c-b640-598d1bf836de/
│
└── [Parent Library]
    ├── components/ (schematic symbols)
    ├── packages/   (PCB footprints)
    └── categories/

```

--------------------------------

### Attribute System Example

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/DELIVERABLES.txt

Shows how attributes are defined and used within a LibrePCB library. Attributes represent component properties like voltage, current, and qualification.

```yaml
attributes:
  - name: "REVERSE_VOLTAGE"
    type: "voltage"
    unit: "V"
    description: "Maximum repetitive reverse voltage."
  - name: "FORWARD_CURRENT"
    type: "current"
    unit: "A"
    description: "Average forward current."
  - name: "QUALIFICATION"
    type: "string"
    description: "Component qualification level (e.g., Automotive, Industrial)."
  - name: "PACKING"
    type: "string"
    description: "Packaging type (e.g., Tape & Reel, Bulk Tape)."

```

--------------------------------

### Timestamp Format Example

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-format-specification.md

Shows the required ISO 8601 UTC format for all timestamp values within LibrePCB library files.

```text
2023-01-03T08:07:04Z
```

--------------------------------

### LibrePCB Git Workflow Example

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-structure.md

Demonstrates common Git operations for interacting with a LibrePCB library repository, including cloning, navigating, viewing history, and checking out specific versions.

```bash
git clone https://github.com/LibrePCB-Libraries/Vishay.lplib
cd Vishay.lplib
git log --oneline  # View version history
git tag -l         # View released versions
git checkout v0.1.1  # Checkout specific version
```

--------------------------------

### LibrePCB Library File Structure Example

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-format-specification.md

Illustrates the expected directory and file naming convention for LibrePCB library elements, including version marker files and data files.

```text
/<uuid>/.librepcb-<object_type>
/<uuid>/<object_type>.lp
```

--------------------------------

### String Attribute Example (Packing)

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/types-and-attributes.md

Another example of a string attribute, used here to specify packing details. This demonstrates the flexibility of the string type for various textual specifications.

```scheme
(attribute "PACKING" (type string) (unit none) (value "T&R 1800"))
```

--------------------------------

### Cloning a Library Repository

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-metadata.md

Users can clone a library repository using Git. Ensure you have Git installed and configured.

```bash
git clone https://github.com/LibrePCB-Libraries/Vishay.lplib
```

--------------------------------

### Library Metadata Example

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/DELIVERABLES.txt

Specifies the metadata for a LibrePCB library, including its unique identifier, version, author, and dependencies. This information is crucial for library management and dependency resolution.

```yaml
library:
  uuid: "f0e1d2c3-b4a5-6789-0123-456789abcdef"
  version: "1.0.0"
  name: "vishay.lplib"
  author: "Example Author"
  description: "Library for Vishay BYG21 diodes."
  dependencies:
    - uuid: "a1b2c3d4-e5f6-7890-1234-567890abcdef"
      version: "1.0.0"

```

--------------------------------

### Bill of Materials (BOM) Example

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/integration-guide.md

A sample Bill of Materials (BOM) for a component in the design, including part number, manufacturer, quantity, and electrical specifications.

```text
Part Number: BYG21K-E3/TR
Manufacturer: Vishay
Quantity: 1
Designator: D1
Package: SMA
Reverse Voltage: 800V
Forward Current: 1.5A
Reel: T&R 1800

```

--------------------------------

### UUID Format Example

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-format-specification.md

Illustrates the standard RFC 4122 format for universally unique identifiers (UUIDs) used in LibrePCB.

```text
c09d3949-d9b4-475a-a563-e3c56807a02b
```

--------------------------------

### String Escaping Example

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-format-specification.md

Demonstrates how to escape double quotes within a string literal in the LibrePCB format.

```Lisp
"This is a \"quoted\" string"
```

--------------------------------

### String Attribute Example

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/types-and-attributes.md

Example of defining a string attribute for categorical data or descriptions. This can be used for qualification or packing information.

```scheme
(attribute "QUALIFICATION" (type string) (unit none) (value "AEC-Q101"))
```

--------------------------------

### Run LibrePCB CLI Validation with Docker

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/ci-cd-pipeline.md

Installs and runs the LibrePCB CLI using Docker to validate a library. Mounts the current directory to the container for access.

```bash
# Install LibrePCB CLI (if not already installed)
docker pull librepcb/librepcb-cli:2.0.0-rc1

# Run validation in repository directory
docker run --rm -v $(pwd):/lib librepcb/librepcb-cli:2.0.0-rc1 \
  librepcb-cli open-library --all --strict --check --minify-step /lib
```

--------------------------------

### Current Attribute Example

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/types-and-attributes.md

Example of defining a current attribute, such as the forward current for a diode. This specifies the device's current handling capability.

```scheme
(attribute "FORWARD_CURRENT" (type current) (unit ampere) (value "1.5"))
```

--------------------------------

### LibrePCB CLI Validation Success Output

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/ci-cd-pipeline.md

Example of a successful library validation run using the LibrePCB CLI. Indicates that all checks passed and the pipeline can continue.

```bash
librepcb-cli version: 2.0.0-rc1
Validating library at: ./ 
Checking library.lp ... OK
Checking device: BYG21 (77982dbc-3e3f-45c2-a7e9-bff5b95a56fd) ... OK
  - Part BYG21K-E3/TR ... OK
  - Part BYG21K-E3/TR3 ... OK
  [... 14 more variants ...]
Checking category: Vishay (ea8e29c6-3436-403c-b640-598d1bf836de) ... OK

All checks passed!
```

--------------------------------

### Device Definition Format Example

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/DELIVERABLES.txt

Illustrates the basic structure of a device definition in LibrePCB, including metadata, attributes, and part variants. This format is used to define electronic components within a library.

```yaml
device:
  uuid: "a1b2c3d4-e5f6-7890-1234-567890abcdef"
  name: "BYG21"
  description: "Vishay BYG21 Avalanche Rectifier Diode"
  attributes:
    - name: "REVERSE_VOLTAGE"
      type: "voltage"
      unit: "V"
    - name: "FORWARD_CURRENT"
      type: "current"
      unit: "A"
    - name: "QUALIFICATION"
      type: "string"
    - name: "PACKING"
      type: "string"
  variants:
    - name: "BYG21-TR"
      description: "BYG21 in Tape & Reel packaging"
      attributes:
        REVERSE_VOLTAGE: "1000V"
        FORWARD_CURRENT: "2A"
        QUALIFICATION: "Automotive"
        PACKING: "Tape & Reel"
    - name: "BYG21-TAP"
      description: "BYG21 in Bulk Tape packaging"
      attributes:
        REVERSE_VOLTAGE: "1000V"
        FORWARD_CURRENT: "2A"
        QUALIFICATION: "Industrial"
        PACKING: "Bulk Tape"

```

--------------------------------

### GitHub Actions CI/CD Pipeline Overview

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/DELIVERABLES.txt

This snippet outlines the typical steps in a GitHub Actions pipeline for validating a LibrePCB library. It includes environment setup, validation commands, and handling of success/failure.

```yaml
name: LibrePCB Library CI


on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Setup LibrePCB CLI
        uses: ./actions/setup-librepcb-cli # Assuming a custom action or manual setup
        with:
          version: '1.0.0' # Specify the desired LibrePCB CLI version

      - name: Validate Library
        run: | 
          librepcb-cli validate --all --strict --check --minify-step --library-path .

      - name: Upload Validation Artifacts (Optional)
        if: failure()
        uses: actions/upload-artifact@v3
        with:
          name: validation-logs
          path: validation.log # Assuming validation output is saved to validation.log

```

--------------------------------

### Run LibrePCB CLI Validation Directly

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/ci-cd-pipeline.md

Executes the LibrePCB CLI directly on the local machine for library validation. Assumes the CLI is installed and in the PATH.

```bash
cd /path/to/vishay.lplib
librepcb-cli open-library --all --strict --check --minify-step .
```

--------------------------------

### Part Variant Specifications Example

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/DELIVERABLES.txt

Defines different part number variants for a device, specifying unique attribute values for each variant. This allows for multiple configurations of the same base device.

```yaml
variants:
  - name: "BYG21-1000-2A-IND-TR"
    description: "BYG21, 1000V, 2A, Industrial, Tape & Reel"
    attributes:
      REVERSE_VOLTAGE: "1000V"
      FORWARD_CURRENT: "2A"
      QUALIFICATION: "Industrial"
      PACKING: "Tape & Reel"
  - name: "BYG21-1000-2A-AUTO-BULK"
    description: "BYG21, 1000V, 2A, Automotive, Bulk"
    attributes:
      REVERSE_VOLTAGE: "1000V"
      FORWARD_CURRENT: "2A"
      QUALIFICATION: "Automotive"
      PACKING: "Bulk"

```

--------------------------------

### Example BYG21 Part Number Decoding

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/device-part-variants.md

Demonstrates how to interpret the components of a specific BYG21 part number, breaking down each segment according to the defined naming convention.

```text
BYG21KHM3_A/H
- BYG21 — Avalanche rectifier diode base part
- K — 800V reverse voltage variant
- H — AEC-Q101 automotive qualified
- M3 — Halogen-free lead material
- _A — Specific variant assignment
- /H — Tape and reel with 1800 unit quantity
```

--------------------------------

### Attribute Example in BOM Generation

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/types-and-attributes.md

Illustrates how component attributes are displayed when a design is exported to a Bill of Materials (BOM). This format is used for part identification and sourcing.

```text
Designator: D1
Part Number: BYG21K-E3/TR
Manufacturer: Vishay
Attributes:
  REVERSE_VOLTAGE: 800V
  FORWARD_CURRENT: 1.5A
  PACKING: T&R 1800
```

--------------------------------

### LibrePCB CLI Validation Failure Output (Syntax Error)

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/ci-cd-pipeline.md

Example of a library validation failure due to a syntax error reported by the LibrePCB CLI. This will stop the pipeline.

```bash
librepcb-cli version: 2.0.0-rc1
Validating library at: ./ 
Checking library.lp ... ERROR
  Parse error at line 4: Unexpected token ')'
  Expected property name or closing parenthesis

Validation failed!
```

--------------------------------

### Voltage Attribute Example

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/types-and-attributes.md

Example of defining a voltage attribute, specifically the reverse voltage for a diode. This is used to document electrical ratings.

```scheme
(attribute "REVERSE_VOLTAGE" (type voltage) (unit volt) (value "800"))
```

--------------------------------

### Library Architecture Overview

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/README.md

Illustrates the modular structure of the Vishay library within the LibrePCB framework, showing how device definitions, package categories, and dependencies are organized.

```text
Vishay Library
├── Device Definition (BYG21)
│   ├── Component Reference → Symbol from parent library
│   ├── Package Reference → Footprint from parent library
│   ├── Category Reference → Package organization
│   └── 16 Part Variants → Electrical attributes
│
├── Package Category → Hierarchy for organization
└── Dependency → Parent library for symbols/footprints
```

--------------------------------

### Root Library Definition (library.lp)

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-metadata.md

This Lisp-like syntax defines the core metadata for the Vishay library, including its name, description, author, version, and a dependency.

```lisp
(librepcb_library c09d3949-d9b4-475a-a563-e3c56807a02b
 (name "Vishay")
 (description "Semiconductors from Vishay (unofficial).")
 (keywords "")
 (author "LibrePCB")
 (version "0.1.1")
 (created 2023-01-03T08:07:04Z)
 (deprecated false)
 (url "https://github.com/LibrePCB-Libraries/Vishay.lplib")
 (dependency a9ddf0c6-9b1c-4730-b300-01b4f192ad40)
 (manufacturer "Vishay")
)
```

--------------------------------

### LibrePCB Data Flow for Device Integration

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/integration-guide.md

Explains the data flow for integrating a device definition in LibrePCB, showing how component, package, and signal UUIDs are resolved from dependency libraries.

```text
Device Definition (device.lp)
  ├─ Component UUID → [Loaded from dependency library]
  │                    └─ Schematic Symbol & Electrical Properties
  ├─ Package UUID  → [Loaded from dependency library]
  │                  └─ PCB Footprint & Pad Coordinates
  └─ Signals     → [Mapped to schematic pins and PCB pads]
```

--------------------------------

### Library Version Format

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-format-specification.md

Illustrates the semantic versioning format (MAJOR.MINOR.PATCH) used for library versions.

```Plain Text
0.1.1  →  MAJOR=0, MINOR=1, PATCH=1
```

--------------------------------

### LibrePCB Component System Hierarchy

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/integration-guide.md

Illustrates the hierarchical structure of a LibrePCB project, from schematic and PCB editors to device, component, package, and signal definitions.

```text
LibrePCB Project
  └── Schematic Editor
        ├── Component Placement (from device definitions)
        │   ├── Device → Component Reference → Schematic Symbol
        │   └── Device → Package Reference → Footprint
        └── Electrical Connectivity
              └── Device Signals → PCB Pad Mapping
  
  └── PCB Layout Editor
        ├── Footprint Placement (from package definitions)
        ├── Pad Management (from component signals)
        └── Design Rule Checking (DRC)
```

--------------------------------

### Device Subdirectory Structure

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-structure.md

Illustrates the expected file and subdirectory layout within a device definition directory. Each device is identified by a UUID.

```text
dev/
└── <device_uuid>/
    ├── .librepcb-dev              # Format version marker
    └── device.lp                  # Device definition file
```

--------------------------------

### Root Library Definition Structure

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-format-specification.md

Specifies the structure for the root library definition in a .lp file, including essential metadata like name, description, version, and author.

```lisp
(librepcb_library <uuid>
 (name "<library_name>")
 (description "<description>")
 (keywords "<keywords>")
 (author "<author>")
 (version "<version>")
 (created <iso_timestamp>Z)
 (deprecated <boolean>)
 (url "<url>")
 (dependency <parent_uuid>)
 (manufacturer "<manufacturer>")
)
```

--------------------------------

### Qualification Variant Selection for BYG21

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/integration-guide.md

Matrix for selecting BYG21 variants based on application qualification needs, such as automotive (AEC-Q101) and environmental compliance (halogen-free). Guides selection for specific industry standards.

```text
Choose Qualification Level:
  ├─ Automotive application?
  │   YES → H flag required (AEC-Q101)
  │   NO  → Can use standard
  │
  └─ Environmental compliance?
      ├─ Halogen-free required?
      │   YES → M3 lead material
      │   NO  → E3 is acceptable
      │
      └─ Combine requirements:
         - Automotive + Standard → KHE3_A or MHE3_A
         - Automotive + Halogen  → KHM3_A or MHM3_A
         - Standard + Standard   → K-E3 or M-E3
         - Standard + Halogen    → K-M3 or M-M3
```

--------------------------------

### LibrePCB Device Definition Structure

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-format-specification.md

This is the main structure for a LibrePCB device definition file. It includes essential metadata and references to component and package definitions.

```lisp
(librepcb_device <uuid>
 (name "<device_name>")
 (description "<description>")
 (keywords "<keywords>")
 (author "<author>")
 (version "<version>")
 (created <iso_timestamp>Z)
 (deprecated <boolean>)
 (generated_by "<source>")
 (category <uuid>)
 (component <uuid>)
 (package <uuid>)
 (pad <pad_uuid> (optional <boolean>)
  (signal <signal_uuid>)
 )
 (part "<part_number>" (manufacturer "<manufacturer>")
  (attribute "<attr_name>" (type <attr_type>) (unit <unit>) (value "<value>"))
 )
)
```

--------------------------------

### Volume Variant Selection for BYG21

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/integration-guide.md

Guide for selecting BYG21 reel packaging based on annual volume requirements. Differentiates between standard reels (/TR) and bulk reels (/TR3) for pricing and supply chain efficiency.

```text
Choose Reel Quantity:
  ├─ Annual volume < 10,000 units?
  │   YES → /TR (1800 unit reel) - standard
  │
  └─ Annual volume > 10,000 units?
      YES → /TR3 (7500 unit reel) - bulk pricing
```

--------------------------------

### Part Variant Structure in device.lp

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-structure.md

Defines the structure for specifying part variants within a `device.lp` file, including attributes.

```lisp
(part "<part_number>" (manufacturer "<manufacturer>")
 (attribute "<attr_name>" (type <type>) (unit <unit>) (value "<value>"))
)
```

--------------------------------

### Declaring Multiple Dependencies

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-metadata.md

This format allows for declaring multiple library dependencies using their UUIDs. Each dependency is listed on a new line within parentheses.

```lisp
(dependency a9ddf0c6-9b1c-4730-b300-01b4f192ad40)
(dependency <uuid-2>)
(dependency <uuid-3>)
```

--------------------------------

### LibrePCB Library File Structure

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-format-specification.md

Defines the general S-expression syntax for LibrePCB .lp files, including the root object type, UUID, properties, and nested structures.

```lisp
(librepcb_<object_type> <uuid>
 (property_name "value")
 (nested_structure_name
  (inner_property "value")
 )
)
```

--------------------------------

### Git Binary Safety Configuration

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-metadata.md

This file configures Git to treat all library files as binary, preventing automatic line-ending conversions that could corrupt structured data files like those used by LibrePCB.

```gitattributes
* -text
```

--------------------------------

### CI/CD Pipeline Configuration

Source: https://github.com/librepcb-libraries/vishay.lplib/blob/master/_autodocs/library-structure.md

Defines the automated validation process for the library using librepcb-cli. It runs on every push or pull request to ensure library integrity.

```yaml
container:
  image: librepcb/librepcb-cli:2.0.0-rc1
  options: --entrypoint /bin/bash
  
commands:
  librepcb-cli open-library --all --strict --check --minify-step .
```