167 lines
9.1 KiB
Markdown
167 lines
9.1 KiB
Markdown
# Mandatory symbol parameters (.SchLib)
|
|
|
|
Vecmocon's Altium SOP (§5) requires every schematic-library symbol to carry a fixed set of
|
|
parameters in its component properties (the panel shown in Altium: *Properties → Parameters*).
|
|
This file defines that set, where each value comes from, and how the skill stamps them onto the
|
|
`.SchLib` symbol.
|
|
|
|
## The symbol mirrors the workbook (fill everything the datasheet gave)
|
|
|
|
**House rule: the symbol's Altium properties must carry _every_ parameter that was filled into
|
|
the part's per-typeid workbook from the datasheet — not just the fixed SOP §5 set.** So a CMC
|
|
symbol also gets `Rated Current(A)`, `Rated Voltage(V)`, `DC Resistance(mΩ)`, `Package`,
|
|
`ESD Withstand Voltage(kV)`, … — whatever that typeid's sheet holds and the datasheet filled.
|
|
The SOP set below is the **minimum**; the workbook is the **source of truth** for the rest.
|
|
|
|
Build the parameter set straight from the finished `<tag>.xlsx` with
|
|
`scripts/schlib_params_from_xlsx.py`, which reads the one data row and keeps every **non-empty**
|
|
column, then hand its output to `schlib_write.py`:
|
|
|
|
```bash
|
|
python scripts/schlib_params_from_xlsx.py --xlsx <stage>/<tag>/<tag>.xlsx \
|
|
--component <LibraryRef> \
|
|
--set "Process=Reflow" --set "Datasheet=<url-or-doc-ref>" \
|
|
[--set "Value=<value>"] [--set "Vecmocon Part Code=<code>"] \
|
|
--out params.json
|
|
python scripts/schlib_write.py --schlib <in>.SchLib --params params.json --out <stage>/<tag>/<sym>.SchLib
|
|
```
|
|
|
|
What the builder does:
|
|
|
|
- **Keeps every filled datasheet column** as a symbol parameter, using the **exact sheet header
|
|
as the parameter name** (e.g. `Rated Current(A)`) so the symbol and the workbook stay
|
|
traceably identical. Empty columns are left out (the SOP hides blank parameters).
|
|
- **Never writes** the identity / versioning / model-link columns — `MPN_make_type`,
|
|
`Skill Version`, `Template Version`, `Library Ref/Path`, `Footprint Ref/Path` (Library Ref is
|
|
the symbol's own name and the footprint is the linked PCB model, not a text property).
|
|
- **Renames** the two columns whose Altium/SOP name differs — `Rohs compliance → ROHS`,
|
|
`Operating Temp(°C) → Operating Temperature` — value copied through unchanged.
|
|
- **Merges in the SOP-only fields the sheet doesn't hold**: `Manufacturer Part` (= the MPN,
|
|
recovered from the tag) is added automatically; pass `Process`, `Datasheet`, and (if known)
|
|
`Value` / `Vecmocon Part Code` via `--set` or a `--sop` JSON. A non-empty override wins over a
|
|
sheet value; an empty one is ignored.
|
|
|
|
Glyph note: Altium stores parameter text as single-byte ANSI, so `schlib_write.py` transliterates
|
|
the few unit glyphs that aren't representable — the ohm sign `Ω → Ohm` (so `DC Resistance(mΩ)`
|
|
lands as `DC Resistance(mOhm)`) and a Greek micro `μ → u`; `±`, `°` and the latin-1 micro sign
|
|
pass through unchanged. So a couple of symbol parameter names are the ASCII form of the sheet
|
|
header — expected, not a mismatch.
|
|
|
|
The rest of this file describes the SOP §5 minimum set and where each value comes from.
|
|
|
|
How the parameters get in: the skill writes them **directly into the `.SchLib` in pure Python**
|
|
via `scripts/schlib_write.py` — it rebuilds the OLE compound file around the enlarged component
|
|
`Data` stream while preserving every other byte (all other streams, the directory tree, the
|
|
Altium CLSIDs). It also **removes the Ultra-Librarian default params `Manufacturer_Name` and
|
|
`Manufacturer_Part_Number`**, which just duplicate the SOP `Manufacturer` / `Manufacturer Part`.
|
|
The output is a ready `.SchLib`. Because this writes Altium's own format from outside Altium, the
|
|
script self-checks that the result re-opens as a valid OLE with the params present — but **always
|
|
open the result in Altium once to confirm it loads** before relying on it. (An older path,
|
|
`scripts/altium_params.py`, instead emits an Altium DXP script to stamp the same parameters from
|
|
inside Altium; keep it as a fallback if a particular file doesn't round-trip.)
|
|
|
|
## The parameter set
|
|
|
|
Use these exact Altium parameter names (they must match the symbol, per the SOP screenshot).
|
|
The **Comment** field is set to the MPN (SOP §4), and the **Description** field is the strict
|
|
string from `references/description_format.md`.
|
|
|
|
| Parameter | Source | Notes |
|
|
|-----------|--------|-------|
|
|
| `Value` | datasheet | the component **value only** (no package), in shorthand — e.g. `1u`, `12p`, `100n`, `10k` |
|
|
| `Manufacturer Part` | datasheet | the MPN; also the **Comment** field |
|
|
| `Manufacturer` | datasheet | manufacturer name as printed, e.g. `YAGEO` |
|
|
| `Manufacturer Part 2` | **leave blank (for now)** | second-source MPN — left empty by default; see optional note below |
|
|
| `Manufacturer 2` | **leave blank (for now)** | second-source manufacturer — left empty by default |
|
|
| `Process` | derived | assembly process from package: SMD → `Reflow`, through-hole → `Wave`/`Manual`; confirm |
|
|
| `Vecmocon Part Code` | engineer | internal code (e.g. `VECESC2421`) — **not on the datasheet**; ask |
|
|
| `Operating Temperature` | datasheet | full range, e.g. `-55 °C to +125 °C` |
|
|
| `Tolerance` | datasheet | e.g. `1%` (or `±1%`) |
|
|
| `Datasheet` | datasheet | source URL or document reference (SOP marks this optional) |
|
|
| `ROHS` | datasheet | RoHS compliance, `Yes`/`No` |
|
|
|
|
**Read the datasheet-sourced values from the actual datasheet — don't echo whatever text was
|
|
handed to you.** Open the PDF, find each real value (`Value`, `Manufacturer Part`,
|
|
`Manufacturer`, `Operating Temperature`, `Tolerance`, `Datasheet`, `ROHS`, and `Process` by
|
|
inference from the package), and fill them verified. An honest blank beats a guess — the SOP
|
|
hides blank parameters, so a gap just stays empty until someone fills it. Only **one** field is
|
|
purely internal and must come from the engineer: `Vecmocon Part Code` — ask for it.
|
|
|
|
The second-source pair (`Manufacturer 2` / `Manufacturer Part 2`) is **left blank for now** —
|
|
don't populate it by default. It simply stays hidden in Altium until someone fills it later.
|
|
|
|
## Optional: second-source cross-reference (currently off)
|
|
|
|
**House preference right now is to leave `Manufacturer 2` / `Manufacturer Part 2` blank**, so do
|
|
not do this unless the engineer explicitly asks you to find a second source. It's documented
|
|
here so it can be switched on later without redesigning anything.
|
|
|
|
If asked to find a second source, it is an **equivalent part from a different manufacturer** that
|
|
could drop into the design unchanged:
|
|
|
|
1. **Pull the original's form-fit-function specs** from the datasheet — capacitance, voltage,
|
|
tolerance, dielectric/temp class, package (for a cap); resistance, power, tolerance, package
|
|
(for a resistor); and so on per type.
|
|
2. **Search for an equivalent from a *different* manufacturer** (distributor/parametric
|
|
cross-reference, "equivalent to `<MPN>`", or another reputable maker's matching series). It
|
|
must match **every** form-fit-function spec and be **at least as good** on tolerance /
|
|
voltage / temperature — never worse.
|
|
3. **Fill** `Manufacturer 2` = its maker, `Manufacturer Part 2` = its exact MPN.
|
|
|
|
Two hard rules if this is ever used: **never invent an MPN** (only a part number you verified
|
|
exists; else leave blank), and **always flag the chosen second source for the engineer to
|
|
confirm** with the specs you compared.
|
|
|
|
## Building the parameter set
|
|
|
|
Collect the values into a `params.json` (same spirit as `part.json`). `component` is the
|
|
symbol's Library Ref (from `altium_refs.py`); omit it to apply to every component in the lib.
|
|
|
|
```json
|
|
{
|
|
"component": "CC0402FRNPO9BN120",
|
|
"comment": "CC0402FRNPO9BN120",
|
|
"parameters": {
|
|
"Value": "12pF_0402",
|
|
"Manufacturer Part": "CC0402FRNPO9BN120",
|
|
"Manufacturer": "YAGEO",
|
|
"Manufacturer Part 2": "0402N120F500CT",
|
|
"Manufacturer 2": "Walsin Tech Corp",
|
|
"Process": "Reflow",
|
|
"Vecmocon Part Code": "VECESC2421",
|
|
"Operating Temperature": "-55 °C to +125 °C",
|
|
"Tolerance": "1%",
|
|
"Datasheet": "https://www.lcsc.com/datasheet/C326662.pdf",
|
|
"ROHS": "Yes"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Writing them into the symbol
|
|
|
|
Write the parameters straight into the `.SchLib`, producing a new file:
|
|
|
|
```bash
|
|
python scripts/schlib_write.py --schlib <in>.SchLib --params params.json --out <out>.SchLib
|
|
```
|
|
|
|
`params.json` may carry a `"remove"` list (defaults to `["Manufacturer_Name",
|
|
"Manufacturer_Part_Number"]`); those Ultra-Librarian defaults are stripped and the SOP params
|
|
added. The script targets the component named in `"component"` (its Library Ref / storage name),
|
|
or every component if omitted, and self-checks the output re-opens as a valid OLE. Deliver the
|
|
resulting `.SchLib`, and have the engineer open it in Altium once to confirm it loads, then Save
|
|
to Server with a revision note per the SOP.
|
|
|
|
Scope note: the direct writer keeps a component's `Data` under Altium's 4096-byte mini-stream
|
|
threshold in the common case; a very large parameter set (or an extremely long datasheet URL)
|
|
can push it past that, at which point fall back to the `altium_params.py` DXP-script path.
|
|
|
|
Fallback (apply from inside Altium):
|
|
|
|
```bash
|
|
python scripts/altium_params.py script --params params.json --out apply_params.pas
|
|
```
|
|
|
|
Then in Altium: open the `.SchLib`, **DXP → Run Script… → ApplyParameters**, review, **Save to
|
|
Server**.
|