Label 4 for rotated keys

[ludvigStrom]

I am currently using the kicad-kle-placer plugin for KiCad 7.0 and have encountered some difficulties and confusion regarding the use of “Label 4” for rotated keys, as mentioned in the documentation.

Issue Description: I am working with a keyboard layout where all keys are rotated, and I understand that I need to use “Label 4” for these rotated keys. However, the term “Label 4” is not clearly defined or explained in the documentation, leading to confusion and challenges in using the plugin effectively.

Specific Points of Confusion: Definition of “Label 4”: The term “Label 4” is not clear to me. I am unsure whether it refers to a specific field in the KiCad Symbol Fields table, a position in the KLE JSON output, or something else. Location of “Label 4”: If “Label 4” refers to a position in the KLE JSON, could you please clarify which position or field this corresponds to? The JSON output has various fields and positions, and it’s not evident which one is “Label 4”. Usage of “Label 4”: Could you provide detailed instructions or examples of how to use “Label 4” correctly for rotated keys? Step-by-step guidance would be greatly appreciated.

Steps Taken: I have assigned legends to keys in KLE and exported the JSON output. I have attempted to use the first legend (top-left) as the reference number for each key (e.g., '1' for SW1), but this approach does not seem to work. I have reviewed the plugin’s Python script but did not find clarification on “Label 4”. I have created a new field in KiCads "Symbol fields table" and added id 1 for SW1 etc. I Have renamed that field to label4 instead of field 4

Request for Assistance: Could you please provide clear definitions and explanations for “Label 4”? Could you offer detailed instructions or examples on how to use “Label 4” for rotated keys? If possible, consider updating the documentation to include this information for the benefit of all users.

[zykrah]

Hi there, the label numbers are as i describe here: https://github.com/zykrah/firmware-scripts. There is an example of where the number should go in the readme on this repo too, on the screenshots of the KLE rotated key examples.

However, i admit the wording is less clear. I'll update it soon. Thanks for the heads up

[xgflash1]

I also have the same confusion here. Looking through everything provides zero insight as to what label 4 is, or what I need to do. I have a split keyboard im working on, and this has lead to a stand still in my project. Any updates on the clarification yet? I'd like to add to this, if you'd be keen on explaining it, please dumb it down. I barely know what I'm doing as is, just tryin my best out here!

[zykrah]

@xgflash1 Seems like i linked the wrong GitHub repo in my reply earlier. The documentation for how to use label 4 for rotated layouts is in this repository.

The screenshot below highlights the key information for using Specific Reference Mode. It's a toggle you can select on the main menu of the plugin.

However, i will attempt to provide further explanation:

The plugin needs to know the order of keys in the KLE in order to know which key in the KLE corresponds to which footprint in KiCAD (MX1, MX2, etc), so that it can actually place them accordingly. Since there is no sense of order in a KLE, I wrote some algorithm to "guess" the order of keys based on what is used conventionally. Most people number their symbols in a sensible way from left to right, top to bottom, so that's how the algorthm basically works to match the KLE order to people's KiCAD order. The behaviour of how the algorithm works is described in the lower section of the screenshot below.

However, when you start to introduce rotated keys in KLE, the algorithm will no longer work. So you need to toggle specfic reference mode ON. This hands off the ordering of keys to the user. You just place a number in the middle of each switch as they are numbered with all the symbols/footprints in your KiCAD project. E.g. 1 for whatever key should represent MX1 in your KiCAD project. It's much similar to the screenshot below, however I just used that to demonstrate how the ordering algorithm would order things.

Slight tangent that might not make sense: you could think of it like, if you took those examples below and turned on specific reference mode, the result would be the same as if specific reference mode was off. Because those examples below are specifically examples of how the algorithm orders keys. The idea behind specific reference mode is just that you get to override the default algorithm and set your own order. This is particularly relevant for rotated layouts because... well the algorithm simply does not work for rotated layouts.

P.S. Also want to apologise to you @ludvigStrom. I misunderstood previously, so hopefully this reply also clears it up for you.

[xgflash1]

This at least gave me what I needed to figure out what you meant! Thank you so much, I definitely misinterpreted the guide a bit. For others struggling with this, in KLE, you literally put a number on every key, centered, rather than their legends, so that it can reference the keys correctly. Example of this: To do this (im sure theres an easier way but this is what I did), Click on every key, delete their legends, and order them from top to bottom, left to right numerically. Then, download the new JSON, and when using the plugin, make sure "Specific Reference Mode" is ticked on. Hope this helps!