Notes about the position file

Position files are quite simple. You can generate them as plain text (ASCII) or as a spreadsheet (CSV).

But some conventions can make them tricky. Some manufacturers, like JLCPCB, uses conventions that are incompatible with KiCad.

The following blog explains how to adapt the position files generated by KiCad to what JLCPCB needs. To achieve it the author uses a script called JLCKicadTools.

You can achieve the same using KiBot. Here is a configuration example that generates the BoM and position files in the same way JLCKicadTools does:

kibot:
  version: 1

filters:
  - name: only_jlc_parts
    comment: 'Only parts with JLC code'
    type: generic
    include_only:
      - column: 'LCSC#'
        regex: '^C\d+'

variants:
  - name: rotated
    comment: 'Just a place holder for the rotation filter'
    type: kibom
    variant: rotated
    pre_transform: _rot_footprint

outputs:
  - name: 'position'
    comment: "Pick and place file, JLC style"
    type: position
    options:
      variant: rotated
      output: '%f_cpl_jlc.%x'
      format: CSV
      units: millimeters
      separate_files_for_front_and_back: false
      only_smd: true
      columns:
        - id: Ref
          name: Designator
        - Val
        - Package
        - id: PosX
          name: "Mid X"
        - id: PosY
          name: "Mid Y"
        - id: Rot
          name: Rotation
        - id: Side
          name: Layer

  - name: 'bom'
    comment: "BoM for JLC"
    type: bom
    options:
      output: '%f_%i_jlc.%x'
      exclude_filter: 'only_jlc_parts'
      ref_separator: ','
      columns:
        - field: Value
          name: Comment
        - field: References
          name: Designator
        - Footprint
        - field: 'LCSC#'
          name: 'LCSC Part #'
      csv:
        hide_pcb_info: true
        hide_stats_info: true
        quote_all: true

The only_jlc_parts filter is used to generate the BoM and assumes you put the JLC component code in a field named LCSC# (JLC uses LCSC as supplier). Note that the author of the blog simply used Field4 for this and his script searches for any field containing the ^C\d+ pattern. I think this isn’t a good idea and I suggest using a defined name, like in this example.

The rotated variant is used only to apply the _rot_footprint transformation filter. This filter is an internal filter of type rot_footprint. Here is the same configuration file making explicit use of the rotation filter:

kibot:
  version: 1

filters:
  - name: fix_rotation
    comment: 'Adjust rotation for JLC'
    type: rot_footprint

  - name: only_jlc_parts
    comment: 'Only parts with JLC code'
    type: generic
    include_only:
      - column: 'LCSC#'
        regex: '^C\d+'

variants:
  - name: rotated
    comment: 'Just a place holder for the rotation filter'
    type: kibom
    variant: rotated
    pre_transform: fix_rotation

outputs:
  - name: 'position'
    comment: "Pick and place file, JLC style"
    type: position
    options:
      variant: rotated
      output: '%f_cpl_jlc.%x'
      format: CSV
      units: millimeters
      separate_files_for_front_and_back: false
      only_smd: true
      columns:
        - id: Ref
          name: Designator
        - Val
        - Package
        - id: PosX
          name: "Mid X"
        - id: PosY
          name: "Mid Y"
        - id: Rot
          name: Rotation
        - id: Side
          name: Layer

  - name: 'bom'
    comment: "BoM for JLC"
    type: bom
    options:
      output: '%f_%i_jlc.%x'
      exclude_filter: 'only_jlc_parts'
      ref_separator: ','
      columns:
        - field: Value
          name: Comment
        - field: References
          name: Designator
        - Footprint
        - field: 'LCSC#'
          name: 'LCSC Part #'
      csv:
        hide_pcb_info: true
        hide_stats_info: true
        quote_all: true

As you can see we now create a filter named fix_rotation of type rot_footprint:

- name: fix_rotation
  comment: 'Adjust rotation for JLC'
  type: rot_footprint

Using it, instead of the internal filter named _rot_footprint, is the same here. But you can then customize the filter.

The filter supports the following options:

• extend: [boolean=true] Extends the internal list of rotations with the one provided. Otherwise just use the provided list.

• negative_bottom: [boolean=true] Rotation for bottom components is computed via subtraction as (component rot - angle). Note that this should be coherent with the bottom_negative_x of the position output.

• invert_bottom: [boolean=false] Rotation for bottom components is negated, resulting in either: (- component rot - angle) or when combined with negative_bottom, (angle - component rot).

• rotations: [list(list(string))] A list of pairs regular expression/rotation. Components matching the regular expression will be rotated the indicated angle. Special names _top and _bottom will match all components on that side of the board.

In order to add a new rotation or just change an existing one you just need to use the rotations option. As an example: the internal list of rotations rotates QFN packages by 270 degrees, no suppose you want to rotate them just 90 degrees. The filter will look like this:

- name: fix_rotation
  comment: 'Adjust rotation for JLC'
  type: rot_footprint
  rotations:
    - ["^QFN-", 90.0]

This regular expression will match any footprint starting with QFN- and rotate it 90 degrees.

The internal list of rotations is:

Footprint	Rotation
^Bosch_LGA-8_2x2.5mm_P0.65mm_ClockwisePinNumbering	90.0
^R_Array_Convex_	90.0
^R_Array_Concave_	90.0
^SOT-223	180.0
^SOT-23	180.0
^TSOT-23	180.0
^SOT-353	180.0
^QFN-	270.0
^LQFP-	270.0
^TQFP-	270.0
^SOP-(?!18_)	270.0
^TSSOP-	270.0
^DFN-	270.0
^SOIC-	270.0
^VSSOP-10_	270.0
^CP_EIA-3216-18_	180.0
^CP_EIA-3528-15_AVX-H	180.0
^CP_EIA-3528-21_Kemet-B	180.0
^CP_Elec_8x10.5	180.0
^CP_Elec_6.3x7.7	180.0
^CP_Elec_8x6.7	180.0
^CP_Elec_8x10	180.0
^(.*?_\|V)?QFN-(16\|20\|24\|28\|40)(-\|_\|$)	270.0
^PowerPAK_SO-8_Single	270.0
^HTSSOP-28-1EP_4.4x9.7mm*	270.0

XYRS files

XYRS files are just BoM files in CSV format that includes pick and place data (X position, Y position, Rotation and Side). You can generate them using the internal BoM generator (bom output). The following fields contains the needed information:

• Footprint X

• Footprint Y

• Footprint Rot

• Footprint Side

Additionally we support:

• Footprint Type (SMD, THT, VIRTUAL)

• Footprint X-Size

• Footprint Y-Size

• Footprint Populate

Important: These files doesn’t support manual panelization with repeated reference names, you’ll get the coordinates for just one component because this is a BoM.