Blueprint

How to submit your project

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:

  • Creating a new GitHub Repository
  • Structuring your project files
  • Creating production files
  • Adding a README

Create a new GitHub Repository

GitHub is a website that allows you to host your project files! A GitHub repository is an individual project that you can share with others

GitHub has an awesome guide on how to create & manage repositories. You can find it here: Creating a new repository

Once you create a repository, make sure to clone it! Cloning it downloads a local copy to your computer & lets you sync it with the version on GitHub servers. GitHub also has a guide on this! You can find it here: Cloning a repository

Once you have it cloned locally, drag and drop all your project files into the folder!

Structuring your project design files

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, .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

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 (length / width / height)
  • You have less than 16 inputs (switches, encoders, etc)
  • You are using approved parts only
  • The PCB only uses 2 layers
  • Your case only has 3D printed parts, no acrylic or laser cut parts

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 organization easy, you should create a folder for each part of your macropad:

CAD:
This should contain a single file containing your ENTIRE hackpad. This should be a .STEP, .STP, or .3MF file

PCB:
This should contain your PCB Design files. This includes the .kicadpro, .kicadsch, and .kicad_pcb file if you're using KiCAD!

Firmware:
This should contain the source files for your firmware. main.py if you're using KMK, and then several files if you're using QMK

In total, you should have 3 folders in your project folder.

Creating production files

Nice job on organizing your design 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.

Before moving on, create a folder called "production"

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.

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.

Put it inside the "production" folder

2) Export your Case parts

Each individual part of the case should be exported into its respective files. For example, if you have a top, bottom, and middle part, you should have 3 files:

  • Top.STEP
  • Bottom.STEP
  • Middle.STEP

If you can't export them as STEPs, STLs are okay too!

Put all of these files in the "production" folder as well

3) Compile your firmware

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, you'll just have a main.py file.

Either way, put them in the "production" folder

Adding a README

A README is essential to all open-source projects. It allows people to know more about you and your project without having to dig into every single file.

The README is pretty flexible, but you MUST include the following parts:

  • A screenshot of your overall hackpad
  • A screenshot of your schematic
  • A screenshot of your PCB
  • A screenshot of your case and how it'll fit together
  • a BOM for your parts

It'll be different for each hackpad, but good examples of what I'm looking for are:

Make a ship post!

Next, you should make a ship post in #blueprint-drafts on slack! Format it like so:

Hackpad name: Orpheuspad

GitHub Repo: https://github.com/qcoral/orpheuspad

Description: This is a 4-key macropad with a rotary encoder, OLED, and neopixel! It's meant to showcase all the different parts in a small, polished project

(attach some images of your hackpad)

You'll need to make a post to get feedback on your project, so don't forget this step!

Submit on the dashboard!

head on over to your dashboard and hit "submit design review" - you're good on the rest!

After submitting

Any questions? Check out the FAQ