Skill/references/description_format.md

# Description format (Vecmocon Altium Library SOP)

This is the authoritative rule for the **Description** field the skill writes into a part's
workbook. It has two layers:

1. The **four formats derived from the SOP** — Resistor, Capacitor, Zener, TVS — from
   *Engineering Data Management — SOP: Component Naming, Mandatory Parameters, and Design Item
   ID Format* (§6). Follow these **parameter orders** strictly. The **prefix**, however, is the
   house `Class_TYPEID` form (see below), which supersedes the SOP's own prefix tokens.
2. A **house extension** that carries the *same basis* to every other type in the library
   (all 125 type-IDs / 18 classes), so no component is left without a Description convention.
   These are built on the SOP pattern and are the working standard; when a specific part
   doesn't fit cleanly, follow the pattern and confirm the token order with the engineer rather
   than inventing something off-pattern.

## The basis (applies to every component)

The Description is **not** a free-form sentence. It is a single string of `_`-joined tokens in
this shape:

```
Class_TYPEID_param1_param2_..._Package_[AECQ-XXX]
```

- **Class_TYPEID** — the **mandatory opening two tokens** of every Description, always. This
  replaces the old technology prefixes (`CHIP_RES`, `ELE_CAP`, `TANT_CAP`, `NMOS`, …) — those
  are **retired and must not be used**. Examples: `Diode_TVS_…`, `Capacitor_TAN_…`,
  `Resistor_FIX_…`, `Transistor_MOS_…`.
  - **Class** — spelled exactly as the library-repo folder name, so a Description's first token
    always matches the folder the part lives in. Take it from `CLASS_FOLDER` in
    `scripts/common.py` (the authoritative map) — e.g. `Diode`, `Capacitor`, `Resistor`,
    `Transistor`, `IC`, `Protection`, `Inductor_Magnetics`, `Relay_Contactor`, `Switch_Button`,
    `Antenna_RF`, `Crystal_Oscillator`, `Battery_Cell`, `Audible_Indicator`, `Display_HMI`,
    `Sensor`, `Thermal_Cooling`, `Connector`. Mixed case as written — do **not** upper-case it.
    Note `Inductor_Magnetics` and friends already contain an `_`; that is expected and correct.
    The one Class whose folder name contains spaces, `Power Conversion Module`, is written
    `Power_Conversion_Module` in a Description.
  - **TYPEID** — the Type ID from `references/taxonomy.md`, **always upper-case**, exactly as
    the template sheet names it (`TVS`, `TAN`, `CER`, `FIX`, `MOS`, `SCH`, `LDO`, …). This is
    the same typeid used in the part tag `MPN_make_typeid`, so the three agree.
  - Get both from the taxonomy for the typeid you classified the part to in step 2 — never
    invent or abbreviate either token.
- **params** — the part's defining ratings, in the **fixed order** given for that class. Read
  them off the datasheet. If the datasheet is silent on a required token, leave it out and flag
  it — an honest gap beats a guessed value.
- **Package** — the IPC/industry package or case code, near the end (`0402`, `SOD-323`,
  `SOIC-8`, `LQFP-48`, `SMD,D6.3xL5.8mm`, …).
- **AECQ-XXX** — only when the datasheet states automotive qualification (`AECQ-200`,
  `AECQ-101`, `AECQ-100`); it is always the **last** token. Omit entirely if not stated —
  never assume qualification.

Description ≠ Design Item ID ≠ Comment — three different fields that share notation but not
content: **Description** is the strict string here (SOP §6); **Design Item ID** (SOP §2) is a
shorter procurement id (`RES_36kΩ_±0.1%_0402`) that keeps its **own** SOP notation and does
**not** take the `Class_TYPEID` prefix — use it only as a guide to token vocabulary,
never put it in the Description column; **Comment** (SOP §4) is always the exact MPN.

## Notation conventions (from the SOP examples)

- **Value / unit** with SOP casing: `36kΩ`, `2.2uF`, `600Ω`, `48MHz`, `10uH`. Use `Ω` for ohms;
  `uF`/`nF`/`pF`, `uH`/`nH`/`mH`, `Hz`/`kHz`/`MHz`, `F` for farads (supercaps). A **range** uses
  `~` (`3.5V~28V`, `5.2V~5.6V`).
- **Power** `62.2mW`, `500mW`, `344W`; **voltage** `100v`, `25V`; **current** `0.25A`, `250mA`.
- **Tolerance** signed percent `±0.1%`, `±10%`.
- **Temperature coefficient** (ceramics) lower-case dielectric class: `x7r`, `c0g`, `x5r`.
- Keep tokens in the same style throughout so descriptions sort and read consistently.

---

# Layer 1 — the four SOP-derived formats (parameter order is strict)

The **parameter orders** below are the SOP's and are not up for reinterpretation. The
**prefix** is the house `Class_TYPEID` form, which replaces the SOP §6 prefix tokens.

**Resistor**

```
Resistor_TYPEID_Value_Wattage_Tolerance_Package_AECQ-XXX(optional)
```

Example: `Resistor_FIX_36kΩ_62.2mW_±0.1%_0402`  (was `CHIP_RES_36kΩ_62.2mW_±0.1%_0402`)

**Capacitor**

```
Capacitor_TYPEID_Value_Voltage_Tolerance_Package_TemperatureCoefficient_AECQ-XXX(optional)
```

Example: `Capacitor_CER_2.2uF_100v_±10%_1210_x7r`  (was `CHIP_CAP_2.2uF_100v_±10%_1210_x7r`)

**Zener diode**

```
Diode_ZEN_VoltageZener(Vz)_Power_Package_AECQ-XXX(optional)
```

**TVS diode**

```
Diode_TVS_VoltageBreakdown(Vbr)_VoltageClamping(Vc)_Current(Ip)_Package_AECQ-XXX(optional)
```

**House prefix note:** SOP §6 wrote the diodes as `DIO-Z` / `DIO-T` and the R/C formats with
technology prefixes (`CHIP_RES`, `CHIP_CAP`). Vecmocon has standardised on `Class_TYPEID` for
**every** component, so all four of these now open with `Resistor_` / `Capacitor_` / `Diode_`
plus the typeid. This is a deliberate house override of SOP §6's prefix; the parameter order
(Vz+Power for Zener; Vbr+Vc+Ip for TVS; etc.) remains exactly the SOP's.

---

# Layer 2 — house extension, every other type (same basis)

Each class below gives its **parameter order** (the tokens between prefix and package) and the
**per-type prefix**. Package is always the second-to-last token; optional `AECQ-XXX` is last.

## Resistor  (RES family) — `Resistor_TYPEID_Value_Power_Tolerance_Package_[AECQ]`

| Type | Prefix | Notes |
|------|--------|-------|
| FIX Thick-film chip| `Resistor_FIX` | SOP example; the strict format above |
| TFR Thin-film chip| `Resistor_TFR` | precision/low-tempco; may append tempco (ppm) |
| MFR Metal-film| `Resistor_MFR` | |
| CFR Carbon-film| `Resistor_CFR` | |
| MOR Metal-oxide| `Resistor_MOR` | high-power leaded |
| WWR Wirewound| `Resistor_WWR` | low-ohm/high-power |
| SHT Current-sense/shunt| `Resistor_SHT` | value in mΩ (e.g. `2mΩ`), power token is the sense power |
| ARR Array/network| `Resistor_ARR` | add element count/config, e.g. `4x`, before value |
| POT Potentiometer/trimmer| `Resistor_POT` | `Resistor_POT_Value_Taper_Power_Package` (taper `LIN`/`LOG`) |
| FSR Fusible/safety| `Resistor_FSR` | |
| NTC thermistor| `Resistor_NTC` | `Resistor_NTC_R25_Beta_Tolerance_Package` (R25 e.g. `10kΩ`, Beta e.g. `B3950`) |
| PTC thermistor| `Resistor_PTC` | `Resistor_PTC_R25_Package` (or trip current/temp if that's the rated spec) |

Example: `Resistor_SHT_2mΩ_1W_±1%_2512` · `Resistor_NTC_10kΩ_B3950_±1%_0402`

## Capacitor  (CAP family) — `Capacitor_TYPEID_Value_Voltage_Tolerance_Package_[Dielectric]_[AECQ]`

| Type | Prefix | Notes |
|------|--------|-------|
| CER Ceramic MLCC| `Capacitor_CER` | SOP; dielectric token (`x7r`/`c0g`…) required |
| ELE Aluminium electrolytic| `Capacitor_ELE` | tolerance often omitted; case like `SMD,D6.3xL5.8mm` |
| TAN Tantalum| `Capacitor_TAN` | |
| PLY Aluminium-polymer| `Capacitor_PLY` | low-ESR; ESR may follow voltage |
| FLM Film (MKT/MKP)| `Capacitor_FLM` | |
| SFY Safety Class-X/Y| `Capacitor_SFY` | add safety class token (`X2`/`Y1`) after value |
| SUP Supercapacitor/EDLC| `Capacitor_SUP` | value in farads, e.g. `1F`; add ESR if rated |

Example: `Capacitor_ELE_33uF_25V_SMD,D6.3xL5.8mm` · `Capacitor_SUP_1F_5.5V_RADIAL`

## Inductor / Magnetics — `Inductor_Magnetics_TYPEID_Value_Current_[DCR]_Package_[AECQ]`

| Type | Prefix | Format detail |
|------|--------|---------------|
| PWR Power inductor| `Inductor_Magnetics_PWR` | `Inductor_Magnetics_PWR_L_Isat_DCR_Package` (L e.g. `10uH`, Isat `3A`) |
| FBD Ferrite bead| `Inductor_Magnetics_FBD` | `Inductor_Magnetics_FBD_Impedance@freq_Current_Package` (e.g. `Inductor_Magnetics_FBD_600Ω@100MHz_2A_0603`) |
| CMC Common-mode choke| `Inductor_Magnetics_CMC` | `Inductor_Magnetics_CMC_Impedance@freq_Current_Package` |
| RFI RFI choke| `Inductor_Magnetics_RFI` | `Inductor_Magnetics_RFI_L_Current_Package` |
| XFM Transformer| `Inductor_Magnetics_XFM` | `Inductor_Magnetics_XFM_Ratio_Power_Package` (ratio e.g. `1:1`) |
| CTX Current transformer| `Inductor_Magnetics_CTX` | `Inductor_Magnetics_CTX_Ratio_Package` (e.g. `1000:1`) |
| CPL Coupled inductor| `Inductor_Magnetics_CPL` | `Inductor_Magnetics_CPL_L_Current_Package` |

## Diode — reverse-voltage / current ratings, then package

The prefix is the **generic diode type code (the typeid itself)** — `REC`, `FRD`, `SCH`, `SIC`,
`ZEN`, `TVS`, `ESD`, `SWI`, `BRG`, `LED` — not a `DIO-x` form.

| Type | Prefix | Format |
|------|--------|--------|
| REC Rectifier| `Diode_REC` | `Diode_REC_Vrrm_Io_Package` |
| FRD Fast-recovery| `Diode_FRD` | `Diode_FRD_Vrrm_Io_trr_Package` |
| SCH Schottky| `Diode_SCH` | `Diode_SCH_Vr_Io_Package` |
| SIC SiC Schottky| `Diode_SIC` | `Diode_SIC_Vr_Io_Package` |
| ZEN Zener| `Diode_ZEN` | `Diode_ZEN_Vz_Power_Package` |
| TVS TVS| `Diode_TVS` | `Diode_TVS_Vbr_Vc_Ip_Package` |
| ESD ESD protection| `Diode_ESD` | `Diode_ESD_Vrwm_Vc_Channels_Package` |
| SWI Switching/small-signal| `Diode_SWI` | `Diode_SWI_Vr_Io_trr_Package` |
| BRG Bridge rectifier| `Diode_BRG` | `Diode_BRG_Vrrm_Io_Package` |
| LED Indicator LED| `Diode_LED` | `Diode_LED_Color_Vf_If_Package` (color e.g. `RED`) |

Example (Schottky BAT46WJ, 100 V / 250 mA): `Diode_SCH_100V_0.25A_SOD-323F`

## Transistor — `Transistor_TYPEID_[Polarity]_Voltage_Current_[Rds(on)]_Package_[AECQ]`

Since the prefix is now `Transistor_TYPEID`, the polarity/channel can no longer ride in the
prefix (the old `NMOS`/`PMOS`/`BJT_NPN` tokens are retired). It is carried as **its own token
immediately after the prefix**: `N`/`P` for FETs, `NPN`/`PNP` for BJTs and digital transistors.
Types with no polarity variant (GaN, IGBT) omit the token entirely.

| Type | Prefix | Format |
|------|--------|--------|
| BJT BJT | `Transistor_BJT` | `Transistor_BJT_Polarity_Vceo_Ic_Package` (polarity `NPN`/`PNP`) |
| MOS MOSFET (Si) | `Transistor_MOS` | `Transistor_MOS_Channel_Vds_Id_Rdson_Package` (channel `N`/`P`) |
| SCM SiC MOSFET | `Transistor_SCM` | `Transistor_SCM_Channel_Vds_Id_Rdson_Package` |
| GAN GaN FET | `Transistor_GAN` | `Transistor_GAN_Vds_Id_Rdson_Package` |
| IGBT IGBT | `Transistor_IGBT` | `Transistor_IGBT_Vces_Ic_Package` |
| JFET JFET | `Transistor_JFET` | `Transistor_JFET_Channel_Vds_Idss_Package` |
| DIG Digital/bias-R transistor | `Transistor_DIG` | `Transistor_DIG_Polarity_Vceo_R1/R2_Package` |

Example: `Transistor_MOS_N_20V_6A_15mΩ_SOT-23` · `Transistor_BJT_NPN_50V_0.1A_SOT-416FL`

## Integrated Circuit (IC) — one line per subtype; package always last (before AECQ)

| Type | Prefix | Format |
|------|--------|--------|
| MCU Microcontroller| `IC_MCU` | `IC_MCU_Core_Flash_Package` (e.g. `IC_MCU_M0+_128Kb_LQFP-48`) |
| LDO LDO regulator| `IC_LDO` | `IC_LDO_Vout_Iout_Package` (`ADJ` if adjustable) |
| DCD DC-DC IC| `IC_DCD` | `IC_DCD_Topology_Vin_Iout_Package` (topology `BUCK`/`BOOST`/`BUCKBOOST`) |
| PMU PMIC| `IC_PMU` | `IC_PMU_Rails_Package` |
| BMS BMS AFE| `IC_BMS` | `IC_BMS_Cells_Package` (e.g. `16S`) |
| DRV Gate/motor driver| `IC_DRV` | `IC_DRV_Type_Voltage_Current_Package` (type `GATE`/`MOTOR`/`HB`) |
| AMP Amplifier/op-amp| `IC_AMP` | `IC_AMP_GBW_Channels_Package` |
| CMP Comparator| `IC_CMP` | `IC_CMP_Channels_Package` |
| VRF Voltage reference| `IC_VRF` | `IC_VRF_Voltage_Tolerance_Package` |
| ADC ADC| `IC_ADC` | `IC_ADC_Bits_Rate_Package` |
| DAC DAC| `IC_DAC` | `IC_DAC_Bits_Channels_Package` |
| ISO Isolator/optocoupler| `IC_ISO` | `IC_ISO_Channels_IsolationV_Package` |
| XCV Transceiver| `IC_XCV` | `IC_XCV_Bus_Speed_Package` (bus `CAN`/`RS485`; e.g. `IC_XCV_CAN_5Mbps_SOIC-8`) |
| AFE Analog front end| `IC_AFE` | `IC_AFE_Function_Package` |
| MEM Memory| `IC_MEM` | `IC_MEM_Type_Size_Interface_Package` (e.g. `IC_MEM_FLASH_128Mb_SPI_SOIC-8`) |
| LOG Logic gate| `IC_LOG` | `IC_LOG_Function_Package` (e.g. `AND2`, `BUF`) |
| SEN Sensor IC| `IC_SEN` | `IC_SEN_Type_Package` |
| IFC Interface/expander| `IC_IFC` | `IC_IFC_Function_Package` |
| CLK Clock/RTC| `IC_CLK` | `IC_CLK_Freq_Package` (or `RTC_Package`) |
| SVR Supervisor/reset| `IC_SVR` | `IC_SVR_Threshold_Package` |
| MTR Energy metering| `IC_MTR` | `IC_MTR_Phases_Package` |

## Protection Device — `Protection_TYPEID_ratings_Package`

| Type | Prefix | Format |
|------|--------|--------|
| FUS Fuse| `Protection_FUS` | `Protection_FUS_Current_Voltage_Package` (speed `F`/`T` may precede current) |
| RSF Resettable/PPTC| `Protection_RSF` | `Protection_RSF_Ihold_Voltage_Package` |
| VAR Varistor/MOV| `Protection_VAR` | `Protection_VAR_Vrms_Energy_Package` |
| GDT Gas-discharge tube| `Protection_GDT` | `Protection_GDT_Vspark_Package` |
| CBK Circuit breaker| `Protection_CBK` | `Protection_CBK_Current_Poles_Package` |

## Power Conversion Module — `Power_Conversion_Module_TYPEID_Vin_Vout_Power_Package`

| Type | Prefix | Notes |
|------|--------|-------|
| DCM DC-DC module| `Power_Conversion_Module_DCM` | non-isolated PoL |
| IDC Isolated DC-DC| `Power_Conversion_Module_IDC` | isolated brick |
| INV Inverter (DC-AC)| `Power_Conversion_Module_INV` | `Power_Conversion_Module_INV_Power_Voltage_Package` |
| OBC On-board charger| `Power_Conversion_Module_OBC` | `Power_Conversion_Module_OBC_Power_Voltage_Package` |
| CHG Charger module| `Power_Conversion_Module_CHG` | `Power_Conversion_Module_CHG_Power_Voltage_Package` |
| PSU AC-DC SMPS| `Power_Conversion_Module_PSU` | `Power_Conversion_Module_PSU_Power_Vout_Package` |
| RCM Rectifier module| `Power_Conversion_Module_RCM` | `Power_Conversion_Module_RCM_Current_Voltage_Package` |

## Relay / Contactor — `Relay_Contactor_TYPEID_CoilVoltage_ContactRating_Package`

| Type | Prefix | Notes |
|------|--------|-------|
| RLS Signal relay| `Relay_Contactor_RLS` | contact rating e.g. `2A/30V` |
| RLP Power relay| `Relay_Contactor_RLP` | |
| SSR Solid-state relay| `Relay_Contactor_SSR` | `Relay_Contactor_SSR_ControlV_LoadRating_Package` |
| RLR Reed relay| `Relay_Contactor_RLR` | |
| CTC Contactor| `Relay_Contactor_CTC` | HV/HC contact rating |

## Switch / Button — `Switch_Button_TYPEID_[Positions]_Rating_Package`

| Type | Prefix | Notes |
|------|--------|-------|
| SWT Tactile| `Switch_Button_SWT` | rating e.g. `50mA/12V` |
| PBT Push button| `Switch_Button_PBT` | |
| DSW DIP/slide| `Switch_Button_DSW` | positions e.g. `4P` |
| RSW Rocker/toggle| `Switch_Button_RSW` | |
| RSY Rotary| `Switch_Button_RSY` | positions e.g. `12POS` |

## Connector — `Connector_TYPEID_Positions_Pitch_Package`

| Type | Prefix | Notes |
|------|--------|-------|
| CWB Wire-to-board| `Connector_CWB` | e.g. `Connector_CWB_2x2_P2.0` |
| CBB Board-to-board| `Connector_CBB` | |
| HDR Header/socket| `Connector_HDR` | pitch e.g. `2.54mm` |
| FFC FFC/FPC| `Connector_FFC` | |
| USB USB/data| `Connector_USB` | add USB type (`C`, `MICRO`) |
| PWC Power/high-current| `Connector_PWC` | add current rating |
| TBK Terminal block| `Connector_TBK` | |

## Antenna / RF — `Antenna_RF_TYPEID_Band_Package`

| Type | Prefix | Notes |
|------|--------|-------|
| ANC Chip antenna| `Antenna_RF_ANC` | band e.g. `2.4GHz` |
| ANP PCB/trace antenna| `Antenna_RF_ANP` | |
| ANE External/whip| `Antenna_RF_ANE` | add connector token |
| SAW SAW filter| `Antenna_RF_SAW` | `Antenna_RF_SAW_Freq_Package` |
| RFM RF/wireless module| `Antenna_RF_RFM` | protocol e.g. `BLE`, `WIFI`, `LTE` |

## Crystal / Oscillator / Timing — `Crystal_Oscillator_TYPEID_Freq_[Load]_Package`

| Type | Prefix | Notes |
|------|--------|-------|
| XTL Crystal| `Crystal_Oscillator_XTL` | `Crystal_Oscillator_XTL_Freq_LoadCap_Package` (e.g. `Crystal_Oscillator_XTL_48MHz_18pF_SMD2016-4P`) |
| OSC Crystal oscillator| `Crystal_Oscillator_OSC` | `Crystal_Oscillator_OSC_Freq_Package` |
| MMO MEMS oscillator| `Crystal_Oscillator_MMO` | |
| RSN Ceramic resonator| `Crystal_Oscillator_RSN` | `Crystal_Oscillator_RSN_Freq_Package` |

## Battery / Cell — `Battery_Cell_TYPEID_Capacity_Voltage_Format`

| Type | Prefix | Notes |
|------|--------|-------|
| CLI Li-ion cell| `Battery_Cell_CLI` | format e.g. `18650`; capacity `2600mAh` |
| CLF LiFePO4 cell| `Battery_Cell_CLF` | |
| CCO Coin/button| `Battery_Cell_CCO` | add chemistry (`CR`/`LIR`) + size (`2032`) |
| CNI NiMH| `Battery_Cell_CNI` | |
| BPK Battery pack| `Battery_Cell_BPK` | `Battery_Cell_BPK_Voltage_Capacity` (e.g. `48V_20Ah`) |
| CHL Cell holder| `Battery_Cell_CHL` | `Battery_Cell_CHL_CellType_Package` |

## Audible / Indicator

| Type | Prefix | Format |
|------|--------|--------|
| BUZ Magnetic buzzer| `Audible_Indicator_BUZ` | `Audible_Indicator_BUZ_Voltage_Freq_Package` |
| PBZ Piezo buzzer| `Audible_Indicator_PBZ` | `Audible_Indicator_PBZ_Voltage_Freq_Package` |
| SPK Speaker| `Audible_Indicator_SPK` | `Audible_Indicator_SPK_Power_Impedance_Package` |
| IND Indicator lamp| `Audible_Indicator_IND` | `Audible_Indicator_IND_Color_Voltage_Package` |

## Display / HMI — `Display_HMI_TYPEID_Resolution/Digits_Size_Interface`

| Type | Prefix | Notes |
|------|--------|-------|
| DSG 7-segment| `Display_HMI_DSG` | `Display_HMI_DSG_Digits_Color_Package` |
| OLE OLED| `Display_HMI_OLE` | resolution e.g. `128x64`, size `0.96in` |
| LCD LCD| `Display_HMI_LCD` | char (`16x2`) or graphic resolution |
| TFT TFT| `Display_HMI_TFT` | resolution + size + interface (`SPI`/`RGB`) |

## Sensor (discrete / module) — `Sensor_TYPEID_Range_[Interface]_Package`

| Type | Prefix | Notes |
|------|--------|-------|
| STE Temperature| `Sensor_STE` | range + interface (`I2C`/`ANALOG`) |
| SCU Current (Hall)| `Sensor_SCU` | range e.g. `±50A` |
| SVO Voltage/isolated| `Sensor_SVO` | |
| SHA Hall/position| `Sensor_SHA` | type (`LATCH`/`LINEAR`) |
| SIM IMU/accel| `Sensor_SIM` | axes (`6AXIS`) + interface |
| SPR Pressure| `Sensor_SPR` | range + interface |

## Thermal / Cooling

| Type | Prefix | Format |
|------|--------|--------|
| FAN Fan| `Thermal_Cooling_FAN` | `Thermal_Cooling_FAN_Size_Voltage_Airflow` (size e.g. `40x40mm`) |
| HSK Heatsink| `Thermal_Cooling_HSK` | `Thermal_Cooling_HSK_Dimensions_ThermalResistance` |
| TPD Thermal pad/TIM| `Thermal_Cooling_TPD` | `Thermal_Cooling_TPD_Conductivity_Thickness` |

---

## When a part doesn't fit

The Layer-2 formats are the working house standard, but real datasheets vary. If a part is
missing a token the format asks for, leave it out and flag it. If it has a defining rating the
format doesn't capture, add it in the sensible position and **tell the engineer** what you
added so the convention can be updated deliberately. Never silently bend a format — an
inconsistent Description is worse than one confirmed question. The Layer-1 (SOP) formats are
fixed and are not up for reinterpretation.