KiCad Stackup Lock Bug: Atopile Decode Error

Understanding the Issue: Locking Layers in KiCad

When you're deep into designing a printed circuit board (PCB), managing the physical board stackup is a crucial step. This involves defining the various layers of your PCB, such as copper layers, dielectric materials, and solder masks, and specifying their order and thickness. KiCad, a popular open-source PCB design software, offers a robust Board Setup panel where you can meticulously configure these parameters. One of the features within the Physical Stackup section is the ability to lock layers. Locking a layer essentially prevents it from being accidentally modified or deleted, which can be a lifesaver during complex design revisions. It provides a safeguard, ensuring that critical layers remain as intended. However, it appears that this seemingly straightforward feature in KiCad has an unintended consequence when interacting with the atopile toolchain, specifically during the build process. Users have reported that attempting to lock a board layer in KiCad can lead to a disruptive Decode Error within atopile. This error halts the build process, preventing the design from being fully processed and generated. The root cause, as identified in the bug report, stems from how atopile's parser interprets the data associated with a locked layer. Instead of recognizing the layer's thickness as a simple numerical value (a float), the parser receives it as a list containing both the numerical value and a Symbol('locked') indicator. This unexpected data type mismatch – expecting a float but receiving a list – triggers a TypeError within atopile's internal parsing logic, specifically in the dataclass_sexp.py file. This situation highlights a subtle but significant interoperability challenge between KiCad's layer locking feature and atopile's data parsing mechanisms. The error occurs because the representation of a locked layer in the KiCad file format is not directly compatible with the data types atopile's parser is expecting for numerical values like layer thickness. This means that while KiCad handles the locked layer information correctly within its own environment, the transition of this data to atopile for processing results in a critical failure.

The Atopile Decode Error: A Closer Look

The atopile build process is the mechanism by which the atopile toolchain takes your design definitions and translates them into various outputs, including potentially a KiCad PCB file. When a KiCad board stackup configuration includes locked layers, atopile encounters a significant roadblock. The error message, a TypeError: float() argument must be a string or a real number, not 'list', is quite telling. It indicates that the Python interpreter, within the atopile framework, is trying to convert a value into a floating-point number (which is expected for something like layer thickness) but is instead receiving a list. This list, in the case of a locked layer, contains both the numerical thickness (e.g., 0.35) and the Symbol('locked') identifier. The Python float() function, which is designed to handle numerical strings or actual numbers, simply cannot process a list as input. This is the core of the Decode Error. The parser, expecting a clean numerical value for the layer's physical dimensions, gets a data structure that includes this extra metadata about the layer's locked status. This mismatch means that atopile cannot correctly interpret the physical properties of the board as defined in KiCad when a layer is locked. Consequently, the ato build command fails, leaving the user unable to proceed with their design flow. The report specifically points to version <= 0.12.4 of atopile as being affected, suggesting that the dataclass_sexp.py file, which contains the problematic parsing logic, might have been refactored or removed in later versions (main). However, given that 0.12.4 is the current published version, this bug remains a pertinent issue for users relying on this specific release. The implications are that users who utilize the layer locking feature in KiCad will be unable to use atopile for building their projects if they are on this version, forcing them to either unlock their layers (risking accidental changes) or refrain from using the feature altogether until a fix is implemented.

Reproducing the Error: A Step-by-Step Guide

For developers and users trying to understand and address the KiCad board stackup bug within atopile, reproducing the error is the first essential step. The process is straightforward and primarily involves interacting with the KiCad PCB editor before running the atopile build command. Here's how you can replicate the Decode Error:

1. Open Your KiCad Project: Begin by opening your PCB design project in KiCad. This could be a new project or an existing one where you intend to define or modify the board's physical stackup.
2. Access Board Setup: Navigate to the main menu and select Board Setup.... This will open a dialog box with various configuration options for your PCB.
3. Go to Physical Stackup: Within the Board Setup dialog, locate and select the Physical Stackup tab. This is where you define the layers of your PCB, their types, thicknesses, and other physical characteristics.
4. Lock a Board Layer: In the Physical Stackup panel, you will see a list of your board's layers. Find a layer (it could be a copper layer, a dielectric layer, or any other) and look for an option to lock it. Typically, there's a lock icon or a checkbox associated with each layer that allows you to toggle its locked status. Click this option to lock the selected layer. You might observe a visual indicator, like a lock symbol appearing next to the layer name, confirming that it is now locked.
5. Save Your KiCad Design: Ensure you save your KiCad project file (.kicad_pcb) after locking the layer. This action writes the updated stackup configuration, including the locked layer information, into the file.
6. Run Atopile Build: Now, switch to your terminal or command prompt and execute the atopile build command for your project. This would typically look something like ato build or a similar command specific to your atopile project structure.

Upon executing the ato build command, you should witness the atopile decode error occurring. The build process will halt, and you'll see a traceback in your console output, similar to the one provided in the bug report, clearly indicating a TypeError originating from the dataclass_sexp.py file. This traceback will likely show val = [0.35, Symbol('locked')] and the subsequent attempt to cast this list to a float, leading to the crash. This reproduction method confirms that the interaction between KiCad's layer locking feature and atopile's parsing of the .kicad_pcb file is indeed the source of the problem. It provides a reliable way for developers to test potential fixes and for users to confirm if they are experiencing the same issue.

The Technical Root: Data Type Mismatch in Parsing

The core of the atopile Decode Error lies in a fundamental data type mismatch that occurs during the parsing of the KiCad .kicad_pcb file. Atopile uses a sophisticated system, including modules like dataclass_sexp.py, to read and interpret the data structures defined in various electronic design files. When dealing with the KiCad board stackup, atopile expects certain fields, such as the thickness of a layer, to be represented by specific data types. For numerical values like thickness, the expected type is typically a floating-point number (a float) or possibly an integer. However, when a layer is locked within KiCad's Physical Stackup panel, the software doesn't just store the numerical thickness. Instead, it modifies the representation of that data in the .kicad_pcb file to include an additional piece of information: a flag or symbol indicating that the layer is locked. In the context of the atopile parser, this results in the value for the layer's thickness being read not as a simple 0.35 (a float), but as a list: [0.35, Symbol('locked')]. This is where the problem surfaces. The _convert function within dataclass_sexp.py, which is responsible for transforming the parsed data into Python objects, is designed to handle type conversions based on the expected schema. When it encounters the thickness field for a locked layer, it receives this list [0.35, Symbol('locked')] and attempts to convert it into the expected float type using t(val), where t is float and val is the list. Since Python's float() constructor cannot directly convert a list into a floating-point number, it throws a TypeError. This error signifies that the parser received data in an unexpected format, preventing it from correctly processing the board's physical configuration. The issue is exacerbated because the 0.12.4 version of atopile, which is currently published, contains this specific parsing logic that fails to accommodate the list format introduced by KiCad's layer locking feature. Later versions might have addressed this by either explicitly handling such lists or by modifying the parsing schema to be more robust against such variations. Understanding this data structure difference is crucial for developers aiming to fix the bug. They need to ensure that atopile's parser can gracefully handle the [value, Symbol('locked')] format when encountered for layer thickness, or potentially preprocess the KiCad file data to extract the numerical value before it reaches the float() conversion.

Expected Behavior: A Seamless Integration

The expected behavior when using atopile with KiCad designs, even those incorporating advanced features like locked layers in the board stackup, is a smooth and error-free ato build process. Ideally, atopile should be capable of interpreting the data from the .kicad_pcb file, including the specific configuration of locked layers, without interruption. This means that when atopile encounters a layer marked as locked in KiCad, it should not result in a crash or a Decode Error. Instead, atopile should be able to correctly parse the physical properties of all layers, whether locked or unlocked. If a layer is locked, atopile might need to recognize this status and potentially treat the numerical thickness value as read-only within its own model, or simply continue processing the numerical value for simulation or layout generation purposes. The crucial point is that the presence of a locked layer should not fundamentally break the build pipeline. A robust toolchain would gracefully handle such variations in the input file format. For instance, atopile could be updated to specifically check for the Symbol('locked') within the list structure for layer thickness. If present, it could extract the numerical value (e.g., 0.35) and ignore the Symbol('locked') part for the purpose of numerical calculations or parsing, while perhaps internally noting that the layer is intended to be immutable. Alternatively, the parsing logic could be made more flexible to accommodate different representations of numerical data, provided a clear numerical value can be extracted. The objective is for the user to be able to leverage KiCad's features, such as layer locking for design integrity, without compromising their ability to use atopile for design automation and generation. A successful ato build signifies that atopile has understood the complete board definition provided by KiCad, allowing the user to proceed with subsequent steps in their electronic design workflow. Therefore, the absence of errors, particularly the TypeError related to data type mismatches in the stackup configuration, is the hallmark of the expected behavior. This ensures that atopile acts as a reliable bridge between different stages of the PCB design process, rather than an obstacle.

Potential Solutions and Future Considerations

Addressing the atopile Decode Error caused by locked KiCad board stackup layers requires modifications to how atopile parses the .kicad_pcb file format. Several potential solutions can be considered, focusing on making the parser more resilient to the data structure variations introduced by layer locking.

One primary approach is to enhance the dataclass_sexp.py module (or its successor in newer versions) to specifically handle the list format [value, Symbol('locked')] when parsing layer thickness. Instead of blindly attempting to cast the entire list to a float, the parser could first check if the received value is a list. If it is, it should then inspect the elements of the list. If the second element is Symbol('locked'), the parser should extract the first element (the numerical value) and use that for the float conversion. This would involve adding conditional logic within the _convert function or a related parsing utility.

Another strategy involves modifying the data schema that atopile uses to represent the KiCad PCB structure. If the schema is updated to allow for an optional 'locked' flag alongside the numerical thickness, the parser could populate these fields accordingly. This would decouple the numerical value from the locking status, allowing both to be represented and processed independently. This approach is cleaner and more aligned with structured data representation.

Furthermore, the atopile team might consider implementing a pre-processing step that sanitizes the data read from the .kicad_pcb file before it's passed to the main parsing logic. This pre-processor could identify and remove the Symbol('locked') from list-based thickness values, ensuring that only the numerical component is presented to the downstream conversion functions.

For users encountering this issue with atopile version 0.12.4, the immediate workaround is to unlock any layers in their KiCad board stackup before running ato build. While this resolves the immediate build error, it sacrifices the protection offered by layer locking, which might not be ideal for complex projects. Users should save their design after unlocking layers to ensure the changes are reflected in the .kicad_pcb file.

Looking ahead, it's essential for the atopile project to maintain compatibility with evolving features in popular EDA tools like KiCad. Regular testing against different versions of KiCad and incorporating a comprehensive suite of test cases, including scenarios with locked layers, would help catch such interoperability bugs early in the development cycle. Adding a test case specifically for locked PCB board layers in the atopile test suite would be a valuable addition to prevent regressions. This proactive approach ensures that atopile remains a reliable and powerful tool for the electronic design community.

For further insights into PCB design best practices and advanced KiCad features, you can refer to the KiCad Documentation.