Skip to the content
2 layers84.2 × 52 mmPicoPico, the printed circuit board in 3D

Pico-8 Player

Size
84.2 × 52 mm
Copper layers
2
Thickness
1.6 mm
Parts
57
Nets
70
Pads
249
Tracks, vias
378, 47
Pours
3
Routed
Yes
KiCad
KiCad 6 (file 20211014)
Created
27 Apr 2022
Updated
1 Apr 2024

Overview

PicoPico is an open-source printed circuit board by DavidVentura, from the DavidVentura/PicoPico repository on GitHub. It is a 2-layer board of 84.2 × 52 mm with 57 parts on 70 nets, routed with 378 tracks and 47 vias.

It is built around the CH340C, ESP32-WROVER-E(4MB) and AP7333-33SAG, with the STC4054GR and BC817 among its other parts. Its parts include 17 resistors, 6 capacitors, 6 ICs, 3 connectors and 3 switches. It belongs with the retro computing and games boards and the ESP32 and RP2040 boards of this library.

Main components

5

README

README.md

Pico Pico

Project to attempt to create hardware for the Pico-8.

I'd like to eventually get full game running on a Raspberry Pi Pico ESP32

Be aware, the code will be terrible, this is a project to learn:

  • C
  • SDL
  • Embedded
  • CMake
  • Lua
    • And how to adapt / modify languages
  • JIT-ting ??

This project uses z8lua to implement Pico8's Lua dialect; I've whacked the original repo to make it build with the Pico as a target, it was all implicit casting, which I hopefully got right.

This project also gets some "inspiration" from tac08 - ideas for things I don't know how to solve, and the "firmware.lua" file for basic implementations.

Demo

In emulator (SDL/rawdraw backed)

https://user-images.githubusercontent.com/3650670/209883786-df8e24eb-6469-4147-87f5-97d2407c08f9.mp4

Celeste in ESP32

https://user-images.githubusercontent.com/3650670/168416377-bf238d62-6be6-4b70-a04c-2d60ab57a269.mp4

In Raspberry pi Pico (port abandoned, not enough RAM)

https://user-images.githubusercontent.com/3650670/166146124-06b8b223-27b1-47ac-931f-67ba8b523d9e.mp4

On Android

https://github.com/DavidVentura/PicoPico/assets/3650670/8b1ce7c6-c577-427d-8bed-b0ab688078c9

On 3DS

https://github.com/DavidVentura/PicoPico/assets/3650670/648f5ae0-5fe0-4eac-8bdf-cbaad8db8e8a

Hardware

BOM

  • 1x THT Power switch TME PDF
  • 8x SMD button TME PDF
  • 1x 10k horixontal potentiometer TME PDF
  • 8x SMD 10k resistor
  • MAX98357 I2S audio amplifier ALI
  • ESP32 "Wrover" with 4MB PSRAM Amazon
  • 1.77" SPI ST7735 128x160 Display (128x128 used for game, 16px for UI, 16px padding) ALI

Goals

  1. ✅ Make hello_world work without regressions )).
    • All letters are white (lazy palette evaluation was missing a palette indirection (screen vs draw))
  2. ✅ Make rockets fully playable (without music // complete SFX).
    • Points go up too fast (time() was returning millis)
  3. ✅ Create some basic automated testing.
    • Tests are at tests/, they run one (or a few) frames and get output.
    • Need to integrate better into the project; exclusive ifdef for header selection
  4. Make celeste fully playable (without music // complete SFX)
    • Clouds suddenly appear (bad rectfill types, took uint instead of int)
    • Sometimes 2 celestes appear?? mostly on level crossings
  5. Make valdi fully playable (without music // complete SFX)
    • Renders offset when looking to the left (wasn't calculating the sprite width accordingly in spr())
    • fillp not implemented (background)
    • Super slow after a few resets? (gfx_line was missing a bounds check, overwriting the delay between frames)
  6. Make awake fully playable (without music // complete SFX)
    • Colors are super glitched, level2 is also glitched

Basic analysis / feasibility:

Memory requirements:

  • Spritesheet, at 128x128 in size = 16KB
    • Can move to flash
  • Fontsheet, at 128x128 in size = 16KB
    • Can move to flash
  • Map, at 64x128 = 8 KB
    • Can move to flash
  • Flags, at 2x128 = 256B
    • Can move to flash
  • Sound effects, 64x84 = 5376B (~5KB)
    • Can move to flash
  • Music patterns, 64x6 = 384B
    • Can move to flash
  • Front buffer 128x128/2 = 8KB (x/y position -> palette)
  • Back buffer 128x128x2 = 32KB (x/y position -> color, at 16bpp)
  • HUD buffer 16x128x2 = 4KB
    • Can squeeze to 8x64x2 = 1KB, or even 7 sprites (896b)
  • Dedicated "Game memory" = 32KB

Totals ~130KB (of which 76KB for screen buffers and game memory have to stay).

And most importantly 2MB for game RAM (Lua memory). This varies based on each game, but on the PICO the 264KB ran out pretty fast. There's this thing to use very slow, very cursed external RAM. Some games

Performance

In RPI Pico:

Running hello_world.lua:

  • Normal: 13ms / frame; of which:

    • Lua: ~9ms / frame
    • Copying backbuffer to screen (uint8_t): ~4ms / frame
  • Display on 2nd core: 7.5ms / frame; of which:

    • Lua: ~7ms / frame
    • Copying backbuffer to screen happens "for free" in the other core
  • Multicore + overclock to 260MHz: 3.5ms/frame

In ESP32:

Celeste takes about 9ms / frame (rendering happens on the second core), including SFX

TODO

Immediate:

  • Get basic rendering on the Pico
    • split backends properly
  • Read code from p8 file instead of having split files
  • Implement map
  • Implement camera
  • Lua dialect (using z8lua)
  • Unify the build systems (Make for pc / CMake for pico)
  • Pre-encode the palette colors as a RGB565 uint16_t; makes no sense to shift them on every pixel write
  • SFX
  • Measure and output the correct number of samples out of the audio buffer, currently it's a (badly) guessed number.
  • Get reasonable audio quality out of SFX
  • Deal with warnings when building for ESP
    • Figure out why they don't show up when building with SDL backend
  • Move hardcoded pin for ESP32 to sdkconfig
    • Extract current values for docs WIP
  • Implement more complete SFX
  • Generate board captures automatically
  • Add support for short-hand print ('?"x"' == print("x"))
  • Implement fillp https://pico-8.fandom.com/wiki/Fillp
  • Lua error: bad argument #1 to 'split' (string expected, got nil)
  • Lua error: bad argument #1 to 'btn' (number expected, got nil)
    • z8lua considers literal circle (🅾️) to be nil but not ❎

Later:

  • Clock rate on SPI? set to 62.5MHz; not sure if it can go higher
  • Implement flash
    • cartdata command could use it
    • carts could be stored in flash instead of static data
  • Investigate pushing pixels to display via DMA
    • worth it? the second core is idle anyway
  • Music
  • Look at optimizing lua bytecode for "fast function calls", for "standard library"
  • Use headers instead of stupid ifdefs
  • Enable -Wconversion
  • Console-based UI game

Other stuff

Resources are parsed from plaintext into a header by the to_c.py script, this also covers converting source code to byte-code. Having byte-code compiled in a pre-processing stage makes parsing faster (112ms -> 18ms for a large cart), uses less memory (bytecode stays in flash, not necessary to load to RAM) and enables future bytecode-level optimization

Sound

I yoinked zepto8's synth and converted it to fix32; an example SFX went from ~25ms to ~2ms on the ESP32.

API Support

Graphics

FunctionSupportedNotes
camera✅
circ✅
circfill✅
oval✅
ovalfill✅
clip✅
cls✅
color✅
cursor❌
fget✅
fillp❌
fset❌
line✅
pal⚠️Only "draw palette" is implemented
palt✅
pget✅
print⚠️Does not automatically scroll
pset✅
rect✅
rectfill✅
sget✅
spr✅
sset✅
sspr⚠️
tline❌

Tables

All implemented (z8lua)

Input

btn implemented

Sound

FunctionSupportedNotes
sfx⚠️Offset is not implemented
music❌

Map

All implemented

Memory

Not implemented

Math

All implemented (z8lua)

Cartridge data

FunctionSupportedNotes
cartdata⚠️Not persistent
dget⚠️Not persistent
dset⚠️Not persistent
cstore❌
reload❌
cartdata/dget/dset are technically implemented, there's no persistence layer though.

cstore/reload are not implemented.

Coroutines

Implemented by aliasing (z8lua)

Strings

Implemented (z8lua)

Values and objects

Implemented (z8lua)

Hardware

Build something like the PicoSystem ?

Development setup

bash
sudo apt install cmake g++ libsdl2-dev
git submodule update --init
mkdir pc_pico && cd pc_pico
cmake -DBACKEND=PC ..

Development on RP2040 (without a second Pico running OpenOCD)

Add this block to a udev rule (adjust the paths to point to this repo)

text
SUBSYSTEM=="block", ATTRS{idVendor}=="2e8a", ATTRS{idProduct}=="0003", ACTION=="add", SYMLINK+="rp2040upl%n"
SUBSYSTEM=="block", ATTRS{idVendor}=="2e8a", ATTRS{idProduct}=="0003", ACTION=="add", RUN+="/home/david/git/luatest/udev_build.sh rp2040upl%n"

Then having an open minicom shell

text
sudo minicom -b 115200 -D /dev/ttyACM1

you can press r on it to reboot into mass-storage mode; which will trigger the udev rules after a second or so.

Tests

There's a CMake backend (TEST) that you can use with cmake -DBACKEND=TEST; in that backend, the command make test will run some tests.

Some of the tests are for the internal APIs, and are written in C. Generally though, most tests should be written as p8 cartridges and placed in tests/regression/*.p8.

Internal API tests usually compare the output with some expected, known-good frontbuffer values (a "screenshot"). Whenever these need to change, the specific test can be re-run with the environment variable OVERWRITE_TEST_BUF set to any value. This will overwrite tests/data/buf_*.bin. To look at these buffers, you can use the command bin_to_png.

text
> make test
Running tests...
Test project /Users/tati/git/PicoPico/tests_build
    Start 1: test_hello_world
1/5 Test #1: test_hello_world .................   Passed    0.03 sec
    Start 2: test_hud
2/5 Test #2: test_hud .........................   Passed    0.03 sec
    Start 3: test_menu
3/5 Test #3: test_menu ........................   Passed    0.03 sec
    Start 4: test_primitives
4/5 Test #4: test_primitives ..................   Passed    0.03 sec
    Start 5: test_regression
5/5 Test #5: test_regression ..................   Passed    0.03 sec

100% tests passed, 0 tests failed out of 5

Total Test time (real) =   0.16 sec
text
> ./test_regression
Testing regression_api_p8
  test_map_no_args                        [ OK]
  test_print_p8scii_color                 [ OK]

Testing regression_asan_p8
  test_sspr_same_size_is_maintained       [ OK]
  test_circ_top_left_edge                 [ OK]

Testing regression_other_p8
  test_nothing                            [ OK]

Useful links

Parts

57
QtyValueFootprintReferences
8TestPointpicopico:padTP5, TP6, TP7, TP8, TP9, TP10, TP11, TP12
6SW_Pushpicopico:evqq2_compactSW_B1, SW_L1, SW_T1, SW3, SW5, SW6
50Resistor_SMD:R_0201_0603MetricR13, R14, R15, R16, R17
5RResistor_SMD:R_1206_3216Metric_Pad1.30x1.75mm_HandSolderR5, R6, R7, R8, R10
410KResistor_SMD:R_1206_3216Metric_Pad1.30x1.75mm_HandSolderR1, R2, R3, R4
4MountingHoleMountingHole:MountingHole_2.2mm_M2H1, H2, H3, H5
30.1uFCapacitor_SMD:C_1206_3216MetricC3, C4, C6
310kResistor_SMD:R_1206_3216Metric_Pad1.30x1.75mm_HandSolderR9, R11, R12
2BC817Package_TO_SOT_SMD:SOT-23Q1, Q2
2SW_PushButton_Switch_SMD:SW_SPST_B3U-1100P-BSW7, SW8
1100nFCapacitor_SMD:C_1206_3216MetricC5
11uFCapacitor_SMD:C_1206_3216MetricC1
122uFCapacitor_SMD:C_1206_3216MetricC2
1AP7333-33SAGPackage_TO_SOT_SMD:SOT-23U3
1Batterypicopico:SM02B-SRSS-TBBT1
1CH340CPackage_SO:SOIC-16_3.9x9.9mm_P1.27mmU6
1Conn_01x04Connector_PinHeader_2.54mm:PinHeader_1x04_P2.54mm_Vertical_SMD_Pin1RightJ1
1ESP32-WROVER-EEspressif:ESP32-WROVER-E_ThermalViasU1
1STC4054GRPackage_TO_SOT_SMD:SOT-23-5U5
1SW_SPDTpicopico:switch_slide_OS102011MA1QN1SW1
1Speakerpicopico:speakerLS1
1USB_B_MicroConnector_USB:USB_Micro-B_Amphenol_10103594-0001LF_HorizontalJ3
1audiopicopico:audioU4
1displaypicopico:lcd smdJ2
1volume_wheelpicopico:volume wheelU2

Similar boards

  • 2 layers82 × 82 mmFtduino32, the printed circuit board in 3D

    Ftduino32

    harbaum/ftduino32

    ESP32 based variant of the ftDuino

    157 parts5
  • 4 layers120 × 108 mmDk2 06, the printed circuit board in 3D

    Dk2 06

    mattybrad/drumkid2

    189 parts12GPL-3.0
  • 2 layers50 × 20 mmM5stack board dynamixel ttl rs3485, the printed circuit board in 3D

    M5stack board dynamixel ttl rs3485

    kim-xps12/m5stack_board_dynamixel_ttl_rs3485

    When using this repository in your own environment, please import HY2.0-4P.kicadmod into the appropriate library. I import it into the global library so that it can be used from other projects as well.

    20 parts6MIT
  • 2 layers72 × 47.5 mmPCB envmeter esp32c3, the printed circuit board in 3D

    PCB envmeter esp32c3

    k-takata/PCB_envmeter_esp32c3

    IoT environment meter using ESP32-C3 and BME680

    31 parts3
  • 2 layers34.3 × 14 mmGrove qwiic breadboard bridge, the printed circuit board in 3D

    Grove qwiic breadboard bridge

    74th/74th-oshw-projects

    74th のPCBデータを公開しているプロジェクト

    15 parts1MIT
  • 2 layers37 × 23.5 mmSmartWatch, the printed circuit board in 3D

    SmartWatch

    Sl-Alex/SmartWatch

    SmartWatch with BLE (open-source SW and HW)

    66 parts1GPL-3.0
  • 2 layers119 × 79 mmHome Ambient, the printed circuit board in 3D

    Home Ambient

    abrahanlp/Home-Ambient

    2-wire home thermostat with temperature, humidity, pressure and air quality measures.

    62 partsAGPL-3.0

Questions

How big is the PicoPico PCB?

It measures 84.2 × 52 mm and has 2 copper layers, 1.6 mm thick.

What parts does the PicoPico use?

57 parts, built around the CH340C, ESP32-WROVER-E(4MB), AP7333-33SAG and STC4054GR. The full list of its parts is on this page, with links to each part's symbol and footprint where PCBKit's library has them.

Where can I download the PicoPico KiCad files?

From the DavidVentura/PicoPico repository on GitHub, at the commit this page was made from: the board is board/picopico/picopico.kicad_pcb and its schematic board/picopico/picopico.kicad_sch. PCBKit opens the board in the browser, with nothing to install.

Can I use the PicoPico design in my own project?

Its repository states no licence, so its author keeps all rights: ask DavidVentura before reusing the design.