phiwan/phiboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: reset readme

Browse source
This commit is contained in:
phiwan-dev 2025-12-05 17:55:03 +01:00
parent b880a7041a
commit 79d46e5a83
1 changed files with 97 additions and 98 deletions
Download patch file Download diff file Expand all files Collapse all files

195
README.md
View file

@ -1,124 +1,123 @@
# phiboard # phiboard
in progress... in progress, currently in the prototype phase...
## Goals <!-- ## Goals -->
- fully reversible pcb including hotswap sockets, MCU, OLED screen <!-- - fully reversible pcb including hotswap sockets, MCU, OLED screen -->
- wireless using the XIAO BLE as MCU <!-- - wireless using the XIAO BLE as MCU -->
- low profile (choc kailh) and thin PCB + components <!-- - low profile (choc kailh) and thin PCB + components -->
- no visible screws from the top <!-- - no visible screws from the top -->
- no visible seams from the top <!-- - no visible seams from the top -->
- custom graphics and silk screen <!-- - custom graphics and silk screen -->
- super easy, local zmk development <!-- - super easy, local zmk development -->
# Manual additions after Ergogen <!-- # Manual additions after Ergogen -->
Ergogen is used to generate most parts of the PCB. From within the ergogen folder, this can be done using: <!-- Ergogen is used to generate most parts of the PCB. From within the ergogen folder, this can be done using: -->
``` <!-- ``` -->
ergogen . && cp output/pcbs/pcb.kicad_pcb ../kicad-prj/ <!-- ergogen . && cp output/pcbs/pcb.kicad_pcb ../kicad-prj/ -->
``` <!-- ``` -->
However, various smaller modifications as well as the reversible OLED and silkscreen graphics are placed manually by hand. <!-- However, various smaller modifications as well as the reversible OLED and silkscreen graphics are placed manually by hand. -->
It is likely that this could be done through ergogen as well, feel free to fork and adjust my config. <!-- It is likely that this could be done through ergogen as well, feel free to fork and adjust my config. -->
All modifications are listed in here: <!-- All modifications are listed in here: -->
- Removed silksceens from diodes and modified silksceen for the battery pads. Be careful with this, as it make messing up the diode configuration very easy! <!-- - Removed silksceens from diodes and modified silksceen for the battery pads. Be careful with this, as it make messing up the diode configuration very easy! -->
- Wired up MCU and keys in a reversible fashion <!-- - Wired up MCU and keys in a reversible fashion -->
- Included reversible OLED <!-- - Included reversible OLED -->
- Put on silkscreens on front [`porsche-front-big.kicad_mod`](./kicad-prj/graphics.pretty/porsche-front-big.kicad_mod) and back [`porsche-back-big.kicad_mod`](./kicad-prj/graphics.pretty/porsche-back-big.kicad_mod) <!-- - Put on silkscreens on front [`porsche-front-big.kicad_mod`](./kicad-prj/graphics.pretty/porsche-front-big.kicad_mod) and back [`porsche-back-big.kicad_mod`](./kicad-prj/graphics.pretty/porsche-back-big.kicad_mod) -->
# Customize Graphics <!-- # Customize Graphics -->
In [graphics](./kicad-prj/graphics/) you can find the source images used in this project. <!-- In [graphics](./kicad-prj/graphics/) you can find the source images used in this project. -->
There are two types of graphics. <!-- There are two types of graphics. -->
### Silkscreen <!-- ### Silkscreen -->
The silksceen uses the porsche images. <!-- The silksceen uses the porsche images. -->
To use a different image you have to open `kicad > image converter`. <!-- To use a different image you have to open `kicad > image converter`. -->
In here you can load your desired image, choose an output size and threshold and save it as footprint on F.Silkscreen. <!-- In here you can load your desired image, choose an output size and threshold and save it as footprint on F.Silkscreen. -->
In order for KiCad to detect your custom footprints, you have to save them to a folder with the extension `.pretty` like in [`kicad-prj/graphics.pretty/`](./kicad-prj/graphics.pretty/). <!-- In order for KiCad to detect your custom footprints, you have to save them to a folder with the extension `.pretty` like in [`kicad-prj/graphics.pretty/`](./kicad-prj/graphics.pretty/). -->
Lastly you need to tell KiCad where to find your footprints. <!-- Lastly you need to tell KiCad where to find your footprints. -->
If you decide to use my project and its `graphics.pretty` folder then KiCad should automatically pick it up through the `fp-lib-table`. <!-- If you decide to use my project and its `graphics.pretty` folder then KiCad should automatically pick it up through the `fp-lib-table`. -->
Else, you can specify your `.pretty` path in `Preferences > Manage Footprint Libraries... > Project Specific Libraries`. <!-- Else, you can specify your `.pretty` path in `Preferences > Manage Footprint Libraries... > Project Specific Libraries`. -->
### Solder Images <!-- ### Solder Images -->
In the palm of the hand there is a little empty space on the PCB which I decided to use with images which are printed on there using solder. <!-- In the palm of the hand there is a little empty space on the PCB which I decided to use with images which are printed on there using solder. -->
I got the idea from [this video](https://www.youtube.com/watch?v=ohu4tZ4qov8). <!-- I got the idea from [this video](https://www.youtube.com/watch?v=ohu4tZ4qov8). -->
Here is the workflow to put your own images on there: <!-- Here is the workflow to put your own images on there: -->
You will most likely have a .png or .jpg image, which needs to be transformed to .svg. <!-- You will most likely have a .png or .jpg image, which needs to be transformed to .svg. -->
For this you can use popular online tools like [convertio.co](https://convertio.co/). <!-- For this you can use popular online tools like [convertio.co](https://convertio.co/). -->
Optionally you can try to optimize your svg using [this website](https://optimize.svgomg.net/), although it didn't make much of a difference for me. <!-- Optionally you can try to optimize your svg using [this website](https://optimize.svgomg.net/), although it didn't make much of a difference for me. -->
Next, we need to transform our svg into an array of points, for which i used [this website](https://shinao.github.io/PathToPoints/). <!-- Next, we need to transform our svg into an array of points, for which i used [this website](https://shinao.github.io/PathToPoints/). -->
Lastly, you can replace the point array in [`ergogen/footprints/phi-caps`](./ergogen/footprints/phi-caps.js) for the front side or [`ergogen/footprints/phi-logo`](./ergogen/footprints/phi-logo.js) for the back side. <!-- Lastly, you can replace the point array in [`ergogen/footprints/phi-caps`](./ergogen/footprints/phi-caps.js) for the front side or [`ergogen/footprints/phi-logo`](./ergogen/footprints/phi-logo.js) for the back side. -->
# Parts <!-- # Parts -->
40 keys, 20 per side <!-- 40 keys, 20 per side -->
- 40 choc kailh switches <!-- - 40 choc kailh switches -->
- 40 choc kailh keycaps <!-- - 40 choc kailh keycaps -->
- 40 choc hotswap sockets <!-- - 40 choc hotswap sockets -->
- 40 smd diodes 1N4148 <!-- - 40 smd diodes 1N4148 -->
- 2 xiao ble <!-- - 2 xiao ble -->
- 2 oled 0.91 inch i2c (optional) <!-- - 2 oled 0.91 inch i2c (optional) -->
- 2 batteries 3.7v (optional, requres cable otherwise) <!-- - 2 batteries 3.7v (optional, requres cable otherwise) -->
# Firmware <!-- # Firmware -->
Usually ZMK is compiled throug a GitHub actions workflow. However, I prefer to use it locally using a docker devcontainer. The devcontainer is provided by the official ZMK project. <!-- Usually ZMK is compiled throug a GitHub actions workflow. However, I prefer to use it locally using a docker devcontainer. The devcontainer is provided by the official ZMK project. -->
## Setting up the ZMK docker toolchain <!-- ## Setting up the ZMK docker toolchain -->
```bash <!-- ```bash -->
nix develop # or install devcontainer cli otherwise <!-- nix develop # or install devcontainer cli otherwise -->
cd <path-to-phiboard>/firmware <!-- cd <path-to-phiboard>/firmware -->
./setup-zmk.sh # this may take a while <!-- ./setup-zmk.sh # this may take a while -->
``` <!-- ``` -->
## Compiling the ZMK firmware <!-- ## Compiling the ZMK firmware -->
```bash <!-- ```bash -->
nix develop # or install devcontainer cli otherwise <!-- nix develop # or install devcontainer cli otherwise -->
cd <path-to-phiboard>/firmware <!-- cd <path-to-phiboard>/firmware -->
./build.sh # clean build, is needed the first time <!-- ./build.sh # clean build, is needed the first time -->
./build.sh --cached # faster, if a build has been done before <!-- ./build.sh --cached # faster, if a build has been done before -->
# the firmware is now located at <path-to-phiboard>/firmware/(left|right).uf2 <!-- # the firmware is now located at <path-to-phiboard>/firmware/(left|right).uf2 -->
``` <!-- ``` -->
## Flashing the firmware <!-- ## Flashing the firmware -->
- connect mcu with pc <!-- - connect mcu with pc -->
- double press the reset button <!-- - double press the reset button -->
- the file explorer should now show a usb media <!-- - the file explorer should now show a usb media -->
- copy the corresponding .uf2 firmware to the usb media <!-- - copy the corresponding .uf2 firmware to the usb media -->
- it should now auto-eject and run the new firmware <!-- - it should now auto-eject and run the new firmware -->
## Fighting with ZMK <!-- ## Fighting with ZMK -->
- spend a lot of time on local toolchain and scripts <!-- - spend a lot of time on local toolchain and scripts -->
- other projects may have their config files in different places <!-- - other projects may have their config files in different places -->
- explain most important files which the user might want to change (and where) <!-- - explain most important files which the user might want to change (and where) -->
- confusing, overwhelming (at first) <!-- - confusing, overwhelming (at first) -->
- flash reset firmware to fix problems <!-- - flash reset firmware to fix problems -->
- dtsi is "weird" because of the way the matrix is connected (only on prototype) <!-- - dtsi is "weird" because of the way the matrix is connected (only on prototype) -->
- right overlay columns are reversed because its mirrored but pcb is non-mirrored <!-- - right overlay columns are reversed because its mirrored but pcb is non-mirrored -->
- main half controls layers of secondary half -> perhaps need to flash both sides for keymap to take new changes <!-- - main half controls layers of secondary half -> perhaps need to flash both sides for keymap to take new changes -->
- displays have close to 0 documentation at all <!-- - displays have close to 0 documentation at all -->
# Soldering <!-- # Soldering -->
- watch a solder intro video if you dont know what you are doing <!-- - watch a solder intro video if you dont know what you are doing -->
- the second half will be better <!-- - the second half will be better -->
- put solder on the pads, then heat the pads and press components in <!-- - put solder on the pads, then heat the pads and press components in -->
- if possible, test connectivity from mcu to front pads <!-- - if possible, test connectivity from mcu to front pads -->
- care for diode direction (on prototype) <!-- - care for diode direction (on prototype) -->
# Future fixes (from prototype) <!-- # Future fixes (from prototype) -->
- key spacing? <!-- - key spacing? -->
- different display <!-- - different display -->
<!-- # Thanks -->
# Thanks <!-- - to https://github.com/MvEerd/ergogen/tree/mveerd for ergogen -->
- to https://github.com/MvEerd/ergogen/tree/mveerd for ergogen <!-- - to https://flatfootfox.com/ergogen-introduction/ for teaching ergogen -->
- to https://flatfootfox.com/ergogen-introduction/ for teaching ergogen <!-- - to https://github.com/Pipshag/goosekb for inspiration on ergogen and zmk -->
- to https://github.com/Pipshag/goosekb for inspiration on ergogen and zmk <!-- - to https://www.youtube.com/watch?v=ohu4tZ4qov8 for finally making me follow through -->
- to https://www.youtube.com/watch?v=ohu4tZ4qov8 for finally making me follow through <!-- - and many, many more! -->
- and many, many more!