#### eboard KiCad design ####

KiCad 9 project. Top level `eboard.kicad_sch`, one sheet per function
(as on ULX3S):

| Sheet                   | Content                                         |
|-------------------------|-------------------------------------------------|
| `power.kicad_sch`       | +1V1, +3V3 buck converters, +2V5 LDO            |
| `usb.kicad_sch`         | USB-C, CH347F (JTAG + UART)                     |
| `fpga_power.kicad_sch`  | ECP5 VCC / VCCAUX / VCCIO decoupling            |
| `fpga_config.kicad_sch` | ECP5 configuration, SPI flash, 50 MHz clock     |
| `ethernet.kicad_sch`    | RTL8211F gigabit PHY, HR911130A RJ45 (A3 sheet) |
| `sdram.kicad_sch`       | 32 MB SDRAM Winbond W9825G6KH-6                 |
| `hdmi.kicad_sch`        | HDMI type A output, TMDS from the FPGA          |
| `user_io.kicad_sch`     | SW, KEY (debounced), LEDR, LEDG, HEX (A3 sheet) |
| `gpio.kicad_sch`        | GPIO_0/GPIO_1 DE1 headers, Pmod A/B, ESD (A3)   |
| `fpga_banks_01.kicad_sch` | ECP5 banks 0 (Ethernet, HDMI) and 1 (GPIO_0) |
| `fpga_banks_23.kicad_sch` | ECP5 banks 2 (GPIO_1) and 3 (GPIO_1, HEX, UART) |
| `fpga_banks_67.kicad_sch` | ECP5 banks 6 (clock, SW, KEY, LEDR, SDRAM control) and 7 (SDRAM) |
| `testpoints.kicad_sch` | Test pads (rails, GND, clock, UART), M3 mounting holes H1-H6 (GND) |

Libraries:

- `lib/eboard_fpga.kicad_sym`: ECP5 LFE5U-25F/45F caBGA256, generated by
  `lib/tools/make_ecp5_symbol.sh` from the Lattice pinout CSVs.
- `lib/eboard.kicad_sym`: CH347F, RTL8211F and SM410561N (kipart CSVs in
  `lib/tools/`) plus the HanRun HR911130A symbol, built by
  `lib/tools/make_eboard_lib.sh`.
- `lib/eboard.pretty`: HanRun HR911130A footprint, and the footprint of the
  ARKLED SM410561N 0.56" 7-segment display (generated by
  `lib/tools/make_7seg_fp.py` from the ARKLED specification).

The generator scripts need Python 3 and
[kipart](https://github.com/devbisme/KiPart), installed with pipx:

    pipx install kipart
    kicad/lib/tools/make_ecp5_symbol.sh   # -> lib/eboard_fpga.kicad_sym
    kicad/lib/tools/make_eboard_lib.sh    # -> lib/eboard.kicad_sym

Both scripts overwrite their library; edit the sources in `lib/tools/`
(kipart CSVs, Lattice pinout CSVs in `datasheets/`, `*.kicad_sym`) instead.
The kipart CSVs `ch347f.csv`, `rtl8211f.csv` and `sm410561n.csv` are transcribed by hand from
the datasheets; every generated symbol has a hidden `Source` field that names
the datasheet tables or the Lattice CSV it was made from.

Self-made footprints and symbols are cross-checked against the EasyEDA data
that JLCPCB uses for assembly, fetched with
[easyeda2kicad](https://github.com/uPesy/easyeda2kicad.py) into a scratch
directory (not into the project libraries):

    pipx install easyeda2kicad
    easyeda2kicad --lcsc_id C141368 --symbol --footprint --output /tmp/ee/ee

Results (pad positions after aligning the orientation):

| Part (LCSC)            | Project footprint                                   | Max. difference |
|------------------------|-----------------------------------------------------|-----------------|
| SM410561N (C141368)    | `eboard:7SegmentLED_0.56in_1Digit_SM410561N`        | 0.000 mm, pin assignment identical |
| RTL8211F (C187932)     | `QFN-40-1EP_5x5mm_P0.4mm_EP3.6x3.6mm_ThermalVias`   | 0.04 mm (pad length), EP 3.6 mm in both |
| CH347F (C18221627)     | `QFN-28-1EP_4x4mm_P0.4mm_EP2.4x2.4mm_ThermalVias`   | 0.06 mm (pad length); EasyEDA EP 2.7 mm, KiCad 2.4 mm |
| HR911130A (C54408)     | `eboard:RJ45_Hanrun_HR911130A_Horizontal`           | 0.10 mm (EasyEDA offsets the even pins by 1.17 mm instead of 1.27 mm from the datasheet) |
| LFE5U-25F caBGA256 (C1550762) | `BGA-256_14.0x14.0mm_Layout16x16_P0.8mm_...`  | 0.000 mm, all 256 balls |
| HDMI 10029449-001RLF (C428493) | `HDMI_A_Amphenol_10029449-x01xLF_Horizontal` | 0.000 mm incl. shell (EasyEDA pad "20" = SH) |
| USB-C TYPE-C-31-M-12 (C165948) | `USB_C_Receptacle_HRO_TYPE-C-31-M-12`        | < 0.1 mm; EasyEDA merges A1/B12 etc. into custom pads, shell slots slightly larger |
| Box header EH254V-12-40P (C5200276) | `IDC-Header_2x20_P2.54mm_Vertical`      | 0.000 mm |
| Pmod socket A2541HWR-2x6P (C5333437) | `PinSocket_2x06_P2.54mm_Horizontal`    | 0.000 mm; drill 1.0 mm (KiCad) vs 1.27 mm (EasyEDA) |
| Slide switch SS-12D07-5 (C2857673) | C&K `SW_Slide_SPDT_Straight_CK_OS102011MS2Q` | 0.000 mm (checked against the ROCPU datasheet) |
| TS-1187A (C318884)     | `SW_Push_1P1T_XKB_TS-1187A`                         | 0.03 mm; EasyEDA numbers the pads 1-4, KiCad 1/1/2/2 (same connected pairs) |
| TPD4E05U06 (C2827646)  | `USON-10_2.5x1.0mm_P0.5mm`                          | 0.015 mm |
| W9825G6KH-6 (C62246)   | `TSOP-II-54_22.2x10.16mm_P0.8mm`                    | 0.11 mm (pad length) |
| SMNR4020-2.2UH (C135262) | `L_Sunlord_SWPA4020S`                             | 0.30 mm, EasyEDA pads larger; matches the SXN land pattern |
| SMF5.0A (C193402)      | `D_SOD-123F`                                        | 0.23 mm, EasyEDA pads further apart |
| all other parts (SOT-23/-5/-553, SOIC, crystals, oscillator, 0402-1206 passives, LEDs, Keystone 5011) | KiCad library | < 0.2 mm (pad length / IPC density) |

Polarity of LEDs and diodes (pad 1 = cathode) and the part rotations are checked in
the JLCPCB placement preview before ordering.

The HR911130A symbol and footprint are taken from the open KiCad library merge
requests [kicad-symbols!5505](https://gitlab.com/kicad/libraries/kicad-symbols/-/merge_requests/5505)
(commit 6183ff89) and [kicad-footprints!4647](https://gitlab.com/kicad/libraries/kicad-footprints/-/merge_requests/4647)
(commit 0c65d539), converted from KiCad 10 to KiCad 9 format (version header
changed, KiCad 10 attributes with default values removed). The footprint was
checked against the HanRun datasheet (all pads within 0.005 mm). KiCad library
license: CC-BY-SA 4.0 with the KiCad library exception. Once the merge requests
are in a KiCad release, the project can switch to `Connector:` /
`Connector_RJ:RJ45_Hanrun_HR911130A_Horizontal`.

The bank assignment of all interfaces is in [PINPLAN.md](PINPLAN.md).

### Schematic generator (historical) ###

The first version of the schematic was generated by `tools/gen_sch.py` (part
choices, LCSC/MPN table, ball assignment of the FPGA banks are in the script).
From now on the schematic is edited in KiCad. **Do not run the script again**:
it overwrites all sheets and discards the changes made in KiCad. It is kept to
document how the schematic was created.

### Net naming ###

Signals between sheets are global labels. Signals that go to the FPGA use the
names of the Terasic DE1 board, so that DE1 course material and constraint
files can be reused. The net name is also the port name in the LPF.

| Net             | LPF / HDL port  | Function                                   |
|-----------------|-----------------|--------------------------------------------|
| `CLOCK_50`      | `CLOCK_50`      | 50 MHz system clock                        |
| `SW0` ... `SW9` | `SW[9:0]`       | slide switches                             |
| `KEY0` ... `KEY3` | `KEY[3:0]`    | push buttons, active low                   |
| `LEDR0` ... `LEDR9` | `LEDR[9:0]` | red LEDs, active high                      |
| `LEDG0` ... `LEDG5` | `LEDG[5:0]` | green LEDs, active high                    |
| `HEX0_0` ... `HEX3_6` | `HEX0[6:0]` ... `HEX3[6:0]` | 7-segment displays, active low |
| `UART_TXD`      | `UART_TXD`      | FPGA transmits (to CH347 RXD0)             |
| `UART_RXD`      | `UART_RXD`      | FPGA receives (from CH347 TXD0)            |
| `GPIO_0_0` ... `GPIO_0_31` | `GPIO_0[31:0]` | DE1 40 pin header, shared with Pmod A/B; pins 37-40 fixed for the THDB-ADA |
| `GPIO_1_0` ... `GPIO_1_35` | `GPIO_1[35:0]` | DE1 40 pin header at the board edge     |
| `DRAM_DQ0` ... `DRAM_DQ15`, `DRAM_ADDR0` ... `DRAM_ADDR12` | `DRAM_DQ[15:0]`, `DRAM_ADDR[12:0]` | SDRAM data and address (DE1 names, ADDR12 added for 32 MB) |
| `DRAM_BA_0`, `DRAM_BA_1`, `DRAM_LDQM`, `DRAM_UDQM`, `DRAM_WE_N`, `DRAM_CAS_N`, `DRAM_RAS_N`, `DRAM_CS_N`, `DRAM_CKE`, `DRAM_CLK` | same | SDRAM control, as on the DE1 |
| `ENET_GTX_CLK`, `ENET_TX_EN`, `ENET_TX_DATA0..3` | `ENET_TX_DATA[3:0]` ... | RGMII transmit, DE2-115 names |
| `ENET_RX_CLK`, `ENET_RX_DV`, `ENET_RX_DATA0..3` | `ENET_RX_DATA[3:0]` ... | RGMII receive |
| `ENET_MDC`, `ENET_MDIO`, `ENET_RST_N`, `ENET_INT_N` | | PHY management, reset (active low, PHY held in reset by a pull-down), interrupt |
| `HDMI_D0_P/N`, `HDMI_D1_P/N`, `HDMI_D2_P/N`, `HDMI_CLK_P/N` | | HDMI TMDS pairs (LVCMOS33D), AC coupled to the connector |
| `JTAG_TCK` ...  |                 | FPGA JTAG, driven by the CH347             |

Directions are always seen from the FPGA.

Local nets inside a sheet (e.g. `FLASH_CS`, `FPGA_DONE`) use local labels.