# buttfinity Full Documentation

![buttfinity1](https://github.com/user-attachments/assets/7be77395-7d78-468e-be83-d2ecec9adc5f)

# Buttfinity


[Print profile here](https://makerworld.com/en/models/1834693-buttfinity-smart-gridfinity-buttons) all models can also be found in the `stls/` folder.


Modular, customizable buttons (and other controls) in a gridfinity layout, allowing you to:

- control your computer (as a "fake" keyboard, either as a BLE keyboard using a ESP32 or as HID usb device using a RP2040 (no tutorial yet for that))
- control your smart home (using a ESP8266 or ESP32)
- use as a MIDI controller (using a RP2040, no tutorial yet for that either)
- anything else you can think of

> [!IMPORTANT]
> Work in progress. Don't expect everything to work perfectly yet.

> [!NOTE]
> No programming necessary, some soldering is required.  

## How to use

> [!NOTE]
> This documentation is for the ESP32 or ESP8266 version only, there is no tutorial for the RP2040 version yet.

1. Get the parts if you don't have them yet, see [Hardware Guide](docs/hardware/1-Hardware.md)
2. 3D print the bins and lids, see [3D Printing](docs/hardware/2-3d-printing.md)
2. Install ESPHome, see [ESPHome Guide](docs/software/1-install-esphome.md)
3. Either:
	- turn your Buttfinity into a BLE keyboard, see [Using as BLE Keyboard](docs/software/2-using-as-ble-keyboard.md)
	- or add buttons to your Home Assistant, see [Add Buttons to Home Assistant](docs/software/3-add-buttons-to-homeassistant.md)

## Credits

- [Gridfinity](https://gridfinity.xyz/) by [Zack Freedman](https://www.youtube.com/@ZackFreedman)
- [Anylid](https://makerworld.com/en/models/1059434-anylid-click-lock-stackable-lid-for-gridfinity) by [rngcntr](https://makerworld.com/en/@rngcntr) for the clickable lids
- [gridfinity-rebuilt-openscad](https://github.com/kennetek/gridfinity-rebuilt-openscad) by [kennetek](https://github.com/kennetek) for the baseplates and bins in openscad
- [Cherry MX switch](https://www.thingiverse.com/thing:5760008) by [neon_c](https://www.thingiverse.com/neon_c/designs)
- [BOSL2](https://github.com/BelfrySCAD/BOSL2) library

Built with:

- [OpenSCAD](https://openscad.org/)
- [Home Assistant](https://www.home-assistant.io/)
- [ESPHome](https://esphome.io/)
- [esphome-blekeyboard](https://github.com/dmamontov/esphome-blekeyboard)

## License

Everything in this repository (excluding everything from the credits section) is licensed under the [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) license.

![buttfinity2](https://github.com/user-attachments/assets/d5923fe3-c8ad-45be-b2aa-9161dcbe902f)

## Parts

> [!NOTE]  
> Amazon links are to the german amazon store and are not affiliate links, just where I bought the parts, I've tried to always use the most available parts, feel free to buy elsewhere. You can also use different microcontrollers, buttons/sensors, etc, see [Creating your own lids/bins](./5-creating-your-own-lids-bins.md) for more information.

### Microcontroller

- ESP32 D1 Mini USB C [amazon](https://amazon.de/dp/B0CJNMRG37) (recommended version, lots of pins, works as a BLE keyboard)

- ESP8266 D1 Mini USB C [amazon](https://amazon.de/dp/B0D9W2WM2K) (cheaper version, less pins, DOES NOT work as a BLE keyboard, only for controlling your smart home with home assistant)

- RP2040 Zero Mini [amazon](https://amazon.de/gp/product/B0CNSQCV9Q) (no bluetooth or wifi but works as a HID usb device)

### Various

- Magnets (6x2mm) [amazon](https://amazon.de/dp/B0DRNQT85B)
- Jumper cables 10cm & 20cm [amazon](https://www.amazon.de/dp/B0CFXZDBVY)
- Pin headers 2.54mm [amazon](https://www.amazon.de/dp/B07XM71CHT)

### Buttons/controls

> [!NOTE]  
> You don't need all of these, mix and match to your needs/preferences. If you have some other buttons/controls, feel free to [design your own lid](./5-creating-your-own-lids-bins.md) (if you design something with a widely available part, a PR is welcome).

For corresponding lids, see [here](./3-Lids.md).

- MX keyswitches [amazon](https://amazon.de/dp/B0BM9KR6QH)
- Self-locking push button switch 8x8mm [amazon](https://amazon.de/dp/B0D2RKL3L1)
- Rotary encoder [amazon](https://amazon.de/dp/B09SG3HF9N)
- Slider potentiometer 10k [amazon](https://www.amazon.de/dp/B0D6244S3Y)
- Capacitive touch sensor [amazon](https://www.amazon.de/dp/B09VPK9N7F)

# 3D Printing

Choose the lids you want to print depending on the buttons/controls you want to use, see [all available lids here](./3-Lids.md).

You can find the stls for all models in the `stls/` folder or get the print profile with [all lids and bins on makerworld](https://makerworld.com/en/models/1834693-buttfinity-smart-gridfinity-buttons). 

You need one special bin for your microcontroller (a 1x1x5 bin with a special cutout for the microcontroller to snap into, currently there are bins for the ESP32 D1 mini, ESP8266 D1 mini and RP2040 Zero Mini), all other bins are basically normal 1x1x5 (or 2x1x5) gridfinity bins, just with some extra cutouts for the cables.

Print one of the microcontroller bins and then the same amount of other bins minus one as you have 1x1 lids (and print a 2x1x5 bin for every 2x1 lid you want).

You can optionally print a normal gridfinity baseplate if you want one or add magnets.

There are also optional plugs for the outside of your assembled module, that can be used to fill the holes in the bins.

# Lids

## Switches

### MX key switches

> [!NOTE]  
> the mx switch lids are too tall to be used as a lid for the bin containing the microcontroller. Either use a lid with a different sensor or a blank lid. 

#### 1x1 round mx switch

![round-mx-key](https://github.com/user-attachments/assets/0d917087-21ff-4c26-b0a9-f32d2f6f3d86)

Use with mx-switch-round-cap-23mm.

#### 1x1 square mx switch

![square-mx-switch](https://github.com/user-attachments/assets/1ea6a703-620f-4e8e-b87d-ada5feed8370)

Use with mx-switch-square-cap-33x33mm.

#### 1x1 2 mx switches

![two-mx-switches](https://github.com/user-attachments/assets/96080e49-99f1-488b-b090-8cc5584aa161)

Use with mx-switch-square-cap-15x33mm.

#### 1x1 4 mx switches

![four-mx-keys](https://github.com/user-attachments/assets/66227468-aff2-439b-9f2a-dfe1a6d98079)

Use with mx-switch-square-cap-15x15mm.

#### 2x1 8 mx switches

![eight-mx-switches](https://github.com/user-attachments/assets/3c29489d-aed7-4dfd-9d7b-b15f0b13cd93)

Use with mx-switch-square-cap-15x15mm.

### Self-locking 8x8mm switch

#### 1x1 round self-locking switch

![round-lock-switch](https://github.com/user-attachments/assets/2db9126a-7a15-454f-b495-049386368cd5)


Use with switch-lock-round-cap-23mm.

### Rotary encoder

#### 1x1 rotary encoder

![rotary-encoder](https://github.com/user-attachments/assets/71e3282d-cf01-481a-a143-e656c34fc811)

Use with rotary-encoder-cap-15mm.

#### 1x1 4 rotary encoders

![four-rotary-encoders](https://github.com/user-attachments/assets/a92af47c-9342-4e72-b5de-7dede6285f84)

Use with rotary-encoder-cap-15mm.

### Slider potentiometer

Use with slider-cap-18mm.

#### 2x1 75mm slider potentiometer

![slider](https://github.com/user-attachments/assets/e280cec2-2faa-49ae-88bf-b97bb8a23d37)

Use with slider-cap-18mm.

# Wiring

The idea is to solder pin headers to your microcontroller and buttons/sensors. 

All buttons/sensors and the microcontroller can then easily be connected and disconnected again with jumper cables.

As an alternative you can also solder jumper cables (ending in a female header) straight onto your buttons/sensors.

# Creating your own lids/bins

## Bins

If you have a microcontroller you want to use that doesn't yet have a bin, you can create your own by using the openscad base file `./models/bins/buttfinity-bin-base.scad`, simply add some cutouts for your microcontroller and export as stl (see `./models/bins/buttfinity-bin-esp32.scad` for an example).

## Lids

If you have a sensor or button you want to use that doesn't yet have a lid, you can create your own by using the openscad base file `./models/lids/lid-module.scad`, add some cutouts for your sensor or button and export as stl (see `./models/lids/switches/buttfinity-1x1-1-round-mx-switch-lid.scad` for an example).

# Installing ESPHome

> [!NOTE]  
> If you don't have Home Assistant and just want to use Buttfinity as a BLE keyboard, instead of step 1, follow [the instructions here](./4-installing-without-homeassistant.md). 


1. Add ESPHome to your Home Assistant by clicking [this link](https://my.home-assistant.io/redirect/supervisor_addon/?addon=5c53de3b_esphome&repository_url=https%3A%2F%2Fgithub.com%2Fesphome%2Fhome-assistant-addon) and clicking "Install". 

Then in ESPHome Device Builder:

2. Click "New Device"

3. Click "Continue"

4. Enter a name for your device and enter your Wifi name and password.

5. Select "ESP32" or "ESP8266" as the board (depending on your microcontroller)

6. Click "Skip" when asked to install to your device.

7. A new device should appear in the list, click "Edit" and you should see the config for your device.

8. If you have an ESP32, change line 5-8 to:

```yaml
esp32:
  board: wemos_d1_mini32
  framework:
    type: arduino
```

If you have an ESP8266, change line 5-6 to:

```yaml
esp8266:
  board: d1_mini
```

9. Click "Install" in the top right corner and select "Manual Download".

10. Wait a few minutes until it's done compiling, then select "Factory Format (Previously Modern)" as the version you want to download.

11. Open [ESPHome Web](https://web.esphome.io/) and click "Add Device" in the top right corner, connect your microcontroller to your computer, click "Connect", select your device.

12. Click "Install" and add the project you downloaded from the ESPHome Device Builder and wait until it's done installing.

13. From now on you can flash you microcontroller wirelessly in the ESPHome Device Builder, you can either [add buttons to connect to Home Assistant](./3-add-buttons-to-homeassistant.md) there or [use it as a BLE keyboard](./2-using-as-ble-keyboard.md)

# Using as a BLE keyboard

> [!IMPORTANT]  
> This only works with the ESP32 version, both ESP8266 and RP2040 are not supported, as they don't have bluetooth.

Turn your Buttfinity module into a BLE keyboard by adding the following to you ESPHome config (in ESPHome Device Builder click "Edit").

```yaml
external_components:
  - source: github://dmamontov/esphome-blekeyboard

ble_keyboard:
  id: my_ble_keyboard
  name: "Buttfinity BLE Keyboard"
  manufacturer_id: "Buttfinity"
  reconnect: true
  battery_level: 50
  buttons: true
```

Now you can add buttons to your Buttfinity that will send keystrokes to your computer like this (you might have to change the pin):

```yaml
# type "hello world" when button is pressed
binary_sensor:
  - platform: gpio
    pin:
      number: GPIO22
      mode: INPUT_PULLUP
      inverted: true
    name: "Button"
    on_press:
      - ble_keyboard.print:
          id: my_ble_keyboard 
          text: "hello world"
```

See [esphome-blekeyboard](https://github.com/dmamontov/esphome-blekeyboard) for more information.

# Adding buttons to Home Assistant

Add buttons or similar to Home Assistant by adding sensors to you ESPHome config (in ESPHome Device Builder click "Edit").

Simple example for a button (you might have to change the pin):

```yaml
binary_sensor:
  - platform: gpio
    pin:
      number: GPIO22
      mode: INPUT_PULLUP
      inverted: true
    name: "Button"
```

In Home Assistant you can then go to "Settings" -> "Devices & Services", where your ESP should appear. Add it and you should see your Button as a sensor. Add automations using that button doing whatever you want it to do.

Other sensors work mostly the same, see [the ESPHome documentation](https://esphome.io/components/) for available sensors.

# Installing ESPHome without Home Assistant

If you don't have Home Assistant you can still use Buttfinity to control your computer (as a "fake" BLE keyboard).

> [!IMPORTANT]  
> This only works with a ESP32 D1 Mini, ESP8266 does not work as a BLE keyboard.

1. Install [ESPHome Device Builder](https://esphome.io/guides/getting_started_command_line/#esphome-device-builder-docker) by:

- Installing [Docker](https://docs.docker.com/get-started/get-docker/) if you don't have it yet

- Running `ESPHome Device Builder` in a terminal:

if you have a mac run:
```bash
# MacOs
docker run --rm -p 6052:6052 -e ESPHOME_DASHBOARD_USE_PING=true -v "${PWD}":/config -it ghcr.io/esphome/esphome
```

otherwise run:
```bash
# On Docker, host networking mode is required for online status indicators
docker run --rm --net=host -v "${PWD}":/config -it ghcr.io/esphome/esphome
```

2. Open [`localhost:6052`](http://localhost:6052) in your browser and you should see the ESPHome dashboard.

Next follow the instructions to [install ESPHome](./1-install-esphome.md) on your ESP32 D1 Mini, then the instructions to [simulate a BLE keyboard](./2-using-as-ble-keyboard.md).