Skip to the content
2 layers80 × 100 mmMacro keyboard, the printed circuit board in 3D

macro keyboard esp32 s3

Size
80 × 100 mm
Copper layers
2
Thickness
1.6 mm
Parts
74
Nets
94
Pads
385
Tracks, vias
728, 153
Pours
2
Routed
Yes
KiCad
KiCad 8.0 (file 20240108)
Created
1 Sep 2024
Updated
26 Jan 2026

Overview

Macro keyboard is an open-source printed circuit board by drfhaust, from the drfhaust/Macro-keyboard repository on GitHub. It is a 2-layer board of 80 × 100 mm with 74 parts on 94 nets, routed with 728 tracks and 153 vias.

It is built around the ESP32-S3-WROOM-1-N8R8, CH343P and GT-TF003-H0185-02, with the AP2112K-3.3, CPG135001S30 and XL-2020RGBC-WS2812B among its other parts. Its parts include 27 capacitors, 15 connectors, 13 diodes, 10 resistors and 4 ICs. It belongs with the keyboards and input boards and the ESP32 boards of this library.

Main components

9

README

README.md

image of the macro keyboard

Macro Keyboard

Macro Keyboard with ESP32-S3

This repository contains the design and code for building a custom macro keyboard powered by the ESP32-S3 microcontroller.

Overview

  • Design: A macro keyboard with customizable keys and LEDs for different functionalities.
  • Microcontroller: Powered by the ESP32-S3 with a built-in touch screen and additional hardware components.
  • Customization: Supports custom key mappings and macros via a JSON configuration.
  • Hardware Design: The keyboard's hardware is modular, making it adaptable for various input needs.

Hardware Specifications

  • Microcontroller: ESP32-S3 with built-in wireless connectivity.
  • Key Components: Uses Cherry MX-compatible key switches.
  • LEDs: Individually addressable RGB LEDs for customizable lighting.
  • Screen: Touch-enabled screen for additional control and feedback.
  • Battery: Supports external power, and can be adapted for battery-powered use.
  • Charging: USB Type-C port for charging and data transfer.
  • Connection: Supports both wired and wireless communication with a host device.

Software Features

  • Macro Management: The macros can be configured through the button.json file, where each button is assigned a specific action or macro.
  • LED Control: RGB LEDs can be customized for each button based on the configuration.
  • Key Mapping: Easily programmable for various applications, from simple shortcuts to complex multi-step macros.
  • Python Integration: Python scripts are provided to manage macro configurations and interface with the hardware.

Power Details

  • Power Input: Powered through USB Type-C or battery.
  • Power Consumption: Optimized for low power consumption during idle states.

Repository Structure

  • Arduino code: Contains the LVGL porting for the ESP32-S3 along with the Arduino source code for the project.

    • lvgl_Porting: Core source files for integrating LVGL (LittlevGL) with the ESP32-S3.
  • Macro keyboard: Includes hardware designs, PCB schematics, and component configurations.

    • GERBER: Files for manufacturing the PCB.
    • custom components: KiCad components for custom parts used in the keyboard.
    • backups: Backup files for the PCB designs.
  • python code: Python scripts to manage macros and configure button functionalities.

    • macro_manager_v4.py: Python script for managing the macro functions of the keyboard.
  • solidwork 3d: 3D models of the keyboard parts, including key switches and case designs.

  • button.json: Configuration file where button mappings and LED colors are stored.

Getting Started

  1. Clone this repository:

    bash
    git clone <repository-url>
  2. Hardware Setup:

    • Flash the ESP32-S3 with the code in Arduino code/lvgl_Porting.
    • Assemble the PCB and components according to the schematics in the Macro keyboard folder.
  3. Software Setup:

    • Install the required Python libraries by running:
      bash
      pip install -r requirements.txt
  4. Macro Management:

    • Configure macros by editing button.json.
    • Run the macro manager script to apply your changes:
      bash
      python python code/v4/macro_manager_v4.py

Contributing

Please read the contribution guidelines before making any changes.

License

This project is licensed under the MIT License.

Parts

74
QtyValueFootprintReferences
12100nCapacitor_SMD:C_0603_1608MetricC13, C14, C15, C16, C17, C18, C19, C20, C21, C22, C23, C24
12CPG135001S30footprints:Connector_Keyswitch_Socket_KAILH_CPG135001S30J2, J3, J4, J5, J6, J7, J8, J9, J10, J11, J12, J13
12RGBfootprints:LED_SMD_XINGLIGHT_XL-2020RGBC-WS2812BD2, D3, D4, D5, D6, D7, D8, D9, D10, D11, D12, D13
410ufCapacitor_SMD:C_0603_1608MetricC6, C12, C25, C26
3100nfCapacitor_SMD:C_0603_1608MetricC3, C4, C5
31UFCapacitor_SMD:C_0603_1608MetricC7, C8, C11
20RResistor_SMD:R_0603_1608MetricR5, R6
210kResistor_SMD:R_0603_1608MetricR11, R12
212kResistor_SMD:R_0603_1608MetricR1, R2
215pfCapacitor_SMD:C_0603_1608MetricC9, C10
21ufCapacitor_SMD:C_0603_1608MetricC1, C27
25k1Resistor_SMD:R_0603_1608MetricR7, R8
2S8050Package_TO_SOT_SMD:SOT-23Q1, Q2
2SW_PushButton_Switch_SMD:SW_SPST_B3U-1000PSW1, SW2
1100KResistor_SMD:R_0603_1608MetricR3
11kResistor_SMD:R_0603_1608MetricR10
14.7ufCapacitor_SMD:C_0603_1608MetricC2
1AP2112K-3.3Package_TO_SOT_SMD:SOT-23-5U3
1B5819WS-TPcustom components:SOD2512X115ND1
1CH343Pcustom components:QFN50P300X300X80-17NU2
1Conn_01x04_PinConnector_JST:JST_XA_B04B-XASK-1_1x04_P2.50mm_VerticalJ16
1Crystal_GND24Crystal:Crystal_SMD_2016-4Pin_2.0x1.6mmY1
1ESP32-S3-WROOM-1-N8R8custom components:XCVR_ESP32S3WROOM1N8R8U1
1GT-TF003-H0185-02footprints:Connector_MicroSD_G-SWITCH_GT-TF003-H0185-02J15
1MC-126D-DG10footprints:Connector_USB-C_HANBO-ELECTRONIC_MC-126D-DG10J1
1~Package_DFN_QFN:QFN-24-1EP_4x4mm_P0.5mm_EP2.75x2.75mm_ThermalViasU4

More from drfhaust/Macro-keyboard

1
  • 2 layers80 × 73.1 mmMacro keyboard, the printed circuit board in 3D

    Macro keyboard

    drfhaust/Macro-keyboard

    macro keyboard esp32 s3

    41 parts

Similar boards

  • 2 layers60 × 50 mmWactrollerLogic, the printed circuit board in 3D

    WactrollerLogic

    hykilpikonna/OpenHardware

    Open-sourced Hardware Experimentation <3

    36 parts10
  • 4 layers97.1 × 26 mmDiveCAN Head2, the printed circuit board in 3D

    DiveCAN Head2

    QuickRecon/DiveCANHead

    An open source rebreather head controller

    157 parts13MIT
  • 6 layers167.5 × 79 mmHandheld, the printed circuit board in 3D

    Handheld

    gamebub/gamebub-pcb

    PCB design files for the Game Bub project

    356 parts31CERN-OHL-S-2.0
  • 2 layers48 × 48 mm1Job v1, the printed circuit board in 3D

    1Job v1

    scottcjx/1-Job

    45 partsGPL-3.0
  • 4 layers93.2 × 35 mmMk2 routed, the printed circuit board in 3D

    Mk2 routed

    Woz4tetra/auto-battlebot

    This project brings aim-assist and autonomous control to combat robots.

    75 parts3
  • 4 layers76.9 × 67.3 mmTerra HW, the printed circuit board in 3D

    Terra HW

    jamesmendel/terra-nova

    Terra 2.0 Firmware and Hardware

    95 parts2GPL-3.0
  • 4 layers52.1 × 40.7 mmXDV, the printed circuit board in 3D

    XDV

    TeamFoxbat/XDV

    100% Digital Video Solution for Original Xbox!

    61 parts2CERN-OHL-P-2.0
  • 4 layers90 × 40 mmLinear act controller, the printed circuit board in 3D

    Linear act controller

    Talw3g/linear_act_controller

    Controller for 24V linear actuator with potentiometer position control and feedback.

    80 parts

Questions

How big is the Macro keyboard PCB?

It measures 80 × 100 mm and has 2 copper layers, 1.6 mm thick.

What parts does the Macro keyboard use?

74 parts, built around the ESP32-S3-WROOM-1-N8R8, CH343P, GT-TF003-H0185-02 and AP2112K-3.3. 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 Macro keyboard KiCad files?

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

Can I use the Macro keyboard design in my own project?

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