Submission tutorial

hackpads/cyaopad/README.md

@@ -1,17 +1,38 @@
-# Macropad
-Hello! This is my first time designing a PCB and a CAD.
+# Cyao's mega macropad
+Hello! This is my submission for hackpad! This was made for Hackpad v1.
 
-<p align="middle">
-    <img src="https://cloud-fwkk14f6r-hack-club-bot.vercel.app/0screenshot_2024-10-09_at_9.59.15_pm.png" width="32%"/>
-    <img src="https://cloud-fwkk14f6r-hack-club-bot.vercel.app/1screenshot_2024-10-09_at_9.58.53_pm.png" width="32%"/>
-    <img src="https://cloud-3jqi500oq-hack-club-bot.vercel.app/2screenshot_2024-10-06_at_3.43.34_pm.png" width="32%"/>
-</p>
+## Features
+- 4x Neopixels!
+- A big 0.96" OLED screen
+- Cool silkcreen art
+- 16x whole kailh choc keys (they were allowed for v1)
+- kmk firmware! Control your mouse with this macropad
 
-Designed using:
+## PCB
+Here are pictures of my pcb:
 
-- KiCad - Made a ton of revisions
-- OpenSCAD then FreeCAD (Fusion 360 doesn't work on my mac lol) Got like 400 constraints in my freecad project
-- Python firmware
+| **Schematic** | **PCB** |
+|---------------|---------|
+|![](https://i.ibb.co/GvsRwfvR/image.png)|![](https://i.ibb.co/fJRxwY7/image.png)|
+
+Hope you like it! I made like 10 revisions. 
+
+![](https://cloud-fwkk14f6r-hack-club-bot.vercel.app/0screenshot_2024-10-09_at_9.59.15_pm.png)
+
+PS. there is a strict assembly order, dm me (`@Cyao` on slack) to know it
+
+[x] I ran DRC and there are 0 errors
+
+## CAD
+Designed using FreeCAD! It was painful. Be glad you have the current guide, I spent 10+ hours figuring out how to do everything correctly (and even like this I still did stupid stuff).
+
+![](https://cloud-3jqi500oq-hack-club-bot.vercel.app/2screenshot_2024-10-06_at_3.43.34_pm.png)
+
+Everything fits together with 4 m3 screws and bolts
+
+## Firmware
+
+I wrote the firmware using kmk, you can see it inside the repo. It can be used to control your mouse!
 
 ## Notes
 Making the pad was fun ^.^ but I was just too paranoid that something would go wrong and made 15+ revisions lol. Ended up learning how to use OpenSCAD and FreeCAD.
@@ -26,37 +47,4 @@ Making the pad was fun ^.^ but I was just too paranoid that something would go w
 - 4x 0.1 uF capacitor (code 104, not obligatory but best have)
 - 1x 1 uF capacitor (105 not obligatory)
 - 4x same screws as orpheuspad and corresponding nuts
-- 1kg of 99.99% gold please UwU
-
-Interactive bom at `PCB/production/ibom.html`
-
-## File list:
-
-```
-.
-├── CAD                                         # 3D Files
-│   ├── case.FCStd                              # Case FreeCAD design file
-│   └── case
-│       └── case.stl                            # The stl for the case
-├── PCB
-│   ├── macropad.step                           # 3D Model of the board
-│   ├── production                              # The output directory for production (Just send this folder to JLCPCB)
-│   │   ├── Cyao_macropad_v7.6.zip              # Final gerbers
-│   │   ├── *.{csv,ipc}                         # Misc files for JLCPCB
-│   │   └── ibom.html                           # Interactive bom for PCBAlex <3
-│   └── third_party                             # 3rd party libraries
-│       ├── Kalih                               # The keys
-│       ├── OPL_Kicad_Library                   # Seed footprint
-│       ├── KiCad-SSD1306-128x64-master         # LCD
-│       └── Seeeduino-xiao-rp2040-KiCAD-Library # Seed schema
-└── firmware                                    # Directory of my own firmware
-    ├── adafruit-circuitpython-seeeduino_xiao_rp2040-en_US-9.1.4.uf2 # Circuitpython firmware
-    ├── main.py                                 # Main firmware
-    ├── boot.py                                 # Boot options (empty)
-    └── kmk                                     # kmk firmware
-```
-
-NOTE: I will need a 0.96” SSD1306 OLED screen that accepts 5V with 3.3V logic
-
-The resistors are allso probably optional - but suggested by reddit
 

website/src/pages/hackpad/AdvancedTutorial.mdx

@@ -5,7 +5,7 @@ Are you not satisfied with a simple macropad? Here you have more information on
 - [Ground Pour](#ground)
 - [Switch Matrix](#matrix)
 - [Silkscreen Art](#silkscreen)
-- [LCD](#lcd)
+- [OLED](#oled)
 - [Jumper Wire Holes](#jumpers)
 - [Reverse Mount Neopixels](#rneopixels)
 - [Rotary Encoder](#rotary_encoder)
@@ -121,7 +121,7 @@ I placed mine on the back side of the PCB, and this is the final result:
 
 Pretty right? UwU
 
-<a name="lcd"/>
+<a name="oled"/>
 ## OLED
 [Download this footprint library and unzip it](https://download-directory.github.io/?url=https%3A%2F%2Fgithub.com%2Fcheyao%2Fmacropad%2Ftree%2Fmain%2FPCB%2Fthird_party%2FKiCad-SSD1306-128x64-master), then add it to kicad.
 

website/src/pages/hackpad/Faq.mdx

@@ -48,6 +48,7 @@ You can! We'll have V2's at HQ. note: please use 19.05x19.05mm spacing, or else
 Join the #hackpad channel in the Hack Club slack!
 
 **What are the footprint name for diodes/resistors?**
+
 Diodes are D_DO-35_SOD27_P7.62mm_Horizontal.
 
 Resistors are R_Axial_DIN0204_L3.6mm_D1.6mm_P7.62mm_Horizontal

website/src/pages/hackpad/Submission.mdx

@@ -2,17 +2,20 @@
 
 Finally finished your hackpad? Nice job! Follow along and we're going to make sure you have everything necessary to *ship* your project, which includes:
 
-- Structuring your project
-- Exporting the production files
-- Publishing the design
+- [Structuring your project](#structure)
+- [Exporting the production files](#export)
+- [Adding the BOM](#bom)
+- [Adding README files](#readme)
+- [Publishing the design](#publishing)
 
+<a name="structure"/>
 ## Structuring your project
 To make reviewing easier, we need to make sure that the source files of our project are formatted in a way that's complete & easy to navigate.
 
 ### 1) Make sure you have everything necessary:
 
 Before we organize anything, make sure 
-- A *complete* CAD model of the assembled case in .STEP or .3MF format
+- A *complete* CAD model of the assembled case in .STEP, .STP or .3MF format
     - This should include the PCB (a blank rectangle is okay!) and all parts of the case
 - Original firmware for your macropad. QMK, KMK, ZMK, etc derivatives are valid
 - A complete BOM (Bill of Materials) with all the parts you would like in a separate markdown document!
@@ -20,9 +23,9 @@ Before we organize anything, make sure
 Additionally, make sure you meet the following requirements:
 - Your design uses a through-hole Seeed XIAO RP2040 as the main MCU
 - Your PCB is smaller or equal to 100mmx100mm
-- Your case fits within 200x200x100mm (x / y / z)
+- Your case fits within 200x200x100mm (length / width / height)
 - You have less than 16 inputs (switches, encoders, etc)
-- You are using approved parts only
+- You are using approved parts only (You can buy extra parts with the 20$ grant)
 - The PCB only uses 2 layers
 - Your case only has 3D printed parts
 
@@ -30,40 +33,77 @@ If you have all of that, it should be ready to go!
 
 ### 2) Organize your folders
 The above is a LOT of files! To make reviewing as easy as possible, your submission format should have 3 folders:
-- pcb
+
+- PCB
 - firmware
 - CAD
 
 Put each part of your design in their correspoding folders.
 
+<a name="export"/>
 ## Creating production files
 Nice job on organizing your files! Next, we need to create the manufacturing files that will actually be used to build your project.
 
 This is separate from the source files, which are usually a reference to check out & iterate on your design.
 
 ### 1) Export your PCB
-Depending on your tool of choice, the exact workflow will be different. What you want to do is export your PCB as a set of files called Gerbers, which are basically instructions for the
- manufacturer to build your PCB. it should be compressed into a .zip file.
+Depending on your tool of choice, the exact workflow will be different. What you want to do is export your PCB as a set of files called Gerbers, which are basically instructions for the manufacturer to build your PCB. It should be compressed into a .zip file.
 
 The internet will help you out on this one. The end file you get should be named gerbers.zip and contain all the production files in it.
 
+But here is a tiny guide anyways:
+
+First, open up the plugin manager of kicad.
+
+<img src="/docs/v2/plugins.png" className="max-w-96" />
+
+Search for "Fabrication Toolkit", select the one with JLC PCB in it's description. Click install, then "Apply Pending Changes". When it's done installing, close the window.
+
+<img src="/docs/v2/install.png" className="max-w-96" />
+
+Now open back up the PCB editor, you should see a new button at the top right:
+
+<img src="/docs/v2/fab.png" className="max-w-96" />
+
+Press it, then click generate. Now you should have a new folder named production, open it up and you should see files like this:
+
+<img src="/docs/v2/files.png" className="max-w-96" />
+
+The one you are looking for is the .zip, you can delete everything else.
+
 ### 2) Export your Case parts
 Each individual part of the case should be exported into its respective files:
 - If the part is 3D printed, it should be exported into STL 
-- If it's going to be laser cut, it should be exported as a DXF
 
 Put it inside a folder called "case"
 
 ### 3) Compile your firmware
-This step is going to depend on what you used specifically, but the resulting file should be named firmware.uf2
+This step is going to depend on what you used specifically, for QMK the resulting file should be named firmware.uf2
+
+If you are using KMK, just put the main.py file inside the firmware folder/
 
 What you want to search for is how to compile firmware for an rp2040. Good luck!
 
 ### 4) Organize it all
 Now that you've made all the production files, create a new folder called production and put all the files in there.
 
-## Publishing your project
-The final step to making your PR is to actually publish your project! This involves writing a simple page for it explaining what it is.
+<a name="bom"/>
+## Adding a BOM
+Add a new file inside the root of your project, and call it BOM.txt.
+
+Write what components you need inside! Example:
+
+```
+- 1x 128x64 0.96" SSD1306 OLED Display
+- 8x SK6812 Mini Neopixels
+- 8x Alps MX switches
+- 1x Seeed XIAO RP2040
+- 2x 4.7kΩ THT resistors
+```
+
+<a name="readme"/>
+## Adding a README
+A README is essential to all open-source projects. It allows people to know more about you and your project. You submission should have one!
 
 You can put absolutely *anything* on it, as it's your page. I recommend talking about:
 
@@ -73,14 +113,85 @@ You can put absolutely *anything* on it, as it's your page. I recommend talking
 
 Every hackpad submission's page will be published on the main hackpad website, so make sure to go submit!
 
-## Make a PR 
+Here is a tiny guide on creating a README.md, be sure to modify your own version!
+
+Start by creating a new file called README.md at the top of your project using any text editor. Any file ending in .md is called a markdown file, it will be parsed by github to create [pretty texts](https://github.com/hackclub/asylum/blob/main/designs/weather_stations/dari_awesome_example/README.md).
+
+Check [here](https://commonmark.org/help/) to learn the basic markdown syntax.
+
+Remember, to make a new line you **must** press enter 2 times!
+
+First please discribe the featurs of your macropad! What did you add? How many leds you have? Do you have any special art on it?
+
+Then please make a part where you introduce your PCB! Write us a little about how you made your PCB. Please also make a table with the pictures of your schematic and pcb:
+
+First, take a screenshot of your macropad. Upload it to the #cdn channel in slack! You should receive a link to the file. (And if #cdn is down, try https://imgbb.com/, you will get a link starting with ibb.co, change it to i.ibb.co then append "/image.png" or "/image.jpg" to the link)
+
+Then add a table of the following format to your README.md:
+
+```
+| **Schematic** | **PCB** |
+|---------------|---------|
+|![](link_to_schematic)|![](link_to_pcb)|
+```
+
+While replacing link_to_schematic and link_to_pcb to your links.
+
+Don't forget to add a line stating that you ran DRC and have 0 erors! If you haven't done it, do it now in kicad!
+
+You can showcase your 3D view too :3
+
+After that make a part showcasing your CAD model. Discribe it a bit, then embed a image of it with `![](link_to_image)`.
+
+After that, give us a overview on your firmware!
+
+At the end, copy and paste your BOM please.
+
+Maybe write something funny at the end! Thats up to you!
+
+A good example would be [this, even if it's not for hackpad](https://github.com/hackclub/asylum/blob/main/designs/weather_stations/dari_awesome_example/README.md). Or look at [my readme!](https://github.com/hackclub/hackpad/blob/main/hackpads/cyaopad/README.md)
+
+PS. You might want to license your work, look at [https://choosealicense.com/](https://choosealicense.com/), pick a license and copy then paste the text into a LICENSE.txt file
+
+If you want, you can also add some readme files into your subdirectories, that would be awesome!
+
+<a name="publishing"/>
+## Publishing your project
+The final step to making your PR is to actually publish your project! This involves writing a simple page for it explaining what it is.
+
+First, go to the directory `website/src/pages/submissions`, create a new folder for your submission (Cyaopad for me). Then make a .mdx file that is named after your macropad (Cyaopad.mdx for me).
+
+Copy all the content of the README.md over, but remove the table and put the images on separate lines.
+
+Then open the file `hackpad/website/src/main.tsx` and add a line of the following format at where it says IMPORT YOUR PROJECTS HERE:
+
+```
+import CyaoPad from "./pages/submissions/Cyaopad/CyaoPad.mdx"
+```
+
+Be sure to change the name to your own.
+
+Then scroll down to almost the bottom of the page, to where it says "Submitting? Great! Do something like this:". Add a new entry in the following format:
+
+```
+  {
+    path: "/projects/cyaopad",
+    element: <DocPage Content={ CyaoPad } SideBar={ SideBar } />
+  },
+```
+
+Be sure to change the name to your own again. Now you should be able to view your site at the adress https://hackpad.hackclub.com/projects/\{yourname\} after your pr is merged.
+
+Your final result should look like this [this](/projects/cyaopad)
+
+### Make a PR 
 First, double check your submission against the [Orpheuspad](https://github.com/hackclub/hackpad/tree/main/hackpads/orpheuspad) example to make sure you have the correct structure. Everything should match exactly, except for the filenames.
 
 If anything is unclear, make sure to ask in #hackpad!
 
 Once everything is organized, you can make a PR to the repository [here](https://github.com/hackclub/hackpad)!
 
-## After submitting
+### After submitting
 If everything went correctly, your PR will be reviewed (and hopefully approved!) by @alexren. If it's approved, then you'll get:
 - All of your parts from the approved list
 - A soldering iron
@@ -88,3 +199,4 @@ If everything went correctly, your PR will be reviewed (and hopefully approved!)
 - Your 3D printed case
 
 For many of you, the firmware may not work the first try. That's okay! Keep working at it until it's fixed; if you send a video in #hackpad showing it working, I'll ship you a free custom hack-club keycap and sticker!
+

website/src/pages/submissions/Cyaopad/CyaoPad.mdx

@@ -1,46 +1,42 @@
-import schematicImage from './schematic.png';
-import pcbImage from './pcb.png';
-import cadImage from './cad.png';
-
-# Cyaopad
-
-Cyaopad is a 16 key macropad with an OLED Display. It also has 4 WS2812B Leds, and uses KMK firmware
-
-It am using it to test my EE knowledge
-
-## Features:
-- 128x32 OLED Display
-- 4 WS2812B RGB LEDs. 
-- 16 keys controlling the mouse
-- choc keys
-
-## CAD Model:
-Everything fits together using 4 M3 Bolts
-
-It has 2 separate printed pieces. The base where the PCB sits, and the top cover.
-
-<img src={cadImage} alt="Schematic" width="500"/>
-
-Made in Fusion360. Nifty
+# Cyao's mega macropad
+Hello! This is my submission for hackpad! This was made for Hackpad v1.
 
+## Features
+- 4x Neopixels!
+- A big 0.96" OLED screen
+- Cool silkcreen art
+- 16x whole kailh choc keys (they were allowed for v1)
+- kmk firmware! Control your mouse with this macropad
 
 ## PCB
-Here's my PCB! It was made in KiCad. The silkscreen was imported from a google image.
+Here are pictures of my pcb:
 
-PCB
-<img src={pcbImage} alt="Schematic" width="300"/>
-<img src={schematicImage} alt="Schematic" width="300"/>
+![](https://i.ibb.co/GvsRwfvR/image.png)
+![](https://i.ibb.co/fJRxwY7/image.png)
 
-I used MX_V2 for the keyswitch footprints. I think in retrospect, I should've added a ground plane
+Hope you like it! I made like 10 revisions. 
 
-## Firmware Overview
-This hackpad uses kmk firmware for everything. 
+![](https://cloud-fwkk14f6r-hack-club-bot.vercel.app/0screenshot_2024-10-09_at_9.59.15_pm.png)
 
-I might add more in the future! That's it for now
+PS. there is a strict assembly order, dm me (`@Cyao` on slack) to know it
 
-## BOM:
-Here should be everything you need to make this hackpad
+[x] I ran DRC and there are 0 errors
 
+## CAD
+Designed using FreeCAD! It was painful. Be glad you have the current guide, I spent 10+ hours figuring out how to do everything correctly (and even like this I still did stupid stuff).
+
+![](https://cloud-3jqi500oq-hack-club-bot.vercel.app/2screenshot_2024-10-06_at_3.43.34_pm.png)
+
+Everything fits together with 4 m3 screws and bolts
+
+## Firmware
+
+I wrote the firmware using kmk, you can see it inside the repo. It can be used to control your mouse!
+
+## Notes
+Making the pad was fun ^.^ but I was just too paranoid that something would go wrong and made 15+ revisions lol. Ended up learning how to use OpenSCAD and FreeCAD.
+
+## BOM
 - 1 SEEEDUINO XIAO RP2040
 - 16x [Kailh Choc V2 switches](https://www.kailh.net/products/kailh-choc-v2-low-profile-switch-set)
 - 16x 1N4148 diodes
@@ -50,7 +46,5 @@ Here should be everything you need to make this hackpad
 - 4x 0.1 uF capacitor (code 104, not obligatory but best have)
 - 1x 1 uF capacitor (105 not obligatory)
 - 4x same screws as orpheuspad and corresponding nuts
-- 1kg of 99.99% gold please UwU
 
-## Extra stuff
-Wrote dis with my pad UwU
+