---
# The chip's hardware in one file: package, pins, the driver hook of each pin, the blocks inside, and the reference
# circuits. `kokeb-docs figures` draws the pinout, the block diagram and the circuits from it, `kokeb-docs gen` writes
# the pin and parts tables on docs/hardware.md, `kokeb-docs hardware --check` validates it and
# `kokeb-docs hardware --kicad-netlist OUT --circuit typical` exports a circuit for a schematic or PCB tool.
# Schema: docs/chip-diagrams.md in kokeb-labs/ci-tools.
#
# Every fact cites the PCA9685 data sheet (Rev. 4), listed in docs/datasheets.yml. Pin numbers are the TSSOP28 ones;
# the HVQFN28 package has other numbers (table 3 gives both) and an exposed pad that is VSS. Its numbers are in
# each pin's function, as "HVQFN28 pin n".
schema: 1
chip: PCA9685

refs:
  blocks: {doc: pca9685, section: "5 Block diagram, Figure 1", page: 5}
  pinout: {doc: pca9685, section: "6.1 Pinning, Figure 2", page: 6}
  pins: {doc: pca9685, section: "6.2 Pin description, Table 3", page: 6}
  pins2: {doc: pca9685, section: "6.2 Pin description, Table 3 (continued)", page: 7}
  address: {doc: pca9685, section: "7.1.1 Regular I2C-bus slave address, Figure 4", page: 7}
  allcall: {doc: pca9685, section: "7.1.2 LED All Call I2C-bus address", page: 8}
  mode1: {doc: pca9685, section: "7.3.1 Mode register 1, MODE1", page: 14}
  outputs: {doc: pca9685, section: "7.3.3 LED output and PWM control", page: 16}
  prescale: {doc: pca9685, section: "7.3.5 PWM frequency PRE_SCALE", page: 25}
  oe: {doc: pca9685, section: "7.4 Active LOW output enable input", page: 27}
  por: {doc: pca9685, section: "7.5 Power-on reset", page: 27}
  drivers: {doc: pca9685, section: "7.7 Using the PCA9685 with and without external drivers", page: 29}
  app: {doc: pca9685, section: "10 Application design-in information, Figure 26", page: 35}
  static: {doc: pca9685, section: "12 Static characteristics, Table 14", page: 38}
  dynamic: {doc: pca9685, section: "13 Dynamic characteristics, Table 15", page: 40}

package:
  type: TSSOP-28
  pins: 28
  ref: pinout

hooks:
  - {id: i2c, call: "Write() / WriteRead()", kind: i2c, source: inc/pca9685_i2c_interface.hpp, symbol: WriteRead}
  - {id: oe, call: "GpioSet(CtrlPin::OutputEnable)", kind: gpio-out, source: inc/pca9685_i2c_interface.hpp,
     symbol: OutputEnable}

pins:
  - {number: 1, name: A0, type: digital-in, domain: VDD,
     function: "Address input 0, no internal pull-up; tie to VDD or VSS (HVQFN28 pin 26)", unused: Never open,
     ref: address}
  - {number: 2, name: A1, type: digital-in, domain: VDD,
     function: "Address input 1, no internal pull-up; tie to VDD or VSS (HVQFN28 pin 27)", unused: Never open,
     ref: address}
  - {number: 3, name: A2, type: digital-in, domain: VDD,
     function: "Address input 2, no internal pull-up; tie to VDD or VSS (HVQFN28 pin 28)", unused: Never open,
     ref: address}
  - {number: 4, name: A3, type: digital-in, domain: VDD,
     function: "Address input 3, no internal pull-up; tie to VDD or VSS (HVQFN28 pin 1)", unused: Never open,
     ref: address}
  - {number: 5, name: A4, type: digital-in, domain: VDD,
     function: "Address input 4, no internal pull-up; tie to VDD or VSS (HVQFN28 pin 2)", unused: Never open,
     ref: address}
  - {number: 6, name: LED0, type: power-out, domain: VDD, function: "Output of channel 0 (HVQFN28 pin 3)",
     unused: Leave open, ref: pins}
  - {number: 7, name: LED1, type: power-out, domain: VDD, function: "Output of channel 1 (HVQFN28 pin 4)",
     unused: Leave open, ref: pins}
  - {number: 8, name: LED2, type: power-out, domain: VDD, function: "Output of channel 2 (HVQFN28 pin 5)",
     unused: Leave open, ref: pins}
  - {number: 9, name: LED3, type: power-out, domain: VDD, function: "Output of channel 3 (HVQFN28 pin 6)",
     unused: Leave open, ref: pins}
  - {number: 10, name: LED4, type: power-out, domain: VDD, function: "Output of channel 4 (HVQFN28 pin 7)",
     unused: Leave open, ref: pins}
  - {number: 11, name: LED5, type: power-out, domain: VDD, function: "Output of channel 5 (HVQFN28 pin 8)",
     unused: Leave open, ref: pins}
  - {number: 12, name: LED6, type: power-out, domain: VDD, function: "Output of channel 6 (HVQFN28 pin 9)",
     unused: Leave open, ref: pins}
  - {number: 13, name: LED7, type: power-out, domain: VDD, function: "Output of channel 7 (HVQFN28 pin 10)",
     unused: Leave open, ref: pins}
  - {number: 14, name: VSS, type: ground, domain: VSS,
     function: "Ground; up to 400 mA in all (HVQFN28 pin 11 and the exposed pad)", ref: pins}
  - {number: 15, name: LED8, type: power-out, domain: VDD, function: "Output of channel 8 (HVQFN28 pin 12)",
     unused: Leave open, ref: pins}
  - {number: 16, name: LED9, type: power-out, domain: VDD, function: "Output of channel 9 (HVQFN28 pin 13)",
     unused: Leave open, ref: pins}
  - {number: 17, name: LED10, type: power-out, domain: VDD, function: "Output of channel 10 (HVQFN28 pin 14)",
     unused: Leave open, ref: pins}
  - {number: 18, name: LED11, type: power-out, domain: VDD, function: "Output of channel 11 (HVQFN28 pin 15)",
     unused: Leave open, ref: pins}
  - {number: 19, name: LED12, type: power-out, domain: VDD, function: "Output of channel 12 (HVQFN28 pin 16)",
     unused: Leave open, ref: pins2}
  - {number: 20, name: LED13, type: power-out, domain: VDD, function: "Output of channel 13 (HVQFN28 pin 17)",
     unused: Leave open, ref: pins2}
  - {number: 21, name: LED14, type: power-out, domain: VDD, function: "Output of channel 14 (HVQFN28 pin 18)",
     unused: Leave open, ref: pins2}
  - {number: 22, name: LED15, type: power-out, domain: VDD, function: "Output of channel 15 (HVQFN28 pin 19)",
     unused: Leave open, ref: pins2}
  - {number: 23, name: OE, type: digital-in, domain: VDD,
     function: "Output enable, active low; high sets every output to the OUTNE level (HVQFN28 pin 20)", hook: oe,
     unused: Tie to VSS, ref: oe}
  - {number: 24, name: A5, type: digital-in, domain: VDD,
     function: "Address input 5, no internal pull-up; tie to VDD or VSS (HVQFN28 pin 21)", unused: Never open,
     ref: address}
  - {number: 25, name: EXTCLK, type: digital-in, domain: VDD,
     function: "External clock input, DC to 50 MHz (HVQFN28 pin 22)", unused: Tie to VSS, ref: pins2}
  - {number: 26, name: SCL, type: bus, domain: VDD,
     function: "I2C clock, up to 1 MHz; pull-up to the bus supply (HVQFN28 pin 23)", hook: i2c, ref: dynamic}
  - {number: 27, name: SDA, type: bus, domain: VDD,
     function: "I2C data; pull-up to the bus supply (HVQFN28 pin 24)", hook: i2c, ref: pins2}
  - {number: 28, name: VDD, type: power, domain: VDD, function: "Supply, 2.3 V to 5.5 V (HVQFN28 pin 25)",
     ref: static}

block_diagram:
  ref: blocks
  blocks:
    - {id: filter, label: Input filter, detail: "SCL and SDA", at: [0, 0], tone: blue, pins: [SCL, SDA]}
    - {id: i2c, label: I2C-bus control, detail: "address 1 A5 A4 A3 A2 A1 A0", at: [0, 1], tone: blue,
       pins: [A0, A1, A2, A3, A4, A5]}
    - {id: por, label: Power-on reset, detail: "every register to its reset value", at: [0, 2], tone: slate,
       pins: [VDD, VSS], ref: por}
    - {id: osc, label: Clock switch, detail: "25 MHz oscillator or EXTCLK", at: [0, 3], tone: amber,
       pins: [EXTCLK], ref: mode1}
    - {id: prescale, label: Prescale, detail: "PRE_SCALE, 3 to 255", at: [1, 3], tone: amber, ref: prescale}
    - {id: pwm, label: PWM registers, detail: "ON and OFF counts, 12-bit, per channel", at: [1, 1], tone: violet,
       ref: outputs}
    - {id: mux0, label: MUX/control 0 to 7, detail: "full ON, full OFF or PWM", at: [2, 0], tone: violet,
       side: right, ref: outputs, pins: [LED0, LED1, LED2, LED3, LED4, LED5, LED6, LED7]}
    - {id: mux1, label: MUX/control 8 to 15, detail: "INVRT, OUTDRV from MODE2", at: [2, 1], tone: violet,
       side: right, ref: outputs, pins: [LED8, LED9, LED10, LED11, LED12, LED13, LED14, LED15]}
    - {id: oe, label: Output enable, detail: "OE high: every output to OUTNE", at: [2, 3], tone: rose, side: right,
       pins: [OE], ref: oe}
  links:
    - {from: filter, to: i2c, label: "SCL, SDA", both: true}
    - {from: i2c, to: pwm, label: registers, both: true}
    - {from: osc, to: prescale, label: clock}
    - {from: prescale, to: pwm, label: count}
    - {from: pwm, to: mux0, label: PWM}
    - {from: pwm, to: mux1, label: PWM}
    - {from: oe, to: mux1, label: enable}

circuits:
  - id: typical
    title: Typical application
    description: >-
      Part of the data sheet's figure 26: the PCA9685 on an MCU's I2C bus with pull-ups on SDA and SCL, OE on an MCU
      output with a 10 kΩ pull-up, EXTCLK and A0 to A5 tied to VSS (address 0x40, where figure 26 straps 0x55), and
      LED0 sinking one LED from 5 V through its resistor. With the LED from the supply the output is active low,
      so it takes DirectLedPreset() (open drain, inverted). Figure 26 drives the other outputs through transistors,
      which this schematic leaves out; LED1 to LED15 are open here.
    ref: app
    parts:
      - {id: U1, kind: chip}
      - id: U2
        kind: mcu
        label: MCU
        pins:
          - {name: SCL, label: I2C SCL}
          - {name: SDA, label: I2C SDA}
          - {name: OE, label: GPIO (OE)}
          - VDD
          - GND
      - {id: R1, kind: resistor, value: 4.7 kΩ,
         unverified: "figure 26 leaves the value to UM10204 section 7; 4.7 kΩ suits 100 kHz and 400 kHz"}
      - {id: R2, kind: resistor, value: 4.7 kΩ,
         unverified: "figure 26 leaves the value to UM10204 section 7; 4.7 kΩ suits 100 kHz and 400 kHz"}
      - {id: R3, kind: resistor, value: 10 kΩ, ref: app}
      - {id: C1, kind: capacitor, value: 100 nF,
         unverified: "figure 26 shows no decoupling capacitor; section 10, question 2 advises one near the chip"}
      - {id: R4, kind: resistor, value: 150 Ω,
         unverified: "figure 26 gives no value; 150 Ω is about 20 mA for a 2 V LED from 5 V, under the 25 mA limit"}
      - {id: D1, kind: led, ref: app}
      - {id: J1, kind: connector, label: 5 V supply, ref: app, pins: [5V, GND]}
    nets:
      - {name: "+3V3", kind: supply, nodes: [U1.VDD, U2.VDD, C1.1, R1.1, R2.1, R3.1]}
      - {name: "+5V", kind: supply, nodes: [R4.1, J1.5V]}
      - {name: GND, kind: ground,
         nodes: [U1.VSS, U1.A0, U1.A1, U1.A2, U1.A3, U1.A4, U1.A5, U1.EXTCLK, U2.GND, C1.2, J1.GND]}
      - {name: SCL, nodes: [U1.SCL, U2.SCL, R1.2]}
      - {name: SDA, nodes: [U1.SDA, U2.SDA, R2.2]}
      - {name: OE, nodes: [U1.OE, U2.OE, R3.2]}
      - {name: LED_A, nodes: [R4.2, D1.A]}
      - {name: LED0, nodes: [U1.LED0, D1.K]}
    unused: [U1.LED1, U1.LED2, U1.LED3, U1.LED4, U1.LED5, U1.LED6, U1.LED7, U1.LED8, U1.LED9, U1.LED10, U1.LED11,
             U1.LED12, U1.LED13, U1.LED14, U1.LED15]
