Horizon Pool Convention

Because Horizon’s part management is based around a single pool, all parts need to follow a clear convention for a consistent look and feel. If you want to add a part to the official Horizon pool, check this convention first before submitting a pull request.

Note that, however, this convention is a very rough draft and far from complete. Suggestions for rules are very welcome! You’re also invited to take part in the discussion in the convention’s repository’s GitHub issues <https://github.com/horizon-eda/horizon-pool-convention/issues>__.

Overview and general rules

File names


1. File names are adapted versions of the pool entry’s name:

   -  Replace each space in the name by a underscore ``_``, except for
      the space before a unit: ``LED 5 mm`` becomes ``LED_5mm.json``
   -  Keep the name’s capitalisation, except for the capitalisation of
      the first letter: ``DO41`` becomes ``DO41.json``, but
      ``Very special connector`` becomes ``very_special_connector.json``
   -  Omit parentheses: ``Resistor 0402 (manual soldering)`` becomes
      ``resistor_0402_manual_soldering.json``

2. In general, use only characters from the following sets:

   -  Alphanumeric characters (``a`` to ``z``, ``A`` to ``Z``, ``0`` to
      ``9``)
   -  Underscore ``_`` and dash/hyphen ``-``
   -  Period/dot ``.``

General naming and organisation

All file names, descriptions, etc. must be in English.
Avoid plural forms. For example, a folder with diode pool entries should be called diode and not diodes.
Use a point . as a decimal separator. Do not use a thousand’s separator.
The first letter of each name must be capitalised.

Parts

Parts should be named for the exact MPN (manufacturer part number). Use the exact spelling from the ‘ordering information’ section of the device’s datasheet.
The Value field does not necessarily contain the full MPN. It should be clear from the value what the part is without occupying too much space in the schematic. For example, for a general purpose resistor the resistance is generally enough for the schematic and a INA219AIDCNR can be shortened to INA219A.
Include sensible information like a description. Use the manufacturer’s website for the datasheet link and not a third-party datasheet site.
Use inheritance for only slightly differing parts (like different packaging, temperature range, etc.).

Packages

Naming and folder structure


Names follow a simple structure, which is best observed with some
examples:

-  ``DIP8, 7.62 mm lead span, 2.54 mm pitch``
-  ``DIP16, 7.62 mm lead span, 2.54 mm pitch (with socket)``
-  ``TO220, 5 pins (staggered pins, horizontal)``
-  ``Pin header, 10 pins, 2 rows, 2.54 mm pitch``
-  ``Pin header, 10 pins, 1 row, 2.54 mm pitch (horizontal)``

They are composed of:

1. A primary identification feature (like ``LED`` or ``DIP8`` or
   ``TO220``). Note that there is no dash included (``SO8`` instead of
   ``SO-8``, etc.).
2. An optional comma-separated list of quantitative specifiers

   -  These should be in order of decreasing importance/frequency of
      usage.
   -  If the have a unit, include a space before the unit. Metric units
      are preferred when appropriate.
   -  The same set of quantitative parameters must be included for all
      footprints of a certain type to avoid ambiguity.
   -  Follow the format ``<number> [unit] <parameter name>``.

3. An optional comma-separated list of qualitative modifiers in
   parentheses

   -  Modifiers which are standard throughout the pool must not be added
      (``IPC compliant``, ``reflow soldering``, etc.).
   -  If the only difference a modifier makes is the 3D model of the
      part, it should probably not be a separate package and instead a
      alternate 3D model within the same part. For example
      ``LED 5 mm (green)`` and ``LED 5 mm (red)`` would have no
      difference in any PCB layer.

The following general rules apply:

1. For a manufacturer-specific footprint, use the respective subfolder
   in ``manufacturer``. Use the exact name of the package from the
   package or device datasheet.
2. If manufacturers disagree on some dimension of the package body or
   land pattern for a package of the same name, consider the package
   manufacturer-specific and place it in the ``manufacturer`` subfolder.
   If the majority of other manufacturers agree, their variant can be
   considered a generic footprint (with the same name). For example,
   there can be both ``manufacturer/stm/TSSOP20`` and
   ``ic/smd/tssop/TSSOP20`` if STMicroelectronics’s TSSOP-20 drawings
   are different from all other manufacturers’.
3. When naming, be verbose: do not abbreviate parameters with single
   letters or symbols, instead write them out.
4. No redundancy: When quantitative or qualitative parameters are
   reflected in the part number within the package’s name (for example
   for connectors where the MPN distinguishes between vertical and
   right-angled-variants), the specifiers must not be included.

General package conventions

The origin of the package should be in the middle of the component body for both SMT and THT packages. Exceptions to this are:
- If a specific origin for pick and place is defined in the component datasheet, it should be used.
- If the part is electro-mechanical and a different footprint anchor simplifies the placement during the PCB design, it should be adapted accordingly. For example, it makes sense to have a potentiometer’s or rotary encoder’s origin exactly at the center of its axis.
- Edge aligned connectors should have their origin on the PCB edge.

Silkscreen


1. All silkscreen text and drawings should have a line width of 0.15 mm.
   Text should have a size of 1 mm.
2. The silkscreen layer must contain a reference designator (``$RD``)
   near pin 1 of the package. This should be the only text on the
   silkscreen layer.
3. Silkscreen must not intersect with pads or package. All silkscreen
   has to be visible after assembly.
4. Silkscreen text and drawings must have a clearance of 0.2 mm to
   package outline and copper layer.
5. A pin 1 indicator is established by extension of an existing outline
   or by omitting a line. Do not use a dot or text or any other marking.

Courtyard

The courtyard polygon is the hull around package body and pads. This means that at a courtyard expansion if 0 mm, the courtyard polygon touches the outermost pad outlines/package outlines.
The courtyard polygon must be parametrised by the courtyard expansion parameter with a parameter program.

Package layer


1. The package layer has to contain the physical size of the part as a
   polygon.
2. Further annotations must not be added.
3. Use a line width of 0 mm.

Assembly layer

The assembly layer is similar to the package layer in that it contains a polygon based on the physical outline of the part.
The assembly layer must include a pin 1 designator in the form of a bevelled corner (if pin 1 is in a corner) or a triangular ‘dent’ (if pin 1 is on an edge). This marking should be normally 1.2 mm large, but maximally half the length of the shorter adjacent side.
Include a text $RD. This text should be rotated along the component width. The text’s origin should be placed on a line along the component’s height in the assembly layer, preferably across from the pin 1 marker. The text should have a size of 1 mm, except for small packages, where the size should be decreased in 0.1 mm steps until a reference designator with 4 numerical digits fits within the assembly polygon.

Copper


1. Use the recommended footprint from the manufacturer’s device or
   package datasheet.
2. If there are multiple recommendations, e. g. for different soldering
   methods, create alternate packages.
3. For THT components, an alternate package can be created featuring a
   square/rectangular pad for pin 1 identification. The main package
   should have identical pads as far as reasonable.

Padstacks
---------

If you create a package, chances are that you don’t need a new padstack,
as the existing general padstacks are parametrised. If you do need to
create a new padstack, take the following rules into account:

1. If the package you’re creating requires a padstack for a special pad
   geometry, the JSON file should be placed in the package’s
   ``padstacks`` directory and not in the root ``padstacks`` directory.
   The latter is reserved for generic padstacks and shouldn’t be
   cluttered with rarely-needed padstacks.
2. Draw the necessary shapes/polygons in all layers, not just the copper
   layer.
3. Use parameter programs to make the padstack as generic as possible.
   As a minimum, solder mask expansion and paste mask contraction must
   be parametrised.

Entities
--------

1. Name the entity for the most general part it applies to. For example,
   do not create a entity ``ATtiny24`` which is implicitly also used for
   the ATtiny44 and ATtiny84 microcontrollers. Instead, use a name like
   ``ATtinyx4``. Unneeded suffixes can just be left out, while
   characters elsewhere must be replaced with a lower-case ``x``.
2. Entities should be split up into multiple units if

   -  they have more than 100 pins (e.g. split up FPGAs into IO banks,
      but not smaller microcontrollers into IO ports),
   -  it is mostly of little importance which physical IC a gate is in
      (e.g. split up multi-gate logic ICs), or
   -  separate placement of units often greatly improves schematic
      clarity (can e.g. make sense for electro-mechanical parts).

3. For entities with multiple gates, make sure that exchangeable gates
   remain exchangeable in the schematic. Don’t use different symbols for
   the same type of gate in order to include some additional pins that
   could have been their own gate.
4. If a entity has multiple gates, make sure that each pin is only
   available via one gate. For example, a quad opamp’s 4 opamp gates
   must not include the power pins of the package because of this.
5. If there is only a single gate, name it ``Main``.
6. A power gate should be named ``Power``.

Prefixes (reference designators)

====== ======================================== Prefix Symbols ====== ======================================== A Sub-assembly or plug-in module AT Attenuator, isolator B Blower, Motor BT Battery C Capacitor CB Circuit breaker CN Capacitor network D Diode, zener diode, TVS diode, DIAC, LED DC Directional coupler DL Delay line DS Display, lamp F Fuse FD Fiducial FL Filter G Generator, oscillator H Hardware (mounting screws, etc.) HY Circulator J Connector JP Jumper, solder jumper K Relay, Contactor L Inductor, coil, ferrite bead LS Loudspeaker, buzzer M Meter MG Motor-generator MH Mounting hole MK Microphone MP Mechanical part (SMD spacer, etc.) PS Power supply Q Transistor, thyristor, TRIAC R Resistor RN Resistor network RT Thermistor S Switch T Transformer TC Thermocouple TP Test point U Integrated circuit, inseparable assembly V Electron tube W Wire, cable, cable assembly Y Crystal, ceramic oscillator ====== ========================================

Symbols

Symbols must have one text $REFDES and one $VALUE. They both should be sized 1.5 mm.
Ensure that a multi-line $VALUE is displayed without overlapping.
Use names as generic as possible (cf. entities).
All pin connection points must be on the 1.25 mm grid and at the outside of the symbol.
Junctions in internal schematics must be a polygon circle with 0.35 mm diameter. Use the ‘Place dot’ tool in the symbol editor to insert a correctly-sized junction dot.

Discrete components


General symbols (ICs, etc.)

Group pins by function, not by pin number. For example, a LED driver’s SPI pins should be placed next to each other, even if they are far apart on the physical device.
If the unit has alternate pin names or using custom pin names is reasonable (e.g. for connectors), enable the ‘can expand’ setting, so users can prevent colliding pin names in their schematics regardless of pin name length.
Consider only the default pin names for the symbol width. Do not make the symbol wide enough to accommodate all possibilities; instead, use the ‘can expand’ setting to let the user choose the width.
Use pin decorations (clock, inverted, etc.) only for digital pins.
Do not use a ‘inverted’ decoration for pins whose name already indicates inversion (n or / in front, overbar, etc.)
The symbol must have a border around it. the $REFDES text is to be placed above the border, $VALUE below. All other text must be within the border.
Power pins should be on the top and bottom of the symbol box. Use the ‘perpendicular’ name orientation unless this forces the symbol to be unreasonably wide. Prefer a uniform spacing of power pins.

Units

Use the pin names exactly like they are written in the device’s datasheet.
Assign electrical functions to the pins according to the device datasheet.
List all alternate pin names. For example, microcontrollers’ pins often have a lot of alternate functions, which should all be listed here.
Do not include annotations for the pin names from the datasheet like footnotes or other markings with a special meaning only explained in the datasheet.