SummerCart64/docs/06_build_guide.md

- [Video guide](#video-guide)
- [Step by step guide how to make SC64](#step-by-step-guide-how-to-make-sc64)
  - [**PCB manufacturing data**](#pcb-manufacturing-data)
  - [**PCB requirements**](#pcb-requirements)
  - [**Components**](#components)
  - [**Plastic shell**](#plastic-shell)
  - [**Putting it together**](#putting-it-together)
  - [**Initial programming**](#initial-programming)
  - [**Troubleshooting**](#troubleshooting)
    - [*`primer.py` threw `No SC64 USB device found` error*](#primerpy-threw-no-sc64-usb-device-found-error)
    - [*`primer.py` threw `SDRAM test error...` message*](#primerpy-threw-sdram-test-error-message)
    - [*`primer.py` threw other error message*](#primerpy-threw-other-error-message)

---

## Video guide

[![Video guide](https://img.youtube.com/vi/t6hyCFpwqz8/0.jpg)](https://www.youtube.com/watch?v=t6hyCFpwqz8 "How to build and program the SummerCart64")

## Step by step guide how to make SC64

All necessary manufacturing files are packaged in every `sc64-extra-{version}.zip` file in GitHub releases.
Please download latest release before proceeding with the instructions.

---

### **PCB manufacturing data**

   1. Locate KiCad project inside `hw/pcb` folder
   2. Export gerber/drill files
   3. Export BOM spreadsheet
   4. Export PnP placement files
   5. Send appropriate files to the PCB manufacturer

---

### **PCB requirements**

***Before ordering PCBs make sure you select correct options listed below:***

  - PCB thickness: 1.2 mm
  - Surface finish (plating): ENIG (Hard gold for edge connector is recommended but it's very expensive)
  - PCB contains edge connector: yes
  - Beveled edge connector: yes, 45° (other angles also should work OK)

---

### **Components**

  1. Locate interactive BOM file inside `hw/pcb` folder (alternatively, check out this [BOM discussion](https://github.com/Polprzewodnikowy/SummerCart64/discussions/27))
  2. Order all parts listed in the BOM file or use PCB assembly service together with your PCB order

---

### **Plastic shell**

  1. Locate `.stl` files inside `hw/shell` folder
  2. Use these files in the slicer and 3D printer of your choice or order ready made prints from 3D printing company
  3. For screws, M2x10 works great for the top two holes while M2x8 fits well in the bottom two

---

### **Putting it together**

There are no special requirements for soldering components to board.
All chips and connectors can be soldered with standard manual soldering iron, although hot air station is recommended.
Interactive BOM has every component and its value highlighted on PCB drawings and it's strongly recommended to use during assembly process.
You can skip this step if PCB assembly service was used in previous steps.

---

### **Initial programming**

**Please read the following instructions carefully before proceeding with programming.**

***Note:*** This guide assumes you are using Windows 10 or above.

You will require the following hardware:
 - A PC running Windows 10 or above (any Linux distro should also work but programming FT232H EEPROM is arguably trickier without an official app).
 - A USB to UART (serial) adapter (with 3.3V signaling is required, e.g. TTL-232R-3V3).

You will require the following applications and packages:
 - [Latest FTDI drivers](https://ftdichip.com/drivers/)
 - [FT_PROG](https://ftdichip.com/utilities/#ft_prog) - FTDI FT232H EEPROM programming software.
 - [Python 3](https://www.python.org/downloads/) with `pip3` - necessary for initial programming script: `primer.py` (Windows install: check option add python to PATH).
 - [`sc64-extra-{version}.zip`](https://github.com/Polprzewodnikowy/SummerCart64/releases) - programming scripts and firmware files, download the latest version.

**Programming must be done in specific order for `primer.py` script to work correctly.**

Preparations:
 1. Install latest FTDI drivers (especially on Windows 10).
 2. Install FT_PROG.
 3. Install Python 3.
 4. Unpack `sc64-extra-{version}.zip` into a folder.
 5. Open terminal and navigate to the folder you've unpacked SC64 files.

First, program the ***FT232H EEPROM***:
 1. Connect the SC64 board to your PC with a USB-C cable.
 2. Locate FT232H EEPROM template `ft232h_config.xml` from the `fw/ftdi/` directory.
 3. Launch `FT_PROG` software.
 4. Click on `Scan and parse` if no device has shown up.
 5. Right click on SC64 device and choose `Apply Template -> From File`.
 6. Select previously located `ft232h_config.xml`.
 7. Right click on SC64 device and choose `Program Device`.

Your SC64 should be ready for next programming step.

Second, program ***FPGA, microcontroller and bootloader***:
 1. Disconnect SC64 board from power (unplug USB-C cable).
 2. Connect serial UART/TTL adapter to `TX/RX/GND` pads marked on the PCB. Cross connection `TX -> RX`, `RX -> TX`!
 3. Connect serial adapter to the PC.
 4. Check in device manager which port number `COMx` is assigned to serial adapter.
 5. Connect SC64 board to the PC with USB-C cable (***IMPORTANT:*** connect it to the same computer as serial adapter).
 6. Locate `primer.py` script in the root folder.
 7. Make sure these files are located in the same folder as `primer.py` script: `requirements.txt`, `sc64-firmware-{version}.bin`.
 8. Run `pip3 install -r requirements.txt` in the terminal to install required python packages.
 9. Run `python3 primer.py COMx sc64-firmware-{version}.bin` (replace `COMx` with port located in step **4**). On Windows it's `python` instead of `python3`.
 10. Follow the instructions on the screen.
 11. Wait until programming process has finished (**DO NOT STOP PROGRAMMING PROCESS OR DISCONNECT SC64 BOARD FROM PC**, doing so might irrecoverably break programming through UART header and you would need to program FPGA and/or microcontroller with separate dedicated programming interfaces through *Tag-Connect* connector on the PCB).

Congratulations! Your SC64 flashcart should be ready for use!

---

### **Troubleshooting**

#### *`primer.py` threw `No SC64 USB device found` error*

This issue can be attributed to incorrectly programmed FT232H EEPROM in the first programming step.
Check again in `FT_PROG` application if device was configured properly.
Make sure default FTDI drivers are installed for the SC64 in the device manager (only on Windows OS).
Make sure you have correct access to `/dev/ttyUSBx` device and `ftdi_sio` and `usbserial` modules are loaded (only on Linux OS).

#### *`primer.py` threw `SDRAM test error...` message*

This issue shows up when there's a problem with the connection to the SDRAM chip or the chip itself is malfunctioning.
Check for any solder bridges and unconnected pins on U8/U9 chips.
Once FPGA and microcontroller has been programmed successfully `primer.py` script needs to be run in special mode.
Please use command `python3 primer.py COMx sc64-firmware-{version}.bin --bootloader-only` to test SDRAM again and continue bootloader programming process.

#### *`primer.py` threw other error message*
Due to multiple possible causes of the problem it's best to start visually inspecting SC64's board for any defects, like bad solder work or chips soldered backwards.
If visual inspection didn't yield any obvious culprits then next step would be to check if everything is connected correctly.
Check if TX/RX signals aren't swapped and if SC64 is getting power from the USB cable. Best place to check supply voltage are the exposed test pads on the left of U8 chip.
If everything at this point was checked and looked fine, then feel free to open new thread in the [*Discussions*](https://github.com/Polprzewodnikowy/SummerCart64/discussions) tab.
Make sure to describe your problem extensively, attach SC64 board photos **from the both sides**, and paste all logs/screenshots from the `primer.py` output.