docu update, add dependency to read xlsx

CHANGELOG.md

@@ -7,16 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.0] - 2024-06-14
+### Added
+ - new dependency for openpyxl to read xlsx-files out of the box
+
+### Updated
+ - Updated tutorial of usage 
+
 ## [0.0.2] - 2024-05-19
 ### Added
  - Fully automated PyPI package upload
 
-
 ## [0.0.1] - 2024-05-19
-
 ### Added
  - Initial release 
 
-[unreleased]: https://github.com/upb-lea/KiClearance/compare/0.0.2...HEAD
+[unreleased]: https://github.com/upb-lea/KiClearance/compare/0.1.0...HEAD
+[0.1.0]: https://github.com/upb-lea/KiClearance/compare/0.0.2...0.1.0
 [0.0.2]: https://github.com/upb-lea/KiClearance/compare/0.0.1...0.0.2
 [0.0.1]: https://github.com/upb-lea/KiClearance/releases/tag/0.0.1

README.rst

@@ -20,9 +20,19 @@ Install KiClearance directly from pyPI:
 Usage
 ---------------------------------------
 
-Create a table (clearance.ods/xls/csv) in your KiCad project directory with voltage clearances defined by your requirements (e.g. standards).
-Use this template as a guide: `clearance.ods <https://github.com/upb-lea/KiClearance/blob/main/examples/clearance.ods>`__.
+Create a table 'clearance.ods/xls/csv' containing clearance distances
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+Create a table (name it clearance.ods/xls/csv) in your KiCad project directory with voltage clearances defined by your requirements (e.g. standards).
+Download and use this template as a guide: `clearance.ods <https://github.com/upb-lea/KiClearance/blob/main/examples/clearance.ods>`__.
+
+The table contains the distances from a potential to another in ``mm``. The same net distance is optional.
+The default distance is ``0.15 mm``.
+
+.. image:: docs/source/figures/table.png
+
+Define net classes in your KiCad project
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Add the net classes to each connection in the circuit diagram.
 
 .. image:: docs/source/figures/net_class_directive_labels.png
@@ -32,21 +42,30 @@ Add the same net classes in the net classes of the PCB editor:
 
 .. image:: docs/source/figures/board_setup.png
 
+Run KiClearance
+~~~~~~~~~~~~~~~
+
 Navigate to the project folder with the KiCad project and the clearance.ods/.xls/.csv file. Open a terminal and execute :
 
 ::
 
     python -m kiclearance
 
-Now a file yourprojectname.kicad_dru is generated, which contains the rule sets.
+Now a file ``yourprojectname.kicad_dru`` is generated, which contains the rule sets.
+
+Open your KiCad project, the rule sets are now stored and you can start the routing.
+
+To see help and options, run
+
+::
 
-Open your Kicad project, the rule sets are now stored and you can start the routing.
+    python -m kiclearance --help
 
 Tips and tricks
 ---------------------------------------
 If two network classes are assigned to a connection by mistake, this is displayed as an error in the Electrical Rules Checker (``Inspect`` -> ``Electrical Rules Checker``).
 
-KiCad works through the rules from bottom to top:  Once an applicable rule has been found, kiCad will not search for further rules. Keep this in mind when adding your own rules. 
+KiCad works through the rules from bottom to top:  Once an applicable rule has been found, KiCad will not search for further rules. Keep this in mind when adding more own rules except from this script here.
 
 Example
 ---------------------------------------
@@ -59,6 +78,6 @@ Find the documentation `here <https://upb-lea.github.io/KiClearance/index.html>`
 
 Troubleshooting
 ---------------------------------------
-This program has so far been tested only on linux.
+This program has so far been tested only on Linux and Windows.
 
 

docs/source/conf.py

@@ -20,7 +20,7 @@
 project = 'kiclearance'
 copyright = '2024, UPB-LEA'
 author = 'UPB-LEA'
-release = '0.0.2'
+release = '0.1.0'
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 

examples/clearance_example.kicad_dru

@@ -1,36 +1,36 @@
 (version 1)
 # Auto-Generated for voltage distances - start
 (rule Default_Default_inner_outer
-	(constraint clearance (min "0.15mm"))
+	(constraint clearance (min "0.35mm"))
 	(condition "A.NetClass == 'Default' && B.NetClass == 'Default'"))
 (rule LV_Default_outer
 	(layer outer)
 	(constraint clearance (min "8.1mm"))
 	(condition "A.NetClass == 'LV' && B.NetClass == 'Default'"))
 (rule LV_Default_inner
 	(layer inner)
-	(constraint clearance (min "4.05mm"))
+	(constraint clearance (min "0.81mm"))
 	(condition "A.NetClass == 'LV' && B.NetClass == 'Default'"))
 (rule LV_LV_inner_outer
-	(constraint clearance (min "0.15mm"))
+	(constraint clearance (min "0.35mm"))
 	(condition "A.NetClass == 'LV' && B.NetClass == 'LV'"))
 (rule HV_Default_outer
 	(layer outer)
 	(constraint clearance (min "8.1mm"))
 	(condition "A.NetClass == 'HV' && B.NetClass == 'Default'"))
 (rule HV_Default_inner
 	(layer inner)
-	(constraint clearance (min "4.05mm"))
+	(constraint clearance (min "0.81mm"))
 	(condition "A.NetClass == 'HV' && B.NetClass == 'Default'"))
 (rule HV_LV_outer
 	(layer outer)
 	(constraint clearance (min "3.3mm"))
 	(condition "A.NetClass == 'HV' && B.NetClass == 'LV'"))
 (rule HV_LV_inner
 	(layer inner)
-	(constraint clearance (min "1.65mm"))
+	(constraint clearance (min "0.33mm"))
 	(condition "A.NetClass == 'HV' && B.NetClass == 'LV'"))
 (rule HV_HV_inner_outer
-	(constraint clearance (min "0.15mm"))
+	(constraint clearance (min "0.35mm"))
 	(condition "A.NetClass == 'HV' && B.NetClass == 'HV'"))
 # Auto-Generated - end

examples/clearance_example.kicad_pcb

@@ -2149,7 +2149,7 @@
 		(descr "LED SMD 0603 (1608 Metric), square (rectangular) end terminal, IPC_7351 nominal, (Body size source: http://www.tortai-tech.com/upload/download/2011102023233369053.pdf), generated with kicad-footprint-generator")
 		(tags "LED")
 		(property "Reference" "D1"
-			(at 2.7 0.1 360)
+			(at 2.7 0.1 0)
 			(layer "B.SilkS")
 			(uuid "1f6903c1-4170-440e-948a-37ba6d6b509f")
 			(effects
@@ -2161,7 +2161,7 @@
 			)
 		)
 		(property "Value" "LED"
-			(at 0 -1.43 360)
+			(at 0 -1.43 0)
 			(layer "B.Fab")
 			(uuid "0ddc1e33-e052-432d-bc89-aa84ddef9bca")
 			(effects
@@ -2337,7 +2337,7 @@
 			(uuid "b0d8b3c8-a33d-4d63-8e13-64597362c650")
 		)
 		(fp_text user "${REFERENCE}"
-			(at 0 0 360)
+			(at 0 0 0)
 			(layer "B.Fab")
 			(uuid "e0686616-cc9e-469a-a03a-3e9e2f19a329")
 			(effects
@@ -2604,4 +2604,102 @@
 		(net 7)
 		(uuid "d0b640e9-2890-4895-b6a9-bf7215d052b5")
 	)
+	(zone
+		(net 2)
+		(net_name "Net-(J1-Pin_1)")
+		(layer "B.Cu")
+		(uuid "54f12446-dd42-4adf-8387-e1b819530631")
+		(hatch edge 0.5)
+		(connect_pads
+			(clearance 0.5)
+		)
+		(min_thickness 0.25)
+		(filled_areas_thickness no)
+		(fill yes
+			(thermal_gap 0.5)
+			(thermal_bridge_width 0.5)
+		)
+		(polygon
+			(pts
+				(xy 129.7 52.4) (xy 102.8 52.3) (xy 102.8 66.3) (xy 129.7 66.3)
+			)
+		)
+		(filled_polygon
+			(layer "B.Cu")
+			(pts
+				(xy 129.576463 52.39954) (xy 129.643427 52.419473) (xy 129.688985 52.472447) (xy 129.7 52.523539)
+				(xy 129.7 52.8755) (xy 129.680315 52.942539) (xy 129.627511 52.988294) (xy 129.576 52.9995) (xy 124.148572 52.9995)
+				(xy 123.81446 52.9995) (xy 123.716216 53.009176) (xy 123.48196 53.032248) (xy 123.154286 53.097424)
+				(xy 123.154275 53.097427) (xy 122.834538 53.194418) (xy 122.525868 53.322273) (xy 122.525854 53.32228)
+				(xy 122.333839 53.424913) (xy 122.333839 53.424914) (xy 122.27491 53.456412) (xy 122.231204 53.479774)
+				(xy 122.231194 53.47978) (xy 121.953406 53.665393) (xy 121.953392 53.665403) (xy 121.69512 53.877361)
+				(xy 120.09861 55.473873) (xy 119.862361 55.71012) (xy 119.650403 55.968392) (xy 119.650393 55.968406)
+				(xy 119.464779 56.246195) (xy 119.444303 56.284503) (xy 119.444302 56.284502) (xy 119.30728 56.540854)
+				(xy 119.307278 56.540859) (xy 119.179419 56.849534) (xy 119.082428 57.16927) (xy 119.057979 57.292189)
+				(xy 119.038499 57.390125) (xy 119.01725 57.49695) (xy 119.017247 57.496967) (xy 118.9845 57.829463)
+				(xy 118.9845 58.653459) (xy 118.964815 58.720498) (xy 118.912011 58.766253) (xy 118.842853 58.776197)
+				(xy 118.799687 58.760624) (xy 118.799473 58.761045) (xy 118.796124 58.759338) (xy 118.795723 58.759194)
+				(xy 118.795143 58.758839) (xy 118.795133 58.758834) (xy 118.795132 58.758833) (xy 118.635881 58.677691)
+				(xy 118.635878 58.677689) (xy 118.465899 58.62246) (xy 118.348209 58.60382) (xy 118.289366 58.5945)
+				(xy 117.390634 58.5945) (xy 117.33179 58.60382) (xy 117.214101 58.62246) (xy 117.214098 58.62246)
+				(xy 117.044121 58.677689) (xy 117.044118 58.677691) (xy 116.884867 58.758833) (xy 116.74027 58.86389)
+				(xy 116.61389 58.99027) (xy 116.508833 59.134867) (xy 116.469637 59.211795) (xy 116.421663 59.262591)
+				(xy 116.359152 59.2795) (xy 113.310889 59.2795) (xy 113.24385 59.259815) (xy 113.203503 59.217501)
+				(xy 113.191862 59.197339) (xy 113.19186 59.197336) (xy 113.072235 59.064478) (xy 113.072232 59.064476)
+				(xy 113.072231 59.064475) (xy 113.07223 59.064474) (xy 112.927593 58.959388) (xy 112.764267 58.886671)
+				(xy 112.764265 58.88667) (xy 112.636594 58.859533) (xy 112.589391 58.8495) (xy 112.410609 58.8495)
+				(xy 112.379954 58.856015) (xy 112.235733 58.88667) (xy 112.235728 58.886672) (xy 112.072408 58.959387)
+				(xy 111.927768 59.064475) (xy 111.80814 59.197336) (xy 111.71875 59.352164) (xy 111.718747 59.35217)
+				(xy 111.663504 59.522192) (xy 111.663503 59.522194) (xy 111.644815 59.7) (xy 111.663503 59.877805)
+				(xy 111.663504 59.877807) (xy 111.69345 59.969971) (xy 111.695445 60.039812) (xy 111.659365 60.099645)
+				(xy 111.649832 60.107554) (xy 111.642816 60.112806) (xy 111.642808 60.112814) (xy 111.556649 60.227906)
+				(xy 111.556645 60.227913) (xy 111.506403 60.36262) (xy 111.506401 60.362627) (xy 111.5 60.422155)
+				(xy 111.5 60.72) (xy 112.290382 60.72) (xy 112.239936 60.770446) (xy 112.197149 60.844555) (xy 112.175 60.927213)
+				(xy 112.175 61.012787) (xy 112.197149 61.095445) (xy 112.239936 61.169554) (xy 112.300446 61.230064)
+				(xy 112.374555 61.272851) (xy 112.457213 61.295) (xy 112.542787 61.295) (xy 112.625445 61.272851)
+				(xy 112.699554 61.230064) (xy 112.760064 61.169554) (xy 112.802851 61.095445) (xy 112.825 61.012787)
+				(xy 112.825 60.927213) (xy 112.802851 60.844555) (xy 112.760064 60.770446) (xy 112.709618 60.72)
+				(xy 113.5 60.72) (xy 113.5 60.422172) (xy 113.499999 60.422155) (xy 113.493598 60.362627) (xy 113.493596 60.362619)
+				(xy 113.488082 60.347835) (xy 113.483096 60.278144) (xy 113.51658 60.21682) (xy 113.577903 60.183334)
+				(xy 113.604263 60.1805) (xy 116.359152 60.1805) (xy 116.426191 60.200185) (xy 116.469637 60.248205)
+				(xy 116.508833 60.325132) (xy 116.613889 60.469728) (xy 116.740272 60.596111) (xy 116.884868 60.701167)
+				(xy 117.044119 60.782309) (xy 117.044121 60.78231) (xy 117.20267 60.833825) (xy 117.214103 60.83754)
+				(xy 117.390634 60.8655) (xy 117.390635 60.8655) (xy 118.289365 60.8655) (xy 118.289366 60.8655)
+				(xy 118.465897 60.83754) (xy 118.4659 60.837539) (xy 118.465901 60.837539) (xy 118.635878 60.78231)
+				(xy 118.635878 60.782309) (xy 118.635881 60.782309) (xy 118.795132 60.701167) (xy 118.795137 60.701163)
+				(xy 118.795706 60.700815) (xy 118.795954 60.700747) (xy 118.799473 60.698955) (xy 118.799849 60.699693)
+				(xy 118.863152 60.682568) (xy 118.929755 60.703682) (xy 118.97437 60.757452) (xy 118.9845 60.80654)
+				(xy 118.9845 61.317944) (xy 118.9845 61.652056) (xy 118.990413 61.712093) (xy 119.017247 61.984546)
+				(xy 119.017248 61.984553) (xy 119.017249 61.984559) (xy 119.044642 62.122279) (xy 119.038415 62.191869)
+				(xy 118.995551 62.247046) (xy 118.929661 62.27029) (xy 118.89488 62.265629) (xy 118.894607 62.266906)
+				(xy 118.887988 62.265488) (xy 118.785327 62.255) (xy 118.09 62.255) (xy 118.09 63.217243) (xy 118.088676 63.215919)
+				(xy 117.996324 63.1626) (xy 117.893319 63.135) (xy 117.786681 63.135) (xy 117.683676 63.1626) (xy 117.591324 63.215919)
+				(xy 117.59 63.217243) (xy 117.59 62.255) (xy 116.894672 62.255) (xy 116.792011 62.265488) (xy 116.792011 62.265489)
+				(xy 116.625668 62.320609) (xy 116.625657 62.320614) (xy 116.476521 62.412603) (xy 116.476517 62.412606)
+				(xy 116.352606 62.536517) (xy 116.352603 62.536521) (xy 116.260614 62.685657) (xy 116.260609 62.685668)
+				(xy 116.205489 62.852011) (xy 116.205488 62.852011) (xy 116.195 62.954672) (xy 116.195 63.29) (xy 117.517243 63.29)
+				(xy 117.515919 63.291324) (xy 117.4626 63.383676) (xy 117.435 63.486681) (xy 117.435 63.593319)
+				(xy 117.4626 63.696324) (xy 117.515919 63.788676) (xy 117.517243 63.79) (xy 116.195 63.79) (xy 116.195 64.125327)
+				(xy 116.205488 64.227988) (xy 116.260609 64.394331) (xy 116.260614 64.394342) (xy 116.352603 64.543478)
+				(xy 116.352606 64.543482) (xy 116.476517 64.667393) (xy 116.476521 64.667396) (xy 116.625657 64.759385)
+				(xy 116.625668 64.75939) (xy 116.792011 64.81451) (xy 116.792011 64.814511) (xy 116.894672 64.824999)
+				(xy 116.894685 64.825) (xy 117.59 64.825) (xy 117.59 63.862757) (xy 117.591324 63.864081) (xy 117.683676 63.9174)
+				(xy 117.786681 63.945) (xy 117.893319 63.945) (xy 117.996324 63.9174) (xy 118.088676 63.864081)
+				(xy 118.09 63.862757) (xy 118.09 64.825) (xy 118.562943 64.825) (xy 118.629982 64.844685) (xy 118.675737 64.897489)
+				(xy 118.685681 64.966647) (xy 118.656656 65.030203) (xy 118.638429 65.047376) (xy 118.494876 65.157527)
+				(xy 118.091193 65.511547) (xy 117.33906 66.263681) (xy 117.277737 66.297166) (xy 117.251379 66.3)
+				(xy 102.924 66.3) (xy 102.856961 66.280315) (xy 102.811206 66.227511) (xy 102.8 66.176) (xy 102.8 61.517844)
+				(xy 111.5 61.517844) (xy 111.506401 61.577372) (xy 111.506403 61.577379) (xy 111.556645 61.712086)
+				(xy 111.556649 61.712093) (xy 111.642809 61.827187) (xy 111.642812 61.82719) (xy 111.757906 61.91335)
+				(xy 111.757913 61.913354) (xy 111.89262 61.963596) (xy 111.892627 61.963598) (xy 111.952155 61.969999)
+				(xy 111.952172 61.97) (xy 112.25 61.97) (xy 112.75 61.97) (xy 113.047828 61.97) (xy 113.047844 61.969999)
+				(xy 113.107372 61.963598) (xy 113.107379 61.963596) (xy 113.242086 61.913354) (xy 113.242093 61.91335)
+				(xy 113.357187 61.82719) (xy 113.35719 61.827187) (xy 113.44335 61.712093) (xy 113.443354 61.712086)
+				(xy 113.493596 61.577379) (xy 113.493598 61.577372) (xy 113.499999 61.517844) (xy 113.5 61.517827)
+				(xy 113.5 61.22) (xy 112.75 61.22) (xy 112.75 61.97) (xy 112.25 61.97) (xy 112.25 61.22) (xy 111.5 61.22)
+				(xy 111.5 61.517844) (xy 102.8 61.517844) (xy 102.8 52.424461) (xy 102.819685 52.357422) (xy 102.872489 52.311667)
+				(xy 102.924457 52.300462)
+			)
+		)
+	)
 )

examples/clearance_example.kicad_sch

@@ -994,6 +994,17 @@
 		)
 		(uuid "c30432b7-0855-4ee4-979d-3a35bde87e77")
 	)
+	(label "trial#"
+		(at 132.08 86.36 0)
+		(fields_autoplaced yes)
+		(effects
+			(font
+				(size 1.27 1.27)
+			)
+			(justify left bottom)
+		)
+		(uuid "f83a7cf7-a3a4-4848-b348-545a8def3b7f")
+	)
 	(netclass_flag ""
 		(length 2.54)
 		(shape round)

kiclearance/__main__.py

@@ -10,7 +10,7 @@
 
 # Parse command line arguments
 try:
-    opts, args = getopt.getopt(sys.argv[1:], "hf:n:t:", ["help", "project_folder=", "project_name=", "table_file="])
+    opts, args = getopt.getopt(sys.argv[1:], "hf:n:t:i:d:", ["help", "project_folder=", "project_name=", "table_file=, 'factor_inner_layers=", "min_track_distance="])
 except getopt.GetoptError as err:
     print(err)
     usage()
@@ -26,9 +26,13 @@
         project_name = a
     elif o in ("-t", "--table_file_name"):
         table_name = a
+    elif o in ("-i", "factor_inner_layers"):
+        factor_inner_layers = float(a)
+    elif o in ("-d", "min_track_distance"):
+        min_track_distance = float(a)
 
 # Run script
 table_file = look_for_clearance_table_file(project_folder, table_name)
 project_name = look_for_kicad_project(project_folder, project_name)
 table_data = parse_excel_table(table_file)
-write_design_rule_file(table_data, project_folder, project_name)
+write_design_rule_file(table_data, project_folder, project_name, factor_inner_layers=factor_inner_layers, min_track_distance=min_track_distance)

kiclearance/kiclearance.py

@@ -7,8 +7,7 @@
 import numpy as np
 
 
-def write_design_rule_file(clearance_table_data, folder, kicad_project_name: str, factor_inner_layers: float = 0.5,
-                           min_track_distance: float = 0.15):
+def write_design_rule_file(clearance_table_data, folder, kicad_project_name: str, factor_inner_layers: float, min_track_distance: float):
     """
     Write the rules to the design rule file (your_project.kicad_dru).
 
@@ -26,6 +25,11 @@ def write_design_rule_file(clearance_table_data, folder, kicad_project_name: str
     :type folder: str
 
     """
+    if factor_inner_layers is None:
+        factor_inner_layers = 0.5
+    if min_track_distance is None:
+        min_track_distance = 0.15
+
     start_comment = "# Auto-Generated for voltage distances - start"
     end_comment = "# Auto-Generated - end"
 
@@ -202,36 +206,12 @@ def usage():
             -h, --help: Prints this information,\n\
             -f, --project_folder (Optional): Path to the folder in which the project is located. Default: Folder in which this python script is located.\n\
             -n, --project_name (Optional): Name of the kicad project (file prefix). Default: Script will look for a file with .kicad_pro in the set folder.\n\
-            -t, --table_file (Optional): Name (and ending) of the file containing the distance values. Default name: 'clearance'."
+            -t, --table_file (Optional): Name (and ending) of the file containing the distance values. Default name: 'clearance'.\n\
+            -fi, --factor_inner_layers (Optional): Reduced factor for the inner layers. Default: 0.5\n\
+            -td, --min_track_distance (Optional): minimum track distance between two tracks on the same potential. Default: 0.15 mm."
+
     print(text)
 
 
 if __name__ == "__main__":
-    project_folder = os.path.dirname(os.path.realpath(__file__))
-    table_name = None
-    project_name = None
-
-    # Parse command line arguments
-    try:
-        opts, args = getopt.getopt(sys.argv[1:], "hf:n:t:", ["help", "project_folder=", "project_name=", "table_file="])
-    except getopt.GetoptError as err:
-        print(err)
-        usage()
-        sys.exit(2)
-
-    for o, a in opts:
-        if o in ("-h", "--help"):
-            usage()
-            sys.exit()
-        elif o in ("-f", "--project_folder"):
-            project_folder = a
-        elif o in ("-n", "--project_name"):
-            project_name = a
-        elif o in ("-t", "--table_file_name"):
-            table_name = a
-
-    # Run script
-    table_file = look_for_clearance_table_file(project_folder, table_name)
-    project_name = look_for_kicad_project(project_folder, project_name)
-    table_data = parse_excel_table(table_file)
-    write_design_rule_file(table_data, project_folder, project_name)
+    pass

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kiclearance"
-version = "0.0.2"
+version = "0.1.0"
 authors = [
     { name = "UPB-LEA" },
 ]