helpers.stanza

; ====================
; A number of helpful functions to check your designs, export to CAD, 
; update your design in CAD, etc.
; ====================
#use-added-syntax(jitx)
defpackage helpers :
  import core
  import jitx
  import jitx/commands
  import ocdb/utils/checks
  import ocdb/utils/generic-components
  import ocdb/utils/generator-utils
  import ocdb/utils/property-structs
  ; import ocdb/utils/bundles
  ; import ocdb/utils/defaults
  import ocdb/utils/design-vars

  import jsl/bundles

;==== Materials ================================================================

pcb-material copper :
  type = Conductor
  name = "Copper"

pcb-material core-45 :
  type = Dielectric
  dielectric-coefficient = 4.5
  name = "4.5 DK FR4 Core"

pcb-material soldermask :
  type = Dielectric
  dielectric-coefficient = 3.9
  name = "Taiyo BSN4000"

; see https://jlcpcb.com/capabilities/pcb-capabilities
; for more details on PCB design rules
public pcb-rules new-jlcpcb-basic-rules :
  min-copper-width = 0.100 ; 3.5mil ; 0.100 for 1 or 2-copper-layer designs
  min-copper-copper-space = 0.100 ; 3.5mil ; 0.100 for 1 or 2-copper-layer designs
  min-copper-hole-space = 0.200 ; 8 mil
  min-copper-edge-space = 0.2 ; 7.87mil
  min-annular-ring = 0.180 ; 
  min-drill-diameter = 0.3 ; 7.87mil
  min-silkscreen-width = 0.153 ; 6mil
  min-pitch-leaded = 0.3 ; 11.81mil (guess)
  min-pitch-bga = 0.377 ; 14.84mil
  max-board-width = 670.0 ; 15.74in
  max-board-height = 600.0 ; 19.68in
  min-silk-solder-mask-space = 0.15
  min-silkscreen-text-height = 1.00
  solder-mask-registration = 0.038
  min-th-pad-expand-outer = 0.26 
  min-soldermask-opening = 0.10 ; solder bridge - solder mask opening/expansion DIAMETER
  min-soldermask-bridge = 0.1 ; green
  min-hole-to-hole = 0.2
  min-pth-pin-solder-clearance = 3.0 ; TODO: lookup actual value

public pcb-via regular-via :
  name = "Regular TH"     
  start = LayerIndex(0, Top)
  stop = LayerIndex(0, Bottom)
  diameter = 0.66
  hole-diameter = 0.3
  type = MechanicalDrill

public pcb-via small-via :
  name = "Minimum TH"     
  start = LayerIndex(0, Top)
  stop = LayerIndex(0, Bottom)
  val annular = 0.18
  val drill = 0.3
  diameter = drill + annular * 2.0
  hole-diameter = drill
  type = MechanicalDrill

public pcb-stackup new-jlcpcb-2-layer :
  name = "JLCPCB 2-layer 1.6mm"
  stack(0.019, soldermask) ; 0.5mil over conductor
  stack(0.035, copper) 
  stack(1.5, core-45)
  stack(0.035, copper) 
  stack(0.019, soldermask) ; 0.5mil over conductor

; Creates a pcb-board with default stackup given the number of layers and board outline.
public pcb-board motion-detector-board (outline:Shape) :
  stackup = new-jlcpcb-2-layer
  boundary = outline
  signal-boundary = outline
  vias = [regular-via small-via]

; =====================
; Setup the board
; =====================
public defn setup-board (board-shape:Shape) :
  set-board(motion-detector-board(board-shape))
  set-rules(new-jlcpcb-basic-rules)
  set-use-layout-groups()
  set-export-backend(`altium) ; set the CAD software for export to be `altium or `kicad)

; =====================
; Run the design checks
; =====================
public defn run-check-on-design (circuit:Instantiable) :
  val main-module = ocdb/utils/generator-utils/run-final-passes(circuit) ; Analyze design with a pass
  set-main-module(main-module) ; Treat the provided module as a design, and compile it.
  run-checks("checks.txt")

; ====================
; Actual Export design
; ====================
public defn export-to-cad () :
  export-cad()

; ====================
; Export design to CAD
; ====================
public defn export-design () :
  set-export-board?(true)
  export-to-cad()

; ===================================
; Update CAD, keeping layout progress
; ===================================
public defn update-design () :
  set-export-board?(false)
  export-to-cad()

; =================
; Setup BOM stuff
; =================
public defn setup-bill-of-materials (qty:Int, vendors:String) :
  set-bom-metrics([
    BOMMetric(BOMMetricLineItems, "Line Items"),
    BOMMetric(BOMMetricComponentCount, "Components"),
    BOMMetric(BOMMetricTotalCost, "Cost")
  ])
  ; BOMField
  ; jitx/BOMFieldStatus
  ; jitx/BOMFieldDescription
  ; jitx/BOMFieldInsts
  ; jitx/BOMFieldDatasheet
  ; jitx/BOMFieldManufacturer
  ; jitx/BOMFieldMPN
  ; jitx/BOMFieldVendor
  ; jitx/BOMFieldSKU
  ; jitx/BOMFieldQuantity
  ; jitx/BOMFieldPrice
  ; jitx/BOMFieldSubtotal
  ; jitx/BOMFieldPreferred
  set-bom-columns([
    BOMColumn(BOMFieldStatus, "Status", 10.0)
    BOMColumn(BOMFieldQuantity, "Qty", 5.0)
    BOMColumn(BOMFieldInsts, "References", 10.0)
    BOMColumn(BOMFieldMPN, "MPN", 10.0)
    BOMColumn(BOMFieldManufacturer, "Manufacturer", 10.0)
    BOMColumn(BOMFieldDescription, "Description", 20.0)
    BOMColumn(BOMFieldVendor, "Supplier", 10.0)
    BOMColumn(BOMFieldSKU, "SKU", 10.0)
    BOMColumn(BOMFieldDatasheet, "Datasheet", 10.0)
  ])

  APPROVED-DISTRIBUTOR-LIST = [vendors]
  set-bom-vendors([vendors])
  DESIGN-QUANTITY = qty
  set-bom-design-quantity(qty)

public defn bom-view-export () :
  view-bom(BOM-STD)
  export-bom()



doc: \<DOC>
The pcb-routing-structure(s) below are just examples of the routing structures that need to be maintained
in the project code because they are dependant on the stack-up and other factors.
<DOC>
public pcb-routing-structure rf-constraint :
  name = "50 Ohm RF single-ended routing structure"
  layer-constraints(Top) :
    trace-width = 0.500  ; mm
    clearance   = 0.200  ; mm
    velocity = 0.19e12   ; mm/s
    insertion-loss = 0.008  ; db/mm @ 1GHz
    neck-down = NeckDown(
      trace-width = 0.127
      clearance = 0.127
    )

doc: \<DOC>
@brief Apply the RF routing structure to a signal.
The function applies the provided pcb-routing-structure
to the signal between the start and endpoint. Note that both start and end points
need to be connected to physical component pins either directly or via pin assignment.
<DOC>

public defn rf-routing-structure (rs:RoutingStructure, x:JITXObject, y:JITXObject) :
  inside pcb-module :
    structure(x => y) = rs

public defn setup-supply-rail (pwr : JITXObject, supply-V : Toleranced) :
  inside pcb-module:
    public net VDD (pwr.V+)
    public net GND (pwr.V-)
    symbol(GND) = ocdb/utils/symbols/ground-sym
    symbol(VDD) = ocdb/utils/symbols/supply-sym
    property(GND.voltage) = typ(0.0)
    property(VDD.voltage) = supply-V
    ; use routing structure instead of net=class property here

    ; property(VDD.net-class) = NetClass(`Vdd, [`min-trace => 0.250])


; 50 ohm line on a 1.5mm h CBCPW

; public val CBCPW = NetClass(`ANT, [`min-trace => 0.5 `min-space => 0.2])

; via stitching function
public defn via-stitch (board-shape, connection) :
  inside pcb-module :
    ; board edge stitching vias
    val x-span = width(board-shape)
    val y-span = height(board-shape)

    val bot-y-coord = -1.0 * y-span / 2.0 + 0.595
    val bot-x-coord-start = -1.0 * x-span / 2.0 + 0.7
    val num-vias-bottom = to-int((x-span - 5.0 - 1.0))
    for x in 0 to num-vias-bottom do :
      val x-d = to-double(x)
      geom(connection) :
        via(small-via) at Point(bot-x-coord-start + x-d, bot-y-coord)

    val num-vias-left = to-int((y-span - 2.0))
    val left-x-coord = -1.0 * x-span / 2.0 + 0.594
    val bot-y-coord-start = -1.0 * y-span / 2.0 + 1.5
    for y in 0 to num-vias-left do :
      val y-d = to-double(y)
      geom(connection) :
        via(small-via) at Point(left-x-coord, bot-y-coord-start + y-d)

    val top-y-coord = y-span / 2.0 - 0.595
    val top-x-coord-start = -1.0 * x-span / 2.0 + 1.5
    val num-vias-top = to-int((x-span - 5.0 - 2.0)) - 1
    for x in 0 to num-vias-top do :
      val x-d = to-double(x)
      geom(connection) :
        via(small-via) at Point(top-x-coord-start + x-d, top-y-coord)


; ========================================================
; =================== Indicators =========================
; ========================================================

; 50 - 200 mcd for daylight
; 4 - 10 mcd for indoor

; Adds an RGB led to a processor using PWM pins
public defn rgb-indicator (brightness:Double, proc:JITXObject, vin:JITXObject):
  inside pcb-module:
    pcb-module rgb-indicator :
      port control-pins : timer[3]
      val vio = 3.3
      ; Calculate resistance to get appropriate brightness
      defn calc-r (l:JITXObject, brightness:Double, vio:Double):
        val i = PWL(property(l.mcd-current))[brightness]
        closest-std-val((vio - property(l.forward-voltage)) / i, 5.0)
      public inst led : components/Foshan-NationStar-Optoelectronics/FM-B2020RGBA-HG/component ;
      
      res-strap(control-pins[0].timer, led.led.r, calc-r(led.led.r, brightness, vio))
      res-strap(control-pins[1].timer, led.led.g, calc-r(led.led.g, brightness, vio))
      res-strap(control-pins[2].timer, led.led.b, calc-r(led.led.b, brightness, vio))

    inst rgb:rgb-indicator
    require control-pins:timer[3] from proc
    net (vin, rgb.led.led.a)
    net (control-pins rgb.control-pins)
    rgb


; Add load balancing caps to crystal oscillator
public defn add-xtal-load-caps (xtal:JITXObject, gnd:JITXObject, stray-capacitance:Double) :
  inside pcb-module:
    val c-load = load-capacitance(property(xtal.crystal-resonator))
    val c-bal = closest-std-val(2.0 * (c-load - stray-capacitance), 5.0)
    cap-strap(xtal.OSC1, gnd, ["capacitance" => c-bal "temperature-coefficient.code" => "C0G" ])
    val c = cap-strap(xtal.OSC2, gnd, ["capacitance" => c-bal "temperature-coefficient.code" => "C0G" ])
    c 
; Default stray capacitance assumed 5pf. 
public defn add-xtal-load-caps (xtal:JITXObject, gnd:JITXObject) :
  add-xtal-load-caps(xtal, gnd, 5.0e-12)